Como programar uma exportação

Nesta página, você aprende a programar uma exportação automática do Cloud Firestore em entidades do modo Datastore.

Para programar exportações das entidades, é recomendável implantar um serviço do App Engine que chame o recurso de exportação gerenciada do modo Datastore. Depois de implantado, esse serviço pode ser executado em uma programação com o Cron Service do App Engine.

Antes de começar

Antes de programar exportações de dados com o App Engine e o recurso de exportação gerenciada, realize as seguintes tarefas:

  1. Ative o faturamento para seu projeto do GCP. Somente os projetos do GCP com faturamento ativado podem usar o recurso de exportação e importação.

  2. Crie um intervalo do Cloud Storage para seu projeto. Todas as exportações e importações gerenciadas dependem do Cloud Storage. Use o mesmo local para o intervalo do Cloud Storage e o banco de dados do modo Datastore.

    Para encontrar o local do banco de dados do modo Datastore, consulte Como visualizar o local do seu projeto.

  3. Instale o SDK do Google Cloud para implantar o aplicativo.

Como configurar exportações programadas

Depois de concluir os requisitos acima, configure as exportações programadas executando os procedimentos a seguir.

Como configurar permissões de acesso

Este aplicativo usa a conta de serviço padrão do App Engine para autenticar e autorizar as solicitações de exportação. Ao criar um projeto, o App Engine cria uma conta de serviço padrão com o seguinte formato:

[PROJECT_ID]@appspot.gserviceaccount.com

A conta de serviço requer permissão para iniciar operações de exportação do banco de dados do modo Datastore e fazer gravações 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
  • Storage Admin do intervalo do Cloud Storage

Use as ferramentas de linha de comando gcloud e gsutil do SDK do Cloud para atribuir esses papéis:

  1. Use a ferramenta de linha de comando gcloud para atribuir o papel Administrador de exportação do Cloud Datastore:

    gcloud projects add-iam-policy-binding [PROJECT_ID] \
        --member serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com \
        --role roles/datastore.importExportAdmin
    

    Como alternativa, atribua esse papel usando o Console do GCP.

  2. Use a ferramenta de linha de comando gsutil para atribuir o papel Administrador do Storage ao intervalo:

    gsutil iam ch serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com:admin \
        gs://[BUCKET_NAME]
    

    Como alternativa, atribua esse papel usando o Console do GCP.

Como implantar o aplicativo

Implante o seguinte aplicativo de amostra em Python ou Java:

Python

Criar os arquivos do aplicativo

Em uma nova pasta na máquina de desenvolvimento, crie os seguintes arquivos que fornecem o código para um aplicativo do App Engine:

  • app.yaml
  • cloud_datastore_admin.py

Use o seguinte código para os arquivos:

app.yaml

Este arquivo configura a implementação do aplicativo:

runtime: python27
api_version: 1
threadsafe: true
service: cloud-datastore-admin

libraries:
- name: webapp2
  version: "latest"

handlers:
- url: /cloud-datastore-export
  script: cloud_datastore_admin.app
  login: admin

A linha service: cloud-datastore-admin implanta o aplicativo no serviço cloud-datastore-admin. Se esse for o único serviço do App Engine no projeto, remova essa linha para, em vez disso, implantar o aplicativo no serviço default.

cloud_datastore_admin.py

import datetime
import httplib
import json
import logging
import webapp2

from google.appengine.api import app_identity
from google.appengine.api import urlfetch

class Export(webapp2.RequestHandler):

  def get(self):
    access_token, _ = app_identity.get_access_token(
        'https://www.googleapis.com/auth/datastore')
    app_id = app_identity.get_application_id()
    timestamp = datetime.datetime.now().strftime('%Y%m%d-%H%M%S')

    output_url_prefix = self.request.get('output_url_prefix')
    assert output_url_prefix and output_url_prefix.startswith('gs://')
    if '/' not in output_url_prefix[5:]:
      # Only a bucket name has been provided - no prefix or trailing slash
      output_url_prefix += '/' + timestamp
    else:
      output_url_prefix += timestamp

    entity_filter = {
        'kinds': self.request.get_all('kind'),
        'namespace_ids': self.request.get_all('namespace_id')
    }
    request = {
        'project_id': app_id,
        'output_url_prefix': output_url_prefix,
        'entity_filter': entity_filter
    }
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + access_token
    }
    url = 'https://datastore.googleapis.com/v1/projects/%s:export' % app_id
    try:
      result = urlfetch.fetch(
          url=url,
          payload=json.dumps(request),
          method=urlfetch.POST,
          deadline=60,
          headers=headers)
      if result.status_code == httplib.OK:
        logging.info(result.content)
      elif result.status_code >= 500:
        logging.error(result.content)
      else:
        logging.warning(result.content)
      self.response.status_int = result.status_code
    except urlfetch.Error:
      logging.exception('Failed to initiate export.')
      self.response.status_int = httplib.INTERNAL_SERVER_ERROR

app = webapp2.WSGIApplication(
    [
        ('/cloud-datastore-export', Export),
    ], debug=True)

Implantar o aplicativo

  1. Verifique se o gcloud está configurado para o projeto correto:

    gcloud config set project [PROJECT_NAME]
    
  2. No mesmo diretório do arquivo app.yaml, implante o aplicativo no projeto:

    gcloud app deploy
    

Java

O exemplo de aplicativo a seguir pressupõe que você tenha configurado o Maven com o plug-in do App Engine.

Fazer o download do aplicativo

Faça o download do repositório java-docs-samples e navegue até o diretório datastore-schedule-export do aplicativo:

  1. Clone o repositório do aplicativo de amostra na máquina local:

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    

    Outra opção é fazer o download da amostra como um arquivo zip e extraí-lo.

  2. Navegue até o diretório que contém o código de amostra:

    cd java-docs-samples/appengine-java8/datastore-schedule-export/
    

O aplicativo configura um servlet no arquivo DatastoreExportServlet.java.

Como implantar em um serviço diferente

Se você implantar o aplicativo como está, ele será implantado no serviço default. Caso você já tenha um serviço default, implante em um serviço diferente.

Modifique o arquivo src/main/webapp/WEB-INF/appengine-web.xml adicionando <module>service_name</module>. Exemplo:

   <?xml version="1.0" encoding="utf-8"?>
   <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java8</runtime>
      <!-- ... -->
      <module>cloud-datastore-admin</module>
      <!-- ... -->
   </appengine-web-app>

Para mais informações sobre o arquivo de configuração do aplicativo, consulte a referência do appengine-web.xml.

Implantar o aplicativo

  1. Verifique se o gcloud está configurado para o projeto correto:

    gcloud config set project [PROJECT_NAME]
    
  2. Implante o aplicativo no projeto:

    mvn appengine:deploy
    

O serviço recebe solicitações de exportação em [SERVICE_URL]/cloud-datastore-export e envia uma solicitação autenticada à API Cloud Datastore Admin para iniciar a exportação.

O serviço usa os seguintes parâmetros de URL para configurar a solicitação de exportação:

  • output_url_prefix (obrigatório): especifica onde a exportação do banco de dados do modo Datastore será salva. Se o URL terminar com /, ele será usado dessa maneira. Caso contrário, o aplicativo adicionará um carimbo de data/hora ao URL.
  • kind (opcional, múltiplo): restringe a exportação a apenas esses tipos.
  • namespace_id (opcional, múltiplo): restringe a exportação a apenas esses namespaces.

Como implantar o cron job

Para configurar um cron job que chame o aplicativo schedule-datastore-exports, crie e implante um arquivo cron.yaml.

  1. Crie um arquivo cron.yaml:

    Python

    cron:
    - description: "Daily Cloud Datastore Export"
      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]
      target: cloud-datastore-admin
      schedule: every 24 hours
    

    Se você tiver implantado o aplicativo no serviço default em vez de no serviço cloud-datastore-admin, remova target: cloud-datastore-admin.

    Java

    cron:
    - description: "Daily Cloud Datastore Export"
      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]
      schedule: every 24 hours
    

    Se você não tiver implantado o aplicativo no serviço default, adicione uma linha de destino de serviço. Por exemplo: target: cloud-datastore-admin.

    Substitua [BUCKET_NAME] pelo nome do intervalo do Cloud Storage.

  2. Configure o cron job. O cron.yaml de exemplo inicia uma solicitação de exportação de todas as entidades a cada 24 horas. Consulte Formato de programação para ver mais opções de programação.

    Para exportar entidades apenas de determinados tipos, adicione parâmetros kind ao valor de url. Da mesma forma, adicione parâmetros namespace_id para exportar entidades de namespaces específicos. Exemplo:

    • Exportar entidades do tipo Song:

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&kind=Song
      
    • Exportar entidades dos tipos Song e Album:

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&kind=Song&kind=Album
      
    • Exportar entidades dos tipos Song e Album, caso estejam nos namespaces Classical ou Pop:

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&namespace_id=Classical&namespace_id=Pop&kind=Song&kind=Album
      
  3. Implante o cron job. Execute este comando no mesmo diretório em que está o arquivo cron.yaml:

      gcloud app deploy cron.yaml
    

Como testar o aplicativo cron

Para testar o cron job implantado, execute-o antecipadamente na página Cron Jobs do Console do Google Cloud Platform:

  1. Abra a página Cron Jobs no Console do GCP.
    Abrir a página "Cron jobs"

  2. Clique no botão Executar agora do cron job.

  3. Depois que job for concluído, verifique a mensagem de status em Status. Para ver o arquivo de registros do cron job, clique em Visualizar na coluna Registro.

Como visualizar exportações

Após a conclusão bem-sucedida do cron job, será possível visualizar as exportações no intervalo do Cloud Storage.

  1. Abra o navegador do Cloud Storage no Console do GCP.
    Abrir o navegador do Cloud Storage

  2. Na lista de intervalos, clique no intervalo criado para suas exportações.

  3. Verifique se as exportações estão listadas no intervalo.

A seguir

  • Para saber como importar dados de uma exportação do banco de dados do modo Datastore, consulte Como importar entidades.
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Cloud Datastore