Como programar uma exportação

Nesta página, descrevemos como programar as exportações dos dados do Firestore no modo Datastore. Para executar exportações em uma programação, recomendamos o uso de funções do Cloud Run e do Cloud Scheduler. Crie uma Função do Cloud que inicie exportações e use o Cloud Scheduler para executar a função.

Antes de começar

Antes de programar exportações de dados, é preciso concluir 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. Crie um bucket do Cloud Storage em um local próximo ao local do banco de dados do modo Datastore. As operações de exportação exigem um bucket de destino do Cloud Storage. Não é possível usar um bucket de pagamentos do solicitante para operações de exportação.

Criar um job do Cloud Function e Cloud Scheduler

Siga as etapas abaixo para criar uma Função do Cloud que inicie exportações de dados e um job do Cloud Scheduler para chamar essa função:

Criar uma Função do Cloud datastore_export

  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 datastoreExport
  4. Em Gatilho, selecione Cloud Pub/Sub O Cloud Scheduler usa o tópico do Pub/Sub para chamar a função.
  5. No campo Tópico, selecione Criar um tópico. Digite um nome para o tópico Pub/Sub, por exemplo, startDatastoreExport. Anote o nome do tópico, conforme necessário para criar o job no Cloud Scheduler.
  6. Em Código-fonte, selecione Editor integrado.
  7. Na lista suspensa Ambiente de execução, selecione Python 3.7.
  8. Digite o seguinte código para main.py:
    # Copyright 2021 Google LLC All Rights Reserved.
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    import base64
    import json
    import os
    
    from google.cloud import datastore_admin_v1
    
    project_id = os.environ.get("GCP_PROJECT")
    client = datastore_admin_v1.DatastoreAdminClient()
    
    
    def datastore_export(event, context):
        """Triggers a Datastore export from a Cloud Scheduler job.
    
        Args:
            event (dict): event[data] must contain a json object encoded in
                base-64. Cloud Scheduler encodes payloads in base-64 by default.
                Object must include a 'bucket' value and can include 'kinds'
                and 'namespaceIds' values.
            context (google.cloud.functions.Context): The Cloud Functions event
                metadata.
        """
        if "data" in event:
            # Triggered via Cloud Scheduler, decode the inner data field of the json payload.
            json_data = json.loads(base64.b64decode(event["data"]).decode("utf-8"))
        else:
            # Otherwise, for instance if triggered via the Cloud Console on a Cloud Function, the event is the data.
            json_data = event
    
        bucket = json_data["bucket"]
        entity_filter = datastore_admin_v1.EntityFilter()
    
        if "kinds" in json_data:
            entity_filter.kinds = json_data["kinds"]
    
        if "namespaceIds" in json_data:
            entity_filter.namespace_ids = json_data["namespaceIds"]
    
        export_request = datastore_admin_v1.ExportEntitiesRequest(
            project_id=project_id, output_url_prefix=bucket, entity_filter=entity_filter
        )
        operation = client.export_entities(request=export_request)
        response = operation.result()
        print(response)
    
  9. Em requirements.txt, adicione a seguinte dependência:
    google-cloud-datastore==2.20.0
    
  10. Em Ponto de entrada, insira datastore_export, o nome da função em main.py.
  11. Clique em Implantar para implantar a função do Cloud.

Configurar as permissões de acesso

Em seguida, conceda permissão ao Cloud Function para iniciar operações de exportação e gravar no bucket do Cloud Storage.

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

Essa conta de serviço precisa de permissão para iniciar operações 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 Storage Object User no bucket

Use a CLI do Google Cloud para atribuir essas funções. Você pode acessar isso ferramenta do 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 Usuário do objeto do Storage ao bucket. Substitua bucket_name e project_id e execute o seguinte comando:

    gcloud storage buckets add-iam-policy-binding gs://bucket_name \
        --member=serviceAccount:project_id@appspot.gserviceaccount.com \
        --role=roles/storage.objectUser

Criar um job do Cloud Scheduler

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

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

  4. Insira uma Frequência no formato unix-cron.

  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, startDatastoreExport no exemplo acima.

  7. No campo Payload, insira um objeto JSON para configurar a operação de exportação. A função do Cloud datastore_export requer um valor bucket. Também é possível incluir valores kinds ou namespaceIDs para definir um filtro de entidade, por exemplo:

    Exportar todas as entidades

    {
    "bucket": "gs://bucket_name"
    }
    

    Exportar com filtro de entidade

    • Exportar entidades do tipo User ou Task de todos os namespaces:

      {
      "bucket": "gs://bucket_name",
      "kinds": ["User", "Task"]
      }
      

    • Exportar entidades do tipo User ou Task dos namespaces padrão e Testers. Use uma string vazia ("") para especificar o namespace padrão:

      {
      "bucket": "gs://bucket_name",
      "kinds": ["User", "Task"],
      "namespaceIds": ["", "Testers"]
      }
      

    • Exportar entidades de qualquer tipo dos namespaces padrão e Testers. Use uma string vazia ("") para especificar o namespace padrão:

      {
      "bucket": "gs://bucket_name",
      "namespaceIds": ["", "Testers"]
      }
      

    Sendo bucket_name o nome do bucket do Cloud Storage.

  8. Clique em Criar.

Testar suas exportações programadas

Para testar o job do Cloud Function e do Cloud Scheduler, execute-o na página Cloud Scheduler do console do Google Cloud. Se for bem-sucedido, isso iniciará uma operação de exportação real.

  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, clique em Atualizar. O job do Cloud Scheduler deverá atualizar a coluna de resultados para Sucesso e a Última execução para o horário atual.

A página do Cloud Scheduler confirma apenas que o job enviou uma mensagem para o tópico do Pub/Sub. Para ver se a solicitação de exportação foi bem-sucedida, veja os registros da sua Função do Cloud.

Exibir os registros da função do Cloud

Para ver se a função do Cloud iniciou uma operação de exportação, faça o seguinte: consulte a página Análise de registros no console do Google Cloud.

Acessar o Explorador de registros

O registro do Cloud Function relata erros e iniciações de exportação bem-sucedidas.

Ver progresso da exportação

É possível usar o comando gcloud datastore operations list para ver o progresso das operações de exportação. Consulte como listar todas as operações de longa duraçã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: O serviço de exportação gerenciado usa um carimbo de data/hora para organizar suas operações de exportação:

Acesse o Cloud Storage