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

Antes de começar

Antes de agendar 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 Firebase CLI. Em um novo diretório, inicialize a CLI do Cloud Functions:

    firebase init functions --project PROJECT_ID
    1. Selecione JavaScriptcomo o idioma.
    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 || process.env.GCLOUD_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 agendada:

    firebase deploy --only functions
Cloud Console
Criar uma função do Cloud
  1. Abra a página Cloud Functions no Console do Cloud:

    Abrir a página do 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 embutido. 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.GCLOUD_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. Abaixo de 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 Functions:

  1. Abra a página Cloud Scheduler no Console do Cloud:

    Abrir a página do 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:

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.

Caso essas ferramentas ainda não tenham sido instaladas, é possível acessá-las 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 Admin 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
    

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

É possível testar seu job do Cloud Scheduler na página Cloud Scheduler do Console do Google Cloud.

  1. Abra a página Cloud Scheduler no Console do Cloud.
    Abrir a página do Cloud Scheduler

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

    Após alguns segundos, o job do Cloud Scheduler deverá 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

Abra a página do Cloud Functions no Console do Firebase.

Abrir a página de Registros de funções

Console do GCP

Abra a página Cloud Functions no Console do Cloud.

Abrir a página do 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:

Abra o navegador do Cloud Storage