Esportare e importare i dati

Puoi utilizzare il servizio di esportazione e importazione gestito Cloud Firestore per recuperare i dati dall'eliminazione accidentale ed esportarli per l'elaborazione offline. Puoi esportare tutti i documenti o solo raccolte specifiche. Allo stesso modo, puoi importare tutti i dati di un'esportazione o solo raccolte specifiche. I dati esportati da un database Cloud Firestore possono essere importati in un altro database Cloud Firestore. Puoi anche caricare le esportazioni di Cloud Firestore in BigQuery.

Questa pagina descrive come esportare e importare documenti Cloud Firestore utilizzando il servizio di esportazione e importazione gestito e Cloud Storage. Il servizio di esportazione e importazione gestito Cloud Firestore è disponibile tramite lo strumento a riga di comando gcloud e l'API Cloud Firestore (REST, RPC).

Prima di iniziare

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

1. Abilita la fatturazione per il tuo progetto Google Cloud. Solo i progetti Google Cloud con la fatturazione abilitata possono utilizzare la funzionalità di esportazione e importazione.
2. Crea un bucket Cloud Storage per il tuo progetto in una località vicina alla posizione del tuo database Cloud Firestore. Non puoi utilizzare un bucket Requester Pays per le operazioni di esportazione e importazione.

3. Assicurati che il tuo account disponga delle autorizzazioni necessarie per Cloud Firestore e Cloud Storage. Se sei il proprietario del progetto, il tuo account dispone delle autorizzazioni richieste. In caso contrario, i seguenti ruoli concedono le autorizzazioni necessarie per le operazioni di esportazione e importazione e per l'accesso a Cloud Storage:

   • Ruoli Cloud Firestore: Owner, Cloud Datastore Owner o Cloud Datastore Import Export Admin

   • Ruoli Cloud Storage: Owner o Storage Admin

Autorizzazioni agente di servizio

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

Agente di servizio di Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Per scoprire di più sugli agenti di servizio, consulta la sezione Agenti di servizio.

L'agente di servizio Cloud Firestore richiede l'accesso al bucket Cloud Storage utilizzato in un'operazione di esportazione o importazione. Se il bucket Cloud Storage si trova nello stesso progetto del database Cloud Firestore, l'agente di servizio Cloud 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 Cloud Firestore l'accesso al bucket Cloud Storage.

Assegnare 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 spazio di archiviazione all'agente di servizio Cloud 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 tuo progetto, che viene utilizzato per denominare l'agente di servizio Cloud Firestore. Per visualizzare il nome dell'agente di servizio, vedi Visualizzare il nome dell'agente di servizio.

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

Visualizzare 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 verificare se il tuo database utilizza l'agente di servizio Cloud Firestore o il service account legacy App Engine.

1. Visualizza l'account di autorizzazione accanto all'etichetta I job di importazione/esportazione vengono eseguiti come.

L'agente di servizio deve disporre del ruolo Storage Admin per il bucket Cloud Storage da utilizzare per l'operazione di esportazione o importazione.

Configura gcloud per il tuo progetto

Puoi avviare le operazioni di importazione ed esportazione tramite la console Google Cloud o lo strumento a riga di comando gcloud. Per utilizzare gcloud, configura lo strumento a riga di comando e connettiti al tuo progetto in uno dei seguenti modi:

• Accedi a gcloud dalla console Google Cloud utilizzando Cloud Shell.

  Avvia Cloud Shell

  Assicurati che gcloud sia configurato per il progetto corretto:

  gcloud config set project [PROJECT_ID]
  

• Installa e inizializza Google Cloud SDK.

Esporta i dati

Un'operazione di esportazione copia i documenti nel database in un insieme di file in un bucket Cloud Storage. Tieni presente che un'esportazione non è uno snapshot esatto del database acquisito all'ora di inizio dell'esportazione. Un'esportazione può includere le modifiche apportate durante l'esecuzione dell'operazione.

Esportare tutti i documenti

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Esportare raccolte specifiche

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Esportare da un timestamp 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 negli ultimi sette giorni, ma non prima del giorno earliestVersionTime. Se i dati non esistono più al 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:

• 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 precedente al earliestVersionTime. Se i dati non esistono più al timestamp specificato, viene generato un errore.
• L'esportazione PITR non riuscita non comporta alcun addebito.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Importa dati

Una volta che hai i file di esportazione in Cloud Storage, puoi importare i documenti in questi file di nuovo nel tuo progetto o in un altro progetto. Tieni presente quanto segue in merito alle operazioni di importazione:

• Quando importi i dati, gli indici richiesti vengono aggiornati utilizzando le definizioni correnti degli indici del database. Un'esportazione non contiene definizioni di indice.

• Le importazioni non assegnano nuovi ID documento. Le importazioni utilizzano gli ID acquisiti al momento dell'esportazione. Durante l'importazione di un documento, il relativo ID viene riservato per evitare conflitti di ID. Se esiste già un documento con lo stesso ID, l'importazione sovrascrive il documento esistente.

• Se un documento nel tuo database non è interessato da un'importazione, rimarrà nel database dopo l'importazione.

• Le operazioni di importazione non attivano Cloud Functions. I listener snapshot ricevono aggiornamenti relativi alle operazioni di importazione.

• Il nome del 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 lo stesso nome per i file PARENT_FOLDER_NAME e .overall_export_metadata.

Importare tutti i documenti da un'esportazione

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Importare raccolte specifiche

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

Importare un'esportazione PITR

Segui i passaggi descritti in Importare tutti i documenti per importare il database esportato. Se nel database esiste già un documento, questo verrà sovrascritto.

Gestione delle operazioni di esportazione e importazione

Dopo aver avviato un'operazione di esportazione o importazione, Cloud Firestore assegna all'operazione un nome univoco. Puoi utilizzare il nome dell'operazione per eliminarla, annullarla o controllarne lo stato.

I nomi delle operazioni hanno il prefisso projects/[PROJECT_ID]/databases/(default)/operations/, ad esempio:

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

Tuttavia, puoi omettere il prefisso quando specifichi un nome di operazione per i comandi describe, cancel e delete.

Elenco di tutte le operazioni di esportazione e importazione

gcloud firestore operations list

Controlla lo stato dell'operazione

gcloud firestore operations describe [OPERATION_NAME]

Stima il tempo di completamento

Una richiesta dello stato di un'operazione a lunga esecuzione restituisce le metriche workEstimated e workCompleted. Ciascuna 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à. Cloud Firestore potrebbe omettere questa metrica se non è in grado di fare 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 superiore al valore di workEstimated.

Dividi workCompleted per workEstimated per una stima approssimativa dei progressi. Questa stima potrebbe non essere precisa perché dipende dalla raccolta ritardata delle statistiche.

Annullare un'operazione

gcloud firestore operations cancel [OPERATION_NAME]

L'annullamento di un'operazione in esecuzione non la annulla. Un'operazione di esportazione annullata lascerà i documenti già esportati in Cloud Storage e un'operazione di importazione annullata lascerà inalterati gli aggiornamenti già apportati al database. Non puoi importare un'esportazione completata parzialmente.

Elimina un'operazione

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

gcloud firestore operations delete [OPERATION_NAME]

Fatturazione e prezzi per le operazioni di esportazione e importazione

Devi attivare la fatturazione per il tuo progetto Google Cloud prima di utilizzare il servizio di importazione ed esportazione gestito.

Le operazioni di esportazione e importazione vengono addebitate per letture e scritture dei documenti alle tariffe indicate nei prezzi di Cloud Firestore. Le operazioni di esportazione comportano un'operazione di lettura per ogni documento esportato. Le operazioni di importazione comportano un'operazione di scrittura per ogni documento importato.

I file di output archiviati in Cloud Storage vengono conteggiati ai fini dei Cloud Storage costi di archiviazione dei dati.

Le operazioni di esportazione o importazione non attiveranno gli avvisi relativi al budget Google Cloud fino al completamento. Le operazioni di esportazione e importazione non influiranno sull'utilizzo mostrato nella sezione Utilizzo della console.

Visualizzare i costi di esportazione e importazione

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

Esporta in BigQuery

Puoi caricare i dati da un'esportazione Cloud Firestore in BigQuery, ma solo se hai specificato un filtro collection-ids. Consulta Caricamento dei dati dalle esportazioni di Cloud Firestore.

Limite di BigQuery colonne

BigQuery impone un limite di 10.000 colonne per tabella. Le operazioni di esportazione Cloud Firestore generano uno schema di tabella BigQuery per ogni gruppo di raccolte. In questo schema, ogni nome di campo univoco all'interno di ungruppo di raccoltea diventa una colonna dello schema.

Se lo schema BigQuery di un gruppo di raccolte supera le 10.000 colonne, l'operazione di esportazione Cloud Firestore tenta di rimanere al di sotto del limite di colonne trattando i campi della mappa come byte. Se questa conversione porta il numero di colonne al di sotto di 10.000, puoi caricare i dati in BigQuery, ma non puoi eseguire query sui sottocampi all'interno dei campi della mappa. Se il numero di colonne supera ancora 10.000, l'operazione di esportazione non genera uno schema BigQuery per il gruppo di raccolta e non puoi caricare i relativi dati in BigQuery.

Esportare file di formato e metadati

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

File di metadati

Un'operazione di esportazione crea un file di metadati per ogni gruppo di raccolte che specifichi. I file di metadati in genere vengono denominati ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

I file di metadati sono buffer di protocollo e puoi decodificarli con il compilatore di protocolli protoc. Ad esempio, puoi decodificare un file di metadati per determinare i gruppi di raccolte contenuti nei file di esportazione:

protoc --decode_raw < export0.export_metadata

Migrazione dell'agente di servizio

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

Agente di servizio di Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore in precedenza utilizzava il service account predefinito App Engine anziché l'agente di servizio Cloud 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 Cloud Firestore.

App Engine service account

PROJECT_ID@appspot.gserviceaccount.com

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

Visualizza account di autorizzazione

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 verificare se il tuo database utilizza già l'agente di servizio Cloud Firestore.

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

   Vai a Database

2. Seleziona il database richiesto dall'elenco.

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

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

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

• Eseguire la migrazione di un progetto controllando e aggiornando le autorizzazioni del bucket Cloud Storage (scelta consigliata).
• Aggiungi un vincolo di policy a livello di organizzazione che influisce su tutti i progetti all'interno dell'organizzazione.

La prima di queste tecniche è preferibile perché limita l'ambito di effetto a un singolo progetto Cloud Firestore. La seconda tecnica non è preferibile perché non esegue la migrazione delle autorizzazioni del bucket Cloud Storage esistente. Tuttavia, offre la conformità alla sicurezza a livello di organizzazione.

Eseguire la migrazione controllando e aggiornando le autorizzazioni del bucket Cloud Storage

La procedura 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 Cloud 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 all'agente di servizio Cloud Firestore le autorizzazioni per quel bucket. Ad esempio, le operazioni che spostano i dati in un altro progetto devono accedere a un bucket in quell'altro progetto. In caso contrario, queste operazioni non vanno a buon fine dopo la migrazione all'agente del servizio Cloud Firestore.

I flussi di lavoro di importazione ed esportazione che rimangono all'interno dello stesso progetto non richiedono modifiche alle autorizzazioni. L'agente di servizio Cloud Firestore può accedere ai bucket nello stesso progetto per impostazione predefinita.

Aggiorna le autorizzazioni per i bucket Cloud Storage di altri progetti per concedere l'accesso all'agente di servizio 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 le autorizzazioni di lettura e scrittura per un bucket Cloud Storage. Se devi concedere solo autorizzazioni di lettura o scrittura, utilizza un ruolo personalizzato.

La procedura di migrazione descritta 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 dall'account di servizio App Engine all'agente di servizio Cloud 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.

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

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

   Fai clic su Controlla stato bucket.

   Viene visualizzato un menu con l'opzione per completare la migrazione e un elenco di bucket Cloud Storage. Potrebbero essere necessari alcuni minuti prima che l'elenco venga caricato completamente.

   Questo elenco include i bucket utilizzati di recente nelle operazioni di importazione ed esportazione, ma che al momento non concedono autorizzazioni di lettura e scrittura all'agente di servizio Cloud Firestore.

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

6. Per ogni bucket nell'elenco che utilizzerai per le 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 del tuo agente di servizio Cloud Firestore.
   4. Nel campo Seleziona un ruolo, seleziona Service Agents > Firestore Service Agent.
   5. Fai clic su Salva.
   6. Torna alla scheda con la pagina Cloud Firestore Importa/Esporta.
   7. Ripeti questi passaggi per gli altri bucket dell'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 Migra.

   Un avviso ti informa al termine della migrazione. La migrazione non può essere annullata.

Visualizzare 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.

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

4. Cerca il principal accanto all'etichetta I job di importazione/esportazione vengono eseguiti come.

   Se l'entità è service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, il tuo progetto è già stato migrato all'agente di servizio Cloud Firestore. La migrazione non può essere annullata.

   Se il progetto non è stato migrato, nella parte superiore della pagina viene visualizzato un banner con un pulsante Controlla stato bucket. Per completare la migrazione, vedi Eseguire la migrazione all'agente di servizio Firestore.

Aggiungere un vincolo dei criteri a livello di organizzazione

• Imposta il seguente vincolo nelle norme della tua organizzazione:

  Richiede 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 Cloud Firestore per autorizzare le richieste. Per impostare questo vincolo, consulta Creazione e gestione delle policy dell'organizzazione .

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

Se il vincolo crea errori di autorizzazione per qualsiasi flusso di lavoro di importazione o esportazione, puoi disattivarlo per tornare a utilizzare l'account di servizio predefinito. Dopo aver controllato e aggiornato le autorizzazioni del bucket Cloud Storage, puoi riattivare il vincolo.