Programa una exportación

En esta página, se describe cómo programar una exportación automática de tus entidades de Cloud Firestore en modo Datastore.

Para programar las exportaciones de tus entidades, te recomendamos que implementes un servicio de App Engine que llame a la función de exportación administrada del modo Datastore. Una vez que lo implementes, puedes ejecutar este servicio de forma programada con el servicio Cron de App Engine.

Antes de comenzar

Antes de poder programar exportaciones de datos con App Engine y la función de exportación administrada, debes realizar las siguientes tareas:

  1. Habilita la facturación para tu proyecto de GCP. Solo los proyectos de GCP que tengan la facturación habilitada pueden usar la función de importación y exportación.

  2. Crea un depósito de Cloud Storage para tu proyecto. Todas las importaciones y exportaciones administradas dependen de Cloud Storage. Debes usar la misma ubicación para el depósito de Cloud Storage y la base de datos en modo Datastore.

    Para encontrar la ubicación de la base de datos en modo Datastore, consulta la sección sobre cómo ver la ubicación de tu proyecto.

  3. Instala el SDK de Google Cloud para implementar la aplicación.

Configura exportaciones programadas

Después de completar los requisitos anteriores, realiza los siguientes procedimientos para configurar las exportaciones programadas.

Configura los permisos de acceso

Esta app usa la cuenta de servicio predeterminada de App Engine para autenticar y autorizar las solicitudes de exportación. Cuando creas un proyecto, App Engine crea una cuenta de servicio predeterminada para ti con el siguiente formato:

[PROJECT_ID]@appspot.gserviceaccount.com

La cuenta de servicio requiere permiso para iniciar las operaciones de exportación de la base de datos en modo Datastore y escribir en tu depósito de Cloud Storage. Para otorgar esos permisos, asigna las siguientes funciones de IAM a la cuenta de servicio predeterminada:

  • Cloud Datastore Import Export Admin
  • Storage Admin del depósito de Cloud Storage

Puedes usar las herramientas de línea de comandos gcloud y gsutil del SDK de Cloud para asignar estas funciones:

  1. Usa la herramienta de línea de comandos de gcloud para asignar la función de Administrador de exportación de Cloud Datastore:

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

    Como alternativa, puedes asignar esta función con GCP Console.

  2. Usa la herramienta de línea de comandos de gsutil para asignar la función de Administrador de almacenamiento en tu depósito:

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

    Como alternativa, puedes asignar esta función con GCP Console.

Implementa la app

Implementa la siguiente app de muestra en Python o Java:

Python

Crea los archivos de la app

En una carpeta nueva de tu máquina de desarrollo, crea los siguientes archivos que proporcionan el código para una app de App Engine:

  • app.yaml
  • cloud_datastore_admin.py

Usa el siguiente código para los archivos.

app.yaml

Con el siguiente archivo, se configura la implementación de la app:

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

La línea service: cloud-datastore-admin implementa la app al servicio cloud-datastore-admin. Si este es el único servicio de App Engine en tu proyecto, quita esta línea para implementar la app al servicio 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)

Implementa la app

  1. Asegúrate de que gcloud esté configurado para el proyecto correcto:

    gcloud config set project [PROJECT_NAME]
    
  2. Desde el directorio en el que se encuentra tu archivo app.yaml, implementa la app en tu proyecto:

    gcloud app deploy
    

Java

En la siguiente app de muestra, se supone que configuraste Maven con el complemento de App Engine

Descarga la app

Descarga el repositorio java-docs-samples y navega al directorio de la app datastore-schedule-export:

  1. Clona el repositorio de la app de muestra en tu máquina local:

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

    Como alternativa, descarga el ejemplo como un archivo ZIP y extráelo.

  2. Navega al directorio que contiene el código de muestra:

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

La app configura un servlet en el archivo DatastoreExportServlet.java.

Implementa en un servicio diferente

Si implementas la app como está, se implementa en el servicio default. Si ya tienes un servicio default, debes implementarla en un servicio diferente.

Agrega <module>service_name</module> al archivo src/main/webapp/WEB-INF/appengine-web.xml para modificarlo. Por ejemplo:

   <?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 obtener más información sobre el archivo de configuración de la app, consulta la referencia de appengine-web.xml

Implementa la app

  1. Asegúrate de que gcloud esté configurado para el proyecto adecuado:

    gcloud config set project [PROJECT_NAME]
    
  2. Implementa la app en tu proyecto:

    mvn appengine:deploy
    

El servicio recibe solicitudes de exportación en [SERVICE_URL]/cloud-datastore-export y envía una solicitud autenticada a la API de administrador de Cloud Datastore para iniciar la exportación.

El servicio usa los siguientes parámetros de URL para configurar la solicitud de exportación:

  • output_url_prefix (obligatorio): especifica dónde guardar la exportación de la base de datos en modo Datastore. Si la URL termina con una /, se usa como está. De lo contrario, la app agrega una marca de tiempo a la URL.
  • kind (opcional, múltiple): restringe la exportación a solo estas categorías.
  • namespace_id (opcional, múltiple): restringe la exportación a solo estos espacios de nombres.

Implementa el trabajo cron

Para configurar un trabajo cron que llame a la app schedule-datastore-exports, crea y, luego, implementa un archivo cron.yaml.

  1. Crea un archivo 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
    

    Si implementaste la app en el servicio default en lugar de en el servicio cloud-datastore-admin, quita 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
    

    Si no implementaste la app en el servicio default, agrega una línea de destino del servicio. Por ejemplo: target: cloud-datastore-admin.

    Reemplaza [BUCKET_NAME] por el nombre de tu depósito de Cloud Storage.

  2. Configura el trabajo cron. El cron.yaml de ejemplo inicia una solicitud de exportación de las entidades cada 24 horas. Para ver más opciones de programación, consulta la sección sobre el formato de Schedule.

    Para exportar entidades de categorías específicas, agrega parámetros kind al valor url. Del mismo modo, agrega parámetros namespace_id para exportar entidades desde espacios de nombres específicos. Por ejemplo:

    • Exporta entidades de la categoría Song:

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&kind=Song
      
    • Exporta entidades de las categorías Song y Album:

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&kind=Song&kind=Album
      
    • Exporta entidades de las categorías Song y Album si están en los espacios de nombres Classical o Pop:

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&namespace_id=Classical&namespace_id=Pop&kind=Song&kind=Album
      
  3. Implementa el trabajo cron. Ejecuta el siguiente comando en el mismo directorio que el archivo cron.yaml:

      gcloud app deploy cron.yaml
    

Prueba tu app cron

Puedes probar los trabajos cron implementados si los ejecutas al principio de la página Trabajos cron de Google Cloud Platform Console:

  1. Abre la página Trabajos cron de GCP Console.
    Abrir la página Trabajos cron

  2. Haz clic en el botón Ejecutar ahora del trabajo cron.

  3. Cuando se complete el trabajo, verifica el mensaje de estado en Estado. Para ver el archivo de registro del trabajo cron, haz clic en Ver en la columna Registro.

Visualiza las exportaciones

Después de que un trabajo cron se completa con éxito, puedes ver las exportaciones en tu depósito de Cloud Storage:

  1. Abre el navegador de Cloud Storage en GCP Console.
    Abrir el navegador de Cloud Storage

  2. En la lista de depósitos, haz clic en el que creaste para tus exportaciones.

  3. Verifica que las exportaciones se encuentren en el depósito.

Qué sigue

  • Para aprender cómo importar datos de una exportación de base de datos en modo Datastore, consulta Importa entidades.