Importazione ed esportazione di dati

Puoi utilizzare il servizio di esportazione e importazione gestito 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 di 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 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 località del tuo database Cloud Firestore. Non puoi utilizzare un bucket con Pagamenti a carico del richiedente o un bucket rapido 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 Project Owner, 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:

Service agent Cloud Firestore

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

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

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

Assegna i ruoli all'agente di servizio

Puoi utilizzare lo strumento a riga di comando gsutil per assegnare uno dei ruoli riportati di seguito. Ad esempio, per assegnare il ruolo Storage Admin 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 progetto, che viene utilizzato per assegnare un nome all'agente di servizio Cloud Firestore. Per visualizzare il nome dell'agente di servizio, consulta Visualizza il nome dell'agente di servizio.

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

Visualizza il nome dell'agente di servizio

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

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

L'agente di servizio deve avere il 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.

  Inizia Cloud Shell

  Assicurati che gcloud sia configurato per il progetto corretto:

  gcloud config set project [PROJECT_ID]
  

• Installa e inizializza Google Cloud SDK.

Importa dati

Una volta esportati i file in Cloud Storage, puoi importare i documenti contenuti in questi 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 degli indici correnti del database. Un'esportazione non contiene definizioni di indici.

• 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 collisioni 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.

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

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

  Se sposti o copi i file di output di un'esportazione, mantieni invariati i nomi file PARENT_FOLDER_NAME e .overall_export_metadata.

• L'importazione in un database Cloud Firestore da un'esportazione con sub-raccolte non riesce perché le sub-raccolte non sono supportate in Cloud Firestore.

• Un'importazione in un database Firestore Standard Edition da un'esportazione con tipi BSON non va a buon fine perché i tipi BSON non sono supportati in Firestore Standard Edition.

• Un'importazione in un database Cloud Firestore non può importare dati da spazi dei nomi non predefiniti (API Datastore).

  L'importazione in un database Cloud Firestore da file di dati contenenti spazi dei nomi non predefiniti è consentita solo se l'operazione di esportazione includeva un filtro --namespace-ids con lo spazio dei nomi predefinito. Vengono importati solo i dati dello spazio dei nomi predefinito.

Importa 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 raccolte specifiche

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

Importa da un'esportazione con dati PITR

Segui gli stessi passaggi descritti in Importa tutti i documenti o Importa raccolte specifiche per importare i dati PITR. Se un documento esiste già nel database, verrà sovrascritto.

Esporta i dati

Un'operazione di esportazione copia i documenti del 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.

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] \
--database=[DATABASE]

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

Esporta 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 compreso 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, 2020-09-01T23:59:30.234233Z.
• Assicurati che il timestamp specificato sia un timestamp di un minuto intero negli ultimi sette giorni, ma non prima del earliestVersionTime. Se i dati non esistono più nel timestamp specificato, viene generato un errore.
• Non ti verrà addebitato alcun costo per un'esportazione PITR non riuscita.

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

Gestisci le 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 sono preceduti dal prefisso projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, ad esempio:

projects/my-project/databases/my-database/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

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 come numero di byte sia come 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 finora. Al termine dell'operazione, il valore mostra il numero totale di byte e documenti effettivamente elaborati, che potrebbe essere maggiore del valore di workEstimated.

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

Annulla un'operazione

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, mentre un'operazione di importazione annullata lascerà invariati 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 eliminerà 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 esportazione e importazione gestito.

Le operazioni di esportazione e importazione vengono addebitate per le unità di lettura e scrittura alle tariffe elencate in Prezzi di Cloud Firestore.

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

Le operazioni di esportazione o importazione non attiveranno gli avvisi relativi al budget di Google Cloud fino al completamento. Le operazioni di esportazione e importazione non influiscono 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 dei report sulla 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.

Quando carichi i dati Cloud Firestore in BigQuery, i tipi di dati BSON vengono rappresentati con il tipo di dati STRING.

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 raccolta. In questo schema, ogni nome di campo univoco all'interno di una raccolta diventa una colonna dello schema.

Se lo schema BigQuery di una raccolta supera le 10.000 colonne, l'operazione di esportazione Cloud Firestore tenta di rimanere al di sotto del limite di colonne trattando i campi 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 campi secondari all'interno dei campi mappa. Se il numero di colonne supera ancora le 10.000, l'operazione di esportazione non genera uno schema BigQuery per la raccolta e non puoi caricare i relativi dati in BigQuery.

Formato di esportazione e file di metadati

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

File di metadati

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

I file dei metadati sono buffer di protocollo e puoi decodificarli con il compilatore di protocollo protoc. Ad esempio, puoi decodificare un file di metadati per determinare le raccolte contenute nei file di esportazione:

protoc --decode_raw < export0.export_metadata