Esportare e importare i dati

Puoi utilizzare il servizio gestito di esportazione e importazione di Cloud Firestore per ripristinare i dati dopo l'eliminazione accidentale ed esportarli per offline e l'elaborazione dei dati. Puoi esportare tutti i documenti o solo raccolte specifiche. Analogamente, puoi importare tutti i dati da un'esportazione o solo raccolte specifiche. Dati esportati da un database Cloud Firestore possono essere importati in un altro Cloud Firestore database. Puoi anche caricare Esportazioni di Cloud Firestore in BigQuery.

In questa pagina viene descritto come esportare e importare Cloud Firestore documenti utilizzando il servizio gestito di esportazione e importazione 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 gestito di esportazione e importazione, devi completare la le seguenti attività:

1. Attiva per il tuo progetto Google Cloud. Solo Google Cloud I progetti con fatturazione abilitata possono utilizzare la funzionalità di esportazione e importazione.
2. Crea un Cloud Storage bucket per il tuo progetto in una località vicino alla tua Cloud Firestore località del database. Non puoi utilizzare un Il richiedente paga il bucket 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 disponga delle autorizzazioni necessarie. In caso contrario, verrà concedono le autorizzazioni necessarie per le operazioni di esportazione e importazione e per accedere a Cloud Storage:

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

   • Cloud Storage ruoli: Owner oppure 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. Agente di servizio Cloud Firestore utilizza la seguente convenzione di denominazione:

Agente di servizio Cloud Firestore

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

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

L'agente di servizio Cloud Firestore richiede l'accesso a Cloud Storage bucket utilizzato in un'operazione di esportazione o importazione. Se le tue Cloud Storage bucket si trova nello stesso progetto del tuo Cloud Firestore , l'agente di servizio Cloud Firestore potrà accedere per impostazione predefinita.

Se il bucket Cloud Storage si trova in un altro progetto, deve concedere all'agente di servizio Cloud Firestore l'accesso a Cloud Storage di sincronizzare la directory di una VM con un bucket.

Assegna ruoli all'agente di servizio

Puoi utilizzare lo strumento a riga di comando gsutil per e assegnare uno dei ruoli seguenti. Ad esempio, per assegnare il ruolo Amministratore dello spazio di archiviazione all'agente di servizio Cloud Firestore, esegui il seguente 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, viene utilizzato per assegnare un nome all'agente di servizio Cloud Firestore. Per visualizzare nome dell'agente di servizio, consulta la sezione Visualizzare 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 richieste dalla pagina Importa/Esporta della console Google Cloud. Puoi anche vedi se il database utilizza Cloud Firestore agente di servizio o l'account di servizio App Engine legacy.

1. Visualizza l'account di autorizzazione accanto a L'etichetta Job di importazione/esportazione eseguiti come.

L'agente di servizio deve avere il ruolo Storage Admin per Cloud Storage bucket 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 oppure 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 di Google Cloud Platform 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 del tuo database in un set di file in un Cloud Storage bucket. Tieni presente che un'esportazione non è uno snapshot esatto del database acquisito al momento di inizio dell'esportazione. Un'esportazione potrebbe includere modifiche apportate durante l'operazione era in esecuzione.

Esporta tutti i documenti

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

Esporta 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'

Esporta da un timestamp PITR

Puoi esportare il tuo database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export. Puoi esportare i dati PITR in cui il timestamp è un timestamp intero di minuti gli ultimi sette giorni, ma non prima di earliestVersionTime. Se i dati non sono più esiste in corrispondenza del timestamp specificato, l'operazione di esportazione non va a buon fine.

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

1. Esporta il database, specificando il parametro snapshot-time nel timestamp di recupero desiderato.

   gcloud

   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.

   Tieni presente quanto segue prima di esportare i dati PITR:

   • Specifica il timestamp in RFC 3339 standard. Ad esempio, 2020-09-01T23:59:30.234233Z.
   • Assicurati che il timestamp specificato sia un timestamp intero di minuti negli ultimi sette giorni, ma non prima del earliestVersionTime. Se i dati non esistono più al timestamp specificato, viene generato un errore.
   • Non ti viene addebitato alcun costo per un'esportazione PITR non riuscita.

Importa dati

Una volta ottenuti i file di esportazione in Cloud Storage, puoi importare i documenti al suo interno di nuovo i file nel tuo progetto o in un altro progetto. Tieni presente quanto segue sulle operazioni di importazione:

• Quando importi i dati, gli indici richiesti vengono aggiornati utilizzando le definizioni dell'indice attuali. Un'esportazione non contiene definizioni di indice.

• Le importazioni non assegnano nuovi ID documento. Le importazioni utilizzano gli ID acquisiti in l'ora dell'esportazione. Durante l'importazione di un documento, il relativo ID viene riservato per evitare collisioni tra 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. Ascoltatori snapshot ricevere aggiornamenti relativi alle operazioni di importazione.

• Il nome del file .overall_export_metadata deve corrispondere a quello del file principale cartella:

  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, conserva i I file PARENT_FOLDER_NAME e .overall_export_metadata assegnano il nome in modo analogo.

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'

Importa collezioni 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 i file esportati per configurare un database. Se esistono già documenti nel database, sovrascritto.

Gestione delle operazioni di esportazione e importazione

Dopo aver avviato un'operazione di esportazione o importazione, Cloud Firestore assegna un nome univoco per l'operazione. Puoi utilizzare il nome dell'operazione per eliminare, annullare l'operazione 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 il nome di un'operazione 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 per lo stato di un'operazione a lunga esecuzione restituisce le metriche workEstimated e workCompleted. Ognuna di queste metriche viene restituita sia in termini di numero di byte sia in termini di numero di entità:

• workEstimated mostra il numero totale stimato di byte e documenti verrà elaborata. Cloud Firestore potrebbe omettere questa metrica se non riesce a 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 potrebbero essere più grandi del pari a workEstimated.

Dividi workCompleted per workEstimated per ottenere una stima approssimativa. Questa stima potrebbe non essere precisa, in quanto dipende dalla raccolta delle statistiche con ritardo.

Annullare un'operazione

gcloud firestore operations cancel [OPERATION_NAME]

L'annullamento di un'operazione in esecuzione non ne annulla l'operazione. Un'operazione di esportazione annullata lascerà i documenti già esportati in Cloud Storage e un'operazione di importazione annullata lascerà invariati gli aggiornamenti già apportati al database. Tu impossibile importare un'esportazione parzialmente completata.

Elimina un'operazione

Utilizza il comando gcloud firestore operations delete per rimuovere un'operazione dall'elenco delle operazioni recenti. Questo comando non eliminerà esporta file 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 progetto Google Cloud prima di utilizzarlo il servizio gestito di esportazione e importazione.

Le operazioni di esportazione e importazione vengono addebitate per le operazioni di lettura e scrittura di documenti alle velocità elencate in 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 del calcolo Cloud Storage costi di archiviazione dei dati.

I costi delle operazioni di esportazione e importazione non vengono conteggiati ai fini della spesa di sicurezza. Le operazioni di esportazione o importazione non attiveranno Avvisi relativi a Google Cloud budget fino al completamento. Analogamente, le letture e le scritture eseguite durante un'operazione di esportazione o importazione vengono applicate la quota giornaliera al termine dell'operazione. Esporta e importa e non influiranno sull'utilizzo, mostrato nella relativa sezione della console.

Visualizzare i costi di esportazione e importazione

Le operazioni di esportazione e importazione applicano goog-firestoremanaged:exportimport alle operazioni fatturate. Nella pagina dei 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 di Cloud Firestore in BigQuery, ma solo se hai specificato un filtro collection-ids. Consulta Caricamento di dati da Cloud Firestore esportazioni.

BigQuery limite di colonne

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

Se lo schema BigQuery di un gruppo di raccolte supera le 10.000 colonne, il valore 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 consente di ridurre il numero di colonne al di sotto di 10.000, puoi caricare i dati in BigQuery, ma non puoi eseguire query sui campi secondari all'interno dei campi mappa. Se il numero di colonne è ancora superiore a 10.000, l'operazione di esportazione non genera uno schema BigQuery per il gruppo di raccolte che non puoi caricare che contiene i suoi dati in BigQuery.

Formati di esportazione e file di metadati

L'output di un'esportazione gestita utilizza Formato log LevelDB:

File di metadati

Un'operazione di esportazione crea un file di metadati per ogni gruppo di raccolte specificato. I file dei 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 Compilatore di protocollo protoc. Ad esempio, puoi decodificare un file di metadati per determinare i gruppi di raccolte i file di esportazione contengono:

protoc --decode_raw < export0.export_metadata

Migrazione dell'agente di servizio

Cloud Firestore utilizza un agente di servizio Cloud Firestore per autorizzare l'importazione e le operazioni di esportazione invece di utilizzare l'account di servizio 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

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

App Engine account di servizio

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 richieste dalla pagina Importa/Esporta della console Google Cloud. Puoi anche verifica se il tuo database utilizza già Cloud Firestore dell'agente di servizio di servizio di 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.

4. Visualizza l'account di autorizzazione accanto a L'etichetta Job di importazione/esportazione eseguiti come.

Se il tuo progetto non utilizza l'agente di servizio Cloud Firestore, può eseguire la migrazione all'agente di servizio Cloud Firestore utilizzando uno dei queste tecniche:

• Esegui la migrazione di un progetto controllando e aggiornando le autorizzazioni dei bucket Cloud Storage (opzione consigliata).
• Aggiungi un vincolo del criterio a livello di organizzazione che interessa tutti i progetti all'interno dell'organizzazione.

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

Esegui la migrazione controllando e aggiornando Cloud Storage autorizzazioni di bucket

La procedura di migrazione prevede due passaggi:

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

Autorizzazioni 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'altra devono accedere a un bucket in quell'altro progetto. In caso contrario, operazioni non riuscite dopo la migrazione al servizio Cloud Firestore un agente.

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 nello stesso progetto per impostazione predefinita.

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

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

Il processo di migrazione descritto nella sezione seguente ti aiuta a identificare Cloud Storage bucket 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 a l'agente di servizio Cloud Firestore. Una volta completata la migrazione, 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 è stata ancora eseguita la migrazione del progetto al servizio Cloud Firestore , vedrai un banner che descrive la migrazione un pulsante Controlla lo stato del bucket. Il passaggio successivo ti consente di identificare correggere i 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. Potrebbero essere necessari alcuni minuti per completare il caricamento dell'elenco.

   Questo elenco include bucket recenti utilizzata nelle operazioni di importazione ed esportazione, ma attualmente non fornisce dati autorizzazioni di scrittura per l'agente di servizio Cloud Firestore.

5. Prendi nota del nome entità di Cloud Firestore del progetto dell'agente di servizio di servizio di Google Cloud. 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 dovrai da utilizzare per operazioni di importazione o esportazione future, completa quanto segue passaggi:

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

   2. Fai clic su Aggiungi.
   3. Nel campo Nuove entità, inserisci il nome delle Agente di servizio Cloud 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 Cloud Firestore Importa/Esporta.
   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 al completamento della migrazione. La migrazione non può essere annullata.

Visualizza stato migrazione

Per verificare lo stato di 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, il progetto è già stato migrato in Cloud Firestore dell'agente di servizio di servizio di Google Cloud. La migrazione non può essere annullata.

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

Aggiungi un vincolo di criteri a livello di organizzazione

• Imposta il seguente vincolo nei criteri della tua organizzazione:

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

  Questo vincolo richiede le operazioni di importazione ed esportazione per utilizzare Agente di servizio Cloud Firestore per autorizzare le richieste. Per impostare questo vincolo, consulta Creare e gestire i criteri dell'organizzazione .

L'applicazione di questo vincolo del criterio dell'organizzazione non concede automaticamente la le autorizzazioni appropriate per il bucket Cloud Storage 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 a usare l'account di servizio predefinito. Dopo aver controllato e aggiornato Cloud Storage bucket autorizzazioni, puoi abilitare di nuovo il vincolo.