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 do Cloud Run functions 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 seu Google Cloud projeto. Somente Google Cloud projetos 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 do Cloud Scheduler e uma função do Cloud

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

CLI do Firebase

  1. Instale a CLI do Firebase. Em um novo diretório, inicialize a CLI do Cloud Run 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');
  });
});
  3. No código anterior, modifique o seguinte:
    • Substitua BUCKET_NAME pelo nome do seu bucket.
    • Substitua YOUR_PROJECT_ID pelo ID do projeto .
    • 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 todos os grupos de coleções.

  4. Implante a função programada:

    firebase deploy --only functions
Google Cloud Console do
Criar uma função do Cloud

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

    Acesse o Cloud Functions

  2. Clique em Escrever uma função
  3. Insira um nome de função como firestore-export
  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) => {
  // Access the GCLOUD_PROJECT environment variable set by the runtime.
  const projectId =
    process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT;
  // Use the DATABASE_ID environment variable if set,
  // otherwise default to '(default)'
  const databaseId = process.env.DATABASE_ID || '(default)';
  const databaseName = client.databasePath(
    projectId,
    databaseId
  );

  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);
    });
};
     No código anterior, modifique o seguinte:
    • Substitua BUCKET_NAME pelo nome do seu bucket.

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

    • (Opcional) Se você estiver usando um banco de dados não padrão, defina a variável de ambiente DATABASE_ID ao criar a função do Cloud. Se você estiver usando um ambiente de execução em que GOOGLE_CLOUD_PROJECT não está definido automaticamente, talvez seja necessário defini-lo manualmente ou substituí-lo pelo ID do projeto no código.

  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 Google Cloud console:

    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 anterior.
  7. No campo Payload, insira start export. O job requer a definição do payload, mas a função do Cloud anterior 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.

Essa função do Cloud Run usa uma conta de serviço para autenticar e autorizar as operações de exportação. A conta de serviço usada depende da configuração do Cloud Run functions:

  • Cloud Functions (1ª geração): usa a conta de serviço padrão do App Engine: PROJECT_ID@appspot.gserviceaccount.com
  • Cloud Run functions (2ª geração): usa a conta de serviço padrão do Compute Engine service account: PROJECT_NUMBER-compute@developer.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:

  • Cloud Datastore Import Export Admin
  • Papel Storage Admin no bucket
  • Cloud Run Invoker (necessário para o Cloud Run functions (2ª geração) permitir que o serviço de acionamento invoque a função)

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 Google Cloud console:
Iniciar o Cloud Shell

  1. Atribua o papel Administrador de exportação e importação do Cloud Datastore. Substitua PROJECT_ID e SERVICE_ACCOUNT (por exemplo, PROJECT_ID@appspot.gserviceaccount.com ou PROJECT_NUMBER-compute@developer.gserviceaccount.com) e execute o seguinte comando:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member serviceAccount:SERVICE_ACCOUNT \
    --role roles/datastore.importExportAdmin

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

    gsutil iam ch serviceAccount:SERVICE_ACCOUNT:admin \
    gs://BUCKET_NAME

  3. (Para o Cloud Run functions (2ª geração)) Atribua o Invocador do Cloud Run papel à conta de serviço. Substitua PROJECT_ID e SERVICE_ACCOUNT e execute o seguinte comando:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member serviceAccount:SERVICE_ACCOUNT \
    --role roles/run.invoker

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 seu job do Cloud Scheduler na página Cloud Scheduler de o Google Cloud console.

  1. Acesse a página Cloud Scheduler no Google Cloud console.
    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

No console do Firebase, acesse Hosting e sem servidor > Funções.

Acessar :"Registros de funções"

Console do GCP

Acesse a página Cloud Run functions no Google Cloud console.

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