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. Este servicio está disponible a través de la consola de Google Cloud, Google Cloud CLI y la API de administrador de Datastore (REST, 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 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. Para cada solicitud, el servicio limita a 100 la cantidad de combinaciones del filtro de entidad.
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.
El nombre de archivo
.overall_export_metadatadebe coincidir con el nombre de su carpeta superior:gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadataSi mueves o copias los archivos de salida de una exportación, mantén el
PARENT_FOLDER_NAME, el contenido de las subcarpetas y el nombre de archivo.overall_export_metadatasin modificar.
Antes de comenzar
Antes de usar el servicio administrado de importación y exportación, debes completar las siguientes tareas:
Habilita la facturación para tu proyecto de Google Cloud. Solo los proyectos de Google Cloud que tengan la facturación habilitada pueden usar las funciones de importación y exportación.
Crea un depósito 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.
Asigna una función de IAM a tu cuenta de usuario que otorgue el permiso
datastore.databases.export, si quieres exportar datos, odatastore.databases.import, si quieres importarlos. Por ejemplo, la funciónDatastore Import Export Adminotorga ambos permisos.Si el bucket de Cloud Storage está en otro proyecto, otorga al agente de servicio de Firestore acceso al bucket.
Configura gcloud para tu proyecto
Si planeas usar gcloud para iniciar las operaciones de importación y exportación, configura gcloud y conéctate al proyecto de una de las siguientes maneras:
Accede a
gclouddesde la consola de Google Cloud con Cloud Shell.Configura gcloud CLI para usar tu proyecto actual:
gcloud config set project project-idInstala y, luego, inicializa la CLI de Google Cloud.
Permisos
Para ejecutar operaciones de importación y exportación, tu cuenta de usuario y el agente de servicio del modo Datastore del proyecto requieren los siguientes permisos de Identity and Access Management.
Permisos de la cuenta de usuario
La cuenta de usuario o cuenta de servicio que inicia la operación requiere los permisos de IAM datastore.databases.export y datastore.databases.import. 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 mediante una función personalizada.
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 del agente de servicio
Las operaciones de importación y exportación usan un agente de servicio de Firestore para autorizar las operaciones de Cloud Storage. El agente de servicio de Firestore usa la siguiente convención de nombres:
- Agente de servicio de Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com
Para obtener más información sobre los agentes de servicio, consulta Agentes de servicio.
El agente de servicio de Firestore requiere acceso al bucket de Cloud Storage que se usa en una operación de importación o exportación. Si el bucket de Cloud Storage está en el mismo proyecto que la base de datos de Firestore, el agente de servicio de Firestore puede acceder al bucket de forma predeterminada.
Si el bucket de Cloud Storage está en otro proyecto, debes darle al agente de servicio de Firestore acceso al bucket de Cloud Storage.
Asigna roles al agente de servicio
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 el rol Administrador de almacenamiento al agente de servicio de Firestore, ejecuta lo siguiente:
gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
gs://[BUCKET_NAME]
Reemplaza PROJECT_NUMBER por el número de tu proyecto, que se usa para asignarle un nombre a tu agente de servicio de Firestore. Para ver el
nombre del agente de servicio, consulta Consulta el nombre del agente de servicio.
Como alternativa, puedes asignar este rol con la consola de Google Cloud.
Consulta el nombre del agente de servicio
Puedes ver la cuenta que usan tus operaciones de importación y exportación para autorizar solicitudes en la página Importar/Exportar en la consola de Google Cloud. También puedes ver si tu base de datos usa el agente de servicio de Firestore o la cuenta de servicio heredada de App Engine.
-
En la consola de Google Cloud, ve a la página Bases de datos.
-
Selecciona la base de datos requerida de la lista.
-
En el menú de navegación, haz clic en Importar/Exportar.
- Consulta la cuenta de autorización junto a la etiqueta Los trabajos de importación o exportación se ejecutan como.
Operaciones de exportación
Para las operaciones de exportación que involucran un bucket en otro proyecto, modifica los permisos del bucket para asignar una de las siguientes funciones de administración de identidades y accesos al agente de servicio del modo Datastore del proyecto que contiene tu base de datos en modo Datastore:
- Administrador de almacenamiento
- Propietario (rol básico)
También puedes crear una función personalizada de IAM con permisos ligeramente diferentes a los que se incluyen en los roles enumerados anteriormente:
storage.buckets.getstorage.objects.createstorage.objects.deletestorage.objects.list
Operaciones de importación
Para las operaciones de importación que involucran un bucket de Cloud Storage en otro proyecto, modifica los permisos del bucket para asignar una de las siguientes funciones de Cloud Storage al agente de servicio de modo Datastore 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.getstorage.objects.get
Inicia operaciones administradas de importación y exportación
En esta sección, se describe cómo iniciar una operación administrada de exportación o importación.
Exporta todas las entidades
Console
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
- En el menú de navegación, haz clic en Importar/Exportar.
- Haz clic en Exportar.
- Establece el campo Espacio de nombres en
All Namespacesy el campo Tipo enAll Kinds. - Debajo de Destino, ingresa el nombre de tu depósito de Cloud Storage.
- Haz clic en Exportar (Export).
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 firestore export para exportar todas las entidades de tu base de datos.
gcloud firestore export gs://bucket-name --async --database=DATABASE
En el ejemplo anterior, bucket-name es el nombre del depósito 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 administrado de exportación crea uno basado en la hora actual.
Usa la marca [--async][async-flag] 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. Esto no cancelará la operación.
Establece la marca --database en el nombre de la base de datos desde la que deseas exportar las entidades. Para la base de datos predeterminada, usa --database='(default)'.
rest
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- project-id: el ID de tu proyecto
- bucket-name: Es el nombre del 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:
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"
}
}
Exporta tipos o espacios de nombres específicos
Si quieres exportar un subconjunto de tipos o espacios de nombres, proporciona un filtro de entidad con valores para los ID de espacios de nombres y tipos. Cada solicitud está limitada a 100 combinaciones de filtro de entidades, y cada una de las combinaciones de tipo y espacio de nombres filtrados cuenta como un filtro diferente en este límite.
Console
En la consola puedes seleccionar todos los tipos o un tipo específico. También puedes seleccionar todos los espacios de nombres o un espacio de nombres específico.
A fin de especificar una lista de espacios de nombres y tipos para exportar, usa gcloud.
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haz clic en Importar/Exportar.
Haz clic en Exportar.
Establece el campo Espacio de nombres en
All Namespaceso el nombre de uno de tus espacios de nombres.Establece el campo Tipo en
All Kindso el nombre de un tipo.En Destino, ingresa el nombre de tu depósito de Cloud Storage.
Haz clic en Exportar (Export).
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 firestore export --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name \ --async \ --database=DATABASE
En el ejemplo anterior, bucket-name es el nombre del depósito 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 administrado de exportación crea uno basado en la hora actual.
Usa la marca [--async][async-flag] 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. Esto no cancelará la operación.
Establece la marca --database en el nombre de la base de datos desde la que deseas exportar tipos o espacios de nombres específicos. Para la base de datos predeterminada, usa --database='(default)'.
rest
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- project-id: el ID de tu proyecto
- bucket-name: Es el nombre del depósito de Cloud Storage.
- kind: Es el tipo de entidad.
- namespace: Es 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:
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"
}
}
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 las categorías que contienen los archivos de exportación:
protoc --decode_raw < export0.export_metadata
Importa todas las entidades
Console
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haz clic en Importar/Exportar.
Haz clic en Importar.
En el campo
File, haz clic en Examinar y selecciona un archivo.overall_export_metadata.Asegúrate de que no se mueva el archivo
.overall_export_metadatade la ubicación predeterminada.Establece el campo Espacio de nombres en
All Namespacesy el campo Tipo enAll Kinds.Haga clic en Import.
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 firestore import para importar todas las entidades que se exportaron anteriormente con el servicio de exportación administrado.
gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \ --async \ --database=DATABASE
En el ejemplo anterior, bucket-name/file-path/file-name es la ruta al archivo overall_export_metadata dentro del depósito de Cloud Storage.
Usa la marca [--async][async-flag] 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. Esto no cancelará la operación.
Establece la marca --database en el nombre de la base de datos en la que deseas importar todas las entidades. Para la base de datos predeterminada, usa --database='(default)'.
rest
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- project-id: el ID de tu proyecto
- bucket-name: Es el nombre del depósito 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"
}
}
Ubica tu archivo overall_export_metadata
Puedes determinar el valor que se usará para la ubicación de la importación con el navegador de Cloud Storage en la consola de Google Cloud:
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
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 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. También puedes seleccionar todos los espacios de nombres o un espacio de nombres específico.
A fin de especificar una lista de espacios de nombres y tipos para importar, usa gcloud.
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haz clic en Importar/Exportar.
Haz clic en Importar.
En el campo
File, haz clic en Examinar y selecciona un archivo.overall_export_metadata.Asegúrate de importar el archivo
.overall_export_metadatay no uno.export_metadata.Establece el campo Espacio de nombres en
All Namespaceso un espacio de nombres específico.Establece el campo Tipo como
All Kindso como un tipo específico.Haga clic en Import.
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 firestore import --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name/file-path/file-nameoverall_export_metadata \ --async \ --database=DATABASE
En el ejemplo anterior, bucket-name/file-path/file-name es la ruta al archivo overall_export_metadata dentro del depósito de Cloud Storage.
Usa la marca [--async][async-flag] 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. Esto no cancelará la operación.
Establece la marca --database en el nombre de la base de datos en la que deseas importar los tipos o espacios de nombres específicos. Para la base de datos predeterminada, usa --database='(default)'.
rest
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- project-id: el ID de tu proyecto
- bucket-name: Es el nombre del depósito 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: Es el tipo de entidad.
- namespace: Es 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:
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"
}
}
Importa y exporta datos de PITR
Puedes exportar tu base de datos a Cloud Storage desde datos de PITR coherentes con el comando gcloud firestore export. Puedes exportar datos de PITR en los que la marca de tiempo sea una de un minuto completo dentro de los últimos siete días, pero no antes que la earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, fallará la operación de exportación.
La operación de exportación de PITR admite todos los filtros, incluida la exportación de todas las entidades y la exportación de tipos o espacios de nombres específicos.
Exporta la base de datos y especifica el parámetro
snapshot-timeen la marca de tiempo de recuperación requerida.gcloud
Ejecuta el siguiente comando para exportar la base de datos a tu bucket.
gcloud firestore export gs://[BUCKET_NAME_PATH] \ --snapshot-time=[PITR_TIMESTAMP] \ --collection-ids=[COLLECTION_IDS] \ --namespace-ids=[NAMESPACE_IDS]En donde,
PITR_TIMESTAMP: Es una marca de tiempo de la PITR en el nivel de detalle por minuto, por ejemplo,2023-05-26T10:20:00.00Z.
También se admite [exportar un subconjunto específico de categorías o espacios de nombres con un filtro de entidad][export-kind].
Ten en cuenta los siguientes puntos antes de exportar los datos de la PITR:
- Especifica la marca de tiempo en formato
RFC 3339.
Por ejemplo,
2020-09-01T23:59:30.234233Z - Asegúrate de que la marca de tiempo que especifiques sea una marca de tiempo de un minuto completo dentro de los últimos siete días, pero no antes que el
earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, recibirás un error. - No se te cobrará por una exportación de PITR fallida.
Importa a una base de datos
Sigue los pasos que se indican en Importa todas las entidades para importar tu base de datos exportada. Si ya existe alguna entidad en tu base de datos, se reemplazará. También se admite [importar un subconjunto específico de categorías o espacios de nombres con un filtro de entidad][import-kind].
Importa transformaciones
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 claves 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 errores de “entidad demasiado grande” o “entradas de índice 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 a las operaciones de importación con datos del mismo proyecto.
Administrar operaciones de larga duración
Las operaciones administradas de importación y exportación son operaciones de larga duración. Estas llamadas de método 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 este nombre para borrar, cancelar o verificar el estado de la operación.
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 larga duración en la página Importaciones/Exportaciones de la consola de Google Cloud.
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haz clic en Importar/Exportar.
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 recientemente 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"
}
}
]
}
rest
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- 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, verás información sobre la respuesta.
Por ejemplo, una operación de exportación completada recientemente 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, haz lo siguiente:
Console
Puedes ver una lista de las operaciones de importación y exportación más recientes en la página Importar/Exportar de la consola de Google Cloud.
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haz clic en Importar/Exportar.
gcloud
Usa el comando operations describe para mostrar el estado de una operación de larga duración.
gcloud datastore operations describe operation-name
rest
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- project-id: el ID de tu proyecto
- operation-name: Es 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:
workEstimatedmuestra la cantidad total estimada de bytes y documentos que se procesarán en una operación. El modo Datastore puede omitir esta métrica si no puede hacer una estimación.workCompletedmuestra la cantidad de bytes y documentos que se procesaron hasta el momento. Cuando la operación se completa, el valor muestra la cantidad total real de bytes y documentos que se procesaron. Es posible que sea mayor que la del valor deworkEstimated.
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 Importar/Exportar de la consola de Google Cloud.
En la consola de Google Cloud, ve a la página Bases de datos.
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haz clic en Importar/Exportar.
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 curso no deshace su progreso. Cuando se cancela una operación de exportación, los documentos que ya se exportaron se conservan en Cloud Storage y, cuando se cancela una operación de importación, se conservan las actualizaciones que ya se efectuaron en la base de datos. No se pueden importar una exportación que se completó de forma parcial.
Borra una operación
gcloud
Usa el comando operations delete para quitar una operación de la lista de operaciones recientes. Este comando no borrará 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:
- Las operaciones de lectura y escritura de entidades que realizan las operaciones de importación y exportación se tienen en cuenta para los costos de Firestore en modo Datastore. Las operaciones de exportación incurren en una operación de lectura por cada entidad exportada. Las operaciones de importación incurren en una operación de escritura por cada entidad importada.
- Los archivos de salida almacenados en Cloud Storage se tienen en cuenta para los costos de almacenamiento de datos de Cloud Storage.
Las operaciones de importación o exportación no activarán alertas de presupuesto en Google Cloud hasta que se completen. De manera similar, las operaciones de lectura y escritura realizadas durante una operación de importación o exportación se aplican a tu cuota diaria una vez que la operación se completa.
Visualiza los costos de importación y exportación
En las operaciones de importación y exportación, se aplica 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:
Diferencias con las copias de seguridad del administrador de Datastore
Si alguna vez usaste la Consola del administrador de Datastore para realizar copias de seguridad, notarás 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 la consola de Google Cloud.
El servicio administrado de importación y exportación no es compatible con los mismos metadatos que la copia de seguridad de administrador de Datastore y no almacena el estado de progreso en la 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 retrocompatible con los archivos de copia de seguridad de administrador de Datastore. Puedes importar un archivo de copia de seguridad de administrador de Datastore con el servicio administrado de importación, 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 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.
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 un tipo se convierte en una columna.
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 reduce el número de columnas en el esquema a menos de 10,000, puedes cargar los datos en BigQuery, pero no puedes consultar las propiedades 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 el tipo y no se pueden cargar sus datos en BigQuery.
Migración con agentes de servicio
Firestore usa un agente de servicio de Firestore para autorizar las operaciones de importación y exportación en lugar de usar la cuenta de servicio de App Engine. El agente de servicio y la cuenta de servicio usan las siguientes convenciones de nombres:
- Agente de servicio de Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com
Anteriormente, Firestore usaba la cuenta de servicio predeterminada de App Engine en lugar del agente de servicio de Firestore. Si tu base de datos todavía usa la cuenta de servicio de App Engine para importar o exportar datos, te recomendamos que sigas las instrucciones de esta sección a fin de migrar al uso del agente de servicio de Firestore.
- 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.
Visualiza la cuenta de autorización
Puedes ver qué cuenta usan tus operaciones de importación y exportación para autorizar solicitudes en la página Importar/Exportar en la consola de Google Cloud. También puedes ver si tu base de datos ya usa el agente de servicio de Firestore.
-
En la consola de Google Cloud, ve a la página Bases de datos.
- Selecciona la base de datos requerida de la lista.
-
En el menú de navegación, haz clic en Importar/Exportar.
- Consulta la cuenta de autorización junto a la etiqueta Los trabajos de importación o exportación se ejecutan como.
Si tu proyecto no usa el agente de servicio de Firestore, puedes migrar al agente de servicio de Firestore mediante cualquiera de estas técnicas:
- Revisa y actualiza los permisos del bucket de Cloud Storage (recomendado) para migrar un proyecto.
- Agrega una restricción de política para toda la organización que afecte a todos los proyectos dentro de la organización.
La primera de estas técnicas es preferible porque localiza el alcance del efecto en un solo proyecto del modo Datastore. No se prefiere la segunda técnica, ya que no migra los permisos del bucket de Cloud Storage existentes. Sin embargo, sí ofrece el cumplimiento de seguridad a nivel de la organización.
Revisa y actualiza los permisos del bucket de Cloud Storage para migrar un proyecto
El proceso de migración consta de dos pasos:
- Actualizar los permisos del bucket de Cloud Storage (consulta la siguiente sección para obtener más detalles).
- Confirma la migración al agente de servicio de Firestore.
Permisos del agente de servicio sobre el bucket
Para cualquier operación de importación o exportación que use un bucket de Cloud Storage en otro proyecto, debes otorgar al agente de servicio de Firestore permisos para ese bucket. Por ejemplo, las operaciones que mueven datos a otro proyecto deben acceder a un bucket de ese otro proyecto. De lo contrario, estas operaciones fallarán 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 buckets del mismo proyecto de forma predeterminada.
Actualiza los permisos de los buckets 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 el rol Firestore Service Agent.
El rol Firestore Service Agent otorga permisos de lectura y escritura a un bucket de Cloud Storage. Si necesitas otorgar solo permisos de lectura o escritura, usa un rol personalizado.
El proceso de migración que se describe en la siguiente sección te ayuda a identificar los buckets 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.
-
En la consola de Google Cloud, ve a la página Bases de datos.
- Selecciona la base de datos requerida de la lista.
-
En el menú de navegación, haz clic en Importar/Exportar.
-
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 Verificar estado del bucket. En el siguiente paso, podrás identificar y corregir posibles errores de permisos.
Haz clic en Verificar estado del bucket.
Aparecerá un menú con la opción de completar tu migración y una lista de buckets de Cloud Storage. Es posible que la lista tarde unos minutos en terminar de cargarse.
En esta lista, se incluyen los buckets que se usaron recientemente en 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.
- Toma nota del nombre principal del agente de servicio del modo Datastore de tu proyecto. El nombre del agente de servicio aparece bajo la etiqueta Service agent to give access to.
-
Para cualquier bucket de la lista que usarás en las operaciones futuras de importación o exportación, completa los siguientes pasos:
-
En la fila de la tabla del bucket, haz clic en Corregir. Se abrirá la página de permisos del bucket en una pestaña nueva.
- Haz clic en Agregar.
- En el campo Principales nuevas, ingresa el nombre del agente de servicio de Firestore.
- En el campo Selecciona un rol, selecciona Agentes de servicio > Agente de servicio de Firestore.
- Haz clic en Guardar.
- Regresa a la pestaña de la página de importación y exportación del modo Datastore.
- Repite estos pasos para otros buckets de la lista. Asegúrate de ver todas las páginas de la lista.
-
-
Haz clic en Migrar al agente de servicio de Firestore. Si aún tienes buckets con verificaciones de permisos con errores, debes confirmar la migración haciendo clic en Migrar.
Una alerta te informa cuando se completa la migración. No se puede deshacer la migración.
Consulta el estado de la migración
Para verificar el estado de migración de tu proyecto, sigue estos pasos:
-
En la consola de Google Cloud, ve a la página Bases de datos.
- Selecciona la base de datos requerida de la lista.
-
En el menú de navegación, haz clic en Importar/Exportar.
-
Busca la principal junto a la etiqueta Los trabajos de importación o exportación se ejecutan como.
Si la principal es
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, significa que tu proyecto ya migró al agente de servicio de Firestore. No se puede deshacer la migración.Si el proyecto no se migró, aparecerá un banner en la parte superior de la página con un botón Verificar estado del bucket. Para completar la migración, consulta Migra al agente de servicio de Firestore.
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:
Requiere el agente de servicio de Firestore para importar y 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 .
Aplicar esta restricción de política de la organización no otorga de forma automática los permisos adecuados bucket de Cloud Storage para el agente de servicio de Firestore.
Si la restricción crea errores de permisos en algún flujo de trabajo de importación o exportación, puedes inhabilitarla para 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.