Programar exportações de dados

Nesta página, descrevemos como agendar exportações dos seus dados do Cloud 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 do seu projeto do Google Cloud Platform. Somente os projetos do GCP com faturamento ativado podem usar o recurso de exportação e importação.
  2. As operações de exportação exigem um intervalo de destino do Cloud Storage. Crie um intervalo do Cloud Storage em um local próximo ao local do banco de dados do Cloud Firestore. Não é possível usar um intervalo 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 para Node.js que inicia uma exportação de dados do Cloud 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 functions/index.js arquivo 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 databaseName =
        client.databasePath(process.env.GCP_PROJECT, '(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']}`);
        return response;
      })
      .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 intervalo.
    • 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 coleta especificados. Deixe como está para exportar todas as coleções.

  4. Implante a função programada

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

    Abrir a página do Cloud Functions

  2. Clique em Criar função.
  3. Insira um nome de função como firestoreExport
  4. Em Acionador, 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 intervalo.
    • Modifique collectionIds: [] para exportar somente os grupos de coleta 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 do Cloud Scheduler no Console do GCP:

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

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

Se essas ferramentas ainda não tiverem sido instaladas, acesse-as no Cloud Shell, no Console do Google Cloud Platform:
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 intervalo. 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 o job do Cloud Scheduler na página do Cloud Scheduler no Console do Google Cloud Platform.

  1. Abra a página do Cloud Scheduler no Console do GCP.
    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 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

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 do Cloud Functions no Console do GCP.

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 intervalo do Cloud Storage:

Abra o navegador do Cloud Storage