Pianificare le esportazioni di dati

Questa pagina descrive come pianificare le esportazioni dei dati di Cloud Firestore. Per eseguire le esportazioni in base a una pianificazione, ti consigliamo di utilizzare Cloud Functions e Cloud Scheduler.

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

Prima di iniziare

Prima di pianificare le esportazioni di dati gestite, devi completare le seguenti attività:

1. Abilita la fatturazione per il tuo progetto Google Cloud. Solo i progetti Google Cloud con la fatturazione abilitata possono utilizzare la funzionalità di esportazione e importazione.
   Nota:i progetti Firebase devono essere nel piano Blaze per utilizzare la funzionalità di esportazione e importazione gestita. L'abilitazione della fatturazione per Google Cloud esegue automaticamente l'upgrade del progetto Firebase al piano Blaze.
2. Le operazioni di esportazione richiedono un bucket Cloud Storage di destinazione. Crea un Cloud Storagebucket in una posizione vicina alla posizione del tuo database Cloud Firestore. Non puoi utilizzare un bucket con pagamenti a carico del richiedente per le operazioni di esportazione.

Crea una funzione Cloud e un job Cloud Scheduler

Segui i passaggi riportati di seguito per creare una funzione Cloud Functions Node.js che avvia un'esportazione di dati Cloud Firestore e un job Cloud Scheduler per chiamare la funzione:

Interfaccia a riga di comando di Firebase

1. Installa la Firebase CLI. In una nuova directory, inizializza la CLI per Cloud Functions:

   firebase init functions --project PROJECT_ID

   1. Seleziona JavaScript come lingua.
   2. (Facoltativo) Attiva ESLint.
   3. Inserisci y per installare le dipendenze.

2. Sostituisci il codice nel file functions/index.js con il seguente:

   const functions = require('firebase-functions');
   const firestore = require('@google-cloud/firestore');
   const client = new firestore.v1.FirestoreAdminClient();
   
   // Replace BUCKET_NAME
   const bucket = 'gs://BUCKET_NAME';
   
   exports.scheduledFirestoreExport = functions.pubsub
                                               .schedule('every 24 hours')
                                               .onRun((context) => {
   
     const projectId = process.env.GCP_PROJECT;
     const databaseName = 
       client.databasePath(projectId, '(default)');
   
     return client.exportDocuments({
       name: databaseName,
       outputUriPrefix: bucket,
       // Leave collectionIds empty to export all collections
       // or set to a list of collection IDs to export,
       // collectionIds: ['users', 'posts']
       collectionIds: []
       })
     .then(responses => {
       const response = responses[0];
       console.log(`Operation Name: ${response['name']}`);
     })
     .catch(err => {
       console.error(err);
       throw new Error('Export operation failed');
     });
   });
   index.js

3. Nel codice precedente, modifica quanto segue:
   • Sostituisci BUCKET_NAME con il nome del tuo bucket.
   • Sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto.
   • Modifica every 24 hours per impostare la pianificazione dell'esportazione. Utilizza la sintassi cron.yaml di App Engine o il formato cron di Unix (* * * * *).

   • Modifica collectionIds: [] per esportare solo i gruppi di raccolte specificati. Lascia invariato per esportare tutti i gruppi di raccolte.

     Nota: se esporti tutte le raccolte, tutte le operazioni di importazione successive devono importare tutte le raccolte nei file di dati di esportazione.

4. Esegui il deployment della funzione pianificata:

   firebase deploy --only functions

Console Google Cloud

Crea una funzione Cloud

1. Vai alla pagina Cloud Functions nella console Google Cloud:

   Vai a Cloud Functions

2. Fai clic su Scrivi una funzione.
3. Inserisci un nome funzione, ad esempio firestore-export.
4. In Trigger, seleziona Cloud Pub/Sub.
5. Nella sezione Argomento, seleziona Crea nuovo argomento. Inserisci un nome per l'argomento Pub/Sub, ad esempio initiateFirestoreExport. Prendi nota del nome dell'argomento perché ti servirà per creare il job Cloud Scheduler.
6. In Codice sorgente, seleziona Editor incorporato. Inserisci il seguente codice in index.js:

   const firestore = require('@google-cloud/firestore');
   const client = new firestore.v1.FirestoreAdminClient();
   // Replace BUCKET_NAME
   const bucket = 'gs://BUCKET_NAME'
   
   exports.scheduledFirestoreExport = (event, context) => {
     const databaseName = client.databasePath(
       YOUR_PROJECT_ID,
       '(default)'
     );
   
     return client
       .exportDocuments({
         name: databaseName,
         outputUriPrefix: bucket,
         // Leave collectionIds empty to export all collection groups
         // or define a list of collection group IDs:
         // collectionIds: ['users', 'posts']
         collectionIds: [],
       })
       .then(responses => {
         const response = responses[0];
         console.log(`Operation Name: ${response['name']}`);
         return response;
       })
       .catch(err => {
         console.error(err);
       });
   };

   Nel codice riportato sopra, modifica quanto segue:
   • Sostituisci BUCKET_NAME con il nome del tuo bucket.

   • Modifica collectionIds: [] per esportare solo i gruppi di raccolte specificati. Lascia invariato per esportare tutti i gruppi di raccolte.

     Nota: se esporti tutti i gruppi di raccolte, tutte le operazioni di importazione successive devono importare tutti i gruppi di raccolte nei file di dati di esportazione.
7. In package.json, aggiungi la seguente dipendenza:

   {
     "dependencies": {
       "@google-cloud/firestore": "^1.3.0"
     }
   }

8. In Funzione da eseguire, inserisci scheduledFirestoreExport, il nome della funzione in index.js.
9. Fai clic su Crea per eseguire il deployment della funzione Cloud Functions.

Crea un job Cloud Scheduler

A questo punto, crea un job Cloud Scheduler che chiama la tua funzione Cloud Functions:

1. Vai alla pagina Cloud Scheduler nella console Google Cloud:

   Vai a Cloud Scheduler

2. Fai clic su Crea job.
3. Inserisci un Nome per il job, ad esempio scheduledFirestoreExport.
4. Inserisci una Frequenza, ad esempio every 24 hours.
5. Seleziona un fuso orario.
6. In Target, seleziona Pub/Sub. Nel campo Argomento, inserisci il nome dell'argomento Pub/Sub che hai definito insieme alla tua funzione Cloud, initiateFirestoreExport nell'esempio precedente.
7. Nel campo Payload, inserisci start export. Il job richiede un payload definito, ma la funzione Cloud Functions precedente non utilizza effettivamente questo valore.
8. Fai clic su Crea.

A questo punto, hai distribuito Cloud Function e il job Cloud Scheduler, ma Cloud Function necessita ancora delle autorizzazioni di accesso per eseguire le operazioni di esportazione.

Configurare i permessi di accesso

Successivamente, autorizza Cloud Function ad avviare le operazioni di esportazione e a scrivere nel bucket GCS.

Questa funzione Cloud utilizza l'account di servizio predefinito del progetto per autenticare e autorizzare le operazioni di esportazione. Quando crei un progetto, viene creato un account di servizio predefinito con il seguente nome:

[e-mail]

Questo account di servizio richiede l'autorizzazione per avviare un'operazione di esportazione e per scrivere nel bucket Cloud Storage. Per concedere queste autorizzazioni, assegnare i seguenti ruoli IAM all'account di servizio predefinito:

• Cloud Datastore Import Export Admin
  Nota: questo ruolo Datastore concede anche le autorizzazioni per Cloud Firestore.
• Ruolo Owner o Storage Admin nel bucket

Per assegnare questi ruoli, puoi utilizzare gli strumenti da riga di comando gcloud e gsutil.

Se non sono già installati, puoi accedere a questi strumenti da Cloud Shell nella console Google Cloud:
Avvia Cloud Shell

1. Assegna il ruolo Cloud Datastore Import Export Admin. Sostituisci PROJECT_ID ed esegui il seguente comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member serviceAccount:[e-mail] \
       --role roles/datastore.importExportAdmin

2. Assegna il ruolo di Amministratore di archiviazione al tuo bucket. Sostituisci PROJECT_ID e BUCKET_NAME ed esegui il seguente comando:

   gsutil iam ch serviceAccount:[e-mail]:admin \
       gs://BUCKET_NAME

Se disabiliti o elimini il tuo account di servizio predefinito App Engine, la tua app App Engine perderà l'accesso al tuo database Cloud Firestore. Se hai disattivato il service account App Engine, puoi riattivarlo. Consulta la sezione Abilitare un service account. Se hai eliminato il tuo account di servizio App Engine negli ultimi 30 giorni, puoi ripristinarlo; consulta la sezione Ripristino dell'eliminazione di un account di servizio.

Metti alla prova il tuo lavoro Cloud Scheduler e Cloud Function

Puoi testare il job Cloud Scheduler nella pagina Cloud Scheduler della console Google Cloud.

1. Vai alla pagina Cloud Scheduler nella console Google Cloud.
   Vai a Cloud Scheduler

2. Nella riga del nuovo job Cloud Scheduler, fai clic su Esegui ora.

   Dopo qualche secondo, il job Cloud Scheduler dovrebbe aggiornare la colonna dei risultati a Success (Riuscito) e Last run (Ultima esecuzione) all'ora corrente. Potrebbe essere necessario fare clic su Aggiorna.

La pagina Cloud Scheduler conferma solo che il job ha chiamato la tua funzione Cloud Functions. Apri la pagina Cloud Functions per visualizzare i log della funzione.

Visualizza i log di Cloud Functions

Per verificare se la funzione Cloud ha avviato correttamente un'operazione di esportazione, apri i log della funzione:

Console Firebase

Vai alla pagina Cloud Functions nella console Firebase.

Vai ai log delle funzioni

Console di GCP

Vai alla pagina Cloud Functions nella console Google Cloud.

Vai al visualizzatore log

Visualizzare l'avanzamento dell'esportazione

Puoi utilizzare il comando gcloud firestore operations list per visualizzare lo stato di avanzamento delle operazioni di esportazione. Per maggiori informazioni, consulta Gestione delle operazioni di esportazione e importazione.

Una volta completata un'operazione di esportazione, puoi visualizzare i file di output nel bucket Cloud Storage:

Apri il browser Cloud Storage