Exportar e importar datos

Puede utilizar el servicio de exportación e importación administrado de Cloud Firestore para recuperarse de una eliminación accidental de datos y exportarlos para procesarlos sin conexión. Puede exportar todos los documentos o solo colecciones específicas. Asimismo, puedes importar todos los datos de una exportación o solo colecciones específicas. Los datos exportados desde una base de datos de Cloud Firestore se pueden importar a otra base de datos de Cloud Firestore. También puedes cargar exportaciones de Cloud Firestore en BigQuery .

Esta página describe cómo exportar e importar documentos de Cloud Firestore utilizando el servicio administrado de exportación e importación y Cloud Storage . El servicio de importación y exportación administrado de Cloud Firestore está disponible a través de la herramienta de línea de comandos gcloud y la API de Cloud Firestore ( REST , RPC ).

Antes de que empieces

Antes de poder utilizar el servicio administrado de exportación e importación, debe completar las siguientes tareas:

1. Habilite la facturación para su proyecto de Google Cloud. Solo los proyectos de Google Cloud con facturación habilitada pueden utilizar la funcionalidad de exportación e importación.
2. Crea un depósito de Cloud Storage para tu proyecto en una ubicación cercana a la ubicación de tu base de datos de Cloud Firestore . No puede utilizar un depósito de Pagos del solicitante para operaciones de exportación e importación.

3. Asegúrese de que su cuenta tenga los permisos necesarios para Cloud Firestore y Cloud Storage. Si eres el propietario del proyecto, tu cuenta tiene los permisos necesarios. De lo contrario, los siguientes roles otorgan los permisos necesarios para operaciones de exportación e importación y para acceder a Cloud Storage:

   • Roles de Cloud Firestore: Owner , Cloud Datastore Owner o Cloud Datastore Import Export Admin

   • Roles de almacenamiento en la nube: Owner o Storage Admin

Permisos del agente de servicio

Las operaciones de exportación e importación utilizan un agente de servicio de Cloud Firestore para autorizar las operaciones de Cloud Storage. El agente de servicio de Cloud Firestore utiliza la siguiente convención de nomenclatura:

Agente de servicio de Cloud Firestore

service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Para obtener más información sobre los agentes de servicio, consulte Agentes de servicio .

El agente de servicio de Cloud Firestore requiere acceso al depósito de Cloud Storage utilizado en una operación de exportación o importación. Si su depósito de Cloud Storage está en el mismo proyecto que su base de datos de Cloud Firestore, entonces el agente de servicio de Cloud Firestore puede acceder al depósito de forma predeterminada .

Si el depósito de Cloud Storage está en otro proyecto, debes darle acceso al agente de servicio de Cloud Firestore al depósito de Cloud Storage.

Asignar roles al agente de servicio

Puedes usar la herramienta de línea de comandos gsutil para asignar uno de los roles siguientes. Por ejemplo, para asignar la función de administrador de almacenamiento al agente de servicio de Cloud Firestore, ejecute lo siguiente:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Reemplace PROJECT_NUMBER con el número de su proyecto, que se utiliza para nombrar a su agente de servicio de Cloud Firestore. Para ver el nombre del agente de servicio, consulte Ver el nombre del agente de servicio .

Alternativamente, puedes asignar este rol usando GCP Console .

Ver el nombre del agente de servicio

Puede ver la cuenta que utilizan sus operaciones de importación y exportación para autorizar solicitudes desde la página Importar/Exportar en Google Cloud Platform Console. También puedes ver si tu base de datos utiliza el agente de servicio de Cloud Firestore o la cuenta de servicio heredada de App Engine.

1. Vea la cuenta de autorización junto a los trabajos de importación/exportación ejecutados como etiqueta.

El agente de servicio necesita la función Storage Admin para el depósito de Cloud Storage que se utilizará para la operación de exportación o importación.

Configura gcloud para tu proyecto

Puede iniciar operaciones de importación y exportación a través de Google Cloud Platform Console o la herramienta de línea de comandos gcloud . Para usar gcloud , configura la herramienta de línea de comandos y conéctate a tu proyecto de una de las siguientes maneras:

• Accede gcloud desde la consola de Google Cloud Platform usando Cloud Shell .

  Iniciar Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

• Instale e inicialice el SDK de Google Cloud.

Exportar datos

Una operación de exportación copia documentos de su base de datos en un conjunto de archivos en un depósito de Cloud Storage. Tenga en cuenta que una exportación no es una instantánea exacta de la base de datos tomada en el momento de inicio de la exportación. Una exportación puede incluir cambios realizados mientras se ejecutaba la operación.

Exportar todos los documentos

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Exportar colecciones específicas

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Exportar desde una marca de tiempo PITR

Puedes exportar tu base de datos a Cloud Storage desde datos PITR usando el comando gcloud firestore export . Puede exportar datos PITR donde la marca de tiempo sea una marca de tiempo de un minuto completo dentro de los últimos siete días, pero no antes de la earliestVersionTime . Si los datos ya no existen en la marca de tiempo especificada, la operación de exportación falla.

La operación de exportación PITR admite todos los filtros, incluida la exportación de todos los documentos y la exportación de colecciones específicas.

1. Exporte la base de datos, especificando el parámetro snapshot-time a la marca de tiempo de recuperación deseada.

   nube de gcloud

   Ejecute el siguiente comando para exportar la base de datos a su depósito.

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Dónde,

   • PITR_TIMESTAMP : una marca de tiempo PITR con granularidad de minutos, por ejemplo, 2023-05-26T10:20:00.00Z .

   Tenga en cuenta los siguientes puntos antes de exportar datos PITR:

   • Especifique la marca de tiempo en formato RFC 3339 . Por ejemplo, 2020-09-01T23:59:30.234233Z .
   • Asegúrese de que la marca de tiempo que especifique sea una marca de tiempo de un minuto completo dentro de los últimos siete días, pero no antes del earliestVersionTime . Si los datos ya no existen en la marca de tiempo especificada, se genera un error.
   • No se le cobrará por una exportación PITR fallida.

Datos de importacion

Una vez que haya exportado archivos en Cloud Storage, puede importar documentos en esos archivos nuevamente a su proyecto o a otro proyecto. Tenga en cuenta los siguientes puntos sobre las operaciones de importación:

• Cuando importa datos, los índices requeridos se actualizan utilizando las definiciones de índice actuales de su base de datos. Una exportación no contiene definiciones de índice.

• Las importaciones no asignan nuevos ID de documentos. Las importaciones utilizan los ID capturados en el momento de la exportación. Mientras se importa un documento, su ID se reserva para evitar colisiones de ID. Si ya existe un documento con el mismo ID, la importación sobrescribe el documento existente.

• Si un documento en su base de datos no se ve afectado por una importación, permanecerá en su base de datos después de la importación.

• Las operaciones de importación no activan Cloud Functions. Los oyentes de instantáneas reciben actualizaciones relacionadas con las operaciones de importación.

• El nombre del archivo .overall_export_metadata debe coincidir con el nombre de su carpeta principal:

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/ PARENT_FOLDER_NAME / PARENT_FOLDER_NAME .overall_export_metadata

  Si mueve o copia los archivos de salida de una exportación, mantenga el mismo nombre de archivo PARENT_FOLDER_NAME y .overall_export_metadata .

Importar todos los documentos de una exportación

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Importar colecciones específicas

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

Importar una exportación PITR

Utilice los pasos en Importar todos los documentos para importar su base de datos exportada. Si algún documento ya existe en su base de datos, se sobrescribirá.

Gestionar operaciones de exportación e importación.

Después de iniciar una operación de exportación o importación, Cloud Firestore asigna a la operación un nombre único. Puede utilizar el nombre de la operación para eliminar, cancelar o verificar el estado de la operación.

Los nombres de las operaciones tienen el prefijo projects/[PROJECT_ID]/databases/(default)/operations/ , por ejemplo:

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

Sin embargo, puede omitir el prefijo al especificar un nombre de operación para los describe , cancel y delete .

Listar todas las operaciones de exportación e importación.

gcloud firestore operations list

Verificar estado de operación

gcloud firestore operations describe [OPERATION_NAME]

Estimar el tiempo de finalización

Una solicitud del estado de una operación de larga duración devuelve las métricas workEstimated y workCompleted . Cada una de estas métricas se devuelve tanto en número de bytes como en número de entidades:

• workEstimated muestra el número total estimado de bytes y documentos que procesará una operación. Cloud Firestore podría omitir esta métrica si no puede hacer una estimación.

• workCompleted muestra el número de bytes y documentos procesados ​​hasta el momento. Una vez completada la operación, el valor muestra la cantidad total de bytes y documentos que realmente se procesaron, que puede ser mayor que el valor de workEstimated .

Divida workCompleted por workEstimated para una estimación aproximada del progreso. Esta estimación podría ser inexacta porque depende de la demora en la recopilación de estadísticas.

Cancelar una operación

gcloud firestore operations cancel [OPERATION_NAME]

Cancelar una operación en ejecución no deshace la operación. Una operación de exportación cancelada dejará los documentos ya exportados en Cloud Storage, y una operación de importación cancelada dejará en su lugar las actualizaciones ya realizadas en su base de datos. No puede importar una exportación parcialmente completada.

Eliminar una operación

Usa el comando gcloud firestore operations delete para eliminar una operación de la lista de operaciones recientes. Este comando no eliminará los archivos de exportación de Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Facturación y fijación de precios para operaciones de exportación e importación.

Debe habilitar la facturación para su proyecto de Google Cloud antes de utilizar el servicio administrado de exportación e importación.

Las operaciones de exportación e importación se cobran por las lecturas y escrituras de documentos según las tarifas indicadas en los precios de Cloud Firestore . Las operaciones de exportación implican una operación de lectura por documento exportado. Las operaciones de importación implican una operación de escritura por documento importado.

Los archivos de salida almacenados en Cloud Storage cuentan para los costos de almacenamiento de datos de Cloud Storage .

Los costos de las operaciones de exportación e importación no cuentan para su límite de gasto . Las operaciones de exportación o importación no activarán las alertas de presupuesto de Google Cloud hasta que finalicen. De manera similar, las lecturas y escrituras realizadas durante una operación de exportación o importación se aplican a su cuota diaria una vez completada la operación. Las operaciones de exportación e importación no afectarán el uso que se muestra en la sección de uso de la consola.

Ver los costos de exportación e importación

Las operaciones de exportación e importació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:

Exportar a BigQuery

Puedes cargar datos de una exportación de Cloud Firestore a BigQuery, pero solo si especificaste un filtro collection-ids . Consulta Carga de datos desde exportaciones de Cloud Firestore .

Límite de columnas de BigQuery

BigQuery impone un límite de 10.000 columnas por tabla. Las operaciones de exportación de Cloud Firestore generan un esquema de tabla de BigQuery para cada grupo de recopilación. En este esquema, cada nombre de campo único dentro de un grupo de colección se convierte en una columna de esquema.

Si el esquema de BigQuery de un grupo de recopilación supera las 10 000 columnas, la operación de exportación de Cloud Firestore intenta mantenerse por debajo del límite de columnas tratando los campos del mapa como bytes. Si esta conversión reduce la cantidad de columnas a menos de 10 000, puedes cargar los datos en BigQuery, pero no puedes consultar los subcampos dentro de los campos del mapa. 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 grupo de recopilación y no puedes cargar sus datos en BigQuery.

Exportar archivos de formato y metadatos

La salida de una exportación administrada utiliza el formato de registro LevelDB .

Archivos de metadatos

Una operación de exportación crea un archivo de metadatos para cada grupo de colección que especifique. Los archivos de metadatos normalmente se denominan ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata .

Los archivos de metadatos son buffers de protocolo y puedes decodificarlos con el compilador de protoc . Por ejemplo, puede decodificar un archivo de metadatos para determinar los grupos de colección que contienen los archivos de exportación:

protoc --decode_raw < export0.export_metadata

Migración del agente de servicio

Cloud Firestore utiliza un agente de servicio de Cloud Firestore para autorizar las operaciones de importación y exportación en lugar de utilizar la cuenta de servicio de App Engine. El agente de servicio y la cuenta de servicio utilizan las siguientes convenciones de nomenclatura:

Agente de servicio de Cloud Firestore

service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore utilizó anteriormente la cuenta de servicio predeterminada de App Engine en lugar del agente de servicio de Cloud Firestore. Si su base de datos todavía usa la cuenta de servicio de App Engine para importar o exportar datos, le recomendamos que siga las instrucciones de esta sección para migrar y usar el agente de servicio de Cloud Firestore.

Cuenta de servicio de App Engine

PROJECT_ID @appspot.gserviceaccount.com

Es preferible el agente de servicio de Cloud Firestore porque es específico de Cloud Firestore. La cuenta de servicio de App Engine es compartida por más de un servicio.

Ver cuenta de autorización

Puede ver qué cuenta utilizan sus operaciones de importación y exportación para autorizar solicitudes desde la página Importar/Exportar en Google Cloud Platform Console. También puedes ver si tu base de datos ya utiliza el agente de servicio de Cloud Firestore.

1. En la consola de Google Cloud Platform, vaya a la página Bases de datos .

   Ir a Bases de Datos

2. Seleccione la base de datos requerida de la lista de bases de datos.

3. En el menú de navegación, haga clic en Importar/Exportar .

4. Vea la cuenta de autorización junto a los trabajos de importación/exportación ejecutados como etiqueta.

Si tu proyecto no utiliza el agente de servicio de Cloud Firestore, puedes migrar al agente de servicio de Cloud Firestore usando cualquiera de estas técnicas:

• Para migrar un proyecto, verifica y actualiza los permisos del depósito de Cloud Storage (recomendado) .
• Agregue 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 único proyecto de Cloud Firestore. No se prefiere la segunda técnica porque no migra los permisos existentes del depósito de Cloud Storage. Sin embargo, ofrece cumplimiento de seguridad a nivel de organización.

Migre verificando y actualizando los permisos del depósito de Cloud Storage

El proceso de migración tiene dos pasos:

1. Actualice los permisos del depósito de Cloud Storage. Consulte la siguiente sección para obtener más detalles.
2. Confirme la migración al agente de servicio de Cloud Firestore.

Permisos del depósito del agente de servicio

Para cualquier operación de exportación o importación que utilice un depósito de Cloud Storage en otro proyecto, debes otorgar permisos al agente de servicio de Cloud Firestore para ese depósito. Por ejemplo, las operaciones que mueven datos a otro proyecto necesitan acceder a un depósito en ese otro proyecto. De lo contrario, estas operaciones fallarán después de migrar al agente de servicio de Cloud Firestore.

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

Actualice los permisos para 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 . Otorgue al agente de servicio la función Firestore Service Agent .

La función Firestore Service Agent otorga permisos de lectura y escritura para un depósito de Cloud Storage. Si necesita otorgar permisos de solo lectura o solo de escritura, use un rol personalizado .

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

Migrar un proyecto al agente de servicio de Firestore

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

1. En la consola de Google Cloud Platform, vaya a la página Bases de datos .

   Ir a Bases de Datos

2. Seleccione la base de datos requerida de la lista de bases de datos.

3. En el menú de navegación, haga clic en Importar/Exportar .

4. Si su proyecto aún no se ha migrado al agente de servicio de Cloud Firestore, verá un banner que describe la migración y un botón Verificar estado del depósito . El siguiente paso le ayuda a identificar y corregir posibles errores de permisos.

   Haga clic en Comprobar estado del depósito .

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

   Esta lista incluye depósitos que se utilizaron recientemente en operaciones de importación y exportación, pero que actualmente no otorgan permisos de lectura y escritura al agente de servicio de Cloud Firestore.

5. Tome nota del nombre principal del agente de servicio Cloud Firestore de su proyecto. El nombre del agente de servicio aparece debajo de Agente de servicio para dar acceso a la etiqueta.

6. Para cualquier depósito de la lista que utilizará para futuras operaciones de importación o exportación, complete los siguientes pasos:

   1. En la fila de la tabla de este depósito, haga clic en Reparar . Esto abre la página de permisos de ese depósito en una nueva pestaña.

   2. Haga clic en Agregar .
   3. En el campo Nuevos directores , ingresa el nombre de tu agente de servicio de Cloud Firestore.
   4. En el campo Seleccionar una función , seleccione Agentes de servicio > Agente de servicio de Firestore .
   5. Clic en Guardar .
   6. Regrese a la pestaña con la página Importar/Exportar de Cloud Firestore.
   7. Repita estos pasos para otros depósitos de la lista. Asegúrese de ver todas las páginas de la lista.

7. Haga clic en Migrar al agente de servicio de Firestore . Si todavía tiene depósitos con comprobaciones de permisos fallidas, debe confirmar su migración haciendo clic en Migrar .

   Una alerta le informa cuando se completa su migración. La migración no se puede deshacer.

Ver estado migratorio

Para verificar el estado de migración de su proyecto:

1. En la consola de Google Cloud Platform, vaya a la página Bases de datos .

   Ir a Bases de Datos

2. Seleccione la base de datos requerida de la lista de bases de datos.

3. En el menú de navegación, haga clic en Importar/Exportar .

4. Busque el principal junto a los trabajos de importación/exportación ejecutados como etiqueta.

   Si la entidad principal es service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com , entonces su proyecto ya se ha migrado al agente de servicio de Cloud Firestore. La migración no se puede deshacer.

   Si el proyecto no se ha migrado, aparece un banner en la parte superior de la página con el botón Comprobar estado del depósito . Consulte Migrar al agente de servicio de Firestore para completar la migración.

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

• Establezca la siguiente restricción en la política de su organización:

  Requiere Firestore Service Agent para importar/exportar ( firestore.requireP4SAforImportExport ).

  Esta restricción requiere operaciones de importación y exportación para utilizar el agente de servicio de Cloud Firestore para autorizar solicitudes. Para establecer esta restricción, consulte Creación y gestión de políticas de organización .

La aplicación de esta restricción de política organizacional no otorga automáticamente los permisos apropiados del depósito de Cloud Storage para el agente de servicio de Cloud Firestore.

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