Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Esportazione e importazione di dati

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

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

Prima di iniziare

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

  1. Abilita la fatturazione per il tuo progetto Google Cloud. Solo i progetti Google Cloud con 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 tua località del database Firestore. Non puoi utilizzare un bucket per i pagamenti a carico del richiedente per le operazioni di esportazione e importazione.
  3. Assicurati che il tuo account disponga delle autorizzazioni necessarie per Firestore e Cloud Storage. Se sei il proprietario del progetto, il tuo account ha le autorizzazioni necessarie. 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 di archivio: Owner, Cloud Datastore Owner o Cloud Datastore Import Export Admin
    • Ruoli di Cloud Storage: Owner o Storage Admin

Autorizzazioni predefinite dell'account di servizio

Ogni progetto di Google Cloud crea automaticamente un account di servizio predefinito denominato PROJECT_ID@appspot.gserviceaccount.com. Le operazioni di esportazione e importazione utilizzano questo account di servizio per autorizzare le operazioni di Cloud Storage.

L'account di servizio predefinito del progetto 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'account di servizio predefinito ha accesso al bucket per impostazione predefinita..

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

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

Se disabiliti o elimini il tuo account di servizio predefinito App Engine, l'app App Engine perderà l'accesso al tuo database Firestore. Se hai disabilitato il tuo account di servizio App Engine, puoi abilitarlo di nuovo, consulta Abilitazione di un account di servizio. Se hai eliminato il tuo account di servizio App Engine negli ultimi 30 giorni, puoi ripristinare il tuo account di servizio, consulta la sezione Annullare l'eliminazione di un account di servizio.

Configura gcloud per il tuo progetto

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

Esportare i dati

Un'operazione di esportazione copia i documenti nel database in una serie di file in un bucket Cloud Storage. Tieni presente che un'esportazione non è un'istantanea del database acquisita al momento dell'avvio dell'esportazione. Un'esportazione può includere le modifiche apportate durante l'esecuzione dell'operazione.

Esportazione di tutti i documenti

Console Google Cloud

  1. Vai alla pagina Importazione/esportazione in Firestore in Google Cloud Console.

    Vai alla pagina Importa/Esporta

  2. Fai clic su Esporta.

  3. Fai clic sull'opzione Esporta l'intero database.

  4. Sotto Scegli la destinazione, inserisci il nome di un bucket Cloud Storage o utilizza il pulsante Sfoglia per selezionare un bucket.

  5. Fai clic su Esporta.

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

gcloud

Utilizza il comando firestore export per esportare tutti i documenti nel database, sostituendo [BUCKET_NAME] con il nome del bucket Cloud Storage. Aggiungi il flag --async per impedire allo strumento gcloud di attendere il completamento dell'operazione.

gcloud firestore export gs://[BUCKET_NAME]

Puoi organizzare le esportazioni aggiungendo un prefisso di file dopo il nome del bucket, ad esempio BUCKET_NAME/my-exports-folder/export-name. Se non specifichi un prefisso del file, il servizio di esportazione gestito ne crea uno in base al timestamp corrente.

Una volta avviata un'operazione di esportazione, la chiusura del terminale non comporta l'annullamento dell'operazione, consulta Annullamento di un'operazione.

Esportare raccolte specifiche

Console Google Cloud

  1. Vai alla pagina Importazione/esportazione in Firestore in Google Cloud Console.

    Vai alla pagina Importa/Esporta

  2. Fai clic su Esporta.

  3. Fai clic sull'opzione Esporta uno o più gruppi di raccolte. Utilizza il menu a discesa per selezionare uno o più gruppi di raccolte.

  4. Sotto Scegli la destinazione, inserisci il nome di un bucket Cloud Storage o utilizza il pulsante Sfoglia per selezionare un bucket.

  5. Fai clic su Esporta.

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

gcloud

Per esportare gruppi di raccolte specifici, utilizza il flag --collection-ids. L'operazione esporta solo i gruppi di raccolte con gli ID raccolta specificati. Il gruppo di raccolte include tutte le raccolte e le sottoraccolte (in qualsiasi percorso) con l'ID raccolta specificato.

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

Importazione dei dati

Dopo aver esportato i file in Cloud Storage, puoi importare i documenti in tali file nel tuo progetto o in un altro progetto. Tieni presenti i seguenti punti sulle operazioni di importazione:

  • Quando importi i dati, gli indici obbligatori vengono aggiornati utilizzando le definizioni dell'indice corrente 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 è 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 database non è interessato da un'importazione, rimarrà nel database dopo l'importazione.

  • Le operazioni di importazione non attivano Cloud Functions. Gli ascoltatori di 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 invariati i nomi dei file PARENT_FOLDER_NAME e .overall_export_metadata.

Importare tutti i documenti da un'esportazione

Console Google Cloud

  1. Vai alla pagina Importazione/esportazione in Firestore in Google Cloud Console.

    Vai alla pagina Importa/Esporta

  2. Fai clic su Import (Importa).

  3. Nel campo Nome file, inserisci il nome file di un file .overall_export_metadata proveniente da un'operazione di esportazione completata. Puoi utilizzare il pulsante Sfoglia per selezionare il file.

  4. Fai clic su Import (Importa).

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

gcloud

Utilizza il comando firestore import per importare documenti da un'operazione di esportazione precedente.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

dove [BUCKET_NAME] e [EXPORT_PREFIX] rimandano alla posizione dei file di esportazione. Ad esempio:

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

Puoi confermare la posizione dei tuoi file di esportazione nel browser Cloud Storage in Google Cloud Console:

Apri il browser Cloud Storage

Una volta avviata un'operazione di importazione, la chiusura del terminale non comporta l'annullamento dell'operazione, consulta Annullamento di un'operazione.

Importa raccolte specifiche

Console Google Cloud

Non puoi selezionare raccolte specifiche nella console. Usa invece il criterio gcloud.

gcloud

Per importare gruppi di raccolte specifici da un insieme di file di esportazione, utilizza il flag --collection-ids. L'operazione importa solo i gruppi di raccolte con gli ID raccolta specificati. Il gruppo di raccolte include tutte le raccolte e le sottoraccolte (in qualsiasi percorso) con l'ID raccolta specificato.

Solo un'esportazione di gruppi di raccolta specifici supporta un'importazione di gruppi di raccolta specifici. Non puoi importare raccolte specifiche da un'esportazione di tutti i documenti.

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

Gestione delle operazioni di esportazione e importazione

Dopo aver avviato un'operazione di esportazione o importazione, Firestore assegna all'operazione un nome univoco. Puoi utilizzare il nome dell'operazione per eliminare, annullare o controllare lo stato.

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

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

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

Elenca tutte le operazioni di esportazione e importazione

Console Google Cloud

Puoi visualizzare un elenco di operazioni recenti di esportazione e importazione nella pagina Importazione/esportazione in Firestore di Google Cloud Console.

Vai alla pagina Importa/Esporta

gcloud

Utilizza il comando operations list per visualizzare tutte le operazioni di esportazione e importazione in esecuzione e completate di recente:

gcloud firestore operations list

Controlla lo stato dell'operazione

Console Google Cloud

Puoi visualizzare lo stato di un'operazione di esportazione o importazione recente nella pagina Importazione/esportazione di Firestore di Google Cloud Console.

Vai alla pagina Importa/Esporta

gcloud

Utilizza il comando operations describe per mostrare lo stato di un'operazione di esportazione o importazione.

gcloud firestore operations describe [OPERATION_NAME]

Stima il tempo di completamento

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 elaborati da un'operazione. Firestore potrebbe omettere questa metrica se non è in grado di fare una stima.

  • workCompleted mostra il numero di byte e documenti elaborati finora. Una volta completata l'operazione, il valore mostra il numero totale di byte e documenti effettivamente elaborati, che potrebbero essere maggiori del valore di workEstimated.

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

Annullare un'operazione

Console Google Cloud

Puoi annullare un'operazione di esportazione o importazione in corso nella pagina Importazione/esportazione di Firestore di Google Cloud Console.

Vai alla pagina Importa/Esporta

Nella tabella Importazioni ed esportazioni recenti, le operazioni attualmente in esecuzione includono un pulsante Annulla nella colonna Completate. Fai clic sul pulsante Annulla per interrompere l'operazione. Il pulsante diventa il messaggio Annullamento, quindi Annullato al termine dell'operazione.

gcloud

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

gcloud firestore operations cancel [OPERATION_NAME]

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

Elimina un'operazione

Per rimuovere un'operazione dall'elenco delle operazioni recenti, utilizza il comando gcloud firestore operations delete. 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 abilitare la fatturazione per il tuo progetto Google Cloud prima di utilizzare il servizio gestito di esportazione e importazione. Le operazioni di esportazione e importazione vengono addebitate per letture e scritture dei documenti alle tariffe elencate nei prezzi di Firestore.

I costi di esportazione e importazione non vengono conteggiati ai fini del limite di spesa. Le operazioni di esportazione o importazione non attiveranno gli avvisi di budget di Google Cloud fino al completamento. Allo stesso modo, le letture e le scritture eseguite durante un'operazione di esportazione o importazione vengono applicate alla quota giornaliera dopo il completamento dell'operazione. Le operazioni di esportazione e importazione non incideranno sull'utilizzo mostrato nella sezione relativa all'utilizzo della console.

Visualizzazione dei costi di esportazione e importazione

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

Accedi all'etichetta goog-firestoremanaged dal menu filtri.

Esporta in BigQuery

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

Limite di colonne BigQuery

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

Se lo schema BigQuery di un gruppo di raccolte supera le 10.000 colonne, l'operazione di esportazione di Firestore tenta di rimanere al di sotto del limite delle colonne trattando i campi della mappa come byte. Se questa conversione porta un numero di colonne inferiore a 10.000, puoi caricare i dati in BigQuery, ma non puoi eseguire query nei 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 raccolte e non è possibile caricare i relativi dati in BigQuery.

Esportare formati e file di metadati

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

File di metadati

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

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

protoc --decode_raw < export0.export_metadata

Migrazione dell'agente di servizio

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

Agente di servizio Firestore
service-project_number@gcp-sa-firestore.iam.gserviceaccount.com
Account di servizio App Engine
project_id@appspot.gserviceaccount.com

L'agente di servizio Firestore è preferibile perché è specifico per 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 di Google Cloud Console. Puoi anche verificare se il tuo database utilizza già l'agente di servizio Firestore.

  1. Vai alla pagina Importazione/esportazione in Firestore in Google Cloud Console.

    Vai a Importa/Esporta

  2. 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 Firestore, puoi eseguire la migrazione all'agente di servizio Firestore utilizzando una delle seguenti tecniche:

È preferibile utilizzare la prima tecnica, in quanto localizza l'ambito di applicazione a un singolo progetto Firestore. La seconda tecnica non è consigliata perché non esegue la migrazione delle autorizzazioni dei bucket Cloud Storage esistenti. offre tuttavia la sicurezza a livello di organizzazione.

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

La procedura di migrazione è composta da due passaggi:

  1. Aggiorna le autorizzazioni dei bucket di Cloud Storage. Consulta la sezione seguente per i dettagli.
  2. Conferma la migrazione all'agente di servizio Firestore.

Autorizzazioni bucket agente di servizio

Per qualsiasi operazione di esportazione o importazione che utilizza un bucket Cloud Storage in un altro progetto, devi concedere le autorizzazioni di agente di servizio Firestore per tale bucket. Ad esempio, le operazioni che spostano dati in un altro progetto devono accedere a un bucket di quell'altro progetto. In caso contrario, queste operazioni non riusciranno dopo la migrazione all'agente di servizio 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 Firestore può accedere ai bucket nello stesso progetto per impostazione predefinita.

Aggiorna le autorizzazioni dei bucket Cloud Storage da 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 autorizzazioni di lettura e scrittura per un bucket Cloud Storage. Se devi concedere solo autorizzazioni di lettura o scrittura, utilizza un ruolo personalizzato.

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

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

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

  1. Vai alla pagina Importazione/esportazione in Firestore in Google Cloud Console.

    Vai a Importa/Esporta

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

    Fai clic su Verifica lo stato del bucket.

    Viene visualizzato un menu con l'opzione per completare la migrazione e un elenco di bucket Cloud Storage. Potrebbero occorrere alcuni minuti per completare il caricamento dell'elenco.

    Questo elenco include i bucket utilizzati di recente nelle operazioni di importazione ed esportazione, ma attualmente non forniscono le autorizzazioni di lettura e scrittura all'agente di servizio Firestore.

  3. Prendi nota del nome dell'entità del tuo agente di servizio Firestore del progetto. Il nome dell'agente di servizio viene visualizzato sotto l'etichetta Agente di servizio per concedere l'accesso.
  4. Per qualsiasi bucket nell'elenco che utilizzerai per le operazioni di importazione o esportazione future, completa i seguenti passaggi:

    1. In questa riga della tabella, fai clic su Correggi. Viene aperta 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 Firestore.
    4. Nel campo Seleziona un ruolo, scegli Agenti di servizio > agente di servizio Firestore.
    5. Fai clic su Salva.
    6. Torna alla scheda con la pagina di importazione/esportazione di Firestore.
    7. Ripeti questi passaggi per gli altri bucket dell'elenco. Assicurati di visualizzare tutte le pagine dell'elenco.
  5. Fai clic su Esegui la migrazione all'agente di servizio Firestore. Se hai ancora bucket con controlli di autorizzazione non riusciti, devi confermare la migrazione facendo clic su Esegui migrazione.

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

Visualizza stato migrazione

  1. Per verificare lo stato della migrazione del progetto, vai alla pagina Importa/Esporta in Google Cloud Console:

    Vai a Importa/Esporta

  2. Cerca l'entità accanto all'etichetta I job di importazione/esportazione vengono eseguiti come.

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

    Se la migrazione del progetto non è avvenuta, nella parte superiore della pagina viene visualizzato un banner con un pulsante Verifica stato del bucket. Consulta Eseguire la migrazione all'agente di servizio Firestore per completare la migrazione.

Aggiungi un vincolo del criterio a livello di organizzazione

  • Imposta il seguente vincolo nel criterio 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 dei criteri dell'organizzazione .

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

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 verificato e aggiornato le autorizzazioni delle bucket di Cloud Storage, puoi abilitare nuovamente il vincolo.