Importa y exporta entidades

En esta página, se describe cómo importar y exportar entidades de Google Cloud Datastore con el servicio administrado de importación y exportación. Este servicio está disponible mediante la herramienta de línea de comandos de gcloud y la API de administrador de Cloud Datastore (REST y RPC).

Gracias al servicio administrado de importación y exportación, es posible recuperar el sistema de la eliminación accidental de datos y exportar datos de procesamiento sin conexión. Puedes exportar todas las entidades o solo categorías específicas de entidades. Asimismo, puedes importar todos los datos de una exportación o solo categorías específicas. Cuando uses este servicio, ten en cuenta lo siguiente:

  • El servicio de exportación usa lecturas de coherencia eventual. No puedes suponer que una exportación ocurre en un momento específico. La exportación podría incluir entidades escritas después del comienzo de esta y no incluir otras escritas antes del comienzo de la exportación.

  • Una exportación no contiene índices. Cuando importas datos, los índices necesarios se vuelven a compilar de forma automática mediante las definiciones de índice actuales de tu base de datos. La configuración de índice de valor de propiedad por entidad se exporta y se respeta durante la importación.

  • Las importaciones no asignan nuevos ID a las entidades. Las importaciones utilizan los ID que existían en el momento de la exportación y reemplazan cualquier entidad existente con el mismo ID. Durante una importación, los ID se reservan por el período en el que se importan las entidades. Esta característica evita conflictos de ID con las entidades nuevas si las operaciones de escritura están habilitadas mientras una importación está activa.

  • Si la importación no afecta a una entidad de tu base de datos, esta se conservará cuando la operación finalice.

  • Los datos que se exportan desde una base de datos de Cloud Datastore se pueden importar en otra base de datos de Cloud Datastore, incluso si es de otro proyecto.

  • El límite que establece el servicio administrado de importaciones y exportaciones es de 50 importaciones y exportaciones simultáneas y permite un máximo de 20 solicitudes de importación y exportación por minuto para un proyecto.

  • El resultado de una exportación administrada utiliza el formato de registro LevelDB.

Antes de comenzar

Antes de usar el servicio administrado de importación y exportación, debes completar las siguientes tareas.

  1. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud Platform. Solo los proyectos de GCP que tengan la facturación habilitada pueden usar la funcionalidad de importación y exportación. Si quieres obtener más información sobre la facturación, consulta Facturación y precio de las importaciones y exportaciones.

  2. Crea un depósito de Cloud Storage para tu proyecto que corresponda con tu ubicación de Cloud Datastore. Todas las importaciones y exportaciones dependen de Cloud Storage y debes utilizar la misma ubicación para tu depósito de Cloud Storage y Cloud Datastore. No puedes usar un depósito de pagos del solicitante para las operaciones de importación y exportación.

  3. Asigna una función de IAM a tu cuenta de usuario que brinda el permiso datastore.databases.export, si quieres exportar datos, o el permiso datastore.databases.import si quieres importarlos. La función Cloud Datastore Import Export Admin, por ejemplo, otorga ambos permisos.

  4. Asigna una función de IAM de Cloud Storage IAM a tu cuenta de usuario que brinda permisos de lectura o escritura a tu depósito de Cloud Storage.

Configura tu entorno

Antes de exportar o importar datos, debes definir variables del entorno para la herramienta gcloud y autenticarte con tu cuenta de usuario.

  1. Define una variable del entorno para tu ID del proyecto de GCP.

    PROJECT_ID="YOUR_PROJECT_ID"
    
  2. Usa esta variable a fin de definir tu proyecto como la configuración activa para la herramienta gcloud.

    gcloud config set project ${PROJECT_ID}
    
  3. Realiza la autenticación con la herramienta gcloud.

    gcloud auth login
    
  4. Define una variable del entorno para el ID de tu depósito de Cloud Storage.

    BUCKET="YOUR_BUCKET_NAME[/NAMESPACE_PATH]"
    

    YOUR_BUCKET_NAME es el nombre del depósito de Cloud Storage y NAMESPACE_PATH es una ruta de espacio de nombres opcional de Cloud Storage (esto no es un espacio de nombres de Cloud Datastore). Para obtener más información sobre las rutas de espacio de nombres de Cloud Storage, consulta Consideraciones sobre el nombre de objeto.

Inicia operaciones administradas de importación y exportación

En esta sección, se describe cómo iniciar una operación administrada de importación o exportación y cómo verificar su progreso.

Antes de importar o exportar entidades, te recomendamos inhabilitar las operaciones de escritura de Cloud Datastore. Una vez que finaliza la importación o la exportación, vuelve a habilitar las operaciones de escritura de Cloud Datastore para tu aplicación.

Exporta entidades

Utiliza el siguiente comando para exportar todas las categorías en el espacio de nombres predeterminado. Puedes agregar la marca --async para evitar que la herramienta gcloud espere que finalice la operación.

gcloud

gcloud datastore export --namespaces="(default)" gs://${BUCKET}

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "namespaceIds": [""], }, }'

Si quieres exportar un subconjunto de categorías o espacios de nombres, proporciona un filtro de entidades con valores para los ID de categorías y espacios de nombres.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="NAMESPACE1,NAMESPACE2" gs://${BUCKET}

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "kinds": ["KIND1", "KIND2", …], "namespaceIds": ["NAMESPACE1", "NAMESPACE2", …], }, }

Importa entidades

Usa el siguiente comando para importar entidades que ya se exportaron con el servicio administrado de importación y exportación. Puedes agregar la marca --async para evitar que la herramienta gcloud espere que finalice la operación.

gcloud

gcloud datastore import gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:import
-d '{ "inputUrl": "gs://'${BUCKET}'/[PATH]/[FILE].overall_export_metadata", }'

Puedes determinar el valor de la ubicación de importación con la IU de Cloud Storage de Google Cloud Platform Console para ver el depósito. También puedes examinar el resultado de gcloud datastore export o ExportEntitiesResponse luego de que termine la exportación. Este es un valor de ejemplo de una ubicación de importación:

gcloud

gs://${BUCKET}/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

Protocolo

"outputUrl": "gs://'${BUCKET}'/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Importaciones o exportaciones asíncronas

Las importaciones y exportaciones pueden tardar mucho tiempo. Agrega la marca --async para evitar que la herramienta gcloud espere a que la operación finalice.

Puedes utilizar el identificador que muestra la herramienta gcloud para revisar el estado de la operación, luego de que comienzas una operación de importación o exportación. Por ejemplo:

gcloud datastore operations describe ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI

Si olvidas la marca --async, puedes utilizar Ctrl+c para dejar de esperar en una operación. Escribir Ctrl+c no cancelará la operación.

Administra operaciones de larga duración

Las operaciones de larga duración son llamadas de método que pueden tardar una gran cantidad de tiempo en completarse. Cloud Datastore crea operaciones de larga duración cuando importas o exportas datos.

Por ejemplo, cuando comienzas una exportación, el servicio de Cloud Datastore crea una operación de larga duración para seguir el estado de la exportación. Este es el resultado desde el comienzo de una exportación:

{
  "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2017-05-25T23:54:39.583780Z",
      "operationType": "EXPORT_ENTITIES"
    },
    "progressEntities": {},
    "progressBytes": {},
    "entityFilter": {
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
  }
}

El valor del campo name es el ID de una operación de larga duración.

Cloud Datastore proporciona una API de Administrador de operaciones que permite revisar el estado de las operaciones de larga duración, así como cancelar, borrar o mostrar una lista de las operaciones de larga duración:

Método Descripción
projects.operations.cancel Cancela una operación de larga duración.
projects.operations.delete Borra una operación de larga duración.

Nota: Borrar una operación no la cancela.
projects.operations.get Obtiene el estado de una operación de larga duración.
projects.operations.list Muestra las operaciones de larga duración.

Obtén una lista de las operaciones de larga duración

Para generar una lista de las operaciones de larga duración, ejecuta los siguientes comandos:

gcloud

gcloud datastore operations list

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}/operations

En este resultado de ejemplo, se muestra una operación de exportación que se completó recientemente. Las operaciones son accesibles durante algunos días luego de completarse:

{
  "operations": [
    {
      "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://[YOUR_BUCKET_NAME]/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Usa el valor input_url cuando importes las entidades.

Estima la hora de finalización

La solicitud de verificación del estado de una operación prolongada muestra las métricas workEstimated y workCompleted. Cada una de estas métricas se muestra en cantidad de bytes y de entidades. workEstimated muestra el número total de bytes y entidades estimado que una operación procesará, según Cloud Datastore Statistics. workCompleted muestra el número de bytes y entidades procesadas hasta el momento. Luego de que la operación se complete, workCompleted muestra el número total de bytes y entidades que fueron procesadas. Este valor puede ser más grande que el valor de workEstimated.

Para obtener una estimación del progreso, divide workCompleted por workEstimated. Es posible que la estimación sea inexacta, ya que depende de la demora en la recopilación de estadísticas.

Por ejemplo, este es el estado de progreso de una operación de exportación:

{
  "operations": [
    {
      "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

Facturación y precios de las importaciones y exportaciones administradas

Es obligatorio que habilites la facturación de tu proyecto de Google Cloud Platform antes de usar el servicio administrado de importación y exportación. Las operaciones de exportación y de importación se cobran como operaciones de lectura y escritura de entidad según las tarifas que aparecen en precios de Cloud Datastore.

No se consideran los costos de las operaciones de importación y exportación en el límite de gastos de App Engine. Además, si configuraste un presupuesto para Google Cloud Platform, la operación de importación o exportación no activará alertas hasta que la operación se complete. Asimismo, las operaciones de lectura y escritura que se realizan durante una operación de importación o exportación se aplican a tu cuota diaria una vez que la operación se completa.

Consulta Asistencia para pagos y facturación a fin de obtener más información sobre la facturación.

Permisos

Para comenzar las operaciones de importación y exportación, las funciones de IAM de tu cuenta de usuario deben otorgar los permisos de datastore.databases.export y datastore.databases.import. La función Cloud Datastore Import Export Admin, por ejemplo, otorga ambos permisos. Asimismo, si emites solicitudes REST desde la línea de comandos con curl, debes asignar una función de IAM que le otorgue estos permisos a tu cuenta de usuario. Consulta Administración de identidades y accesos (IAM) para obtener más información sobre los permisos de Cloud Datastore.

Si utilizas la aplicación de ejemplo cron, sus solicitudes usan la cuenta de servicio predeterminada de App Engine del proyecto de GCP. Debes otorgarle la función Cloud Datastore Import Export Admin o alguna función que otorgue el permiso datastore.databases.export a la cuenta de servicio predeterminada de App Engine.

Además, para todas las solicitudes de exportación, la cuenta que realiza la solicitud y la cuenta de servicio predeterminada de App Engine del proyecto de GCP deben tener una función de IAM que otorgue los siguientes permisos para tu depósito de Cloud Storage:

Nombre del permiso Descripción
storage.buckets.get Lee los metadatos del depósito, excluidas las políticas de IAM.
storage.objects.create Agrega objetos nuevos a un depósito.
storage.objects.list Hace una lista de objetos en el depósito. Además, lee metadatos de objeto, excluidos los LCA, cuando hace la lista.

Consulta Funciones IAM de Cloud Storage para obtener una lista de funciones de Cloud Storage. Las funciones Storage Admin o Storage Legacy Bucket Writer, por ejemplo, incluyen todos los permisos necesarios de Cloud Storage para una exportación y pueden aplicarse a un proyecto entero o a un depósito específico. Ten en cuenta que la función Storage Object Creator no incluye todos los permisos necesarios de Cloud Storage para una exportación.

Para las solicitudes de importación, la cuenta que realiza la solicitud y la cuenta de servicio predeterminada del proyecto de GCP deben tener una función de IAM que otorgue los siguientes permisos para tu depósito de Cloud Storage:

Nombre del permiso Descripción
storage.objects.get Lee datos y metadatos de objeto, excluidos los LCA.
storage.objects.list Hace una lista de objetos en el depósito. Además, lee metadatos de objeto, excluidos los LCA, cuando hace la lista.

La función Storage Object Viewer otorga todos los permisos requeridos para la importación.

Diferencias con las copias de seguridad de administrador de Cloud Datastore

Si alguna vez usaste la Consola del administrador de Cloud Datastore para realizar copias de seguridad, notarás las siguientes diferencias:

  • No hay ningún GUI para el servicio administrado de importación y exportación.

  • Las exportaciones que crea una exportación administrada no aparecen en la Consola del administrador de Cloud Datastore. Las importaciones y exportaciones administradas son un servicio nuevo que no comparte datos con la función de copia de seguridad y restablecimiento de App Engine. Esta se administra a través de la GCP Console.

  • El servicio administrado de importación y exportación no es compatible con los mismos metadatos que la copia de seguridad de administrador de Cloud Datastore y no guarda el estado de progreso en tu base de datos. Consulta Administra operaciones de larga duración para obtener más información sobre cómo revisar el progreso de las operaciones de importación y exportación.

  • No puedes ver los registros de servicio de las operaciones administradas de importación y exportación.

  • El servicio administrado de importación es compatible con versiones anteriores de los archivos de copias de seguridad de administrador de Cloud Datastore. Puedes importar un archivo de copia de seguridad de administrador de Cloud Datastore con el servicio administrado de importación, pero no puedes importar el resultado de una exportación administrado con la Consola del administrador de Cloud Datastore.

Importa a BigQuery

Consulta Carga datos desde las copias de seguridad de Cloud Datastore para importar datos desde una exportación administrada a BigQuery.

Limitaciones

  • Los datos que se exportan sin especificar un filtro de entidad no pueden cargarse en BigQuery. Si quieres importar datos a BigQuery, tu solicitud de exportación debe incluir uno o más nombres de categorías en el filtro de entidad.
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Documentación de Cloud Datastore