Programar exportações de dados

Esta página descreve como programar exportações dos seus dados do Firestore. Para executar exportações em uma programação, recomendamos o uso de funções do Cloud Run e do Cloud Scheduler.

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.
  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 para Funções do Cloud Run:

    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');
      });
    });
  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.

  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 do 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.

  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 Scheduler e a função do Cloud foram implantados, 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:

PROJECT_ID@appspot.gserviceaccount.com

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
  • papel Owner ou Storage Admin no bucket

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

Se 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:PROJECT_ID@appspot.gserviceaccount.com \
        --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:PROJECT_ID@appspot.gserviceaccount.com: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.

Teste 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 no 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 Funções do Cloud Run no Console do Firebase.

Acessar :"Registros de funções"

Console do GCP

Acesse a página do Cloud Run 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