Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Exportar e importar datos

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

Puede usar el servicio de exportación e importación administrado de Cloud Firestore para recuperarse de la eliminación accidental de datos y para exportar datos para su procesamiento sin conexión. Puede exportar todos los documentos o solo colecciones específicas. Asimismo, puede 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 las exportaciones de Cloud Firestore en BigQuery .

En esta página, se describe cómo exportar e importar documentos de Cloud Firestore mediante el servicio administrado de exportación e importación y Cloud Storage . El servicio administrado de exportación e importació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 , RPC ).

Antes de que empieces

Antes de poder utilizar el servicio de exportación e importación administrado, debe 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 funcionalidad de exportación e importación.
  2. Cree un depósito de Cloud Storage para su proyecto en una ubicación cercana a la ubicación de su base de datos de Cloud Firestore . No puede usar un depósito de pago 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 es el propietario del proyecto, su cuenta tiene los permisos necesarios. De lo contrario, los siguientes roles otorgan los permisos necesarios para las operaciones de exportación e importación y para acceder a Cloud Storage:

Permisos de cuenta de servicio predeterminados

Cada proyecto de Google Cloud crea automáticamente una cuenta de servicio predeterminada denominada PROJECT_ID @appspot.gserviceaccount.com . Las operaciones de exportación e importación usan esta cuenta de servicio para autorizar las operaciones de Cloud Storage.

La cuenta de servicio predeterminada de tu proyecto requiere acceso al depósito de Cloud Storage que se usa en una operación de 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, la cuenta de servicio predeterminada tiene acceso al depósito de forma predeterminada .

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

La cuenta de servicio necesita la función de Storage Admin para que el depósito de Cloud Storage se use para la operación de exportación o importación.

Si deshabilita o elimina su cuenta de servicio predeterminada de App Engine, su aplicación de App Engine perderá el acceso a su base de datos de Cloud Firestore. Si inhabilitó su cuenta de servicio de App Engine, puede volver a habilitarla; consulte habilitar una cuenta de servicio . Si eliminó su cuenta de servicio de App Engine en los últimos 30 días, puede restaurar su cuenta de servicio; consulte cómo recuperar una cuenta de servicio .

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 de gcloud . Para usar gcloud , configure la herramienta de línea de comandos y conéctese a su proyecto de una de las siguientes maneras:

Exportar datos

Una operación de exportación copia documentos en su base de datos a 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

Consola de la nube de Google

  1. Vaya a la página de importación/exportación de Cloud Firestore en Google Cloud Platform Console.

    Ir a la página Importar/Exportar

  2. Haga clic en Exportar .

  3. Haga clic en la opción Exportar toda la base de datos.

  4. Debajo de Elegir destino , ingrese el nombre de un depósito de Cloud Storage o use el botón Examinar para seleccionar un depósito.

  5. Haga clic en Exportar .

La consola vuelve a la página Importar/Exportar . Si la operación se inicia correctamente, la página agrega una entrada a la página de importaciones y exportaciones recientes. En caso de falla, la página muestra un mensaje de error.

gcloud

Use el comando de exportación de firestore export para exportar todos los documentos en su base de datos, reemplazando [BUCKET_NAME] con el nombre de su depósito de Cloud Storage. Agrega la --async para evitar que la herramienta gcloud espere a que se complete la operación.

gcloud firestore export gs://[BUCKET_NAME]

Puede organizar sus exportaciones agregando un prefijo de archivo después del nombre del depósito, por ejemplo, BUCKET_NAME/my-exports-folder/export-name . Si no proporciona un prefijo de archivo, el servicio de exportación administrado crea uno basado en la marca de tiempo actual.

Una vez que inicia una operación de exportación, cerrar la terminal no cancela la operación, consulte cancelar una operación .

Exportar colecciones específicas

Consola de la nube de Google

  1. Vaya a la página de importación/exportación de Cloud Firestore en Google Cloud Platform Console.

    Ir a la página Importar/Exportar

  2. Haga clic en Exportar .

  3. Haga clic en la opción Exportar uno o más grupos de colecciones . Use el menú desplegable para seleccionar uno o más grupos de colección.

  4. Debajo de Elegir destino , ingrese el nombre de un depósito de Cloud Storage o use el botón Examinar para seleccionar un depósito.

  5. Haga clic en Exportar .

La consola vuelve a la página Importar/Exportar . Si la operación se inicia correctamente, la página agrega una entrada a la página de importaciones y exportaciones recientes. En caso de falla, la página muestra un mensaje de error.

gcloud

Para exportar grupos de colecciones específicos, use la --collection-ids . La operación exporta solo los grupos de colección con los ID de colección proporcionados. El grupo de colección incluye todas las colecciones y subcolecciones (en cualquier ruta) con el ID de colección especificado.

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

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 acerca de 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. A medida que 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

Consola de la nube de Google

  1. Vaya a la página de importación/exportación de Cloud Firestore en Google Cloud Platform Console.

    Ir a la página Importar/Exportar

  2. Haga clic en Importar .

  3. En el campo Nombre de archivo, ingrese el nombre de archivo de un archivo .overall_export_metadata de una operación de exportación completa. Puede usar el botón Examinar para ayudarlo a seleccionar el archivo.

  4. Haga clic en Importar .

La consola vuelve a la página Importar/Exportar . Si la operación se inicia correctamente, la página agrega una entrada a la página de importaciones y exportaciones recientes. En caso de falla, la página muestra un mensaje de error.

gcloud

Utilice el comando de firestore import para importar documentos de una operación de exportación anterior.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

donde [BUCKET_NAME] y [EXPORT_PREFIX] apuntan a la ubicación de sus archivos de exportación. Por ejemplo:

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

Puede confirmar la ubicación de sus archivos de exportación en el navegador de Cloud Storage en Google Cloud Platform Console:

Abra el navegador de almacenamiento en la nube

Una vez que inicia una operación de importación, cerrar la terminal no cancela la operación, consulte cancelar una operación .

Importar colecciones específicas

Consola de la nube de Google

No puede seleccionar colecciones específicas en la consola. Usa gcloud en su lugar.

gcloud

Para importar grupos de colecciones específicos de un conjunto de archivos de exportación, use la --collection-ids . La operación importa solo los grupos de colección con los ID de colección proporcionados. El grupo de colección incluye todas las colecciones y subcolecciones (en cualquier ruta) con el ID de colección especificado.

Solo una exportación de grupos de colección específicos admite una importación de grupos de colección específicos. No puede importar colecciones específicas de una exportación de todos los documentos.

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

Gestión de operaciones de exportación e importación.

Después de iniciar una operación de exportación o importación, Cloud Firestore asigna un nombre único a la operación. Puede usar 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 comandos describe , cancel y delete .

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

Consola de la nube de Google

Puede ver una lista de operaciones recientes de exportación e importación en la página de importación/exportación de Cloud Firestore de Google Cloud Platform Console.

Ir a la página Importar/Exportar

gcloud

Utilice el comando de operations list para ver todas las operaciones de exportación e importación en ejecución y recientemente completadas:

gcloud firestore operations list

Verificar estado de operación

Consola de la nube de Google

Puede ver el estado de una operación de exportación o importación reciente en la página de importación/exportación de Cloud Firestore de Google Cloud Platform Console.

Ir a la página Importar/Exportar

gcloud

Utilice el comando de operations describe para mostrar el estado de una operación de exportación o importació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 se procesaron realmente, lo que puede ser mayor que el valor de workEstimated .

Divida workCompleted por workEstimated para obtener una estimación aproximada del progreso. Esta estimación puede ser inexacta, ya que depende de la recopilación de estadísticas retrasada.

Cancelar una operación

Consola de la nube de Google

Puede cancelar una operación de exportación o importación en ejecución en la página de importación/exportación de Cloud Firestore de Google Cloud Platform Console.

Ir a la página Importar/Exportar

En la tabla Importaciones y exportaciones recientes , las operaciones que se están ejecutando actualmente incluyen un botón Cancelar en la columna Completado . Haga clic en el botón Cancelar para detener la operación. El botón cambia a un mensaje Cancelando y luego a Cancelado cuando la operación se detiene por completo.

gcloud

Utilice el comando de operations cancel para detener una operación en curso:

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á las actualizaciones ya realizadas en su base de datos. No puede importar una exportación completada parcialmente.

Eliminar una operación

Usa el comando de eliminación de operaciones de 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 tarificación de operaciones de exportación e importación

Debe habilitar la facturación para su proyecto de Google Cloud antes de usar el servicio de importación y exportación administrado. Las operaciones de exportación e importación se cobran por las lecturas y escrituras de documentos según las tarifas que se indican en los precios de Cloud Firestore .

Los costos de las operaciones de exportación e importación no cuentan para su límite de gastos . Las operaciones de exportación o importación no activarán sus 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 que se completa 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.

Visualización de los costos de exportación e importación

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

Acceda a la etiqueta administrada por goog-firestore desde el menú de filtros.

Exportar a BigQuery

Puede cargar datos de una exportación de Cloud Firestore en BigQuery, pero solo si especificó un filtro collection-ids . Consulta Cargar datos de las exportaciones de Cloud Firestore .

Límite de columna 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 colecció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 colección supera las 10 000 columnas, la operación de exportación de Cloud Firestore intenta mantenerse por debajo del límite de columnas al tratar los campos del mapa como bytes. Si esta conversión hace que la cantidad de columnas sea inferior a 10 000, puede cargar los datos en BigQuery, pero no puede 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 colección y no puede cargar sus datos en BigQuery.

Formato de exportación y archivos de metadatos

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

Archivos de metadatos

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

Los archivos de metadatos son búferes de protocolo y puede decodificarlos con el compilador de protocolo 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 de agentes de servicio

Ahora puede usar un agente de servicio de Cloud 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 utilizan las siguientes convenciones de nomenclatura:

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

El agente de servicio de Cloud Firestore es preferible 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 usan sus operaciones de importación y exportación para autorizar solicitudes desde la página Importar/Exportar en Google Cloud Platform Console. También puede ver si su base de datos ya usa el agente de servicio de Cloud Firestore.

  1. Vaya a la página de importación/exportación de Cloud Firestore en Google Cloud Platform Console.

    Ir a Importar/Exportar

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

Si su proyecto no usa el agente de servicio de Cloud Firestore, puede migrar al agente de servicio de Cloud Firestore usando cualquiera de estas técnicas:

La primera de estas técnicas es preferible porque localiza el alcance del efecto en un solo proyecto de Cloud Firestore. La segunda técnica no es la preferida porque no migra los permisos de depósito de Cloud Storage existentes. Sin embargo, ofrece cumplimiento de seguridad a nivel de organización.

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

El proceso de migración consta de dos pasos:

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

Permisos de depósito de agente de servicio

Para cualquier operación de exportación o importación que use un depósito de Cloud Storage en otro proyecto, debe 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 fallan 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 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 el rol 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 escritura, use un rol personalizado .

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

Migrar un proyecto a Firestore Service Agent

Complete 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. Vaya a la página de importación/exportación de Cloud Firestore en Google Cloud Platform Console.

    Ir a Importar/Exportar

  2. Si su proyecto aún no 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 lo ayuda a identificar y corregir posibles errores de permisos.

    Haga clic en Verificar el estado del depósito .

    Aparece un menú con la opción para completar la migración y una lista de depósitos de Cloud Storage. La lista puede tardar unos minutos en terminar de cargarse.

    Esta lista incluye depósitos que se usaron 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.

  3. Tome nota del nombre principal del agente de servicio de Cloud Firestore de su proyecto. El nombre del agente de servicio aparece debajo del Agente de servicio para dar acceso a la etiqueta.
  4. Para cualquier cubo de la lista que usará 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 principales , ingrese el nombre de su agente de servicio de Cloud Firestore.
    4. En el campo Seleccionar una función , seleccione Agentes de servicio > Agente de servicio de Firestore .
    5. Haga clic en Guardar .
    6. Regrese a la pestaña con la página Importar/Exportar de Cloud Firestore.
    7. Repita estos pasos para otros cubos de la lista. Asegúrese de ver todas las páginas de la lista.
  5. Haga clic en Migrar a Firestore Service Agent . Si aún tiene depósitos con verificaciones 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 el estado de la migración

  1. Para verificar el estado de migración de su proyecto, vaya a la página Importar/Exportar en Google Cloud Platform Console:

    Ir a Importar/Exportar

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

    Si el principal es service- project_number @gcp-sa-firestore.iam.gserviceaccount.com , entonces su proyecto ya migró 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 Verificar 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:

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

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

La aplicación de esta restricción de política organizacional no otorga automáticamente los permisos de depósito de Cloud Storage apropiados 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 , puede habilitar la restricción nuevamente.