Esportazione e importazione delle entità

Questa pagina descrive come esportare e importare le entità Firestore 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 ripristinare gli eventi accidentali l'eliminazione dei dati ed esportarli 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 l'interfaccia di esportazione e importazione, considera quanto segue:

  • Il servizio di esportazione utilizza letture a coerenza finale. Non puoi assumere che un'esportazione avvenga in un unico 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, le informazioni richieste Gli indici vengono ricreati automaticamente utilizzando l'indice attuale del database le tue definizioni. Le impostazioni di indice del valore della proprietà per entità sono esportate e rispettate durante l'importazione.

  • Le importazioni non assegnano nuovi ID alle entità. Le importazioni utilizzano gli ID esistenti in l'ora dell'esportazione e sovrascrivere qualsiasi entità esistente con lo stesso ID. Durante un'importazione, gli ID vengono riservati durante il periodo di tempo in cui le entità in fase di importazione. Questa funzionalità evita i conflitti di ID con nuove entità se le scritture sono abilitate mentre è in corso un'importazione.

  • Se un'entità nel tuo database non è interessata da un'importazione, rimarrà in del database dopo l'importazione.

  • I dati esportati da un database in modalità Datastore possono essere importati in un altro database in modalità Datastore, anche in un altro progetto.

  • Il servizio di esportazione e importazione gestito limita il numero di esportazioni e importazioni simultanee a 50 e consente un massimo di 20 richieste di esportazione e importazione al minuto per un progetto. Per ogni richiesta, il servizio limita a 100 il numero di combinazioni di filtri delle entità.

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

  • Per importare solo un sottoinsieme di entità o per importare i dati in BigQuery, devi specificare un filtro delle entità nell'esportazione.

  • Il nome file .overall_export_metadata deve corrispondere al nome 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 PARENT_FOLDER_NAME, i contenuti delle sottocartelle e i .overall_export_metadata nome file uguale.

Prima di iniziare

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

  1. Abilitare la fatturazione per il progetto Google Cloud. Solo i progetti Google Cloud con la fatturazione abilitata possono utilizzare l'esportazione di importazione delle caratteristiche.

  2. Crea un bucket Cloud Storage nella stessa posizione del database Firestore in modalità Datastore. Non puoi utilizzare un Il richiedente paga il bucket per le operazioni di esportazione e importazione.

  3. Assegna un ruolo IAM al tuo account utente che conceda il datastore.databases.export, se esporti dati oppure l'autorizzazione datastore.databases.import, se importi dati. Ad esempio, il ruolo Datastore Import Export Admin concede entrambe le autorizzazioni.

  4. Se il bucket Cloud Storage si trova in un altro progetto, concedere 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 tuo progetto in una delle nei seguenti modi:

Autorizzazioni

Per eseguire le operazioni di esportazione e importazione, il tuo account utente e L'agente di servizio in modalità Datastore richiede le seguenti autorizzazioni di Identity and Access Management.

Autorizzazioni account utente

L'account utente o l'account di servizio che avvia l'operazione richiede datastore.databases.export e datastore.databases.import Autorizzazioni IAM. Se sei il proprietario del progetto, il tuo account dispone di: le autorizzazioni richieste. In caso contrario, i seguenti ruoli IAM concedi 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 in Concedi l'accesso.

Autorizzazioni agente di servizio

Le operazioni di esportazione e importazione utilizzano un agente di servizio Firestore 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 le tue Il bucket Cloud Storage si trova nello stesso progetto di Firestore , l'agente di servizio Firestore potrà accedere per impostazione predefinita.

Se il bucket Cloud Storage si trova in un altro progetto, deve concedere all'agente di servizio 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 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 del tuo progetto, viene utilizzato per assegnare un nome all'agente di servizio 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 le richieste dalla pagina Importa/Esporta nella console Google Cloud. Puoi anche per vedere se il database utilizza Firestore un agente di servizio o l'account di servizio legacy di App Engine.

  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.

Operazioni di esportazione

Per le operazioni di esportazione che coinvolgono un bucket in un altro progetto, modifica 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 Ruolo personalizzato IAM con autorizzazioni leggermente diverse da quelle contenute nei ruoli elencati in precedenza:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.list

Operazioni di importazione

Per le operazioni di importazione che coinvolgono un bucket Cloud Storage in un altro progetto, modificare le autorizzazioni del bucket per assegnare una delle seguenti opzioni Ruoli Cloud Storage per il servizio in modalità Datastore del progetto che contiene il database in modalità Datastore:

  • Amministratore Storage
  • Sia Storage Object Viewer sia Storage Legacy Bucket Reader

Puoi anche creare Ruolo personalizzato IAM con le seguenti autorizzazioni:

  • storage.buckets.get
  • storage.objects.get

Avvio di operazioni di esportazione e importazione gestite

Questa sezione descrive come avviare un'operazione di esportazione o importazione gestita.

Esportazione di tutte le entità

Console

  1. Nella console Google Cloud, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  1. Nel menu di navigazione, fai clic su Importa/Esporta.
  2. Fai clic su Esporta.
  3. Imposta il campo Spazio dei nomi su All Namespaces e poi Kind. su All Kinds.
  4. In Destination (Destinazione), inserisci il nome del bucket Cloud Storage.
  5. Fai clic su Esporta.

La console torna alla pagina Importa/Esporta. Un avviso segnala se la tua richiesta di esportazione gestita ha avuto esito positivo o negativo.

gcloud

Utilizza il comando gcloud firestore export per esportare tutte le entità del database.

 gcloud firestore export gs://bucket-name --async --database=DATABASE

dove bucket-name è il nome del tuo 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 sì non fornire un prefisso di file, il servizio di esportazione gestito ne crea uno in base l'ora corrente.

Usa il flag [--async][async-flag] per impedire a gcloud di attendere l'operazione da completare. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di 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, usa --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 delle seguenti 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"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi controllare il completamento.

Esportazione di tipi o spazi dei nomi specifici

Per esportare un sottoinsieme specifico di tipi e/o spazi dei nomi, fornisci un filtro delle entità con i valori per i tipi e gli ID spazio dei nomi. Ogni richiesta è limitata a 100 combinazioni di filtri di entità, dove 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 uno 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 invece gcloud.

  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. Fai clic su Esporta.

  5. Imposta il campo Spazio dei nomi su All Namespaces o sul nome di uno di dei tuoi spazi dei nomi.

  6. Imposta il Tipo su All Kinds o al nome di un tipo.

  7. In Destinazione, inserisci il nome del bucket Cloud Storage.

  8. Fai clic su Esporta.

La console torna alla pagina Importa/Esporta. Un avviso segnala se la tua richiesta di esportazione gestita ha avuto esito positivo o negativo.

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

dove bucket-name è il nome del tuo bucket Cloud Storage e un prefisso facoltativo, ad esempio bucket-name/datastore-exports/export-name. Non puoi riutilizzare lo stesso prefisso per un'altra esportazione operativa. Se sì non fornire un prefisso di file, il servizio di esportazione gestito ne crea uno in base l'ora corrente.

Usa il flag [--async][async-flag] per impedire a gcloud di attendere l'operazione da completare. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di 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, usa --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: ID dello spazio dei nomi (utilizza "" per l'ID dello 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 delle seguenti 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"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi controllare il completamento.

File di metadati

Un'operazione di esportazione crea un file di metadati per ogni coppia di tipo e spazio dei nomi specificata. I file di metadati sono in genere denominati NAMESPACE_NAME_KIND_NAME.export_metadata. Tuttavia, se uno spazio dei nomi o un tipo creerebbe un nome oggetto Cloud Storage non valido, il nome del file sarà export[NUM].export_metadata.

I file di metadati sono buffer di protocollo e possono essere decodificati 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 contenuti:

protoc --decode_raw < export0.export_metadata

Importazione di tutte le entità

Console

  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. Fai clic su Importa.

  5. Nel campo File, fai clic su Sfoglia e seleziona un'opzione .overall_export_metadata file.

    Assicurati che il file .overall_export_metadata non venga spostato dalla posizione predefinita.

  6. Imposta il campo Spazio dei nomi su All Namespaces e poi Kind. su All Kinds.

  7. Fai clic su Importa.

La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della tua richiesta di importazione gestita.

gcloud

Utilizza gcloud firestore import per importare tutte le entità esportate in precedenza con di Google Cloud.

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 overall_export_metadata all'interno del bucket Cloud Storage.

Usa il flag [--async][async-flag] per impedire a gcloud di attendere l'operazione da completare. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di 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, usa --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: il 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 delle seguenti 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"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi controllare il completamento.

Individuazione 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:

Apri il browser Cloud Storage

Puoi anche elencare e descrivere le operazioni completate. Il campo outputURL mostra il nome il 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 delle 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 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 invece gcloud.

  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. Fai clic su Importa.

  5. Nel campo File, fai clic su Sfoglia e seleziona un'opzione .overall_export_metadata file.

    Assicurati di importare il file .overall_export_metadata e non un .export_metadata file.

  6. Imposta il campo Spazio dei nomi su All Namespaces o su uno spazio dei nomi specifico.

  7. Imposta il campo Tipo su All Kinds o su un tipo specifico.

  8. Fai clic su Importa.

La console torna alla pagina Importa/Esporta. Un avviso segnala l'esito positivo o negativo della tua 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 overall_export_metadata all'interno del bucket Cloud Storage.

Usa il flag [--async][async-flag] per impedire a gcloud di attendere l'operazione da completare. Se ometti il flag --async, puoi digitare Ctrl+c per interrompere l'attesa di 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, usa --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: il 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: ID dello spazio dei nomi (utilizza "" per l'ID dello 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 delle seguenti 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"
  }
}
La risposta è un'operazione a lunga esecuzione, di cui puoi controllare il completamento.

Esportazione e importazione da 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 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, inclusa l'esportazione di tutte le entità e l'esportazione di tipi o spazi dei nomi specifici.

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

    gcloud

    Esegui il comando seguente per esportare il database nel 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.

    È supportata anche l'[esportazione di un sottoinsieme specifico di tipi e/o spazi dei nomi con un filtro delle entità][export-kind].

    Prima di esportare i dati PITR, tieni presente quanto segue:

    • Specifica il timestamp in RFC 3339 standard. Ad esempio, 2020-09-01T23:59:30.234233Z.
    • Assicurati che il timestamp specificato sia un timestamp di un minuto intero compreso negli ultimi sette giorni, ma non precedente al giorno earliestVersionTime. Se i dati non esistono più al timestamp specificato, verrà visualizzato un errore.
    • Non ti verrà addebitato alcun importo per un'esportazione PITR non riuscita.

  2. Importa in un database.

    Segui i passaggi descritti in Importare tutte le entità per importare il database esportato. Se esiste già un'entità nel tuo verrà sovrascritto. [L'importazione di un sottoinsieme specifico di tipi e/o spazi dei nomi con un filtro di entità] è supportata anche [import-kind].

Importa trasformazioni

Quando importi entità da un altro progetto, ricorda che le chiavi di entità includono l'ID progetto. Un'operazione di importazione aggiorna le chiavi delle entità e le principali proprietà di riferimento importare i dati con l'ID del progetto di destinazione. Se questo aggiornamento aumenta le dimensioni delle entità, può causare errori "entità troppo grande" o "voci dell'indice troppo grandi" per le operazioni di importazione.

Per evitare entrambi gli errori, esegui l'importazione in un progetto di destinazione con un progetto più breve ID. Ciò non influisce sulle operazioni di importazione con dati provenienti dallo stesso progetto.

Gestione di operazioni a lunga esecuzione

Le operazioni di importazione ed esportazione gestite sono operazioni a lunga esecuzione. Il completamento di queste chiamate al metodo può richiedere molto tempo.

Dopo aver avviato un'operazione di esportazione o importazione, la modalità Datastore 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 dal prefisso projects/[PROJECT_ID]/databases/(default)/operations/ Ad esempio:

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

Puoi omettere il prefisso quando specifichi il nome di un'operazione Comandi gcloud.

Elenco di tutte le operazioni a lunga esecuzione

Puoi visualizzare le operazioni in corso e completate di recente nei seguenti modi. Le operazioni vengono 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.

  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 Importazione/esportazione.

gcloud

Per elencare le operazioni a lunga esecuzione, utilizza elenco operazioni gcloud datastore . 

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 delle seguenti 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.

  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 Importazione/esportazione.

gcloud

Utilizza il comando operations describe per visualizzare 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: il 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 delle seguenti 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 complessivo 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 numero di byte e numero di entità:

  • workEstimated mostra il numero totale stimato di byte e documenti che verrà elaborato da un'operazione. La modalità Datastore potrebbe omettere questa metrica se non può fare 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 potrebbero essere più grandi del pari a workEstimated.

Dividi workCompleted per workEstimated per ottenere una stima approssimativa. Questo potrebbe non essere precisa, perché dipende da statistiche ritardate .

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 termine di un'operazione, la relativa descrizione contiene "done": true. Visualizza il valore del campo state per il risultato dell'operazione. Se il campo done non è impostato nella risposta, il suo valore è false. Non dipendono dall'esistenza del valore done per le operazioni in corso.

Annullare un'operazione

Console

Puoi annullare un'operazione di esportazione o importazione in esecuzione nella pagina Importa/Esporta della console 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 Importazione/esportazione.

Nella tabella Importazioni ed esportazioni recenti, le operazioni in esecuzione includono un pulsante Annulla nella colonna Completata. Fai clic sull' Pulsante Annulla per interrompere l'operazione. Il pulsante diventa Cancellazione e poi su Annullato quando l'operazione si interrompe completamente.

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 invariati gli aggiornamenti già apportati al database. Tu impossibile importare un'esportazione parzialmente completata.

Elimina un'operazione

gcloud

Utilizza il comando operations delete per rimuovere un'operazione dal delle operazioni recenti. Questo comando non eliminerà i file di esportazione di archiviazione ideale in Cloud Storage.

gcloud datastore operations delete operation-name

Fatturazione e prezzi per le esportazioni e le importazioni gestite

Devi abilitare la fatturazione per il tuo progetto Google Cloud prima di utilizzare il servizio gestito di esportazione e importazione. Contributo alle operazioni di esportazione e importazione 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 fini dei costi di Firestore in modalità Datastore. Le operazioni di esportazione sono soggette a una lettura operativa per entità esportata. Le operazioni di importazione comportano un'operazione di scrittura per ogni entità importata.
  • I file di output archiviati in Cloud Storage vengono conteggiati ai fini del calcolo Costi di archiviazione dei dati di Cloud Storage.

Le operazioni di esportazione o importazione non attivano gli avvisi relativi al budget di Google Cloud fino al termine. Analogamente, le operazioni di lettura e scrittura eseguite durante un'operazione di esportazione applicata alla tua quota giornaliera al termine dell'operazione.

Visualizzazione dei 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:

Accedi all&#39;etichetta goog-firestoremanaged dal menu dei filtri.

Differenze rispetto ai backup di Datastore Admin

Se in precedenza hai utilizzato la Console di amministrazione di Datastore per i backup, tieni presente 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 una nuova servizio che non condivide dati con il servizio 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 Datastore e non memorizza lo stato di avanzamento del database. Per informazioni su come controllare l'avanzamento le operazioni di esportazione e importazione, Gestione delle operazioni a lunga esecuzione

  • Non puoi visualizzare i log di servizio delle operazioni di esportazione e importazione gestite.

  • Il servizio di importazione gestita è compatibile con le versioni precedenti di Datastore File di backup dell'amministratore. Puoi importare un file di backup dell'amministratore Datastore utilizzando il servizio di importazione gestito, ma non è possibile importare l'output di un esportarla utilizzando la console di amministrazione di Datastore.

Importazione in BigQuery

Per importare i dati da un'esportazione gestita in BigQuery, consulta Caricare i dati del servizio di esportazione di Datastore.

I dati esportati senza specificare un filtro entità non possono essere è stato caricato in BigQuery. Se vuoi importare i 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 una tabella BigQuery schema per ogni tipo. In questo schema, ogni proprietà univoca all'interno del parametro delle entità diventa una colonna di 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 questa conversione genera di colonne nello schema inferiore a 10.000, puoi caricare i dati in BigQuery, ma non puoi eseguire query sulle proprietà all'interno di entità incorporate. Se il numero di colonne è ancora superiore a 10.000, l'operazione di esportazione non generare uno schema BigQuery per il tipo e non puoi caricarne i dati in BigQuery.

Migrazione dell'agente di servizio

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

Agente di servizio Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Firestore in precedenza utilizzava il 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 dati, ti consigliamo di seguire le istruzioni in questa sezione per eseguire la migrazione all'utilizzo dell'agente di servizio Firestore.

Service account App Engine
PROJECT_ID@appspot.gserviceaccount.com

È preferibile utilizzare l'agente di servizio Firestore perché è specifico in Firestore. L'account di servizio App Engine è condiviso da più di un servizio.

Visualizza account di autorizzazione

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

  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 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 uno dei queste tecniche:

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

Eseguire la migrazione controllando e aggiornando le autorizzazioni dei bucket Cloud Storage

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 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 Firestore 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, non vanno a buon fine dopo la migrazione al servizio Firestore un agente.

I flussi di lavoro di importazione ed esportazione che rimangono all'interno dello 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 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 nel bucket Cloud Storage. Se devi concedere solo l'autorizzazione di lettura o solo scrittura autorizzazioni, utilizza ruolo personalizzato.

Il processo di migrazione descritto nella sezione seguente 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 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 è ancora stata eseguita la migrazione del progetto all'agente di servizio Firestore, viene visualizzato un banner che descrive la migrazione e un pulsante Controlla stato del bucket. Il passaggio successivo ti aiuta a identificare e risolvere 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 l'elenco per completare il caricamento.

    Questo elenco include bucket recenti utilizzati nelle operazioni di importazione ed esportazione, ma attualmente non forniscono dati le autorizzazioni di scrittura per l'agente di servizio in modalità Datastore.

  5. Prendi nota del nome dell'entità della modalità Datastore del progetto dell'agente di servizio di servizio di Google Cloud. Il nome dell'agente di servizio viene visualizzato sotto 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 dell'agente di servizio Firestore.
    4. Nel campo Seleziona un ruolo, scegli Agenti di servizio > Agente di servizio Firestore.
    5. Fai clic su Salva.
    6. Torna alla scheda con la pagina di importazione/esportazione in modalità Datastore.
    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, confermare la migrazione facendo clic su Migra.

    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 a Firestore dell'agente di servizio di servizio di Google Cloud. La migrazione non può essere annullata.

    Se non è stata eseguita la migrazione del progetto, nella parte superiore della pagina viene visualizzato un banner con il pulsante Verifica stato del bucket. Per completare la migrazione, consulta Eseguire la migrazione all'agente di servizio Firestore.

Aggiungere un vincolo dei criteri a livello di organizzazione

  • Imposta il seguente vincolo nel criterio della tua organizzazione:

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

    Questo vincolo richiede le operazioni di importazione ed esportazione per utilizzare Agente di servizio Firestore per autorizzare le richieste. Per impostare questo vincolo, consulta Creazione e gestione dei criteri dell'organizzazione .

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