Questa pagina descrive come esportare e importare Firestore in entità in modalità Datastore utilizzando il servizio gestito di esportazione e importazione. Il servizio gestito di esportazione e importazione è disponibile tramite la console Google Cloud, Google Cloud CLI e l'API Datastore Admin (REST, RPC).
Con il servizio gestito di esportazione e importazione puoi recuperare i dati dall'eliminazione accidentale ed esportare i dati per l'elaborazione offline. Puoi esportare tutte le entità o solo tipi specifici di entità. Allo stesso modo, puoi importare tutti i dati da un'esportazione o solo tipi specifici. Quando utilizzi il servizio gestito di esportazione e importazione, considera quanto segue:
Il servizio di esportazione utilizza letture a livello di coerenza finale. Non puoi presumere che un'esportazione venga eseguita in un singolo momento. L'esportazione potrebbe includere entità scritte dopo l'inizio dell'esportazione ed escludere entità scritte prima dell'inizio dell'esportazione.
Un'esportazione non contiene indici. Quando importi i dati, gli indici richiesti vengono ricreati automaticamente utilizzando le attuali definizioni degli indici attuali del database. Le impostazioni dell'indice dei valori delle proprietà per entità vengono esportate e rispettate durante l'importazione.
Le importazioni non assegnano nuovi ID alle entità. Le importazioni utilizzano gli ID esistenti al momento dell'esportazione e sovrascrivono qualsiasi entità esistente con lo stesso ID. Durante un'importazione, gli ID vengono prenotati per il periodo di tempo in cui le entità vengono importate. Questa funzionalità impedisce conflitti tra ID con nuove entità se le scritture sono abilitate durante l'esecuzione di un'importazione.
Se un'entità del database non è interessata da un'importazione, rimarrà nel database dopo l'importazione.
I dati esportati da un database in modalità Datastore possono essere importati in un altro database in modalità Datastore, anche uno in un altro progetto.
Il servizio gestito di esportazione e importazione limita a 50 il numero di esportazioni e importazioni simultanee e consente un massimo di 20 richieste di esportazione e importazione al minuto per un progetto. Per ogni richiesta, il servizio limita il numero di combinazioni di filtri entità a 100.
L'output di un'esportazione gestita utilizza il formato di log LevelDB.
Per importare solo un sottoinsieme di entità o per importare dati in BigQuery, devi specificare un filtro entità nell'esportazione.
Il nome file
.overall_export_metadatadeve corrispondere a quello della relativa cartella principale:gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadataSe sposti o copi i file di output di un'esportazione, mantieni lo stesso
PARENT_FOLDER_NAME, i contenuti delle sottocartelle e il nome del file.overall_export_metadata.
Prima di iniziare
Prima di poter utilizzare il servizio gestito di esportazione e importazione, devi completare le attività seguenti.
Abilitare la fatturazione per il tuo progetto Google Cloud. Solo i progetti Google Cloud con fatturazione abilitata possono utilizzare le funzionalità di esportazione e importazione.
Crea un bucket Cloud Storage nella stessa località del database Firestore in modalità Datastore. Non puoi utilizzare un bucket Pagamenti a carico del richiedente per le operazioni di esportazione e importazione.
Assegna un ruolo IAM al tuo account utente che conceda l'autorizzazione
datastore.databases.export, se stai esportando i dati, o l'autorizzazionedatastore.databases.import, se stai importando i dati. Il ruoloDatastore Import Export Admin, ad esempio, concede entrambe le autorizzazioni.Se il bucket Cloud Storage si trova in un altro progetto, concedi all'agente di servizio Firestore l'accesso al bucket.
Configura gcloud per il progetto
Se prevedi di utilizzare gcloud per avviare le operazioni di importazione ed esportazione, configura gcloud e connettiti al progetto in uno dei seguenti modi:
Accedi a
gclouddalla console Google Cloud utilizzando Cloud Shell.Configura gcloud CLI per utilizzare il tuo progetto attuale:
gcloud config set project project-id
Autorizzazioni
Per eseguire operazioni di esportazione e importazione, il tuo account utente e l'agente di servizio in modalità Datastore del progetto richiedono le seguenti autorizzazioni di Identity and Access Management.
Autorizzazioni account utente
L'account utente o l'account di servizio che avvia l'operazione
richiede le autorizzazioni IAM datastore.databases.export e datastore.databases.import. Se sei il proprietario del progetto, il tuo account dispone delle autorizzazioni necessarie. In caso contrario, i seguenti ruoli IAM concedono le autorizzazioni necessarie:
- Proprietario Datastore
- Amministratore importazione/esportazione Datastore
Puoi anche assegnare queste autorizzazioni con un ruolo personalizzato.
Un proprietario del progetto può concedere uno di questi ruoli seguendo i passaggi descritti in Concedi l'accesso.
Autorizzazioni agente di servizio
Le operazioni di esportazione e importazione utilizzano un agente di servizio Firestore per autorizzare le operazioni di Cloud Storage. L'agente di servizio Firestore utilizza la seguente convenzione di denominazione:
- Agente di servizio 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 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 Firestore, l'agente di servizio 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 Firestore l'accesso al bucket Cloud Storage.
Assegna ruoli all'agente di servizio
Puoi utilizzare lo strumento a riga di comando gsutil per assegnare uno dei ruoli seguenti. Ad esempio, per assegnare il ruolo Amministratore Storage all'agente di servizio 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 di progetto, utilizzato per assegnare un nome all'agente di servizio 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.
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 vedere se il database utilizza l'agente di servizio Firestore o l'account di servizio App Engine legacy.
-
Nella console Google Cloud, vai alla pagina Database.
-
Seleziona il database richiesto dall'elenco dei database.
-
Nel menu di navigazione, fai clic su Importa/Esporta.
- Visualizza l'account di autorizzazione accanto all'etichetta I job di importazione/esportazione vengono eseguiti come.
Operazioni di esportazione
Per le operazioni di esportazione che coinvolgono un bucket in un altro progetto, modifica le autorizzazioni del bucket per assegnare uno dei seguenti ruoli Identity and Access Management all'agente di servizio in modalità Datastore del progetto che contiene il database in modalità Datastore:
- Amministratore Storage
- Proprietario (ruolo di base)
Puoi anche creare un ruolo IAM personalizzato con autorizzazioni leggermente diverse rispetto a quelle contenute nei ruoli elencati in precedenza:
storage.buckets.getstorage.objects.createstorage.objects.deletestorage.objects.list
Operazioni di importazione
Per le operazioni di importazione che coinvolgono un bucket Cloud Storage in un altro progetto, modifica le autorizzazioni del bucket per assegnare uno dei seguenti ruoli Cloud Storage all'agente di servizio in modalità Datastore del progetto che contiene il database in modalità Datastore:
- Amministratore Storage
- Sia Visualizzatore oggetti Storage che Lettore bucket legacy Storage
Puoi anche creare un ruolo IAM personalizzato con le seguenti autorizzazioni:
storage.buckets.getstorage.objects.get
Avvio delle operazioni di esportazione e importazione gestite
Questa sezione descrive come avviare un'operazione di esportazione o importazione gestita.
Esportare tutte le entità
Console
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
- Nel menu di navigazione, fai clic su Importa/Esporta.
- Fai clic su Esporta.
- Imposta il campo Spazio dei nomi su
All Namespacese il campo Kind suAll Kinds. - Sotto Destinazione, inserisci il nome del bucket Cloud Storage.
- Fai clic su Esporta.
La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di esportazione gestita.
gcloud
Utilizza il comando gcloud firestore export per esportare tutte le entità nel tuo database.
gcloud firestore export gs://bucket-name --async --database=DATABASE
dove bucket-name è il nome del bucket Cloud Storage e un prefisso facoltativo, ad esempio
bucket-name/datastore-exports/export-name. Non puoi riutilizzare lo stesso prefisso per un'altra operazione di esportazione. Se non fornisci un prefisso file, il servizio di esportazione gestita ne crea uno in base all'ora attuale.
Utilizza il flag [--async][async-flag] per evitare che gcloud attenda il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per non aspettare più un'operazione. L'operazione non verrà annullata.
Imposta il flag --database sul nome del database da cui vuoi esportare le entità. Per il database predefinito, utilizza --database='(default)'.
rest
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- project-id: il tuo ID progetto
- bucket-name: nome del bucket Cloud Storage
Metodo HTTP e URL:
POST https://datastore.googleapis.com/v1/projects/project-id:export
Corpo JSON della richiesta:
{
"outputUrlPrefix": "gs://bucket-name",
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"name": "projects/project-id/operations/operation-id",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
"common": {
"startTime": "2019-09-18T18:42:26.591949Z",
"operationType": "EXPORT_ENTITIES",
"state": "PROCESSING"
},
"entityFilter": {},
"outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
}
}
Esportazione di tipi o spazi dei nomi specifici
Per esportare un sottoinsieme specifico di tipi e/o spazi dei nomi, fornisci un filtro entità con valori per tipi e ID spazio dei nomi. Ogni richiesta è limitata a 100 combinazioni di filtri di entità, in cui ogni combinazione di tipo e spazio dei nomi filtrati viene conteggiata come un filtro separato per questo limite.
Console
Nella console, puoi selezionare tutti i tipi o solo un tipo specifico. Allo stesso modo, puoi selezionare tutti gli spazi dei nomi o uno specifico.
Per specificare un elenco di spazi dei nomi e tipi da esportare, utilizza gcloud.
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Importa/Esporta.
Fai clic su Esporta.
Imposta il campo Spazio dei nomi su
All Namespaceso sul nome di uno dei tuoi spazi dei nomi.Imposta il campo Kind su
All Kindso sul nome di un tipo.In Destinazione, inserisci il nome del bucket Cloud Storage.
Fai clic su Esporta.
La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di esportazione gestita.
gcloud
gcloud firestore export --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name \ --async \ --database=DATABASE
dove bucket-name è il nome del bucket Cloud Storage e un prefisso facoltativo, ad esempio
bucket-name/datastore-exports/export-name. Non puoi riutilizzare lo stesso prefisso per un'altra operazione di esportazione. Se non fornisci un prefisso file, il servizio di esportazione gestita ne crea uno in base all'ora attuale.
Utilizza il flag [--async][async-flag] per evitare che gcloud attenda il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per non aspettare più un'operazione. L'operazione non verrà annullata.
Imposta il flag --database sul nome del database da cui vuoi esportare tipi o spazi dei nomi specifici. Per il database predefinito, utilizza --database='(default)'.
rest
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- project-id: il tuo ID progetto
- bucket-name: nome del bucket Cloud Storage
- kind: il tipo di entità
- namespace: l'ID spazio dei nomi (utilizza "" per l'ID spazio dei nomi predefinito)
Metodo HTTP e URL:
POST https://datastore.googleapis.com/v1/projects/project-id:export
Corpo JSON della richiesta:
{
"outputUrlPrefix": "gs://bucket-name",
"entityFilter": {
"kinds": ["kind"],
"namespaceIds": ["namespace"],
},
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"name": "projects/project-id/operations/operation-id",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
"common": {
"startTime": "2019-09-18T21:17:36.232704Z",
"operationType": "EXPORT_ENTITIES",
"state": "PROCESSING"
},
"entityFilter": {
"kinds": [
"Task"
],
"namespaceIds": [
""
]
},
"outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
}
}
File di metadati
Un'operazione di esportazione crea un file di metadati per ogni coppia di spazio dei nomi-tipo specificata. I file di metadati sono in genere denominati
NAMESPACE_NAME_KIND_NAME.export_metadata. Tuttavia, se uno spazio dei nomi o un tipo crea un nome oggetto Cloud Storage non valido, il file verrà denominato export[NUM].export_metadata.
I file di metadati sono buffer di protocollo e possono essere decodificati con il compilatore di protocollo protoc.
Ad esempio, puoi decodificare un file di metadati per determinare lo spazio dei nomi e i tipi di file di esportazione contenenti:
protoc --decode_raw < export0.export_metadata
Importazione di tutte le entità
Console
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Importa/Esporta.
Fai clic su Importa.
Nel campo
File, fai clic su Sfoglia e seleziona un file.overall_export_metadata.Assicurati che il file
.overall_export_metadatanon venga spostato dalla posizione predefinita.Imposta il campo Spazio dei nomi su
All Namespacese il campo Kind suAll Kinds.Fai clic su Importa.
La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di importazione gestita.
gcloud
Utilizza il comando gcloud firestore import per importare tutte le entità esportate in precedenza con il servizio di esportazione gestito.
gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \ --async \ --database=DATABASE
dove bucket-name/file-path/file-name è il percorso del file
overall_export_metadata all'interno del bucket Cloud Storage.
Utilizza il flag [--async][async-flag] per evitare che gcloud attenda il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per non aspettare più un'operazione. L'operazione non verrà annullata.
Imposta il flag --database sul nome del database in cui vuoi importare tutte le entità. Per il database predefinito, utilizza --database='(default)'.
rest
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- project-id: il tuo ID progetto
- bucket-name: nome del bucket Cloud Storage
- object-name: nome dell'oggetto Cloud Storage (esempio:
2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata
Metodo HTTP e URL:
POST https://datastore.googleapis.com/v1/projects/project-id:import
Corpo JSON della richiesta:
{
"inputUrl": "gs://bucket-name/object-name",
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"name": "projects/project-id/operations/operation-id",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
"common": {
"startTime": "2019-09-18T21:25:02.863621Z",
"operationType": "IMPORT_ENTITIES",
"state": "PROCESSING"
},
"entityFilter": {},
"inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
}
}
Localizzazione del file overall_export_metadata in corso...
Puoi determinare il valore da utilizzare per la posizione di importazione utilizzando il browser Cloud Storage nella console Google Cloud:
Puoi anche elencare e descrivere le operazioni completate. Il campo outputURL mostra il nome del file overall_export_metadata:
"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",
Importazione di tipi o spazi dei nomi specifici
Per importare un sottoinsieme specifico di tipi e/o spazi dei nomi, fornisci un filtro entità con valori per tipi e ID spazio dei nomi.
Puoi specificare tipi e spazi dei nomi solo se i file di esportazione sono stati creati con un filtro di entità. Non puoi importare un sottoinsieme di tipi e spazi dei nomi da un'esportazione di tutte le entità.
Console
Nella console, puoi selezionare tutti i tipi o solo un tipo specifico. Allo stesso modo, puoi selezionare tutti gli spazi dei nomi o uno specifico.
Per specificare un elenco di spazi dei nomi e tipi da importare, utilizza gcloud.
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Importa/Esporta.
Fai clic su Importa.
Nel campo
File, fai clic su Sfoglia e seleziona un file.overall_export_metadata.Assicurati di importare il file
.overall_export_metadatae non un file.export_metadata.Imposta il campo Spazio dei nomi su
All Namespaceso su uno spazio dei nomi specifico.Imposta il campo Tipo su
All Kindsoppure su un tipo specifico.Fai clic su Importa.
La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della richiesta di importazione gestita.
gcloud
gcloud firestore import --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name/file-path/file-nameoverall_export_metadata \ --async \ --database=DATABASE
dove bucket-name/file-path/file-name è il percorso del file
overall_export_metadata all'interno del bucket Cloud Storage.
Utilizza il flag [--async][async-flag] per evitare che gcloud attenda il completamento dell'operazione. Se ometti il flag --async, puoi digitare Ctrl+c per non aspettare più un'operazione. L'operazione non verrà annullata.
Imposta il flag --database sul nome del database in cui vuoi importare tipi o spazi dei nomi specifici. Per il database predefinito, utilizza --database='(default)'.
rest
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- project-id: il tuo ID progetto
- bucket-name: nome del bucket Cloud Storage
- object-name: nome dell'oggetto Cloud Storage (esempio:
2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata - kind: il tipo di entità
- namespace: l'ID spazio dei nomi (utilizza "" per l'ID spazio dei nomi predefinito)
Metodo HTTP e URL:
POST https://datastore.googleapis.com/v1/projects/project-id:import
Corpo JSON della richiesta:
{
"inputUrl": "gs://bucket-name/object-name",
"entityFilter": {
"kinds": ["kind"],
"namespaceIds": ["namespace"],
},
}
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"name": "projects/project-id/operations/operation-id",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
"common": {
"startTime": "2019-09-18T21:51:02.830608Z",
"operationType": "IMPORT_ENTITIES",
"state": "PROCESSING"
},
"entityFilter": {
"kinds": [
"Task"
],
"namespaceIds": [
""
]
},
"inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
}
}
Esportare e importare dai dati PITR
Puoi esportare il database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export. Puoi esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero compreso negli ultimi sette giorni, ma non prima di earliestVersionTime. Se i dati non esistono più nel timestamp specificato, l'operazione di esportazione non va a buon fine.
L'operazione di esportazione PITR supporta tutti i filtri, tra cui l'esportazione di tutte le entità e l'esportazione di tipi o spazi dei nomi specifici.
Esporta il database, specificando il parametro
snapshot-timenel timestamp di recupero richiesto.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 esempio2023-05-26T10:20:00.00Z.
È anche supportata l'esportazione di un sottoinsieme specifico di tipi e/o spazi dei nomi con un filtro di entità][export-kind].
Prima di esportare i dati PITR, tieni presente quanto segue:
- Specifica il timestamp in formato RFC 3339.
Ad esempio,
2020-09-01T23:59:30.234233Z. - Assicurati che il timestamp specificato sia un timestamp di un minuto intero relativo agli ultimi sette giorni, ma non precedente a
earliestVersionTime. Se i dati non esistono più al timestamp specificato, verrà visualizzato un errore. - Non ti verrà addebitato alcun costo per un'esportazione PITR non riuscita.
Importa in un database.
Segui i passaggi descritti in Importare tutte le entità per importare il database esportato. Se un'entità è già presente nel database, verrà sovrascritta. È anche supportata [l'importazione di un sottoinsieme specifico di tipi e/o spazi dei nomi con un filtro di entità][import-kind].
Importa trasformazioni
Quando importi entità da un altro progetto, tieni presente che le chiavi delle entità includono l'ID progetto. Un'operazione di importazione aggiorna le chiavi entità e le proprietà di riferimento delle chiavi nei dati di importazione con l'ID progetto del progetto di destinazione. Se questo aggiornamento aumenta le dimensioni dell'entità, può causare l'errore "L'entità è troppo grande" o le "Voci di indice troppo grandi" per le operazioni di importazione.
Per evitare entrambi gli errori, esegui l'importazione in un progetto di destinazione con un ID progetto più breve. Ciò non influisce sulle operazioni di importazione con dati dello stesso progetto.
Gestione di operazioni a lunga esecuzione
Le operazioni di importazione ed esportazione gestite sono operazioni a lunga esecuzione. Queste chiamate al metodo possono richiedere molto tempo.
Dopo aver avviato un'operazione di esportazione o importazione, la modalità Datastore 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/(default)/operations/, ad esempio:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Puoi escludere il prefisso quando specifichi un nome di operazione per i comandi gcloud.
Elenco di tutte le operazioni a lunga esecuzione
Puoi visualizzare le operazioni in corso e quelle completate di recente nei seguenti modi. Le operazioni sono elencate per alcuni giorni dopo il completamento:
Console
Puoi visualizzare un elenco delle operazioni a lunga esecuzione nella pagina Importa/Esporta della console Google Cloud.
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Importa/Esporta.
gcloud
Per elencare le operazioni a lunga esecuzione, utilizza il comando gcloud datastore Operations list.
gcloud datastore operations list
Ad esempio, un'operazione di esportazione completata di recente mostra le seguenti informazioni:
{
"operations": [
{
"name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
"common": {
"startTime": "2017-12-05T23:01:39.583780Z",
"endTime": "2017-12-05T23:54:58.474750Z",
"operationType": "EXPORT_ENTITIES"
},
"progressEntities": {
"workCompleted": "21933027",
"workEstimated": "21898182"
},
"progressBytes": {
"workCompleted": "12421451292",
"workEstimated": "9759724245"
},
"entityFilter": {
"namespaceIds": [
""
]
},
"outputUrlPrefix": "gs://bucket-name"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
}
}
]
}
rest
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- project-id: il tuo ID progetto
Metodo HTTP e URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations
Per inviare la richiesta, espandi una di queste opzioni:
Leggi le informazioni sulla risposta di seguito.
Ad esempio, un'operazione di esportazione completata di recente mostra le seguenti informazioni:
{
"operations": [
{
"name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
"common": {
"startTime": "2017-12-05T23:01:39.583780Z",
"endTime": "2017-12-05T23:54:58.474750Z",
"operationType": "EXPORT_ENTITIES"
},
"progressEntities": {
"workCompleted": "21933027",
"workEstimated": "21898182"
},
"progressBytes": {
"workCompleted": "12421451292",
"workEstimated": "9759724245"
},
"entityFilter": {
"namespaceIds": [
""
]
},
"outputUrlPrefix": "gs://bucket-name"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
}
}
]
}
Controlla lo stato dell'operazione
Per visualizzare lo stato di un'operazione a lunga esecuzione:
Console
Puoi visualizzare un elenco delle operazioni di esportazione e importazione più recenti nella pagina Importa/Esporta della console Google Cloud.
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Importa/Esporta.
gcloud
Utilizza il comando operations describe per mostrare lo stato di un'operazione a lunga esecuzione.
gcloud datastore operations describe operation-name
rest
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- project-id: il tuo ID progetto
- operation-name: nome dell'operazione
Metodo HTTP e URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name
Per inviare la richiesta, espandi una di queste opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{
"name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
"common": {
"startTime": "2019-10-08T20:07:28.105236Z",
"endTime": "2019-10-08T20:07:36.310653Z",
"operationType": "EXPORT_ENTITIES",
"state": "SUCCESSFUL"
},
"progressEntities": {
"workCompleted": "21",
"workEstimated": "21"
},
"progressBytes": {
"workCompleted": "2272",
"workEstimated": "2065"
},
"entityFilter": {},
"outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
"outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
}
}
Stima del tempo di completamento
Durante l'esecuzione dell'operazione, controlla il valore del campo state per lo stato generale dell'operazione.
Una richiesta per lo stato di un'operazione a lunga esecuzione restituisce le metriche workEstimated e workCompleted. Ognuna di queste metriche viene restituita in numero di byte e numero di entità:
workEstimatedmostra il numero totale stimato di byte e documenti elaborati da un'operazione. La modalità Datastore potrebbe omettere questa metrica se non può effettuare una stima.workCompletedmostra 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 potrebbero essere superiori al valore diworkEstimated.
Dividi workCompleted per workEstimated per ottenere una stima approssimativa dell'avanzamento. Questa stima potrebbe non essere precisa, perché dipende da un ritardo nella raccolta delle statistiche.
Ad esempio, ecco lo stato di avanzamento di un'operazione di esportazione:
{
"operations": [
{
"name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
"metadata": {
"@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
...
"progressEntities": {
"workCompleted": "1",
"workEstimated": "3"
},
"progressBytes": {
"workCompleted": "85",
"workEstimated": "257"
},
...
Al completamento di un'operazione, la relativa descrizione contiene "done":
true. Visualizza il valore del campo state relativo al risultato dell'operazione. Se il campo done non è impostato nella risposta,
il suo valore è false. Non dipendere dall'esistenza del valore done per le operazioni in corso.
Annullamento di un'operazione
Console
Puoi annullare un'operazione di esportazione o importazione in esecuzione nella pagina Importa/Esporta della console Google Cloud.
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su 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 cambia in Annullamento e poi in Annullato quando l'operazione viene interrotta.
gcloud
Utilizza il comando operations cancel per arrestare un'operazione in corso:
gcloud datastore operations cancel operation-name
L'annullamento di un'operazione in esecuzione non annulla l'operazione. Un'operazione di esportazione annullata lascia i documenti già esportati in Cloud Storage e un'operazione di importazione annullata lascia gli aggiornamenti già apportati al database. Non puoi importare un'esportazione parzialmente completata.
Elimina un'operazione
gcloud
Utilizza il comando operations delete per rimuovere un'operazione dall'elenco delle operazioni recenti. Questo comando non eliminerà i file delle esportazioni da Cloud Storage.
gcloud datastore operations delete operation-name
Fatturazione e prezzi per esportazioni e importazioni gestite
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 contribuiscono ai costi di Google Cloud nei seguenti modi:
- Le letture e le scritture delle entità eseguite dalle operazioni di esportazione e importazione vengono conteggiate ai costi di Firestore in modalità Datastore. Le operazioni di esportazione comportano un'operazione di lettura per entità esportata. Le operazioni di importazione comportano un'operazione di scrittura per entità importata.
- 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 alcun avviso Budget di Google Cloud fino al completamento. Analogamente, le letture e le scritture eseguite durante un'operazione di esportazione o importazione vengono applicate alla tua quota giornaliera dopo il completamento dell'operazione.
Visualizzare i costi di esportazione e importazione
Le operazioni di esportazione e importazione applicano l'etichetta 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:
Differenze rispetto ai backup di Amministrazione Datastore
Se in precedenza hai utilizzato la Console di amministrazione Datastore per i backup, dovresti notare le seguenti differenze:
Le esportazioni create da un'esportazione gestita non vengono visualizzate nella Console di amministrazione di Datastore. Le esportazioni e le importazioni gestite sono un nuovo servizio che non condivide i dati con la funzionalità di backup e ripristino di App Engine, amministrata tramite la console Google Cloud.
Il servizio gestito di esportazione e importazione non supporta gli stessi metadati del backup di amministrazione di Datastore e non archivia lo stato di avanzamento nel database. Per informazioni su come verificare l'avanzamento delle operazioni di esportazione e importazione, consulta Gestione delle operazioni a lunga esecuzione
Non puoi visualizzare i log di servizio delle operazioni di esportazione e importazione gestite.
Il servizio di importazione gestito è compatibile con le versioni precedenti dei file di backup di amministrazione Datastore. Puoi importare un file di backup dell'amministratore di Datastore utilizzando il servizio di importazione gestito, ma non puoi importare l'output di un'esportazione gestita utilizzando la Console di amministrazione di Datastore.
Importazione in BigQuery
Per importare i dati da un'esportazione gestita in BigQuery, vedi Caricamento dei dati del servizio di esportazione di Datastore.
I dati esportati senza specificare un filtro entità non possono essere caricati in BigQuery. Se vuoi importare dati in BigQuery, la richiesta di esportazione deve includere uno o più nomi di tipo nel filtro delle entità.
Limite di colonne BigQuery
BigQuery impone un limite di 10.000 colonne per tabella. Le operazioni di esportazione generano uno schema di tabella BigQuery per ogni tipo. In questo schema, ogni proprietà univoca all'interno delle entità di un tipo diventa una colonna dello schema.
Se lo schema BigQuery di un tipo supera le 10.000 colonne, l'operazione di esportazione tenta di rimanere al di sotto del limite di colonne trattando le entità incorporate come BLOB. Se con questa conversione il numero di colonne nello schema è inferiore a 10.000, puoi caricare i dati in BigQuery, ma non puoi eseguire query sulle proprietà all'interno delle entità incorporate. Se il numero di colonne supera comunque 10.000, l'operazione di esportazione non genera uno schema BigQuery per il tipo e non puoi caricare i relativi dati in BigQuery.
Migrazione dell'agente di servizio
Firestore utilizza un agente di servizio Firestore per autorizzare le operazioni di importazione ed esportazione, anziché 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 Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com
In precedenza, Firestore utilizzava l'account di servizio predefinito di App Engine anziché l'agente di servizio Firestore. Se il database utilizza ancora l'account di servizio App Engine per importare o esportare i dati, ti consigliamo di seguire le istruzioni in questa sezione per eseguire la migrazione utilizzando l'agente di servizio Firestore.
- Account di servizio App Engine
PROJECT_ID@appspot.gserviceaccount.com
È preferibile utilizzare l'agente di servizio Firestore perché è specifico di Firestore. L'account di servizio App Engine è condiviso da più servizi.
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 vedere se il tuo database utilizza già l'agente di servizio Firestore.
-
Nella console Google Cloud, vai alla pagina Database.
- Seleziona il database richiesto dall'elenco dei database.
-
Nel menu di navigazione, fai clic su Importa/Esporta.
- 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 di queste tecniche:
- Esegui la migrazione di un progetto controllando e aggiornando le autorizzazioni per i bucket Cloud Storage (opzione consigliata).
- Aggiungi un vincolo di criterio a livello di organizzazione che interessi tutti i progetti all'interno dell'organizzazione.
La prima di queste tecniche è da preferire perché localizza l'ambito di effetto in un singolo progetto in modalità Datastore. La seconda tecnica non è preferita perché non esegue la migrazione delle autorizzazioni esistenti per i bucket Cloud Storage. Tuttavia, offre conformità di sicurezza a livello di organizzazione.
Esegui la migrazione controllando e aggiornando le autorizzazioni del bucket Cloud Storage
Il processo di migrazione prevede due passaggi:
- Aggiorna le autorizzazioni del bucket Cloud Storage. Per i dettagli, consulta la sezione seguente.
- Conferma la migrazione all'agente di servizio 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 le autorizzazioni dell'agente di servizio Firestore per il bucket in questione. Ad esempio, le operazioni che spostano dati in un altro progetto devono accedere a un bucket in quell'altro progetto. In caso contrario, queste operazioni non andranno a buon fine dopo la migrazione all'agente di servizio Firestore.
I flussi di lavoro di importazione ed esportazione che si trovano nello stesso progetto non richiedono modifiche alle autorizzazioni. Per impostazione predefinita, l'agente di servizio Firestore può accedere ai bucket nello stesso progetto.
Aggiorna le autorizzazioni per i 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 le autorizzazioni di lettura e scrittura per un bucket Cloud Storage. Se devi concedere autorizzazioni di sola lettura o sola scrittura, utilizza un ruolo personalizzato.
Il processo di migrazione descritto nella sezione seguente 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 Firestore. Una volta completata, la migrazione non può essere annullata.
-
Nella console Google Cloud, vai alla pagina Database.
- Seleziona il database richiesto dall'elenco dei database.
-
Nel menu di navigazione, fai clic su Importa/Esporta.
-
Se la migrazione del tuo progetto all'agente di servizio Firestore non è stata ancora eseguita, 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.
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. Il caricamento dell'elenco potrebbe richiedere alcuni minuti.
Questo elenco include i bucket utilizzati di recente nelle operazioni di importazione ed esportazione, ma al momento non concedere autorizzazioni di lettura e scrittura all'agente di servizio in modalità Datastore.
- Prendi nota del nome dell'entità dell'agente di servizio in modalità Datastore del progetto. Il nome dell'agente di servizio viene visualizzato sotto l'etichetta Agente di servizio a cui concedere l'accesso.
-
Per qualsiasi bucket nell'elenco che utilizzerai per future operazioni di importazione o esportazione, completa questi passaggi:
-
Nella riga della tabella del bucket, fai clic su Correggi. La pagina delle autorizzazioni del bucket si apre in una nuova scheda.
- Fai clic su Aggiungi.
- Nel campo Nuove entità, inserisci il nome dell'agente di servizio Firestore.
- Nel campo Seleziona un ruolo, scegli Agenti di servizio > Agente di servizio Firestore.
- Fai clic su Salva.
- Torna alla scheda con la pagina di importazione/esportazione in modalità Datastore.
- Ripeti questi passaggi per gli altri bucket dell'elenco. Assicurati di visualizzare tutte le pagine dell'elenco.
-
-
Fai clic su Esegui la migrazione all'agente di servizio Firestore. Se hai ancora bucket con controlli delle autorizzazioni non superati, devi confermare la migrazione facendo clic su Esegui la 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 tuo progetto:
-
Nella console Google Cloud, vai alla pagina Database.
- Seleziona il database richiesto dall'elenco dei database.
-
Nel menu di navigazione, fai clic su Importa/Esporta.
-
Cerca l'entità accanto all'etichetta I job di importazione/esportazione 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 il progetto non è stato migrato, nella parte superiore della pagina viene visualizzato un banner con un pulsante Verifica lo stato del bucket. Per completare la migrazione, consulta Eseguire la migrazione all'agente di servizio Firestore.
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 operazioni di importazione ed esportazione per utilizzare l'agente di servizio Firestore per autorizzare le richieste. Per impostare questo vincolo, vedi Creazione e gestione dei criteri dell'organizzazione .
L'applicazione di questo vincolo del criterio dell'organizzazione non concede automaticamente le autorizzazioni appropriate per il bucket Cloud Storage all'agente di servizio Firestore.
Se il vincolo crea errori di autorizzazione per qualsiasi flusso di lavoro di importazione o esportazione, puoi disabilitarlo per tornare a utilizzare l'account di servizio predefinito. Dopo aver controllato e aggiornato le autorizzazioni per il bucket Cloud Storage, puoi abilitare nuovamente il vincolo.