Importa y exporta datos

Puedes usar el servicio administrado de importación y exportación de Cloud Firestore para recuperar datos que hayas borrado de manera accidental y exportar datos para realizar un procesamiento sin conexión. Puedes 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 de 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.

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

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 con facturación habilitada pueden usar la función de importación y exportación.
2. Crea un bucket de Cloud Storage para tu proyecto en una ubicación cercana a la ubicación de tu base de datos Cloud Firestore. No puedes usar un depósito de pagos del solicitante para las operaciones de importación y exportación.

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

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

   • Roles de Cloud Storage: Owner o Storage Admin

Permisos del agente de servicio

Las operaciones de importación y exportación usan un agente de servicio de Cloud Firestore para autorizar las operaciones de Cloud Storage. El agente de servicio de Cloud Firestore usa la siguiente convención de nombres:

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, consulta Agentes de servicio.

El agente de servicio de Cloud Firestore requiere acceso al bucket de Cloud Storage que se usó 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 de Cloud Firestore, el agente de servicio de Cloud 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 Cloud 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 Cloud 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 proyecto, que se usa para nombrar tu agente de servicio de Cloud 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 desde 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 Cloud Firestore o la cuenta de servicio heredada de App Engine.

1. Consulta la cuenta de autorización junto a la etiqueta Los trabajos de importación o exportación se ejecutan como.

La cuenta de servicio necesita el rol Storage Admin para que el bucket de Cloud Storage se use en la operación de importación o exportación.

Configura gcloud para tu proyecto

Puedes iniciar operaciones de importación y exportación mediante la consola de Google Cloud o la herramienta de línea de comandos de gcloud. Para usar gcloud, configura la herramienta de línea de comandos y conecta tu proyecto de una de las siguientes maneras:

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

  Inicia Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

• Instala y, luego, inicializa el SDK de Google Cloud:

Exportar datos

En una operación de exportación se copian documentos de tu base de datos a un conjunto de archivos en un depósito de Cloud Storage. Ten presente que no es una instantánea exacta de la base de datos en el momento de inicio de la operación. Es posible que incluya los cambios efectuados mientras se ejecuta la exportación.

Exporta todos los documentos

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

Exporta 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'

Exporta a partir de una marca de tiempo de PITR

Puedes exportar tu base de datos a Cloud Storage desde los datos de PITR 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 la PITR admite todos los filtros, incluida la exportación de todos los documentos y la exportación de colecciones específicas.

1. Exporta la base de datos y especifica el parámetro snapshot-time en la marca de tiempo de recuperación deseada.

   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.

   Ten en cuenta los siguientes puntos antes de exportar los datos de la PITR:

   • Especifica la marca de tiempo en formato RFC 3339. Un ejemplo es 2020-09-01T23:59:30.234233Z.
   • Asegúrate de que la marca de tiempo que especifiques sea de un minuto completo en los últimos siete días, pero no antes de la earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, se generará un error.
   • No se te cobra por una exportación de la PITR con errores.

Importa datos

Tras exportar los archivos de Cloud Storage, puedes volver a importar documentos de esos archivos a tu proyecto o a otro. Ten presente los siguientes puntos sobre las operaciones de importación:

• Cuando importas datos, se actualizan los índices necesarios con las definiciones de índices actuales de tu base de datos. Una exportación no contiene definiciones de índices.

• Las importaciones no asignan nuevos ID a los documentos, sino que usan los ID capturados en el momento en que se realizó la exportación. Cuando se importa un documento, se conserva su ID para evitar conflictos entre estos. Si ya existe un documento con el mismo ID, se reemplaza el documento existente durante la importación.

• Si la importación no afecta a un documento de la base de datos, este se conservará cuando la operación finalice.

• Las operaciones de importación no activan Cloud Functions. Los objetos de escucha 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 superior:

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

  Si mueves o copias los archivos de salida de una exportación, mantén los nombres de archivo PARENT_FOLDER_NAME y .overall_export_metadata iguales.

Importa todos los documentos desde 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'

Importa colecciones específicas

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

Importa una exportación de PITR

Sigue los pasos que se indican en Importa todos los documentos para importar la base de datos exportada. Si ya existe un documento en tu base de datos, se reemplazará.

Administra las operaciones de importación y exportación

Después de iniciar una operación de importación o exportación, Cloud Firestore le asigna 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/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Sin embargo, puedes omitir el prefijo cuando especifiques el nombre de una operación para los comandos describe, cancel, y delete.

Genera una lista de todas las operaciones de importación y exportación

gcloud firestore operations list

Verifica el estado de la operación

gcloud firestore operations describe [OPERATION_NAME]

Calcula el tiempo de finalización

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. Cloud Firestore podría omitir esta métrica si no puede hacer una estimación.

• workCompleted muestra 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 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.

Cancela una operación

gcloud firestore 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 le efectuaron a la base de datos. No se pueden importar documentos desde una exportación que se completó en forma parcial.

Borra una operación

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

gcloud firestore operations delete [OPERATION_NAME]

Facturación y precio de las operaciones de importación y exportación

Es obligatorio que habilites la facturación en el proyecto de Google Cloud antes de usar el servicio administrado de importación y exportación.

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

Los archivos de salida almacenados en Cloud Storage se tienen en cuenta en tus costos de almacenamiento de datos de Cloud Storage.

El límite de gasto no considera los costos de las operaciones de importación y exportación. Las operaciones de importación y exportación no activan alertas de presupuesto de 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. Las operaciones de importación y exportación no afectarán el uso que se muestra en la sección de uso de la consola.

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:

Exporta a BigQuery

Puedes cargar datos de una exportación de Cloud Firestore a BigQuery, pero solo si especificaste un filtro collection-ids. Consulta Cómo cargar datos de 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 colecciones. En este esquema, cada nombre de campo único dentro de un grupo de colecciones se convierte en una columna del esquema.

Si el esquema de BigQuery de un grupo de colecciones supera las 10,000 columnas, la operación de exportación de Cloud Firestore intenta mantenerse por debajo del límite de columnas. Para ello, trata los campos del mapa como bytes. Si esta conversión lleva 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 colecciones, por lo que no se pueden cargar tus datos en BigQuery.

Exporta archivos de formato y de metadatos

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

Archivos de metadatos

Una operación de exportación crea un archivo de metadatos para cada grupo de colecciones que especifiques. Por lo general, los archivos de metadatos se denominan ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

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

protoc --decode_raw < export0.export_metadata

Migración con agentes de servicio

Cloud Firestore usa un agente de servicio de Cloud 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 Cloud Firestore

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

Antes, Cloud Firestore usaba la cuenta de servicio predeterminada de App Engine en lugar del agente de servicio de Cloud Firestore. Si tu base de datos aún usa la cuenta de servicio de App Engine para importar o exportar datos, te recomendamos que sigas las instrucciones de esta sección para migrar al agente de servicio de Cloud Firestore.

Cuenta de servicio de App Engine

PROJECT_ID@appspot.gserviceaccount.com

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

Visualiza la cuenta de autorización

Puedes ver qué cuenta usan tus operaciones de importación y exportación para autorizar solicitudes desde la página Importaciones/Exportaciones en la consola de Google Cloud. También puedes ver si tu base de datos ya usa el agente de servicio de Cloud Firestore.

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

   Ir a Bases de datos

2. Selecciona la base de datos requerida de la lista.

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

4. 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 Cloud Firestore, puedes migrar al agente de servicio de Cloud Firestore con 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 a un solo proyecto de Cloud Firestore. La segunda técnica no se prefiere porque no migra los permisos existentes del bucket de Cloud Storage. 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:

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 Cloud 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 Cloud 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 fallan después de migrar agente de servicio de Cloud 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 Cloud Firestore puede acceder a buckets en el mismo proyecto de forma predeterminada.

Actualiza los permisos de los buckets de Cloud Storage de otros proyectos para otorgar acceso al agente de servicio de 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 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 Cloud Firestore. Una vez completada, la migración no se puede deshacer.

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

   Ir a Bases de datos

2. Selecciona la base de datos requerida de la lista.

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

4. Si tu proyecto aún no se ha migrado al agente de servicio de Cloud 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 de Cloud Firestore.

5. Toma nota del nombre principal del agente de servicio de Cloud Firestore de tu proyecto. El nombre del agente de servicio aparece bajo la etiqueta Service agent to give access to.

6. Para cualquier bucket de la lista que usarás en las operaciones futuras de importación o exportación, completa los siguientes pasos:

   1. 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.

   2. Haz clic en Agregar.
   3. En el campo Principales nuevas, ingresa el nombre de tu agente de servicio de Cloud Firestore.
   4. En el campo Selecciona un rol, selecciona Agentes de servicio > Agente de servicio de Firestore.
   5. Haz clic en Guardar.
   6. Regresa a la pestaña que tiene la página Cloud Firestore Import/Export.
   7. Repite estos pasos para otros buckets de la lista. Asegúrate de ver todas las páginas de la lista.

7. 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:

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

   Ir a Bases de datos

2. Selecciona la base de datos requerida de la lista.

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

4. 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, tu proyecto ya migró al agente de servicio de Cloud 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 Cloud 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 sobre los buckets de Cloud Storage al agente de servicio de Cloud 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.