Importa y exporta entidades

En esta página, se describe cómo importar y exportar entidades de Cloud Firestore en modo Datastore con el servicio administrado de importación y exportación. El servicio administrado de importación y exportación está disponible a través de 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 de su comienzo y excluir otras escritas antes.

  • 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 ID nuevos a las entidades. Las importaciones usan 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 durante el tiempo en 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 exportados desde una base de datos en modo Datastore pueden importarse a otra, incluso si está en 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 usa el formato de registro LevelDB.

  • Para importar solo un subconjunto de entidades o importar datos en BigQuery, debes especificar un filtro de entidad en tu exportación.

Antes de comenzar

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

  1. Habilita la facturación 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.

  2. Crea un depósito de Cloud Storage en la misma ubicación que tu base de datos de Cloud Firestore en modo Datastore. Todas las importaciones y exportaciones se basan en Cloud Storage y debes usar la misma ubicación para tu depósito de Cloud Storage y la base de datos de Cloud Firestore en modo 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 otorgue el permiso datastore.databases.export, si quieres exportar datos, o datastore.databases.import, si quieres importarlos. Por ejemplo, la función Cloud Datastore Import Export Admin otorga ambos permisos.

  4. Si el depósito de Cloud Storage está en otro proyecto, otorga a la cuenta de servicio predeterminada de tu proyecto acceso al depósito.

Configura tu entorno

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

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

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

    gcloud config set project ${PROJECT_ID}
    
  3. Realiza autenticaciones con la herramienta de gcloud.

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

    BUCKET="YOUR_BUCKET_NAME[/NAMESPACE_PATH]"
    

    en la que 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 (este no es un espacio de nombres en modo Datastore). Para obtener más información sobre las rutas de espacio de nombres de Cloud Storage, consulta las consideraciones sobre los nombres de objetos.

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.

Exporta todas las entidades

Usa el comando gcloud datastore export para exportar todas las entidades de tu base de datos. Puedes agregar la marca --async para evitar que la herramienta de gcloud espere a que se complete la operación.

gcloud

gcloud datastore export gs://${BUCKET} --async

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: tu ID del proyecto
  • bucket-name: el nombre de tu depósito de Cloud Storage

Método HTTP y URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

Cuerpo JSON de la solicitud:

{
  "outputUrlPrefix": "gs://bucket-name",
}

Para enviar tu solicitud, expande una de estas opciones:

Exporta categorías o espacios de nombres específicos

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

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://${BUCKET} --async

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: tu ID del proyecto
  • bucket-name: el nombre de tu depósito de Cloud Storage
  • kind: la categoría de la entidad
  • namespace: el ID del espacio de nombres (usa “” para el ID del espacio de nombres predeterminado)

Método HTTP y URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

Cuerpo JSON de la solicitud:

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Para enviar tu solicitud, expande una de estas opciones:

Exporta archivos de metadatos

Una operación de exportación crea un archivo de metadatos para cada par de categoría y espacio de nombres especificado. Por lo general, los archivos de metadatos se denominan [NAMESPACE_NAME]_[KIND_NAME].export_metadata. Sin embargo, si un espacio de nombres o una categoría crean un nombre de objeto de Cloud Storage no válido, el archivo se llamará export[NUM].export_metadata.

Los archivos de metadatos son búferes de protocolo y se pueden decodificar con el compilador de protocolo protoc. Por ejemplo, puedes decodificar un archivo de metadatos para determinar el espacio de nombres y las categorías que contienen los archivos de exportación:

protoc --decode_raw < export0.export_metadata

Importa todas las entidades

Usa el comando gcloud datastore import para importar todas las entidades que se exportaron con el servicio de exportación administrado. Puedes agregar la marca --async para evitar que la herramienta de gcloud espere a que se complete la operación.

gcloud

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

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: tu ID del proyecto
  • bucket-name: el nombre de tu depósito de Cloud Storage
  • object-name: tu nombre de objeto de Cloud Storage (ejemplo: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)

Método HTTP y URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

Cuerpo JSON de la solicitud:

{
  "inputUrl": "gs://bucket-name/object-name",
}

Para enviar tu solicitud, expande una de estas opciones:

Puedes determinar el valor que se usará para la ubicación de importación mediante la IU de Cloud Storage en Google Cloud Platform Console a fin de ver el depósito, o mediante la examinación del resultado de gcloud datastore export o ExportEntitiesResponse una vez finalizada 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 --async

rest

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

Importa categorías o espacios de nombres específicos

Para importar un subconjunto específico de categorías o espacios de nombres, proporciona un filtro de entidad con valores de ID de espacios de nombres y categorías.

Solo puedes especificar categorías y espacios de nombres si los archivos de exportación se crearon con un filtro de entidad. No puedes importar un subconjunto de categorías y espacios de nombres desde una exportación de todas las entidades.

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata --async

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: tu ID del proyecto
  • bucket-name: el nombre de tu depósito de Cloud Storage
  • object-name: tu nombre de objeto de Cloud Storage (ejemplo: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)
  • kind: la categoría de la entidad
  • namespace: el ID del espacio de nombres (usa “” para el ID del espacio de nombres predeterminado)

Método HTTP y URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

Cuerpo JSON de la solicitud:

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Para enviar tu solicitud, expande una de estas opciones:

Importaciones o exportaciones asíncronas

Las importaciones y exportaciones pueden tardar mucho tiempo. Cuando realizas una exportación o importación, puedes proporcionar la marca --async para evitar que la herramienta de gcloud espere a que se complete la operación.

Después de iniciar una operación de importación o exportación, puedes usar el identificador que muestra la herramienta de gcloud para verificar el estado de la operación. Por ejemplo:

gcloud datastore operations describe ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI

Si olvidas la marca --async, también puedes usar Ctrl+c para dejar de esperar 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 a métodos que pueden tardar una gran cantidad de tiempo en completarse. Las bases de datos en modo Datastore crean operaciones de larga duración cuando exportas o importas datos.

Por ejemplo, cuando inicias una exportación, la base de datos en modo Datastore crea una operación de larga duración para realizar un seguimiento del 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 Firestore en modo Datastore proporciona una API de administrador de operaciones para verificar el estado de las operaciones de larga duración, además de cancelar, borrar o enumerar 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: Si se borra una operación, no se cancela.
projects.operations.get Obtiene el estado de una operación de larga duración.
projects.operations.list Enumera las operaciones de larga duración.

Enumera las operaciones de larga duración

Para enumerar las operaciones de larga duración, usa el comando gcloud datastore operations list:

gcloud

gcloud datastore operations list

rest

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: tu ID del proyecto

Método HTTP y URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Para enviar tu solicitud, expande una de estas opciones:

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

A medida que se ejecuta tu operación, mira el valor del campo state para conocer el estado general.

Una solicitud del estado de una operación de larga duración también muestra las métricas workEstimated y workCompleted. Cada una de estas métricas se muestra en cantidad de bytes y de entidades: workEstimated muestra la cantidad total estimada de bytes y de entidades que procesará una operación, según las estadísticas de base de datos. workCompleted muestra la cantidad de bytes y de entidades que se procesaron hasta el momento. Una vez que se completa la operación, workCompleted refleja la cantidad total de bytes y entidades que se procesaron, que podría ser mayor que el valor de workEstimated.

Divide workCompleted entre workEstimated para obtener una estimación aproximada del progreso. 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"
        },
        ...

Cuando se realiza una operación, su descripción contendrá "done": true. Consulta el valor del campo state para ver el resultado de la operación. Si el campo done no está establecido en la respuesta, su valor es false. No dependas de la existencia del valor done para las operaciones en curso.

Facturación y precios de las importaciones y exportaciones administradas

Es obligatorio que habilites la facturación en tu proyecto de Google Cloud Platform antes de usar el servicio administrado de importación y exportación. Las operaciones de importación y exportación contribuyen a los costos de Google Cloud Platform de las siguientes maneras:

No se consideran los costos de las operaciones de importación y exportación en el límite de gastos de App Engine. Las operaciones de exportación o importación no activan alertas de presupuesto de Google Cloud Platform hasta que se completan. Así mismo, 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.

Permisos

Para ejecutar operaciones de importación y exportación, tu cuenta de usuario y la cuenta de servicio predeterminada de tu proyecto necesitan los permisos de Cloud Identity and Access Management que se describen a continuación.

Permisos de la cuenta de usuario

La cuenta de usuario o cuenta de servicio que inicia la operación requiere los permisos datastore.databases.export y datastore.databases.import de Cloud IAM. Si eres el propietario del proyecto, tu cuenta ya tiene los permisos necesarios. De lo contrario, las siguientes funciones de Cloud IAM otorgan los permisos necesarios:

  • Propietario de Cloud Datastore
  • Administrador de importación y exportación de Cloud Datastore

El propietario de un proyecto puede otorgar una de estas funciones si sigue los pasos en la sección sobre cómo otorgar acceso.

Permisos de la cuenta de servicio predeterminada

Cada proyecto de GCP crea de forma automática una cuenta de servicio predeterminada llamada PROJECT_ID@appspot.gserviceaccount.com. Las operaciones de importación y exportación usan esta cuenta de servicio para autorizar las operaciones de Cloud Storage.

La cuenta de servicio predeterminada de tu proyecto requiere acceso al depósito de Cloud Storage que se usa en una operación de importación o exportación. Si tu depósito de Cloud Storage está en el mismo proyecto que tu base de datos en modo Datastore, la cuenta de servicio predeterminada tiene acceso al depósito de forma predeterminada.

Si el depósito de Cloud Storage está en otro proyecto, debes darle a la cuenta de servicio predeterminada acceso al depósito de Cloud Storage.

Asigna funciones a la cuenta de servicio predeterminada

Puedes usar la herramienta de línea de comandos gsutil para asignar una de las funciones que se encuentran a continuación. Por ejemplo, para asignar la función de administrador de almacenamiento a la cuenta de servicio predeterminada, ejecuta el siguiente comando:

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

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

Operaciones de exportación

Para las operaciones de exportación que involucran un depósito en otro proyecto, debes modificar los permisos del depósito para asignar una de las siguientes funciones de Cloud Storage a la cuenta de servicio predeterminada del proyecto que contiene tu base de datos en modo Datastore:

  • Administrador de almacenamiento
  • Administrador de objeto de almacenamiento
  • Escritor de depósitos heredados de almacenamiento

También puedes crear una función personalizada de Cloud IAM con los siguientes permisos:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.list

Operaciones de importación

Para las operaciones de importación que involucran un depósito en otro proyecto, debes modificar los permisos del depósito para asignar una de las siguientes funciones de Cloud Storage a la cuenta de servicio predeterminada del proyecto que contiene tu base de datos en modo Datastore:

  • Administrador de almacenamiento
  • Visualizador de objetos de almacenamiento y Lector de depósitos heredados de almacenamiento

También puedes crear una función personalizada de Cloud IAM con los siguientes permisos:

  • storage.buckets.get
  • storage.objects.get

Diferencias de 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 almacena 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 de importación administrado, pero no puedes importar el resultado de una exportación administrada con la Consola del administrador de Cloud Datastore.

Importa a BigQuery

Para importar datos de una exportación administrada a BigQuery, consulta Carga datos del servicio de exportación de Cloud Datastore.

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 sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Documentación de Cloud Datastore