Esportazione e importazione delle entità

Questa pagina descrive come esportare e importare entità Firestore in modalità Datastore utilizzando il servizio di esportazione e importazione gestito. Il servizio di esportazione e importazione gestito è disponibile tramite la console Google Cloud , Google Cloud CLI e l'API Admin di Datastore (REST, RPC).

Con il servizio di esportazione e importazione gestito, puoi recuperare i dati dall'eliminazione accidentale ed esportarli per l'elaborazione offline. Puoi esportare tutte le entità o solo tipi specifici di entità. Allo stesso modo, puoi importare tutti i dati di un'esportazione o solo tipi specifici. Quando utilizzi il servizio di esportazione e importazione gestito, tieni presente quanto segue:

  • Il servizio di esportazione utilizza letture con coerenza finale. Non puoi presumere che un'esportazione avvenga in un singolo momento. L'esportazione potrebbe includere entità scritte dopo l'inizio dell'esportazione ed escludere entità scritte prima dell'inizio dell'esportazione.

  • Un'esportazione non contiene indici. Quando importi i dati, gli indici richiesti vengono ricreati automaticamente utilizzando le definizioni degli indici correnti del database. Le impostazioni dell'indice dei valori delle proprietà per entità vengono esportate e rispettate durante l'importazione.

  • Le importazioni non assegnano nuovi ID alle entità. Le importazioni utilizzano gli ID esistenti al momento dell'esportazione e sovrascrivono qualsiasi entità esistente con lo stesso ID. Durante un'importazione, gli ID vengono riservati per il periodo di tempo in cui le entità vengono importate. Questa funzionalità impedisce i conflitti di ID con le nuove entità se le scritture sono abilitate durante l'esecuzione di un'importazione.

  • Se un'entità del tuo database non è interessata da un'importazione, rimarrà nel database dopo l'importazione.

  • I dati esportati da un database in modalità Datastore possono essere importati in un altro database in modalità Datastore, anche in un altro progetto.

  • Il servizio di esportazione e importazione gestito limita il numero di esportazioni e importazioni simultanee a 50 e consente un massimo di 20 richieste di esportazione e importazione al minuto per un progetto. Per ogni richiesta, il servizio limita a 100 il numero di combinazioni di filtri entità.

  • L'output di un'esportazione gestita utilizza il formato dei log LevelDB.

  • Per importare solo un sottoinsieme di entità o per importare dati in BigQuery, devi specificare un filtro entità nell'esportazione.

  • Il nome file .overall_export_metadata deve corrispondere al nome della cartella principale:

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

    Se sposti o copi i file di output di un'esportazione, mantieni invariati PARENT_FOLDER_NAME, i contenuti delle sottocartelle e il nome file .overall_export_metadata.

Prima di iniziare

Prima di poter utilizzare il servizio di esportazione e importazione gestite, devi completare le seguenti attività.

  1. Attiva la fatturazione per il tuo progetto Google Cloud . Solo i progetti Google Cloud con fatturazione abilitata possono utilizzare le funzionalità di esportazione e importazione.

  2. Crea un bucket Cloud Storage nella stessa località del tuo database Firestore in modalità Datastore. Non puoi utilizzare un bucket con Pagamenti a carico del richiedente o un bucket Rapid per le operazioni di esportazione e importazione.

  3. Assegna un ruolo IAM al tuo account utente che concede l'autorizzazione datastore.databases.export, se esporti i dati, o l'autorizzazione datastore.databases.import, se importi i dati. Ad esempio, il ruolo Datastore Import Export Admin concede entrambe le autorizzazioni.

  4. Se il bucket Cloud Storage si trova in un altro progetto, concedi all'agente di servizio Firestore l'accesso al bucket.

Configura gcloud per il tuo progetto

Se prevedi di utilizzare gcloud per avviare le operazioni di importazione ed esportazione, configura gcloud e connettiti al tuo progetto in uno dei seguenti modi:

Autorizzazioni

Per eseguire operazioni di esportazione e importazione, il tuo account utente e l'agente di servizio in modalità Datastore del tuo progetto devono disporre delle seguenti autorizzazioni di Identity and Access Management.

Autorizzazioni dell'account utente

L'account utente o il account di servizio che avvia l'operazione richiede le autorizzazioni IAM datastore.databases.export e datastore.databases.import. Se sei il Project Owner, il tuo account dispone delle autorizzazioni richieste. In caso contrario, i seguenti ruoli IAM concedono le autorizzazioni necessarie:

  • Proprietario Datastore
  • Datastore Import Export Admin

Puoi anche assegnare queste autorizzazioni con un ruolo personalizzato.

Un Project Owner può concedere uno di questi ruoli seguendo i passaggi descritti in Concedi l'accesso.

Autorizzazioni agente di servizio

Le operazioni di esportazione e importazione utilizzano un agente di servizio Firestore per autorizzare le operazioni di Cloud Storage. L'agente di servizio Firestore utilizza la seguente convenzione di denominazione:

Service agent Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Per saperne di più sugli agenti di servizio, consulta Agenti di servizio.

L'agente di servizio Firestore richiede l'accesso al bucket Cloud Storage utilizzato in un'operazione di esportazione o importazione. Se il tuo bucket Cloud Storage si trova nello stesso progetto del tuo database Firestore, l'agente di servizio Firestore può accedere al bucket per impostazione predefinita.

Se il bucket Cloud Storage si trova in un altro progetto, devi concedere all'agente di servizio Firestore l'accesso al bucket Cloud Storage.

Assegna i ruoli all'agente di servizio

Puoi utilizzare lo strumento a riga di comando gsutil per assegnare uno dei ruoli riportati di seguito. Ad esempio, per assegnare il ruolo Amministratore Storage all'agente di servizio Firestore, esegui questo comando:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Sostituisci PROJECT_NUMBER con il numero del progetto, che viene utilizzato per assegnare un nome all'agente di servizio Firestore. Per visualizzare il nome dell'agente di servizio, consulta Visualizza il nome dell'agente di servizio.

In alternativa, puoi assegnare questo ruolo utilizzando la console Google Cloud .

Visualizza il nome dell'agente di servizio

Puoi visualizzare l'account utilizzato dalle operazioni di importazione ed esportazione per autorizzare le richieste dalla pagina Importa/Esporta nella console Google Cloud . Puoi anche visualizzare se il tuo database utilizza l'agente di servizio Firestore o l'account di servizio App Engine legacy.

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Visualizza l'account di autorizzazione accanto all'etichetta Esegui job di importazione/esportazione come.

Operazioni di esportazione

Per le operazioni di esportazione che coinvolgono un bucket in un altro progetto, modifica le autorizzazioni del bucket per assegnare uno dei seguenti ruoli di Identity and Access Management all'agente di servizio in modalità Datastore del progetto che contiene il database in modalità Datastore:

  • Amministratore Storage
  • Proprietario (ruolo di base)

Puoi anche creare un ruolo IAM personalizzato con autorizzazioni leggermente diverse da quelle contenute nei ruoli elencati in precedenza:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.list

Operazioni di importazione

Per le operazioni di importazione che coinvolgono un bucket Cloud Storage in un altro progetto, modifica le autorizzazioni del bucket per assegnare uno dei seguenti ruoli Cloud Storage all'agente di servizio della modalità Datastore del progetto che contiene il database in modalità Datastore:

  • Amministratore Storage
  • Sia Storage Object Viewer che Storage Legacy Bucket Reader

Puoi anche creare un ruolo IAM personalizzato con le seguenti autorizzazioni:

  • storage.buckets.get
  • storage.objects.get

Avvio delle operazioni di esportazione e importazione gestite

Questa sezione descrive come avviare un'operazione di esportazione o importazione gestita.

Esportazione di tutte le entità

Console

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  1. Nel menu di navigazione, fai clic su Importa/Esporta.
  2. Fai clic su Esporta.
  3. Imposta il campo Spazio dei nomi su All Namespaces e il campo Tipo su All Kinds.
  4. In Destinazione, inserisci il nome del bucket Cloud Storage.
  5. Fai clic su Esporta.

La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di esportazione gestita.

gcloud

Utilizza il comando gcloud firestore export per esportare tutte le entità nel database.

 gcloud firestore export gs://bucket-name --async --database=DATABASE

dove bucket-name è il nome del bucket Cloud Storage e un prefisso facoltativo, ad esempio bucket-name/datastore-exports/export-name. Non puoi riutilizzare lo stesso prefisso per un'altra operazione di esportazione. Se non fornisci un prefisso del file, il servizio di esportazione gestito ne crea uno in base all'ora corrente.

Utilizza il flag --async per impedire a gcloud di attendere il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di un'operazione. L'operazione non verrà annullata.

Imposta il flag --database sul nome del database da cui vuoi esportare le entità. Per il database predefinito, utilizza --database='(default)'.

rest

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • project-id: il tuo ID progetto
  • bucket-name: il nome del tuo bucket Cloud Storage

Metodo HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:export

Corpo JSON della richiesta: 

{
  "outputUrlPrefix": "gs://bucket-name",
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi verificare il completamento.

Esportazione di tipi o spazi dei nomi specifici

Per esportare un sottoinsieme specifico di tipi e/o spazi dei nomi, fornisci un filtro entità con valori per i tipi e gli ID spazio dei nomi. Ogni richiesta è limitata a 100 combinazioni di filtri di entità, dove ogni combinazione di tipo filtrato e spazio dei nomi viene conteggiata come un filtro separato ai fini di questo limite.

Console

Nella console puoi selezionare tutti i tipi o un tipo specifico. Analogamente, puoi selezionare tutti gli spazi dei nomi o uno spazio dei nomi specifico.

Per specificare un elenco di spazi dei nomi e tipi da esportare, utilizza invece gcloud.

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Fai clic su Esporta.

  5. Imposta il campo Spazio dei nomi su All Namespaces o sul nome di uno dei tuoi spazi dei nomi.

  6. Imposta il campo Kind su All Kinds o sul nome di un tipo.

  7. In Destinazione, inserisci il nome del bucket Cloud Storage.

  8. Fai clic su Esporta.

La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di esportazione gestita.

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

dove bucket-name è il nome del bucket Cloud Storage e un prefisso facoltativo, ad esempio bucket-name/datastore-exports/export-name. Non puoi riutilizzare lo stesso prefisso per un'altra operazione di esportazione. Se non fornisci un prefisso del file, il servizio di esportazione gestito ne crea uno in base all'ora corrente.

Utilizza il flag --async per impedire a gcloud di attendere il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di un'operazione. L'operazione non verrà annullata.

Imposta il flag --database sul nome del database da cui vuoi esportare tipi o spazi dei nomi specifici. Per il database predefinito, utilizza --database='(default)'.

rest

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • project-id: il tuo ID progetto
  • bucket-name: il nome del tuo bucket Cloud Storage
  • kind: il tipo di entità
  • namespace: l'ID dello spazio dei nomi (utilizza "" per l'ID dello spazio dei nomi predefinito)

Metodo HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:export

Corpo JSON della richiesta: 

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi verificare il completamento.

File di metadati

Un'operazione di esportazione crea un file di metadati per ogni coppia spazio dei nomi-tipo specificata. I file di metadati sono in genere denominati NAMESPACE_NAME_KIND_NAME.export_metadata. Tuttavia, se uno spazio dei nomi o un tipo crea un nome di oggetto Cloud Storage non valido, il file verrà denominato export[NUM].export_metadata.

I file di metadati sono buffer di protocollo e possono essere decodificati con il compilatore di protocollo protoc. Ad esempio, puoi decodificare un file di metadati per determinare lo spazio dei nomi e i tipi contenuti nei file di esportazione:

protoc --decode_raw < export0.export_metadata

Importazione di tutte le entità

Console

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Fai clic su Importa.

  5. Nel campo File, fai clic su Sfoglia e seleziona un file .overall_export_metadata.

    Assicurati che il file .overall_export_metadata non venga spostato dalla posizione predefinita.

  6. Imposta il campo Spazio dei nomi su All Namespaces e il campo Tipo su All Kinds.

  7. Fai clic su Importa.

La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di importazione gestita.

gcloud

Utilizza il comando gcloud firestore import per importare tutte le entità esportate in precedenza con il servizio di esportazione gestito.

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

dove bucket-name/file-path/file-name è il percorso del file overall_export_metadata all'interno del bucket Cloud Storage.

Utilizza il flag --async per impedire a gcloud di attendere il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di un'operazione. L'operazione non verrà annullata.

Imposta il flag --database sul nome del database in cui vuoi importare tutte le entità. Per il database predefinito, utilizza --database='(default)'.

rest

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • project-id: il tuo ID progetto
  • bucket-name: il nome del tuo bucket Cloud Storage
  • object-name: il nome dell'oggetto Cloud Storage (ad esempio: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)

Metodo HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:import

Corpo JSON della richiesta: 

{
  "inputUrl": "gs://bucket-name/object-name",
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi verificare il completamento.

Individuazione del file overall_export_metadata

Puoi determinare il valore da utilizzare per la località di importazione utilizzando il browser Cloud Storage nella console Google Cloud :

Apri il browser Cloud Storage

Puoi anche elencare e descrivere le operazioni completate. Il campo outputURL mostra il nome del file overall_export_metadata:

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Importazione di tipi o spazi dei nomi specifici

Per importare un sottoinsieme specifico di tipi e/o spazi dei nomi, fornisci un filtro entità con valori per i tipi e gli ID spazio dei nomi.

Puoi specificare i tipi e gli spazi dei nomi solo se i file di esportazione sono stati creati con un filtro entità. Non puoi importare un sottoinsieme di tipi e spazi dei nomi da un'esportazione di tutte le entità.

Console

Nella console puoi selezionare tutti i tipi o un tipo specifico. Analogamente, puoi selezionare tutti gli spazi dei nomi o uno spazio dei nomi specifico.

Per specificare un elenco di spazi dei nomi e tipi da importare, utilizza invece gcloud.

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Fai clic su Importa.

  5. Nel campo File, fai clic su Sfoglia e seleziona un file .overall_export_metadata.

    Assicurati di importare il file .overall_export_metadata e non un file .export_metadata.

  6. Imposta il campo Spazio dei nomi su All Namespaces o su uno spazio dei nomi specifico.

  7. Imposta il campo Tipo su All Kinds o su un tipo specifico.

  8. Fai clic su Importa.

La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di importazione gestita.

gcloud

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

dove bucket-name/file-path/file-name è il percorso del file overall_export_metadata all'interno del bucket Cloud Storage.

Utilizza il flag --async per impedire a gcloud di attendere il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di un'operazione. L'operazione non verrà annullata.

Imposta il flag --database sul nome del database in cui vuoi importare i tipi o gli spazi dei nomi specifici. Per il database predefinito, utilizza --database='(default)'.

rest

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • project-id: il tuo ID progetto
  • bucket-name: il nome del tuo bucket Cloud Storage
  • object-name: il nome dell'oggetto Cloud Storage (ad esempio: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata
  • kind: il tipo di entità
  • namespace: l'ID dello spazio dei nomi (utilizza "" per l'ID dello spazio dei nomi predefinito)

Metodo HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:import

Corpo JSON della richiesta: 

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi verificare il completamento.

Esporta e importa dai dati PITR

Puoi esportare il database in Cloud Storage dai dati PITR. Puoi esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero compreso negli ultimi sette giorni, ma non prima del giorno earliestVersionTime. Se i dati non esistono più nel timestamp specificato, l'operazione di esportazione non va a buon fine.

L'operazione di esportazione PITR supporta tutti i filtri, inclusa l'esportazione di tutti i documenti e di raccolte specifiche.

Tieni presente quanto segue prima di esportare i dati PITR:

  • Abilita il PITR nel tuo database. Se il PITR è disabilitato, l'esportazione in un timestamp dello snapshot non va a buon fine, anche per i timestamp nell'ultima ora dopo earliestVersionTime. L'operazione di esportazione restituisce l'errore Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp.
  • Specifica il timestamp nel formato RFC 3339. Ad esempio, 2023-05-26T10:20:00.00Z.
  • Assicurati che il timestamp specificato sia un timestamp di un minuto intero negli ultimi sette giorni, ma non prima del earliestVersionTime. Se i dati non esistono più nel timestamp specificato, viene generato un errore.
  • Non ti verrà addebitato alcun costo per un'esportazione PITR non riuscita.

Console

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database
  2. Seleziona un database dall'elenco dei database.
  3. Nel menu di navigazione, fai clic su Importa/Esporta.
  4. Fai clic su Esporta.
  5. Scegli uno spazio dei nomi da esportare
  6. Seleziona i tipi da esportare.

  7. Nella sezione Scegli lo stato del database da esportare, seleziona Esporta da un momento precedente.

    Seleziona un'ora dello snapshot da utilizzare per l'esportazione

  8. Nella sezione Destinazione, inserisci il nome di un bucket Cloud Storage o utilizza il pulsante Sfoglia per selezionare un bucket.

  9. Fai clic su Esporta.

    La console torna alla pagina Importa/Esporta. Se l'operazione viene avviata correttamente, la pagina aggiunge una voce alla pagina delle importazioni e delle esportazioni recenti. In caso di errore, la pagina mostra un messaggio di errore.

gcloud

Puoi esportare il database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export. L'operazione di esportazione PITR supporta tutti i filtri, inclusa l'esportazione di tutte le entità e l'esportazione di tipi o spazi dei nomi specifici.

Esporta il database, specificando il parametro snapshot-time su un timestamp di recupero. Esegui questo comando per esportare il database nel tuo bucket.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
          --snapshot-time=[PITR_TIMESTAMP] \
          --collection-ids=[COLLECTION_IDS] \
          --namespace-ids=[NAMESPACE_IDS]

Dove PITR_TIMESTAMP è un timestamp PITR con granularità al minuto, ad esempio 2023-05-26T10:20:00.00Z.

Importa trasformazioni

Quando importi entità da un altro progetto, tieni presente che le chiavi delle entità includono l'ID progetto. Un'operazione di importazione aggiorna le chiavi delle entità e le proprietà di riferimento delle chiavi nei dati di importazione con l'ID progetto del progetto di destinazione. Se questo aggiornamento aumenta le dimensioni delle entità, può causare errori "entità troppo grande" o "voci dell'indice troppo grandi" per le operazioni di importazione.

Per evitare entrambi gli errori, importa in un progetto di destinazione con un ID progetto più breve. Ciò non influisce sulle operazioni di importazione con dati dello stesso progetto.

Gestione di operazioni a lunga esecuzione

Le operazioni di importazione ed esportazione gestite sono operazioni a lunga esecuzione. Il completamento di queste chiamate ai metodi può richiedere molto tempo.

Dopo aver avviato un'operazione di esportazione o importazione, la modalità Datastore assegna all'operazione un nome univoco. Puoi utilizzare il nome dell'operazione per eliminarla, annullarla o verificarne lo stato.

I nomi delle operazioni sono preceduti dal prefisso projects/[PROJECT_ID]/databases/(default)/operations/, ad esempio:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Puoi omettere il prefisso quando specifichi un nome di operazione per i comandi gcloud.

Elenco di tutte le operazioni a lunga esecuzione

Puoi visualizzare le operazioni in corso e quelle completate di recente nei seguenti modi. Le operazioni vengono elencate per alcuni giorni dopo il completamento:

Console

Puoi visualizzare un elenco delle operazioni a lunga esecuzione nella pagina Importa/Esporta della console Google Cloud .

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

gcloud

Per elencare le operazioni a lunga esecuzione, utilizza il comando gcloud datastore operations list. 

gcloud datastore operations list

Ad esempio, un'operazione di esportazione completata di recente mostra le seguenti informazioni:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

rest

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • project-id: il tuo ID progetto

Metodo HTTP e URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Per inviare la richiesta, espandi una di queste opzioni:

Consulta le informazioni sulla risposta di seguito.

Ad esempio, un'operazione di esportazione completata di recente mostra le seguenti informazioni:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Controlla lo stato dell'operazione

Per visualizzare lo stato di un'operazione a lunga esecuzione:

Console

Puoi visualizzare un elenco delle operazioni di esportazione e importazione più recenti nella pagina Importa/Esporta della console Google Cloud .

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

gcloud

Utilizza il comando operations describe per visualizzare lo stato di un'operazione a lunga esecuzione.

gcloud datastore operations describe operation-name

rest

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • project-id: il tuo ID progetto
  • operation-name: il nome dell'operazione

Metodo HTTP e URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

Stima del tempo di completamento

Durante l'esecuzione dell'operazione, controlla il valore del campo state per lo stato complessivo dell'operazione.

Una richiesta per lo stato di un'operazione a lunga esecuzione restituisce le metriche workEstimated e workCompleted. Ognuna di queste metriche viene restituita sia in numero di byte sia in numero di entità:

  • workEstimated mostra il numero totale stimato di byte e documenti che un'operazione elaborerà. La modalità Datastore potrebbe omettere questa metrica se non può effettuare una stima.

  • workCompleted mostra il numero di byte e documenti elaborati finora. Al termine dell'operazione, il valore mostra il numero totale di byte e documenti effettivamente elaborati, che potrebbe essere maggiore del valore di workEstimated.

Dividi workCompleted per workEstimated per una stima approssimativa dell'avanzamento. Questa stima potrebbe non essere precisa, perché dipende dalla raccolta ritardata delle statistiche.

Ad esempio, ecco lo stato di avanzamento di un'operazione di esportazione:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

Al termine di un'operazione, la descrizione dell'operazione contiene "done": true. Controlla il valore del campo state per il risultato dell'operazione. Se il campo done non è impostato nella risposta, il suo valore è false. Non fare affidamento sull'esistenza del valore done per le operazioni in corso.

Annulla un'operazione

Console

Puoi annullare un'operazione di esportazione o importazione in esecuzione nella pagina Importa/Esporta della console Google Cloud .

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

Nella tabella Importazioni ed esportazioni recenti, le operazioni attualmente in esecuzione includono un pulsante Annulla nella colonna Completata. Fai clic sul pulsante Annulla per interrompere l'operazione. Il pulsante cambia in un messaggio Annullamento in corso e poi in Annullato quando l'operazione si interrompe completamente.

gcloud

Utilizza il comando operations cancel per interrompere un'operazione in corso:

gcloud datastore operations cancel operation-name

L'annullamento di un'operazione in esecuzione non annulla l'operazione. Un'operazione di esportazione annullata lascia i documenti già esportati in Cloud Storage, mentre un'operazione di importazione annullata lascia invariati gli aggiornamenti già apportati al database. Non puoi importare un'esportazione completata parzialmente.

Elimina un'operazione

gcloud

Utilizza il comando operations delete per rimuovere un'operazione dall'elenco delle operazioni recenti. Questo comando non eliminerà i file di esportazione da Cloud Storage.

gcloud datastore operations delete operation-name

Fatturazione e prezzi per esportazioni e importazioni gestite

Devi abilitare la fatturazione per il tuo progetto Google Cloud prima di utilizzare il servizio di esportazione e importazione gestito. Le operazioni di esportazione e importazione contribuiscono ai costi di Google Cloud nei seguenti modi:

  • Le letture e le scritture di entità eseguite dalle operazioni di esportazione e importazione vengono conteggiate ai fini dei costi di Firestore in modalità Datastore. Le operazioni di esportazione comportano un'operazione di lettura per entità esportata. Le operazioni di importazione comportano un'operazione di scrittura per ogni entità importata.
  • I file di output archiviati in Cloud Storage vengono conteggiati ai fini dei costi di archiviazione dei dati di Cloud Storage.

Le operazioni di esportazione o importazione non attiveranno alcun avviso relativo al budgetGoogle Cloud fino al completamento. Analogamente, le letture e le scritture eseguite durante un'operazione di esportazione o importazione vengono applicate alla tua quota giornaliera al termine dell'operazione.

Visualizzazione dei costi di esportazione e importazione

Le operazioni di esportazione e importazione applicano l'etichetta goog-firestoremanaged:exportimport alle operazioni fatturate. Nella pagina dei report sulla fatturazione Cloud, puoi utilizzare questa etichetta per visualizzare i costi relativi alle operazioni di importazione ed esportazione:

Accedi all'etichetta goog-firestoremanaged dal menu dei filtri.

Differenze rispetto ai backup di Datastore Admin

Se in precedenza hai utilizzato la console di amministrazione di Datastore per i backup, tieni presente le seguenti differenze:

  • Le esportazioni create da un'esportazione gestita non vengono visualizzate nella console di amministrazione di Datastore. Le esportazioni e le importazioni gestite sono un nuovo servizio che non condivide i dati con la funzionalità di backup e ripristino di App Engine, che viene amministrata tramite la console Google Cloud .

  • Il servizio di esportazione e importazione gestito non supporta gli stessi metadati del backup di Datastore Admin e non archivia lo stato di avanzamento nel database. Per informazioni su come controllare l'avanzamento delle operazioni di esportazione e importazione, consulta Gestione delle operazioni a lunga esecuzione.

  • Non puoi visualizzare i log del servizio delle operazioni di esportazione e importazione gestite.

  • Il servizio di importazione gestito è compatibile con le versioni precedenti dei file di backup di Datastore Admin. Puoi importare un file di backup di Datastore Admin utilizzando il servizio di importazione gestito, ma non puoi importare l'output di un'esportazione gestita utilizzando la console di Datastore Admin.

Importazione in BigQuery

Per importare i dati da un'esportazione gestita in BigQuery, consulta Caricamento dei dati del servizio di esportazione di Datastore.

I dati esportati senza specificare un filtro entità non possono essere caricati in BigQuery. Se vuoi importare dati in BigQuery, la richiesta di esportazione deve includere uno o più nomi di tipo nel filtro delle entità.

Limite di colonne BigQuery

BigQuery impone un limite di 10.000 colonne per tabella. Le operazioni di esportazione generano uno schema di tabella BigQuery per ogni tipo. In questo schema, ogni proprietà univoca all'interno delle entità di un tipo diventa una colonna dello schema.

Se lo schema BigQuery di un tipo supera le 10.000 colonne, l'operazione di esportazione tenta di rimanere al di sotto del limite di colonne trattando le entità incorporate come blob. Se questa conversione porta il numero di colonne nello schema a meno di 10.000, puoi caricare i dati in BigQuery, ma non puoi eseguire query sulle proprietà all'interno delle entità incorporate. Se il numero di colonne supera ancora 10.000, l'operazione di esportazione non genera uno schema BigQuery per il tipo e non puoi caricare i relativi dati in BigQuery.

Migrazione degli agenti di servizio

Firestore utilizza un agente di servizio Firestore per autorizzare le operazioni di importazione ed esportazione anziché utilizzare l'account di servizio App Engine. L'agente di servizio e l'account di servizio utilizzano le seguenti convenzioni di denominazione:

Service agent Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

In precedenza, Firestore utilizzava l'account di servizio predefinito di App Engine anziché l'agente di servizio Firestore. Se il tuo database utilizza ancora l'account di servizio App Engine per importare o esportare dati, ti consigliamo di seguire le istruzioni riportate in questa sezione per eseguire la migrazione all'utilizzo dell'agente di servizio Firestore.

Service account App Engine
PROJECT_ID@appspot.gserviceaccount.com

L'agente di servizio Firestore è preferibile perché è specifico per Firestore. Il account di servizio App Engine è condiviso da più servizi.

Visualizza l'account di autorizzazione

Puoi visualizzare l'account utilizzato dalle operazioni di importazione ed esportazione per autorizzare le richieste dalla pagina Importa/Esporta della console Google Cloud . Puoi anche visualizzare se il tuo database utilizza già l'agente di servizio Firestore.

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Visualizza l'account di autorizzazione accanto all'etichetta Esegui job di importazione/esportazione come.

Se il tuo progetto non utilizza l'agente di servizio Firestore, puoi eseguire la migrazione all'agente di servizio Firestore utilizzando una di queste tecniche:

La prima di queste tecniche è preferibile perché localizza l'ambito dell'effetto a un singolo progetto in modalità Datastore. La seconda tecnica non è consigliata perché non esegue la migrazione delle autorizzazioni esistenti del bucket Cloud Storage. Tuttavia, offre la conformità della sicurezza a livello di organizzazione.

Esegui la migrazione controllando e aggiornando le autorizzazioni dei bucket Cloud Storage

Il processo di migrazione prevede due passaggi:

  1. Aggiorna le autorizzazioni del bucket Cloud Storage. Per maggiori dettagli, consulta la sezione seguente.
  2. Conferma la migrazione all'agente di servizio Firestore.

Autorizzazioni del bucket dell'agente di servizio

Per qualsiasi operazione di esportazione o importazione che utilizza un bucket Cloud Storage in un altro progetto, devi concedere le autorizzazioni dell'agente di servizio Firestore per quel bucket. Ad esempio, le operazioni che spostano i dati in un altro progetto devono accedere a un bucket in quel progetto. In caso contrario, queste operazioni non riusciranno dopo la migrazione all'agente di servizio Firestore.

I workflow di importazione ed esportazione che rimangono all'interno dello stesso progetto non richiedono modifiche alle autorizzazioni. Per impostazione predefinita, l'agente di servizio Firestore può accedere ai bucket nello stesso progetto.

Aggiorna le autorizzazioni per i bucket Cloud Storage di altri progetti per concedere l'accesso al service agent service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com. Concedi all'agente di servizio il ruolo Firestore Service Agent.

Il ruolo Firestore Service Agent concede autorizzazioni di lettura e scrittura per un bucket Cloud Storage. Se devi concedere solo autorizzazioni di lettura o solo di scrittura, utilizza un ruolo personalizzato.

Il processo di migrazione descritto nella sezione seguente ti aiuta a identificare i bucket Cloud Storage che potrebbero richiedere aggiornamenti delle autorizzazioni.

Esegui la migrazione di un progetto all'agente di servizio Firestore

Completa i seguenti passaggi per eseguire la migrazione dal account di servizio App Engine all'agente di servizio Firestore. Una volta completata, la migrazione non può essere annullata.

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Se non è ancora stata eseguita la migrazione del progetto all'agente di servizio Firestore, viene visualizzato un banner che descrive la migrazione e un pulsante Controlla stato bucket. Il passaggio successivo ti aiuta a identificare e correggere potenziali errori di autorizzazione.

    Fai clic su Controlla lo stato del bucket.

    Viene visualizzato un menu con l'opzione per completare la migrazione e un elenco di bucket Cloud Storage. Il caricamento dell'elenco potrebbe richiedere alcuni minuti.

    Questo elenco include i bucket che sono stati utilizzati di recente nelle operazioni di importazione ed esportazione, ma che al momento non concedono autorizzazioni in lettura e autorizzazioni in scrittura all'agente di servizio in modalità Datastore.

  5. Prendi nota del nome dell'entità dell'agente di servizio in modalità Datastore del tuo progetto. Il nome dell'agente di servizio viene visualizzato sotto l'etichetta Agente di servizio a cui concedere l'accesso.

  6. Per qualsiasi bucket nell'elenco che utilizzerai per future operazioni di importazione o esportazione, completa i seguenti passaggi:

    1. Nella riga della tabella di questo bucket, fai clic su Correggi. Si apre la pagina delle autorizzazioni del bucket in una nuova scheda.

    2. Fai clic su Aggiungi.
    3. Nel campo Nuove entità, inserisci il nome dell'agente di servizio Firestore.
    4. Nel campo Seleziona un ruolo, seleziona Agenti di servizio > Agente di servizio Firestore.
    5. Fai clic su Salva.
    6. Torna alla scheda con la pagina Importa/Esporta in modalità Datastore.
    7. Ripeti questi passaggi per gli altri bucket nell'elenco. Assicurati di visualizzare tutte le pagine dell'elenco.

  7. Fai clic su Esegui la migrazione all'agente di servizio Firestore. Se hai ancora bucket con controlli delle autorizzazioni non riusciti, devi confermare la migrazione facendo clic su Esegui migrazione.

    Un avviso ti informa quando la migrazione è completata. La migrazione non può essere annullata.

Visualizza lo stato della migrazione

Per verificare lo stato della migrazione del progetto:

  1. Nella console Google Cloud , vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Importa/Esporta.

  4. Cerca l'entità accanto all'etichetta Job di importazione/esportazione eseguiti come.

    Se l'entità è service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, la migrazione del progetto all'agente di servizio Firestore è già stata eseguita. La migrazione non può essere annullata.

    Se non è stata eseguita la migrazione del progetto, nella parte superiore della pagina viene visualizzato un banner con il pulsante Controlla stato bucket. Consulta Esegui la migrazione all'agente di servizio Firestore per completare la migrazione.

Aggiungi un vincolo delle policy a livello di organizzazione

  • Imposta il seguente vincolo nella policy della tua organizzazione:

    Richiedi l'agente di servizio Firestore per l'importazione/esportazione (firestore.requireP4SAforImportExport).

    Questo vincolo richiede che le operazioni di importazione ed esportazione utilizzino l'agente di servizio Firestore per autorizzare le richieste. Per impostare questo vincolo, consulta Creazione e gestione delle policy dell'organizzazione.

L'applicazione di questo vincolo della policy dell'organizzazione non concede automaticamente le autorizzazioni appropriate per i bucket Cloud Storage all'agente di servizio Firestore.

Se il vincolo genera errori di autorizzazione per i workflow di importazione o esportazione, puoi disattivarlo per tornare a utilizzare il account di servizio predefinito. Dopo aver controllato e aggiornato le autorizzazioni dei bucket Cloud Storage, puoi riattivare il vincolo.