Importa y exporta datos

Solo es relevante para la edición Enterprise de Cloud Firestore.

Puedes usar el servicio administrado de importación y exportación 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 que se exportan desde una base de datos de Cloud Firestore con compatibilidad con MongoDB se pueden importar en otra base de datos de Cloud Firestore con compatibilidad con MongoDB. También puedes cargar exportaciones de Cloud Firestore con compatibilidad con MongoDB en BigQuery.

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

Precaución: La exportación de datos desde Cloud Firestore compatible con MongoDB generará una operación de lectura por documento exportado. Sin embargo, estas lecturas no aparecerán en la sección de uso de la consola. Asegúrate de comprender esto antes de configurar las exportaciones recurrentes para evitar generar una factura inesperada.

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 de Cloud Firestore con compatibilidad con MongoDB. 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 compatible con MongoDB 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:

   • Funciones de Cloud Firestore con compatibilidad con MongoDB: Owner, Cloud Datastore Owner o Cloud Datastore Import Export Admin
     Nota: Estas funciones de Datastore también otorgan permisos en Cloud Firestore con compatibilidad con MongoDB.

   • 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

[e-mail]

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

Nota: Cloud Firestore usaba antes el servicio predeterminado App Engine en lugar del agente de servicio de Cloud Firestore. Si tu base de datos aún usa la cuenta de servicio App Engine para importar o exportar datos, te recomendamos que migres al agente de servicio de Cloud Firestore específico del servicio. Puedes ver qué cuenta usan tus operaciones de importación y exportación en la consola de Google Cloud.

Si usas los Controles del servicio de VPC, debes usar el agente de servicio de Cloud Firestore específico del servicio para proteger por completo las operaciones de importación y exportación. Los Controles del servicio de VPC no son compatibles con la cuenta de servicio de App Engine.

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:[e-mail]: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 con Cloud Shell.

  Inicia Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

• Instala e inicializa el SDK de Google Cloud:

Importar 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 IDs 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.

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

• Se produce un error en la importación a una base de datos de Cloud Firestore con compatibilidad con MongoDB desde una exportación con subcolecciones, ya que las subcolecciones no son compatibles con Cloud Firestore con compatibilidad con MongoDB.

• Una importación a una base de datos de la edición estándar de Cloud Firestore desde una exportación con tipos BSON falla porque los tipos BSON no son compatibles con la edición estándar de Cloud Firestore.

• Una importación a una base de datos de Cloud Firestore con compatibilidad con MongoDB no puede importar datos de espacios de nombres no predeterminados (API de Datastore).

  Solo se permite una importación a una base de datos de Cloud Firestore con compatibilidad con MongoDB desde archivos de datos que contienen espacios de nombres no predeterminados si la operación de exportación incluyó un filtro --namespace-ids con el espacio de nombres predeterminado. Solo se importan los datos del espacio de nombres predeterminado.

Importa todos los documentos desde una exportación

Consola de Google Cloud

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

   Ir a Bases de datos

2. Selecciona una base de datos de la lista.

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

4. Haz clic en Importar.

5. En el campo Nombre de archivo, 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.

6. Haz clic en Importar.

La consola regresa a la página 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]/ --database=[DATABASE]

Reemplaza lo siguiente:

• BUCKET_NAME/EXPORT_PREFIX: Es la ubicación de tus archivos de exportación.

• DATABASE: Es el nombre de la base de datos.

Por ejemplo:

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

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

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

Nota: Para importar colecciones específicas, debes usar el resultado de una operación de exportación en la que hayas exportado colecciones específicas.

Consola de Google Cloud

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

gcloud

Para importar colecciones específicas a partir de un conjunto de archivos de exportación, usa la marca --collection-ids. Con esta operación, se importan solo las colecciones que tienen los IDs de colección especificados. Especifica el nombre de la base de datos con la marca --database.

Solo una exportación de colecciones específicas 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] \
  --database=[DATABASE]

Importa desde una exportación con datos de PITR

Sigue los mismos pasos que en Importa todos los documentos o Importa colecciones específicas para importar datos de la PITR. Si ya existe un documento en tu base de datos, se reemplazará.

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.

Nota: Debes exportar colecciones específicas si deseas hacer lo siguiente:

• Importar solo colecciones específicas
• Carga datos de Cloud Firestore con compatibilidad con MongoDB en BigQuery

Exporta todos los documentos

Consola de Google Cloud

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. Haz clic en Exportar.

5. Haz clic en la opción Exportar la base de datos completa.

6. Selecciona Exportar el estado actual de la base de datos para exportar los datos actuales.

7. En la sección Destino, ingresa el nombre de un bucket de Cloud Storage o usa el botón Navegar para seleccionar un bucket.

8. Haz clic en Exportar.

La consola regresa a la página 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 export para exportar todos los documentos de tu base de datos (reemplaza [BUCKET_NAME] con el nombre de tu bucket 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] \
  --database=[DATABASE]

Reemplaza lo siguiente:

• BUCKET_NAME: Organiza tus exportaciones. Para ello, agrega un prefijo de archivo después del nombre del bucket, 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.

• DATABASE: Es el nombre de la base de datos desde la que deseas exportar los documentos.

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

Consola de Google Cloud

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. Haz clic en Exportar.

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

6. Selecciona Exportar el estado actual de la base de datos para exportar los datos actuales.

7. En la sección Destino, ingresa el nombre de un bucket de Cloud Storage o usa el botón Navegar para seleccionar un bucket.

8. Haz clic en Exportar.

La consola regresa a la página 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 colecciones específicas, usa la marca --collection-ids. Con esta operación, se exportan solo las colecciones que tienen los IDs de colección especificados.

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

Por ejemplo, puedes diseñar una colección de restaurants en la base de datos de foo para incluir colecciones adicionales, como ratings, reviews o outlets. Para exportar una colección de restaurants y reviews específica, tu comando se verá de la siguiente manera:

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 a partir de datos de PITR. 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 de colecciones específicas.

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

Console

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

   Ir a Bases de datos
2. Selecciona una base de datos de la lista.
3. En el menú de navegación, haz clic en Importar/Exportar.
4. Haz clic en Exportar.
5. Configura la fuente de exportación para exportar toda la base de datos o solo colecciones específicas.

6. En la sección Elige el estado de la base de datos que deseas exportar, selecciona Exportar desde un punto anterior en el tiempo.

   Selecciona una fecha y hora de la instantánea para usar en la exportación

7. En la sección Destino, ingresa el nombre de un bucket de Cloud Storage o usa el botón Navegar para seleccionar un bucket.

8. Haz clic en Exportar.

   La consola regresa a la página 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

Puedes exportar tu base de datos a Cloud Storage a partir de los datos de PITR con el comando gcloud firestore export.

Exporta la base de datos y especifica el parámetro snapshot-time en una marca de tiempo de recuperación. Ejecuta el siguiente comando para exportar la base de datos a tu bucket.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Aquí, 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.

Agrega la marca --collection-ids para exportar colecciones específicas.

Administra las operaciones de importación y exportación

Después de iniciar una operación de importación o exportación, Cloud Firestore con compatibilidad con MongoDB 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/[DATABASE_ID]/operations/. Por ejemplo:

projects/my-project/databases/my-database/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

Consola de Google Cloud

Puedes ver una lista de las operaciones de importación y exportación recientes en la página Importaciones/Exportaciones de la consola de Google Cloud.

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.

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

Consola de Google Cloud

Puedes ver el estado de una operación de importación o exportación reciente en la página Importaciones/Exportaciones de la consola de Google Cloud.

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.

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. Es posible que Cloud Firestore con compatibilidad con MongoDB omita 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

Consola de Google Cloud

Puedes cancelar una operación de importación o exportación en ejecución en la página Importaciones/Exportaciones de la consola de Google Cloud.

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.

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 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 por unidades de lectura y escritura según las tarifas que se indican en los precios de Cloud Firestore con compatibilidad con MongoDB.

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

Las operaciones de importación y exportación no activarán las alertas de presupuesto de Google Cloud hasta que se completen. 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:

Nota: En las operaciones de importación y exportación que se ejecutaron antes del 8 de septiembre de 2020, no se aplicó la etiqueta goog-firestoremanaged.

Exporta a BigQuery

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

Cuando se cargan datos de Cloud Firestore con compatibilidad con MongoDB en BigQuery, los tipos de datos BSON se representan con el tipo de datos STRING.

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 con compatibilidad con MongoDB generan un esquema de tabla de BigQuery para cada colección. En este esquema, cada nombre de campo único dentro de una colección se convierte en una columna del esquema.

Si el esquema de BigQuery de una colección supera las 10,000 columnas, la operación de exportación de Cloud Firestore con compatibilidad con MongoDB 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 la colección y no puedes cargar sus 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 colección 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 las colecciones que contienen los archivos de exportación:

protoc --decode_raw < export0.export_metadata