Importar y exportar entidades

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En esta página, se describe cómo importar y exportar entidades de Firestore en modo Datastore mediante el servicio administrado de importación y exportación. El servicio administrado de importación y exportación está disponible a través de Cloud Console, la CLI de Google Cloud y la API de Administrador de Datastore (REST, RPC).

Con el servicio administrado de importación y exportación, puedes recuperarte de la eliminación accidental de datos y exportar datos para su procesamiento sin conexión. Puedes exportar todas las entidades o solo tipos específicos de entidades. Del mismo modo, puedes importar todos los datos de una exportación o solo tipos específicos. Cuando uses el servicio administrado de importación y exportación, ten en cuenta lo siguiente:

  • El servicio de exportación usa lecturas de coherencia eventual. No puedes suponer que una exportación se realiza en un momento determinado. La exportación puede incluir entidades escritas después de que comience la exportación y excluir entidades escritas antes de que comience.

  • Una exportación no contiene índices. Cuando importas datos, los índices necesarios se vuelven a compilar de forma automática mediante las definiciones de índices 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 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 función evita los conflictos de ID con entidades nuevas si las operaciones de escritura están habilitadas mientras se ejecuta una importación.

  • Si una 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 en modo Datastore se pueden importar en otra base de datos en modo Datastore, incluso en otro proyecto.

  • El servicio de importación y exportación administrado limita la cantidad de importaciones y exportaciones simultáneas a 50 y permite un máximo de 20 solicitudes de importación y exportación por minuto para un proyecto. Para cada solicitud, el servicio limita la cantidad de combinaciones de filtros de entidad a 100.

  • 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. Solo los proyectos de Google Cloud que tengan la facturación habilitada pueden usar la función de importación y exportación.

  2. Crea un bucket de Cloud Storage en la misma ubicación que la base de datos de Firestore en modo Datastore. No puedes usar un bucket de pagos del solicitante para las operaciones de importación y exportación.

  3. Asigna una función de IAM a la cuenta de usuario que otorga el permiso datastore.databases.export si quieres exportar datos, o el permiso datastore.databases.import si quieres importar datos. Por ejemplo, la función Datastore Import Export Admin otorga ambos permisos.

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

Configura gcloud para tu proyecto

Si planeas usar gcloud para iniciar tus operaciones de importación y exportación, configura gcloud y conéctate a tu proyecto de una de las siguientes maneras:

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.

Exporta todas las entidades

Console

  1. Ve a la página Importaciones/Exportaciones de Datastore en Google Cloud Console.

    Ir a la página Importaciones/Exportaciones

  2. Haz clic en Exportar.

  3. Establece el campo Espacio de nombres en All Namespaces y el campo Tipo en All Kinds.

  4. En Destino, ingresa el nombre de tu bucket de Cloud Storage.

  5. Haz clic en Exportar.

La consola regresa a la página Importaciones/Exportaciones. Una alerta informa sobre el éxito o el fracaso de tu solicitud de exportación administrada.

gcloud

Usa el comando gcloud datastore export para exportar todas las entidades de la base de datos.

 gcloud datastore export gs://bucket-name --async

En el ejemplo anterior, bucket-name es el nombre de tu bucket de Cloud Storage y un prefijo opcional, por ejemplo, bucket-name/datastore-exports/export-name. No puedes volver a usar el mismo prefijo para otra operación de exportación. Si no proporcionas un prefijo de archivo, el servicio de exportación administrado crea uno en función de la hora actual.

Usa la marca --async para evitar que gcloud espere a que se complete la operación. Si omites la marca --async, puedes escribir Ctrl+c para dejar de esperar una operación. Esta acción no cancelará la operación.

descansar

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

  • project-id: El ID de tu proyecto
  • bucket-name: Es el nombre del bucket 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:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}
La respuesta es una operación de larga duración que se puede verificar para ver si se completó.

Exporta tipos o espacios de nombres específicos

Para exportar un subconjunto específico de categorías o espacios de nombres, proporciona un filtro de entidad con valores para los ID de categorías y espacios de nombres. Cada solicitud está limitada a 100 combinaciones de filtros de entidades, donde cada combinación de tipo y espacio de nombres filtrados cuenta como un filtro independiente para este límite.

Console

En la consola, puedes seleccionar todos los tipos o un tipo específico. Del mismo modo, puedes seleccionar todos los espacios de nombres o un espacio de nombres específico.

Si deseas especificar una lista de espacios de nombres y tipos para exportar, usa gcloud en su lugar.

  1. Ve a la página Exportación de Datastore en Google Cloud Console.

    Ir a la página de exportación de Datastore

  2. Haz clic en Exportar.

  3. Establece el campo Espacio de nombres en All Namespaces o el nombre de uno de tus espacios de nombres.

  4. Establece el campo Tipo como All Kinds o el nombre de un tipo.

  5. En Destino, ingresa el nombre de tu bucket de Cloud Storage.

  6. Haz clic en Exportar.

La consola regresa a la página Importaciones/Exportaciones. Una alerta informa sobre el éxito o el fracaso de tu solicitud de exportación administrada.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name --async

En el ejemplo anterior, bucket-name es el nombre de tu bucket de Cloud Storage y un prefijo opcional, por ejemplo, bucket-name/datastore-exports/export-name. No puedes volver a usar el mismo prefijo para otra operación de exportación. Si no proporcionas un prefijo de archivo, el servicio de exportación administrado crea uno en función de la hora actual.

Usa la marca --async para evitar que gcloud espere a que se complete la operación. Si omites la marca --async, puedes escribir Ctrl+c para dejar de esperar una operación. Esta acción no cancelará la operación.

descansar

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

  • project-id: El ID de tu proyecto
  • bucket-name: Es el nombre del bucket de Cloud Storage.
  • kind: El tipo de entidad
  • namespace: El ID del espacio de nombres (usa &ID) 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:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}
La respuesta es una operación de larga duración que se puede verificar para ver si se completó.

Archivos de metadatos

Una operación de exportación crea un archivo de metadatos para cada par de tipo 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 los tipos que contienen los archivos de exportación:

protoc --decode_raw < export0.export_metadata

Importa todas las entidades

Console

  1. Ve a la página Importación de Datastore en Google Cloud Console.

    Ir a la página Importación de Datastore

  2. Haz clic en Importar.

  3. En el campo File, haz clic en Explorar y selecciona un archivo overall_export_metadata.

  4. Establece el campo Espacio de nombres en All Namespaces y el campo Tipo en All Kinds.

  5. Haz clic en Importar.

La consola regresa a la página Importaciones/Exportaciones. Una alerta informa sobre el éxito o el fracaso de tu solicitud de importación administrada.

gcloud

Usa el comando gcloud datastore import para importar todas las entidades que se exportaron con anterioridad con el servicio de exportación administrado.

gcloud datastore import gs://bucket-name/file-path/file-name.overall_export_metadata --async

En el ejemplo anterior, bucket-name/file-path/file-name es la ruta al archivo overall_export_metadata dentro del bucket de Cloud Storage.

Usa la marca --async para evitar que gcloud espere a que se complete la operación. Si omites la marca --async, puedes escribir Ctrl+c para dejar de esperar una operación. Esta acción no cancelará la operación.

descansar

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

  • project-id: El ID de tu proyecto
  • bucket-name: Es el nombre del bucket de Cloud Storage.
  • object-name: Es el nombre del 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:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}
La respuesta es una operación de larga duración que se puede verificar para ver si se completó.

Ubica tu archivo overall_export_metadata

Puedes determinar el valor que se usará para la ubicación de importación mediante el navegador de Cloud Storage en Google Cloud Console:

Abre el navegador de Cloud Storage.

También puedes enumerar y describir las operaciones completadas. El campo outputURL muestra el nombre del archivo overall_export_metadata:

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Importa tipos o espacios de nombres específicos

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

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

Console

En la consola, puedes seleccionar todos los tipos o un tipo específico. Del mismo modo, puedes seleccionar todos los espacios de nombres o un espacio de nombres específico.

Si deseas especificar una lista de espacios de nombres y tipos para importar, usa gcloud.

  1. Ve a la página Importación de Datastore en Google Cloud Console.

    Ir a la página Importación de Datastore

  2. Haz clic en Importar.

  3. En el campo File, haz clic en Explorar y selecciona un archivo overall_export_metadata.

  4. Establece el campo Espacio de nombres en All Namespaces o en un espacio de nombres específico.

  5. Establece el campo Tipo como All Kinds o en un tipo específico.

  6. Haz clic en Importar.

La consola regresa a la página Importaciones/Exportaciones. Una alerta informa sobre el éxito o el fracaso de tu solicitud de importación administrada.

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name/file-path/file-name.overall_export_metadata --async

En el ejemplo anterior, bucket-name/file-path/file-name es la ruta al archivo overall_export_metadata dentro del bucket de Cloud Storage.

Usa la marca --async para evitar que gcloud espere a que se complete la operación. Si omites la marca --async, puedes escribir Ctrl+c para dejar de esperar una operación. Esta acción no cancelará la operación.

descansar

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

  • project-id: El ID de tu proyecto
  • bucket-name: Es el nombre del bucket de Cloud Storage.
  • object-name: Es el nombre del objeto de Cloud Storage (ejemplo: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata).
  • kind: El tipo de entidad
  • namespace: El ID del espacio de nombres (usa &ID) 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:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}
La respuesta es una operación de larga duración que se puede verificar para ver si se completó.

Transformaciones de importación

Cuando importes entidades desde otro proyecto, ten en cuenta que las claves de entidad incluyen el ID del proyecto. Una operación de importación actualiza las claves de entidad y las propiedades de referencia de clave en los datos de importación con el ID del proyecto de destino. Si esta actualización aumenta los tamaños de entidades, puede causar que la entidad sea demasiado grande o que las entradas de índice sean demasiado grandes para las operaciones de importación.

Para evitar cualquiera de los errores, importa a un proyecto de destino con un ID del proyecto más corto. Esto no afecta las operaciones de importación con datos del mismo proyecto.

Administra operaciones de larga duración

Las operaciones administradas de importación y exportación son operaciones de larga duración. Estas llamadas a los métodos pueden tardar bastante tiempo en completarse.

Después de iniciar una operación de importación o exportación, el modo Datastore le asigna a la operación un nombre único. Puedes usar el nombre de la operación para borrarla, cancelarla o verificar su estado.

Los nombres de las operaciones incluyen el prefijo projects/[PROJECT_ID]/databases/(default)/operations/. Por ejemplo:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Puedes omitir el prefijo cuando especifiques el nombre de una operación para los comandos gcloud.

Enumera todas las operaciones de larga duración

Puedes ver las operaciones en curso y las que se completaron recientemente de las siguientes maneras. Las operaciones se enumeran durante algunos días luego de completarse:

Console

Puedes ver una lista de las operaciones de importación y exportación más recientes en la página Importaciones/Exportaciones en modo Datastore de Google Cloud Console.

Ir a la página Importaciones/Exportaciones

gcloud

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

gcloud datastore operations list

Por ejemplo, una operación de exportación completada de forma reciente muestra la siguiente información:

{
  "operations": [
    {
      "name": "projects/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://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

descansar

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

  • project-id: El ID de tu 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:

A continuación, encontrarás información sobre la respuesta.

Por ejemplo, una operación de exportación completada de forma reciente muestra la siguiente información:

{
  "operations": [
    {
      "name": "projects/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://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Verifica el estado de la operación

Para ver el estado de una operación de larga duración, sigue estos pasos:

Console

Puedes ver una lista de las operaciones de importación y exportación más recientes en la página Importaciones/Exportaciones en modo Datastore de Google Cloud Console.

Ir a la página Importaciones/Exportaciones

gcloud

Usa el comando operations describe para mostrar el estado de una operación de larga duración.

gcloud datastore operations describe operation-name

descansar

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

  • project-id: El ID de tu proyecto
  • operation-name: El nombre de la operación

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

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 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 documentos que se procesarán en una operación.

  • workCompleted muestra la cantidad de bytes y documentos que se procesaron hasta el momento. Una vez que se completa la operación, el valor muestra la cantidad total real de bytes y documentos que se procesaron. Es posible que sea mayor que la del valor de workEstimated.

Divide workCompleted entre workEstimated para obtener una estimación aproximada del progreso. Es posible que esta 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/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 completa una operación, la descripción de la operación contiene "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.

Cancela una operación

Console

Puedes cancelar una operación de importación o exportación en ejecución en la página Importaciones/Exportaciones en modo Datastore de Google Cloud Console.

Ir a la página Importaciones/Exportaciones

En la tabla Importaciones y exportaciones recientes, las operaciones que se ejecutan actualmente incluyen un botón Cancelar en la columna Finalizada. Haz clic en el botón Cancelar para detener la operación. El botón cambia al mensaje Cancelando y, luego, a Cancelada cuando se detiene por completo la operación.

gcloud

Para detener una operación en curso, usa el comando operations cancel:

gcloud datastore operations cancel operation-name

Cancelar una operación en ejecución no deshace la operación. Una operación de exportación cancelada deja los documentos ya exportados en Cloud Storage y una operación de importación cancelada deja las actualizaciones ya implementadas en la base de datos. No se pueden importar documentos desde una exportación que se completó en forma parcial.

Borra una operación

gcloud

Usa el comando operations delete para quitar una operación de la lista de operaciones recientes. Con este comando, no se borrarán los archivos de exportación de Cloud Storage.

gcloud datastore operations delete operation-name

Facturación y precios de las importaciones y exportaciones administradas

Es obligatorio que habilites la facturación en tu proyecto de Google Cloud 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 de las siguientes maneras:

El límite de gasto de App Engine no se incluye en los costos de las operaciones de importación y exportación. Las operaciones de importación y exportación no activarán alertas de presupuesto en Google Cloud hasta que se completen. Asimismo, las lecturas y escrituras que se realicen durante una operación de importación o exportación se aplican a la cuota diaria cuando esta se completa.

Visualiza los costos de importación y exportación

Las operaciones de importación y exportación aplican la etiqueta goog-firestoremanaged:exportimport a las operaciones facturadas. En la página de informes de Facturación de Cloud, puedes usar esta etiqueta para ver los costos relacionados con las operaciones de importación y exportación:

Accede a la etiqueta goog-firestoremanaged desde el menú de filtros.

Permisos

Para ejecutar operaciones de importación y exportación, tu cuenta de usuario y la cuenta de servicio predeterminada del proyecto requieren los permisos de administración de identidades y accesos que se describen a continuación.

Permisos de cuenta de usuario

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

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

También puedes asignar estos permisos con una función personalizada.

El propietario de un proyecto puede otorgar una de estas funciones siguiendo los pasos que se indican en Otorga acceso.

Permisos de la cuenta de servicio predeterminada

Cada proyecto de Google Cloud 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 bucket de Cloud Storage que se usa en una operación de importación o exportación. Si tu bucket de Cloud Storage está en el mismo proyecto que tu base de datos en modo Datastore, la cuenta de servicio predeterminada tiene acceso al bucket de forma predeterminada.

Si el bucket de Cloud Storage está en otro proyecto, debes otorgar a la cuenta de servicio predeterminada acceso al bucket de Cloud Storage.

Asigna funciones a la cuenta de servicio predeterminada

Puedes usar la herramienta de línea de comandos de gsutil para asignar una de las funciones 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 Cloud Console.

Operaciones de exportación

Para las operaciones de exportación que involucran un bucket en otro proyecto, debes modificar los permisos del bucket 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 objetos de almacenamiento
  • Escritor de buckets heredados de almacenamiento

También puedes crear una función personalizada de IAM con permisos ligeramente diferentes a los que se encuentran en las funciones mencionadas anteriormente:

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

Operaciones de importación

Para las operaciones de importación que involucran un bucket de Cloud Storage en otro proyecto, debes modificar los permisos del bucket 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 IAM con los siguientes permisos:

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

Cuenta de servicio predeterminada inhabilitada o borrada

Si inhabilitas o borras tu cuenta de servicio predeterminada de App Engine, tu aplicación de App Engine perderá el acceso a tu base de datos en modo Datastore. Si inhabilitaste tu cuenta de servicio de App Engine, puedes volver a habilitarla. Para ello, consulta la documentación sobre cómo habilitar una cuenta de servicio. Si borraste tu cuenta de servicio de App Engine en los últimos 30 días, puedes restablecerla. Para ello, consulta cómo recuperar una cuenta de servicio.

Diferencias con las copias de seguridad de administrador de Datastore

Si ya usaste la Consola del administrador de Datastore para las copias de seguridad, debes tener en cuenta las siguientes diferencias:

  • Las exportaciones que crea una exportación administrada no aparecen en la Consola del administrador de 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, que se administra a través de Cloud Console.

  • El servicio de importación y exportación administrado no admite los mismos metadatos que la copia de seguridad de administrador de Datastore y no almacena el estado de progreso en tu base de datos. Para obtener información sobre cómo verificar el progreso de las operaciones de importación y exportación, consulta Administra operaciones de larga duración.

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

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

Importa a BigQuery

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

Los datos exportados sin especificar un filtro de entidad no se pueden cargar en BigQuery. Si deseas importar datos a BigQuery, tu solicitud de exportación debe incluir uno o más nombres de categorías en el filtro de entidad.

Límite de columnas de BigQuery

BigQuery impone un límite de 10,000 columnas por tabla. Las operaciones de exportación generan un esquema de tabla de BigQuery para cada tipo. En este esquema, cada propiedad única dentro de las entidades de una categoría se convierte en una columna del esquema.

Si el esquema de BigQuery de un tipo supera las 10,000 columnas, la operación de exportación intenta mantenerse por debajo del límite de columnas. Para ello, trata las entidades incorporadas como BLOB. Si esta conversión lleva la cantidad de columnas del esquema a menos de 10,000, puedes cargar los datos en BigQuery, pero no puedes consultar las propiedades dentro de las entidades incorporadas. Si la cantidad de columnas aún supera las 10,000, la operación de exportación no genera un esquema de BigQuery para la categoría y no puedes cargar sus datos en BigQuery.

Migración del agente de servicio

Ahora puedes usar un agente de servicio de Firestore para autorizar operaciones de importación y exportación en lugar de la cuenta de servicio de App Engine. El agente de servicio y la cuenta de servicio usan las siguientes convenciones de nombre:

Agente de servicio de Firestore
service-project_number@gcp-sa-firestore.iam.gserviceaccount.com
Cuenta de servicio de App Engine
project_id@appspot.gserviceaccount.com

Se prefiere el agente de servicio de Firestore porque es específico de Firestore. Más de un servicio comparte la cuenta de servicio de App Engine.

Puedes migrar al agente de servicio de Firestore mediante cualquiera de estas técnicas:

La primera de estas técnicas es preferible porque localiza el alcance del efecto en un solo proyecto en modo Datastore. No se prefiere la segunda técnica, porque no migra los permisos del bucket de Cloud Storage existente. Sin embargo, sí ofrece cumplimiento de seguridad a nivel de la organización.

Migra y verifica permisos de bucket de Cloud Storage

El proceso de migración tiene los siguientes dos pasos:

  1. Actualiza los permisos del bucket de Cloud Storage. Consulta la siguiente sección para obtener más detalles.
  2. Confirma la migración al agente de servicio de Firestore.

Permisos del bucket del agente de servicio

Para cualquier operación de importación o exportación que use un depósito de Cloud Storage en otro proyecto, debes otorgar los permisos del agente de servicios de Firestore para ese depósito. Por ejemplo, las operaciones que transfieren datos a otro proyecto deben acceder a un bucket en ese otro proyecto. De lo contrario, estas operaciones fallan después de migrar al agente de servicio de Firestore.

Los flujos de trabajo de importación y exportación que se encuentran dentro del mismo proyecto no requieren cambios en los permisos. El agente de servicio de Firestore puede acceder a los depósitos en el mismo proyecto de forma predeterminada.

Actualiza los permisos de los depósitos de Cloud Storage de otros proyectos para otorgar acceso al agente de servicio service-project_number@gcp-sa-firestore.iam.gserviceaccount.com. Otorga al agente de servicio la función Firestore Service Agent.

La función Firestore Service Agent otorga permisos de lectura y escritura a un bucket de Cloud Storage. Si necesitas otorgar solo permisos de lectura o solo escritura, usa una función personalizada.

El proceso de migración que se describe en la siguiente sección te ayuda a identificar los depósitos de Cloud Storage que pueden requerir actualizaciones de permisos.

Migra un proyecto al agente de servicio de Firestore

Completa los siguientes pasos para migrar de la cuenta de servicio de App Engine al agente de servicio de Firestore. Una vez completada, la migración no se puede deshacer.

  1. Ve a la página Importaciones/Exportaciones de Datastore en Google Cloud Console.

    Ir a la página Importaciones/Exportaciones

  2. Si tu proyecto aún no se migró al agente de servicio de Firestore, verás un banner que describe la migración y un botón Check Bucket Status. En el siguiente paso, podrás identificar y corregir posibles errores de permisos.

    Haga clic en Check Bucket Status.

    Aparecerá un menú con la opción de completar la migración y una lista de los depósitos de Cloud Storage. Es posible que la lista tarde unos minutos en terminar de cargarse.

    En esta lista, se incluyen los depósitos que se usaron recientemente en las operaciones de importación y exportación, pero que en la actualidad no otorgan permisos de lectura y escritura al agente de servicio del modo Datastore.

  3. Toma nota del nombre principal del agente de servicios del modo Datastore de tu proyecto. El nombre del agente de servicio aparece en la etiqueta Agente de servicio para otorgar acceso a.
  4. En el caso de cualquier bucket de la lista que usarás para operaciones futuras de importación o exportación, completa los siguientes pasos:

    1. En la fila de la tabla de este bucket, haz clic en Corregir. Se abrirá la página de permisos de ese bucket en una pestaña nueva.

    2. Haz clic en Agregar.
    3. En el campo Nuevos principales, ingresa el nombre de tu agente de servicio de Firestore.
    4. En el campo Seleccionar una función, selecciona Agentes de servicio > Agente de servicio de Firestore.
    5. Haz clic en Guardar.
    6. Regrese a la pestaña con la página Importaciones/Exportaciones del modo Datastore.
    7. Repite estos pasos para otros depósitos de la lista. Asegúrate de ver todas las páginas de la lista.
  5. Haz clic en Migrar al agente de servicio de Firestore. Si aún tienes depósitos con verificaciones de permisos con errores, haz clic en Migrar para confirmar la migración.

    Una alerta te informa cuando se completa tu migración. La migración no se puede deshacer.

Ver estado de migración

Para verificar el estado de migración de tu proyecto, ve a la página Importaciones/Exportaciones en Google Cloud Console.

Ir a la página Importaciones/Exportaciones

Busca la principal junto a la etiqueta Cuenta de servicio utilizada:.

Si la principal es service-project_number@gcp-sa-firestore.iam.gserviceaccount.com, entonces tu proyecto ya migró al agente de servicio de Firestore. La migración no se puede deshacer.

Si no se migró el proyecto, aparecerá un banner en la parte superior de la página con un botón Verificar estado del bucket . Consulta Migra al agente de servicio de Firestore para completar la migración.

Agrega una restricción de política para toda la organización

Establece la siguiente restricción en la política de tu organización:

Requerir un agente de servicio de Firestore para importar/exportar (firestore.requireP4SAforImportExport)

Esta restricción requiere que las operaciones de importación y exportación usen el agente de servicio de Firestore para autorizar solicitudes.

Para establecer esta restricción, consulta Crea y administra políticas de la organización.

La aplicación de esta restricción de la política de la organización no otorga automáticamente los permisos adecuados del bucket de Cloud Storage para el agente de servicio de Firestore.

Si la restricción crea errores de permisos para cualquier flujo de trabajo de importación o exportación, puedes inhabilitarlo a fin de volver a usar la cuenta de servicio predeterminada. Después de verificar y actualizar los permisos del bucket de Cloud Storage, puedes volver a habilitar la restricción.