Importa y exporta datos

Puedes usar el servicio administrado de importación y exportación de Firestore a fin de recuperar datos borrados de manera accidental y exportar datos para el 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 Firestore se pueden importar a otra base de datos de Firestore. También puedes cargar exportaciones de Firestore en BigQuery.

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

Antes de comenzar

Antes de usar el servicio administrado de importación y exportación, debes completar las siguientes tareas:

  1. Habilita la facturación para tu proyecto de Google Cloud. Solo los proyectos de Google Cloud que tengan la facturación habilitada pueden usar la función de importación y exportación.
  2. Crea un depósito de Cloud Storage para el proyecto en una ubicación cercana a la base de datos de Firestore. No puedes usar un bucket de pagos del solicitante para las operaciones de importación y exportación.
  3. Asegúrate de que la cuenta tenga los permisos necesarios para Firestore y Cloud Storage. Si eres el propietario del proyecto, tu cuenta ya tiene los permisos necesarios. De lo contrario, las siguientes funciones otorgan los permisos necesarios para realizar las operaciones de importación y exportación, y acceder a Cloud Storage:

Permisos de la cuenta de servicio predeterminada

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

La cuenta de servicio predeterminada de tu proyecto requiere acceso al bucket de Cloud Storage que se usa en una operación de importación o exportación. Si tu depósito de Cloud Storage está en el mismo proyecto que tu base de datos de Firestore, la cuenta de servicio predeterminada tiene acceso al depósito de forma predeterminada.

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

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

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

Configura gcloud para tu proyecto

Puedes iniciar operaciones de importación y exportación mediante Google Cloud Console 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:

Exportar datos

En una operación de exportación se copian documentos de tu base de datos a un conjunto de archivos en un bucket 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

Google Cloud Console

  1. Ve a la página de importaciones/exportaciones de Firestore en Google Cloud Console.

    Ir a la página de importaciones/exportaciones

  2. Haz clic en Exportar (Export).

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

  4. Debajo de Elegir destino, ingresa el nombre de un bucket de Cloud Storage o usa el botón Explorar para seleccionar un bucket.

  5. Haz clic en Exportar (Export).

La consola regresa a la página de importaciones/exportaciones. Si la operación se inicia correctamente, la página agrega una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Use el comando firestore export para exportar todos los documentos de tu base de datos (reemplaza [BUCKET_NAME] con el nombre de tu depósito de Cloud Storage). Agrega la marca --async para evitar que la herramienta de gcloud espere a que se complete la operación.

gcloud firestore export gs://[BUCKET_NAME]

Puedes organizar las exportaciones si agregas un prefijo de archivo después del nombre del depósito, por ejemplo, BUCKET_NAME/my-exports-folder/export-name. Si no lo agregas, el servicio administrado de exportación crea uno en función de la marca de tiempo actual.

Una vez que inicies la operación de exportación, esta no se cancela si cierras la terminal. Consulta cómo cancelar una operación.

Exporta colecciones específicas

Google Cloud Console

  1. Ve a la página de importaciones/exportaciones de Firestore en Google Cloud Console.

    Ir a la página de importaciones/exportaciones

  2. Haz clic en Exportar (Export).

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

  4. Debajo de Elegir destino, ingresa el nombre de un bucket de Cloud Storage o usa el botón Explorar para seleccionar un bucket.

  5. Haz clic en Exportar (Export).

La consola regresa a la página de importaciones/exportaciones. Si la operación se inicia correctamente, la página agrega una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Para exportar grupos de colecciones específicos, usa la marca --collection-ids. Con esta operación, se exportan solo los grupos de colecciones que tienen los ID de colección especificados. El grupo de colecciones incluye todas las colecciones y subcolecciones (ubicadas en cualquier ruta) que tienen ese ID de colección.

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

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.

Cómo importar todos los documentos desde una exportación

Google Cloud Console

  1. Ve a la página de importaciones/exportaciones de Firestore en Google Cloud Console.

    Ir a la página de importaciones/exportaciones

  2. Haga clic en Import.

  3. En el campo Nombre de archivo (Filename), ingresa el nombre de archivo de un archivo .overall_export_metadata de una operación de exportación completada. Puedes usar el botón Explorar para seleccionar el archivo.

  4. Haga clic en Import.

La consola regresa a la página de importaciones/exportaciones. Si la operación se inicia correctamente, la página agrega una entrada a la página de importaciones y exportaciones recientes. Si se produce un error, la página muestra un mensaje de error.

gcloud

Usa el comando 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 los archivos de exportación. Por ejemplo:

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

Puedes confirmar la ubicación de los archivos de exportación en el navegador de Cloud Storage en Google Cloud Console:

Abre el navegador de Cloud Storage

Una vez que inicies la operación de importación, esta no se cancelará si cierras la terminal. Consulta cómo cancelar una operación.

Importa colecciones específicas

Google Cloud Console

No puedes seleccionar colecciones específicas en la consola. Utiliza gcloud en lugar de esta función.

gcloud

Para importar grupos de colecciones específicos de un conjunto de archivos de exportación, usa la marca --collection-ids. Con esta operación, se importan solo los grupos de colecciones que tienen los ID de colección especificados. El grupo de colecciones incluye todas las colecciones y subcolecciones (ubicadas en cualquier ruta) que tienen ese ID de colección.

Solo una exportación de grupos de colecciones específicos admite una importación de este tipo. No puedes importar colecciones específicas a partir de una exportación de todos los documentos.

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

Administra las operaciones de importación y exportación

Después de iniciar una operación de importación o exportación, 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

Google Cloud Console

Puedes ver una lista de las operaciones de importación y exportación recientes en la página de importaciones/exportaciones de Firestore de Google Cloud Console.

Ir a la página de importaciones/exportaciones

gcloud

Para ver todas las operaciones de importación y exportación activas o que se completaron recientemente, usa el comando operations list:

gcloud firestore operations list

Verifica el estado de la operación

Google Cloud Console

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

Ir a la página de importaciones/exportaciones

gcloud

Usa el comando operations describe para que aparezca el estado de una operación de importación o exportació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.

  • 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

Google Cloud Console

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

Ir a la página de importaciones/exportaciones

En la tabla Importaciones y exportaciones recientes, las operaciones que se ejecutan actualmente incluyen un botón Cancelar en la columna Completadas. 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 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. Con este comando, no se borrarán los archivos de exportación 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 Firestore.

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 activarán las alertas de presupuesto en Google Cloud hasta que se completen. Asimismo, las lecturas y escrituras que se realicen durante una operación de importación o exportación se aplican a la cuota diaria cuando esta se completa. 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 Cloud Billing, puedes usar esta etiqueta para ver los costos relacionados con las operaciones de importación y exportación:

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

Registros de auditoría

Firestore escribe registros de auditoría de actividad del administrador para los registros de auditoría de Cloud. Estos registros incluyen operaciones de importación, indexación y exportación. Para ver los registros de auditoría de actividad del administrador de la base de datos de Firestore, consulta Visualiza registros de auditoría.

Los registros de auditoría de actividad del administrador de Firestore aparecen en los tipos de recursos Cloud Datastore Database y Cloud Datastore Index. Aunque los tipos de recursos usan el nombre Cloud Datastore, las entradas de registro individuales contienen un identificador de Firestore. Firestore registra las siguientes operaciones:

Categoría de registros de auditoría Operaciones de Firestore
Actividad del administrador FirestoreAdmin.CreateIndex
FirestoreAdmin.DeleteIndex
FirestoreAdmin.ExportDocuments
FirestoreAdmin.GetField
FirestoreAdmin.GetIndex
FirestoreAdmin.ImportDocuments
FirestoreAdmin.ListFields
FirestoreAdmin.ListIndexes
FirestoreAdmin.UpdateField

Exporta a BigQuery

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

Límite de columnas de BigQuery

BigQuery impone un límite de 10,000 columnas por tabla. Las operaciones de exportación de 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 Firestore intenta mantenerse por debajo del límite de columnas. Para ello, trata los campos de asignación 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 de asignación. 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 y no se pueden cargar tus datos en BigQuery.