Programar exportações de dados

Programar exportações de dados

Esta página descreve como programar exportações dos seus dados do Firestore. Para executar exportações em um agendamento, recomendamos o uso do Cloud Functions e do Cloud Scheduler.

Atenção: a exportação de dados do Firestore gera uma operação de leitura por documento exportado. No entanto, essas leituras não aparecerão na seção de uso do console. Certifique-se de entender isso antes de configurar exportações recorrentes para evitar uma fatura inesperada.

Antes de começar

Antes de programar exportações de dados gerenciados, conclua as seguintes tarefas:

1. Ative o faturamento para o projeto do Google Cloud. Apenas projetos do Google Cloud com faturamento ativado podem usar o recurso de exportação e importação.
   Observação: os projetos do Firebase precisam estar no plano Blaze para usar o recurso de exportação e importação gerenciada. A ativação do faturamento do Google Cloud faz o upgrade automático do seu projeto do Firebase para o plano Blaze.
2. As operações de exportação exigem um bucket de destino do Cloud Storage. Crie um bucket do Cloud Storage em um local próximo ao local do banco de dados do Firestore. Não é possível usar um bucket de pagamentos do solicitante para operações de exportação.

Criar um job Cloud Scheduler e uma função do Cloud

Siga as etapas abaixo para criar uma Função do Cloud em Node.js que inicie uma exportação de dados do Firestore e um job do Cloud Scheduler para chamar essa função:

Firebase CLI

1. Instale a CLI do Firebase. Em um novo diretório, inicialize a CLI do Cloud Functions:

   firebase init functions --project PROJECT_ID

   1. Selecione JavaScript como a linguagem.
   2. Opcionalmente, ative o ESLint.
   3. Digite y para instalar dependências.

2. Substitua o código no arquivo functions/index.js pelo seguinte:

   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. No código acima, modifique o seguinte:
   • Substitua BUCKET_NAME pelo nome do bucket.
   • Modifique every 24 hours para definir a programação de exportação. Use a sintaxe cron.yaml do AppEngine ou o formato unix-cron (* * * * *).

   • Modifique collectionIds: [] para exportar somente os grupos de coleções especificados. Deixe como está para exportar todas as coleções.

     Observação: se você exportar todas as coleções, qualquer operação de importação seguinte precisará importar todas as coleções nos arquivos de dados de exportação.

4. Implante a função programada:

   firebase deploy --only functions

Console do Google Cloud

Criar uma função do Cloud

1. Acesse a página Cloud Functions no console do Google Cloud:

   Acesse o Cloud Functions

2. Clique em Criar função.
3. Insira um nome de função como firestoreExport
4. Em Gatilho, selecione Cloud Pub/Sub
5. Em Tópico, selecione Criar novo tópico. Digite um nome para o tópico pub/sub, por exemplo, initiateFirestoreExport. Anote o nome do tópico, conforme necessário para criar o job no Cloud Scheduler.
6. Em Código-fonte, selecione Editor in-line. Digite o seguinte código em 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(
       process.env.GCP_PROJECT,
       '(default)'
     );
   
     return client
       .exportDocuments({
         name: databaseName,
         outputUriPrefix: bucket,
         // Leave collectionIds empty to export all collections
         // or define a list of collection IDs:
         // collectionIds: ['users', 'posts']
         collectionIds: [],
       })
       .then(responses => {
         const response = responses[0];
         console.log(`Operation Name: ${response['name']}`);
         return response;
       })
       .catch(err => {
         console.error(err);
       });
   };

   No código acima, modifique o seguinte:
   • Substitua BUCKET_NAME pelo nome do bucket.

   • Modifique collectionIds: [] para exportar somente os grupos de coleções especificados. Deixe como está para exportar todas as coleções.

     Observação: se você exportar todas as coleções, qualquer operação de importação seguinte precisará importar todas as coleções nos arquivos de dados de exportação.
7. Em package.json, adicione a seguinte dependência:

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

8. Em Função a ser executada, insira scheduledFirestoreExport, o nome da função em index.js.
9. Clique em Criar para implantar a função do Cloud.

Criar um job do Cloud Scheduler

Em seguida, crie um job do Cloud Scheduler que chame a função do Cloud:

1. Acesse a página Cloud Scheduler no console do Google Cloud:

   Acessar o Cloud Scheduler

2. Clique em Criar job.
3. Insira um Nome para o job, como scheduledFirestoreExport.
4. Insira uma Frequência, por exemplo, every 24 hours.
5. Selecione um fuso horário.
6. Em Destino, selecione Pub/Sub. No campo Tópico, insira o nome do tópico pub/sub que você definiu com a função do Cloud, initiateFirestoreExport no exemplo acima.
7. No campo Payload, insira start export. O job requer a definição do payload, mas a função do Cloud acima não usa esse valor.
8. Clique em Criar.

Neste ponto, o job do Cloud Function e Cloud Scheduler foi implantado, mas a função do Cloud ainda precisa de permissões de acesso para executar operações de exportação.

Configurar as permissões de acesso

Em seguida, conceda à função do Cloud a permissão para iniciar operações de exportação e gravar no bucket do GCS.

Esta função do Cloud usa a conta de serviço padrão do projeto para autenticar e autorizar as operações de exportação. Quando um projeto é criado, uma conta de serviço padrão é criada para você com o seguinte nome:

[e-mail]

A conta de serviço precisa de permissão para iniciar uma operação de exportação e gravar no bucket do Cloud Storage. Para conceder essas permissões, atribua os seguintes papéis de IAM à conta de serviço padrão:

• Cloud Datastore Import Export Admin
  Observação: esse papel do Datastore também concede permissões para o Firestore.
• papel Owner ou Storage Admin no bucket

Use as ferramentas de linha de comando gcloud e gsutil para atribuir essas funções.

Se elas ainda não estiverem instaladas, acesse essas ferramentas no Cloud Shell, no console do Google Cloud:
Iniciar o Cloud Shell

1. Atribua o papel Administrador de exportação e importação do Cloud Datastore. Substitua PROJECT_ID e execute o seguinte comando:

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

2. Atribua o papel Administrador do Storage ao bucket. Substitua PROJECT_ID e BUCKET_NAME e execute o seguinte comando:

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

Ao desativar ou excluir sua conta de serviço padrão do App Engine, seu aplicativo do App Engine perderá o acesso ao banco de dados do Firestore. Se você desativou sua conta de serviço do App Engine, poderá reativá-la. Consulte este link para ver como fazer isso. Se você excluiu sua conta de serviço do App Engine nos últimos 30 dias, poderá restaurá-la. Consulte Como cancelar a exclusão de uma conta de serviço.

Testar o job do Cloud Scheduler e a função do Cloud

É possível testar o job do Cloud Scheduler na página Cloud Scheduler do console do Google Cloud.

1. Vá para a página Cloud Scheduler no Console do Google Cloud.
   Acessar o Cloud Scheduler

2. Na linha do novo job do Cloud Scheduler, clique em Executar agora.

   Após alguns segundos, o job do Cloud Scheduler deve atualizar a coluna de resultados para Sucesso e a Última execução para o horário atual. Pode ser necessário clicar em Atualizar.

A página do Cloud Scheduler apenas confirma que o job chamou a função do Cloud. Abra a página da função do Cloud para ver os registros da função.

Exibir os registros da função do Cloud

Para verificar se a função do Cloud iniciou com êxito uma operação de exportação, abra os registros da função:

Console do Firebase

Acesse a página Cloud Functions no console do Firebase.

Acessar :"Registros de funções"

Console do GCP

Acesse a página de visão geral do Cloud Functions no console do Google Cloud.

Acessar o visualizador de registros

Ver progresso da exportação

É possível usar o comando gcloud firestore operations list para visualizar o progresso das operações de exportação. Veja como gerenciar operações de exportação e importação.

Após a conclusão de uma operação de exportação, será possível visualizar os arquivos de saída no bucket do Cloud Storage:

Abrir o navegador do Cloud Storage