Esportazione e importazione di dati

Esportazione e importazione di dati

Puoi utilizzare il servizio gestito di esportazione e importazione di Firestore per recuperare i dati dall'eliminazione accidentale ed esportare i dati per l'elaborazione offline. Puoi esportare tutti i documenti o solo raccolte specifiche. Analogamente, puoi importare tutti i dati da un'esportazione o solo raccolte specifiche. I dati esportati da un database Firestore possono essere importati in un altro database Firestore. Puoi anche caricare le esportazioni di Firestore in BigQuery.

Questa pagina descrive come esportare e importare i documenti Firestore utilizzando il servizio gestito di esportazione e importazione e Cloud Storage. Il servizio gestito di esportazione e importazione di Firestore è disponibile tramite lo strumento a riga di comando di gcloud e l'API Firestore (REST, RPC).

Attenzione: l'esportazione dei dati da Firestore comporterà un'operazione di lettura per documento esportato. Tuttavia, queste letture non verranno visualizzate nella sezione relativa all'utilizzo della console. Assicurati di comprenderlo prima di configurare le esportazioni ricorrenti per evitare una fattura imprevista.

Prima di iniziare

Prima di poter utilizzare il servizio gestito di esportazione e importazione, 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.
   Nota: i progetti Firebase devono far parte del piano Blaze
2. Crea un bucket Cloud Storage per il tuo progetto in una località vicino alla località del tuo database Firestore. Non puoi utilizzare un bucket per i pagamenti a carico del richiedente per le operazioni di esportazione e importazione.

3. Assicurati che il tuo account disponga delle autorizzazioni necessarie per Firestore e Cloud Storage. Se sei il proprietario del progetto, il tuo account dispone delle autorizzazioni richieste. In caso contrario, i ruoli seguenti concedono le autorizzazioni necessarie per le operazioni di esportazione e importazione e per l'accesso a Cloud Storage:

   • Ruoli Firestore: Owner, Cloud Datastore Owner o Cloud Datastore Import Export Admin
     Nota: questi ruoli Datastore concedono anche autorizzazioni in Firestore.

   • Ruoli di Cloud Storage: Owner o Storage Admin

Autorizzazioni dell'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

[e-mail]

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

Nota: Firestore utilizzava in precedenza l'account di servizio predefinito App Engine anziché l'agente di servizio Firestore. Se il tuo database utilizza ancora l'account di servizio App Engine per importare o esportare i dati, ti consigliamo di eseguire la migrazione all'agente di servizio Firestore specifico per il servizio. Puoi visualizzare l'account utilizzato dalle operazioni di importazione ed esportazione nella console Google Cloud.

Se utilizzi Controlli di servizio VPC, devi utilizzare l'agente di servizio Firestore specifico del servizio per proteggere completamente le operazioni di importazione ed esportazione. I Controlli di servizio VPC non sono compatibili con l'account di servizio App Engine.

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:[e-mail]: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 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 tuo database utilizza l'agente di servizio Firestore o l'account di servizio App Engine legacy.

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.

L'agente di servizio richiede il ruolo Storage Admin affinché il bucket Cloud Storage venga utilizzato per l'operazione di esportazione o importazione.

Configura gcloud per il 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 progetto in uno dei seguenti modi:

• Accedi a gcloud dalla console della Google Cloud Platform utilizzando Cloud Shell.

  Avviare Cloud Shell

  Assicurati che gcloud sia configurato per il progetto corretto:

  gcloud config set project [PROJECT_ID]
  

• Installa e inizializza Google Cloud SDK.

Esporta i dati

Un'operazione di esportazione copia i documenti del 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 potrebbe includere modifiche apportate mentre l'operazione era in esecuzione.

Nota: devi esportare raccolte specifiche se prevedi di:

• Importare solo raccolte specifiche
• Carica i dati Firestore in BigQuery

Esportazione di tutti i documenti

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 Importa/Esporta.

4. Fai clic su Esporta.

5. Fai clic sull'opzione Esporta intero database.

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

7. Fai clic su Esporta.

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

gcloud

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

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

Sostituisci quanto segue:

• BUCKET_NAME: organizza le tue esportazioni aggiungendo un prefisso del file dopo il nome del bucket, ad esempio BUCKET_NAME/my-exports-folder/export-name. Se non fornisci un prefisso file, il servizio di esportazione gestito ne crea uno in base al timestamp attuale.

• DATABASE: nome del database da cui vuoi esportare i documenti. Per il database predefinito, utilizza --database='(default)'.

Una volta avviata un'operazione di esportazione, la chiusura del terminale non comporta l'annullamento dell'operazione. Consulta l'articolo su come annullare un'operazione.

Esportare raccolte specifiche

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 Importa/Esporta.

4. Fai clic su Esporta.

5. Fai clic sull'opzione Esporta uno o più gruppi di raccolte. Utilizza il menu a discesa per selezionare uno o più gruppi di raccolte.

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

7. Fai clic su Esporta.

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

gcloud

Per esportare gruppi di raccolte specifici, utilizza il flag --collection-ids. L'operazione esporta solo i gruppi di raccolte con gli ID raccolta specificati. Il gruppo di raccolte include tutte le raccolte e le sottoraccolte (in qualsiasi percorso) con l'ID raccolta specificato.

Nota: l'esportazione di una raccolta non esporta automaticamente le relative sottoraccolte. Devi inoltre specificare le sottoraccolte da esportare.

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

Ad esempio, puoi progettare una raccolta restaurants nel database foo in modo che includa più sottoraccolte, come ratings, reviews o outlets. Per esportare la raccolta specifica restaurants e reviews, il comando sarà il seguente:

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

Esportazione da un timestamp 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 minuti interi negli ultimi sette giorni, ma non precedente a 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, tra cui l'esportazione di tutti i documenti e l'esportazione di raccolte specifiche.

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

   gcloud

   Esegui questo comando 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 alla granularità dei minuti, ad esempio 2023-05-26T10:20:00.00Z.

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

   • 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 relativo agli ultimi sette giorni, ma non precedente a earliestVersionTime. Se i dati non esistono più nel timestamp specificato, viene generato un errore.
   • Non ti viene addebitato alcun costo per un'esportazione PITR non riuscita.

Importa dati

Dopo aver esportato i file in Cloud Storage, puoi importare di nuovo i documenti al loro interno nel tuo progetto o in un altro progetto. Tieni presente i seguenti punti relativi alle operazioni di importazione:

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

• Le importazioni non assegnano nuovi ID documento. Le importazioni utilizzano gli ID acquisiti al momento dell'esportazione. Durante l'importazione di un documento, il suo ID è riservato per evitare collisioni tra gli 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.

• Le operazioni di importazione non attivano le funzioni Cloud Functions. I Listener di snapshot ricevono gli aggiornamenti relativi alle operazioni di importazione.

• Il nome del 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 lo stesso nome dei file PARENT_FOLDER_NAME e .overall_export_metadata.

Importa tutti i documenti da un'esportazione

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 Importa/Esporta.

4. Fai clic su Importa.

5. Nel campo Nome file, inserisci il nome del file .overall_export_metadata di un'operazione di esportazione completata. Puoi utilizzare il pulsante Sfoglia per selezionare il file.

6. Fai clic su Importa.

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

gcloud

Utilizza il comando firestore import per importare documenti da un'operazione di esportazione precedente.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

Sostituisci quanto segue:

• BUCKET_NAME/EXPORT_PREFIX: posizione dei file di esportazione.

• DATABASE: nome del database. Per il database predefinito, utilizza --database='(default)'.

Ad esempio:

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Puoi confermare la posizione dei file di esportazione nel browser Cloud Storage nella console Google Cloud:

Apri il browser Cloud Storage

Una volta avviata un'operazione di importazione, la chiusura del terminale non annulla l'operazione. Consulta l'articolo su come annullare un'operazione.

Importare raccolte specifiche

Nota: per importare raccolte specifiche, devi utilizzare l'output di un'operazione di esportazione in cui hai esportato raccolte specifiche.

Console Google Cloud

Non puoi selezionare raccolte specifiche nella console. Usa invece il criterio gcloud.

gcloud

Per importare gruppi di raccolte specifici da un insieme di file di esportazione, utilizza il flag --collection-ids. L'operazione importa solo i gruppi di raccolte con gli ID raccolta indicati. Il gruppo di raccolte include tutte le raccolte e le sottoraccolte (in qualsiasi percorso) con l'ID raccolta specificato. Specifica il nome del database utilizzando il flag --database. Per il database predefinito, utilizza --database='(default)'.

Solo un'esportazione di gruppi di raccolte specifici supporta l'importazione di gruppi di raccolte specifici. Non puoi importare raccolte specifiche da un'esportazione di tutti i documenti.

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

Importare un'esportazione PITR

Segui i passaggi descritti in Importa tutti i documenti per importare il database esportato. Se nel database è già presente un documento, questo verrà sovrascritto.

Gestione delle operazioni di esportazione e importazione

Dopo aver avviato un'operazione di esportazione o importazione, Firestore assegna all'operazione un nome univoco. Puoi usare il nome dell'operazione per eliminare, annullare o controllare lo stato dell'operazione.

I nomi delle operazioni sono preceduti dal prefisso projects/[PROJECT_ID]/databases/(default)/operations/, ad esempio:

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

Tuttavia, puoi escludere il prefisso quando specifichi il nome di un'operazione per i comandi describe, cancel e delete.

Elenco di tutte le operazioni di esportazione e importazione

Console Google Cloud

Puoi visualizzare un elenco delle operazioni di esportazione e importazione 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 Importa/Esporta.

gcloud

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

gcloud firestore operations list

Controllare lo stato dell'operazione

Console Google Cloud

Puoi visualizzare lo stato di un'operazione di esportazione o importazione recente 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 Importa/Esporta.

gcloud

Utilizza il comando operations describe per visualizzare lo stato di un'operazione di esportazione o importazione.

gcloud firestore operations describe [OPERATION_NAME]

Stima il tempo di completamento

Una richiesta dello stato di un'operazione a lunga esecuzione restituisce le metriche workEstimated e workCompleted. Ognuna di queste metriche viene restituita in termini di numero di byte e numero di entità:

• workEstimated mostra il numero totale stimato di byte e documenti elaborati da un'operazione. Firestore potrebbe omettere questa metrica se non è possibile 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 potrebbe essere maggiore del valore di workEstimated.

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

Annullare un'operazione

Console Google Cloud

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 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 arrestare l'operazione. Il pulsante diventa Annullamento e poi diventa Annullato quando l'operazione si interrompe completamente.

gcloud

Utilizza il comando operations cancel per arrestare un'operazione in corso:

gcloud firestore operations cancel [OPERATION_NAME]

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

Elimina un'operazione

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

gcloud firestore operations delete [OPERATION_NAME]

Fatturazione e prezzi per le operazioni di esportazione e importazione

Prima di utilizzare il servizio gestito di esportazione e importazione, devi abilitare la fatturazione per il tuo progetto Google Cloud.

Le operazioni di esportazione e importazione vengono addebitate per letture e scritture dei documenti alle tariffe indicate nei prezzi di Firestore. Le operazioni di esportazione comportano un'operazione di lettura per documento esportato. Le operazioni di importazione comportano un'operazione di scrittura per ogni documento importato.

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

I costi delle operazioni di esportazione e importazione non vengono conteggiati ai fini del limite di spesa. Le operazioni di esportazione o importazione attiveranno gli avvisi sul budget di Google Cloud solo dopo il completamento. Allo stesso modo, le letture e le scritture eseguite durante un'operazione di esportazione o importazione vengono applicate alla tua quota giornaliera al termine dell'operazione. Le operazioni di esportazione e importazione non influiscono sull'utilizzo mostrato nella sezione Utilizzo della console.

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:

Nota: le operazioni di esportazione e importazione eseguite prima dell'8 settembre 2020 non hanno applicato l'etichetta goog-firestoremanaged.

Esporta in BigQuery

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

Limite di colonne BigQuery

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

Se lo schema BigQuery di un gruppo di raccolte supera le 10.000 colonne, l'operazione di esportazione Firestore tenta di rimanere al di sotto del limite di colonne trattando i campi mappa come byte. Se questa conversione riporta 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 della mappa. Se il numero di colonne supera ancora 10.000, l'operazione di esportazione non genera uno schema BigQuery per il gruppo di raccolte 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 log di LevelDB.

File di metadati

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

I file di metadati sono buffer di protocollo e puoi decodificarli con il compilatore di protocolli protoc. Ad esempio, puoi decodificare un file di metadati per determinare i gruppi di raccolte contenuti nei file di esportazione:

protoc --decode_raw < export0.export_metadata

Migrazione degli agenti 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

[e-mail]

Firestore utilizzava in precedenza l'account di servizio predefinito di App Engine anziché l'agente di servizio Firestore. Se il tuo 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

[e-mail]

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

Nota: se utilizzi Controlli di servizio VPC, devi utilizzare l'agente di servizio Firestore per proteggere completamente le operazioni di importazione ed esportazione. I Controlli di servizio VPC non sono compatibili con l'account di servizio App Engine.

Visualizza account 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.

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 una di queste tecniche:

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

La prima di queste tecniche è preferibile perché localizza l'ambito di effetto a un singolo progetto Firestore. 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 dei bucket Cloud Storage

Il processo di migrazione prevede due passaggi:

1. Aggiorna le autorizzazioni del bucket Cloud Storage. Consulta la seguente sezione 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 le autorizzazioni dell'agente di servizio Firestore per quel bucket. 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 riusciranno dopo la migrazione all'agente di servizio Firestore.

I flussi di lavoro di importazione ed esportazione che fanno parte 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 di altri progetti per concedere l'accesso all'agente di servizio [e-mail]. 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 passaggi seguenti per eseguire la migrazione dall'account di servizio App Engine all'agente di servizio Firestore. Una volta completata, la migrazione non può essere annullata.

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

   Vai a Database

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

3. Nel menu di navigazione, fai clic su Importa/Esporta.

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

   Fai clic su Verifica lo stato del bucket.

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

5. Prendi nota del nome dell'entità dell'agente di servizio Firestore del progetto. Il nome dell'agente di servizio viene visualizzato sotto l'etichetta Agente di servizio a cui concedere l'accesso.

6. Per qualsiasi bucket nell'elenco che utilizzerai per future operazioni di importazione o esportazione, completa questi passaggi:

   1. Nella riga della tabella del bucket, fai clic su Correggi. Si apre la pagina delle autorizzazioni del bucket 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 di Firestore.
   7. Ripeti questi passaggi per gli altri bucket dell'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 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:

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 I job di importazione/esportazione vengono eseguiti come.

   Se l'entità è [e-mail], significa che è già stata eseguita la migrazione del progetto 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 il pulsante Verifica lo stato del bucket. Vedi Eseguire la migrazione all'agente di servizio Firestore per completare la migrazione.

Aggiungi un vincolo dei 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 che le operazioni di importazione ed esportazione utilizzino 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 verificato e aggiornato le autorizzazioni per il bucket Cloud Storage, puoi abilitare di nuovo il vincolo.