Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

Esporta e importa dati

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

Puoi utilizzare il servizio di importazione e esportazione gestita di Cloud Firestore per il ripristino dall'eliminazione accidentale dei dati e per 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 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 da 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, è necessario 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 di Cloud Storage per il tuo progetto in una posizione vicino alla posizione del database di Cloud Firestore . Non puoi utilizzare un bucket con pagamento del richiedente 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:

Autorizzazioni dell'account di servizio predefinito

Ogni progetto 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 tuo 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 Cloud Firestore, l'account di servizio predefinito ha accesso al bucket per impostazione predefinita .

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

L'account di servizio richiede il ruolo di Storage Admin dello storage per utilizzare il bucket di Cloud Storage per l'operazione di esportazione o importazione.

Se disabiliti o elimini il tuo account di servizio predefinito di App Engine, l'app di App Engine perderà l'accesso al database di Cloud Firestore. Se hai disabilitato il tuo account di servizio App Engine, puoi riattivarlo, vedi 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, vedi Annullamento dell'eliminazione di un account di servizio .

Configura gcloud per il tuo progetto

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

Esporta dati

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

Esporta tutti i documenti

Google Cloud Console

  1. Vai alla pagina di importazione/esportazione di Cloud Firestore nella console di Google Cloud Platform.

    Vai alla pagina Importa/Esporta

  2. Fare clic su Esporta .

  3. Fare clic sull'opzione Esporta intero database .

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

  5. Fare 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 ed esportazioni recenti. In caso di errore, la pagina visualizza un messaggio di errore.

gcloud

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

gcloud firestore export gs://[BUCKET_NAME]

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

Una volta avviata un'operazione di esportazione, la chiusura del terminale non annulla l'operazione, vedere annullare un'operazione .

Esporta raccolte specifiche

Google Cloud Console

  1. Vai alla pagina di importazione/esportazione di Cloud Firestore nella console di Google Cloud Platform.

    Vai alla pagina Importa/Esporta

  2. Fare clic su Esporta .

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

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

  5. Fare 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 ed esportazioni recenti. In caso di errore, la pagina visualizza un messaggio di errore.

gcloud

Per esportare gruppi di raccolte specifici, utilizzare il --collection-ids . L'operazione esporta solo i gruppi di raccolta con gli ID raccolta specificati. Il gruppo di raccolta include tutte le raccolte e 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]

Importa dati

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

  • Quando si importano i dati, gli indici richiesti vengono aggiornati utilizzando le definizioni degli indici correnti 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 suo 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 tuo database dopo l'importazione.

  • Le operazioni di importazione non attivano le funzioni cloud. I listener di snapshot ricevono gli aggiornamenti relativi alle operazioni di importazione.

  • Il nome del file .overall_export_metadata deve corrispondere al nome della sua 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 del file PARENT_FOLDER_NAME e .overall_export_metadata .

Importa tutti i documenti da un'esportazione

Google Cloud Console

  1. Vai alla pagina di importazione/esportazione di Cloud Firestore nella console di Google Cloud Platform.

    Vai alla pagina Importa/Esporta

  2. Fare clic su Importa .

  3. Nel campo Nome file , immettere il nome file di un file .overall_export_metadata da un'operazione di esportazione completata. Puoi usare il pulsante Sfoglia per aiutarti a selezionare il file.

  4. Fare clic su Importa .

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

gcloud

Utilizzare il comando di 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] puntano alla posizione dei tuoi file di esportazione. Per 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 nella console di Google Cloud Platform:

Apri il browser Cloud Storage

Una volta avviata un'operazione di importazione, la chiusura del terminale non annulla l'operazione, vedere annullare un'operazione .

Importa raccolte specifiche

Google Cloud Console

Non è possibile selezionare raccolte specifiche nella console. Usa invece gcloud .

gcloud

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

Solo un'esportazione di gruppi di raccolte specifici supporta l'importazione di gruppi di raccolte specifici. Non è possibile 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, Cloud Firestore assegna all'operazione un nome univoco. È possibile utilizzare il nome dell'operazione per eliminare, annullare o controllare lo stato dell'operazione.

I nomi delle operazioni sono preceduti da 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 .

Elenca tutte le operazioni di esportazione e importazione

Google Cloud Console

Puoi visualizzare un elenco delle recenti operazioni di esportazione e importazione nella pagina di importazione/esportazione di Cloud Firestore della console di Google Cloud Platform.

Vai alla pagina Importa/Esporta

gcloud

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

gcloud firestore operations list

Controllare lo stato dell'operazione

Google Cloud Console

Puoi visualizzare lo stato di un'operazione di esportazione o importazione recente nella pagina di importazione/esportazione di Cloud Firestore della console di Google Cloud Platform.

Vai alla pagina Importa/Esporta

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

Stimare il tempo di completamento

Una richiesta per lo stato di un'operazione di lunga durata restituisce le metriche workEstimated e workCompleted . Ognuna di queste metriche viene restituita sia in numero di byte che 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 effettuare una stima.

  • workCompleted mostra il numero di byte e documenti elaborati fino a quel momento. 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 essere imprecisa, perché dipende dalla raccolta ritardata delle statistiche.

Annulla un'operazione

Google Cloud Console

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

Vai alla pagina Importa/Esporta

Nella tabella Importazioni ed esportazioni recenti , le operazioni attualmente in esecuzione includono un pulsante Annulla nella colonna Completato . Fare clic sul pulsante Annulla per interrompere l'operazione. Il pulsante cambia in un messaggio di annullamento e quindi in Annullato quando l'operazione si interrompe completamente.

gcloud

Utilizzare il comando di operations cancel delle operazioni per interrompere un'operazione in corso:

gcloud firestore operations cancel [OPERATION_NAME]

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

Elimina un'operazione

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

gcloud firestore operations delete [OPERATION_NAME]

Fatturazione e prezzi per operazioni di esportazione e importazione

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 vengono addebitate per le letture e le scritture dei documenti alle tariffe elencate nei prezzi di Cloud Firestore .

I costi delle operazioni di esportazione e importazione non vengono conteggiati nel limite di spesa . Le operazioni di esportazione o importazione non attiveranno gli avvisi sul 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 tua quota giornaliera al termine dell'operazione. Le operazioni di esportazione e importazione non influiranno sull'utilizzo mostrato nella sezione 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 fatturazione cloud , puoi utilizzare questa etichetta per visualizzare i costi relativi alle operazioni di importazione ed esportazione:

Accedi all'etichetta gestita da goog-firestore dal menu dei filtri.

Esporta in BigQuery

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

Limite di colonne BigQuery

BigQuery impone un limite di 10.000 colonne per tabella. Le operazioni di esportazione di Cloud 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 raccolta diventa una colonna dello schema.

Se lo schema BigQuery di un gruppo di raccolta supera le 10.000 colonne, l'operazione di esportazione di 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 interrogare i 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 caricarne i dati in BigQuery.

Esporta file di formato e metadati

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

File di metadati

Un'operazione di esportazione crea un file di metadati per ogni gruppo di raccolta 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 raccolta contenuti nei file di esportazione:

protoc --decode_raw < export0.export_metadata

Migrazione dell'agente di servizio

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

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

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

Visualizza account di autorizzazione

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

  1. Vai alla pagina di importazione/esportazione di Cloud Firestore nella console di Google Cloud Platform.

    Vai a Importa/Esporta

  2. Visualizza l'account di autorizzazione accanto ai lavori di importazione/esportazione eseguiti come etichetta.

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

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

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

Il processo di migrazione prevede due fasi:

  1. Aggiorna le autorizzazioni del bucket di Cloud Storage. Vedere la sezione seguente per i dettagli.
  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 riescono dopo la migrazione all'agente di 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 di Cloud Storage da altri progetti per consentire l'accesso all'agente di servizio service- project_number @gcp-sa-firestore.iam.gserviceaccount.com . Concedere all'agente di servizio il ruolo di Firestore Service Agent .

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

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

Migrare un progetto in Firestore Service Agent

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

  1. Vai alla pagina di importazione/esportazione di Cloud Firestore nella console di Google Cloud Platform.

    Vai a Importa/Esporta

  2. Se il tuo progetto non è ancora migrato all'agente di servizio Cloud Firestore, vedrai un banner che descrive la migrazione e un pulsante Verifica lo stato del bucket . Il passaggio successivo ti aiuta a identificare e correggere potenziali errori di autorizzazione.

    Fare clic su Verifica stato bucket .

    Viene visualizzato un menu con l'opzione per completare la migrazione e un elenco di bucket di Cloud Storage. Il completamento del 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 attualmente non forniscono autorizzazioni di lettura e scrittura all'agente di servizio di Cloud Firestore.

  3. Prendi nota del nome principale dell'agente di servizio Cloud Firestore del tuo progetto. Il nome dell'agente di servizio viene visualizzato sotto l' agente di servizio per consentire l'accesso all'etichetta.
  4. 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 . Verrà aperta la pagina delle autorizzazioni del bucket in una nuova scheda.

    2. Fare clic su Aggiungi .
    3. Nel campo Nuovi principal , inserisci il nome del tuo agente di servizio Cloud Firestore.
    4. Nel campo Seleziona un ruolo , seleziona Agenti di servizio > Agente di servizio Firestore .
    5. Fare clic su Salva .
    6. Torna alla scheda con la pagina Import/Export di Cloud Firestore.
    7. Ripeti questi passaggi per gli altri bucket nell'elenco. Assicurati di visualizzare tutte le pagine dell'elenco.
  5. Fare clic su Migra a Firestore Service Agent . 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.

Visualizza lo stato della migrazione

  1. Per verificare lo stato di migrazione del tuo progetto, vai alla pagina Importa/Esporta nella Console di Google Cloud Platform:

    Vai a Importa/Esporta

  2. Cerca l'entità accanto ai lavori di importazione/esportazione eseguiti come etichetta.

    Se il principal è service- project_number @gcp-sa-firestore.iam.gserviceaccount.com , il tuo progetto è già 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 Verifica stato bucket . Consulta Migrazione all'agente di servizio Firestore per completare la migrazione.

Aggiungi un vincolo di policy a livello di organizzazione

  • Imposta il seguente vincolo nei criteri della tua organizzazione:

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

    Questo vincolo richiede operazioni di importazione ed esportazione per utilizzare l'agente di servizio Cloud Firestore per autorizzare le richieste. Per impostare questo vincolo, vedere Creazione e gestione delle politiche dell'organizzazione .

L'applicazione di questo vincolo di policy dell'organizzazione non garantisce automaticamente le autorizzazioni del 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 disabilitarlo per tornare all'utilizzo dell'account di servizio predefinito. Dopo aver verificato e aggiornato le autorizzazioni del bucket di Cloud Storage , puoi abilitare nuovamente il vincolo.