Exportar e importar entidades

En esta página se describe cómo exportar e importar entidades de Firestore en modo Datastore mediante el servicio de exportación e importación gestionado. El servicio de exportación e importación gestionado está disponible a través de la consola de Google Cloud , la CLI de Google Cloud y la API Admin de Datastore (REST y RPC).

Con el servicio gestionado de exportación e importación, puedes recuperar datos que hayas eliminado accidentalmente y exportar datos para procesarlos sin conexión. Puedes exportar todas las entidades o solo tipos específicos de entidades. Del mismo modo, puedes importar todos los datos de una exportación o solo tipos específicos. Cuando utilices el servicio de importación y exportación gestionado, ten en cuenta lo siguiente:

• El servicio de exportación usa lecturas eventualmente coherentes. No puedes dar por hecho que una exportación se produce en un momento concreto. La exportación puede incluir entidades escritas después de que se inicie y excluir entidades escritas antes de que se inicie.

• Una exportación no contiene ningún índice. Cuando importa datos, los índices necesarios se vuelven a crear automáticamente con las definiciones de índice actuales de su base de datos. Los ajustes de índice de valor de propiedad por entidad se exportan y se respetan durante la importación.

• Las importaciones no asignan IDs nuevos a las entidades. En las importaciones se usan los IDs que existían en el momento de la exportación y se sobrescribe cualquier entidad que tenga el mismo ID. Durante una importación, los IDs se reservan mientras se importan las entidades. Esta función evita que se produzcan colisiones de IDs con entidades nuevas si se habilitan las escrituras mientras se está ejecutando una importación.

• Si una entidad de tu base de datos no se ve afectada por una importación, permanecerá en ella después de la importación.

• Los datos exportados de una base de datos en modo Datastore se pueden importar a otra base de datos en modo Datastore, incluso a una de otro proyecto.

• El servicio de exportación e importación gestionado limita el número de exportaciones e importaciones simultáneas a 50 y permite un máximo de 20 solicitudes de exportación e importación por minuto en un proyecto. En cada solicitud, el servicio limita el número de combinaciones de filtros de entidades a 100.

• La salida de una exportación gestionada usa el formato de registro LevelDB.

• Para importar solo un subconjunto de entidades o importar datos a BigQuery, debe especificar un filtro de entidades en la exportación.

• El nombre de 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 mueves o copias los archivos de salida de una exportación, mantén el archivo PARENT_FOLDER_NAME, el contenido de las subcarpetas y el nombre de archivo .overall_export_metadata.

Antes de empezar

Para poder usar el servicio de exportación e importación gestionado, debes completar las siguientes tareas.

1. Habilita la facturación de tu Google Cloud proyecto. Solo los Google Cloud proyectos con la facturación habilitada pueden usar las funciones de exportación e importación.

2. Crea un segmento de Cloud Storage en la misma ubicación que tu base de datos de Firestore en el modo de Datastore. No puedes usar un contenedor de pago por el solicitante para las operaciones de exportación e importación.

3. Asigna un rol de gestión de identidades y accesos a tu cuenta de usuario que conceda el permiso datastore.databases.export si vas a exportar datos o el permiso datastore.databases.import si vas a importar datos. El Datastore Import Export Admin rol, por ejemplo, concede ambos permisos.

4. Si el segmento de Cloud Storage está en otro proyecto, concede acceso al segmento al agente de servicio de Firestore.

Configurar gcloud en tu proyecto

Si tienes previsto usar gcloud para iniciar tus operaciones de importación y exportación, configura gcloud y conéctalo a tu proyecto de una de las siguientes formas:

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

  Iniciar Cloud Shell

  Configura la CLI de gcloud para que use tu proyecto actual:

  gcloud config set project project-id
  

• Instala e inicializa Google Cloud CLI.

Permisos

Para ejecutar operaciones de exportación e importación, tu cuenta de usuario y el agente de servicio del modo Datastore de tu proyecto requieren los siguientes permisos de gestión de identidades y accesos.

Permisos de cuenta de usuario

La cuenta de usuario o de servicio que inicia la operación requiere los permisos de IAM datastore.databases.export y datastore.databases.import. Si eres el propietario del proyecto, tu cuenta tiene los permisos necesarios. De lo contrario, los siguientes roles de gestión de identidades y accesos conceden los permisos necesarios:

• Propietario de Datastore
• Administrador de importaciones y exportaciones de Datastore

También puedes asignar estos permisos con un rol personalizado.

El propietario de un proyecto puede conceder uno de estos roles siguiendo los pasos que se indican en Conceder acceso.

Permisos de agente de servicio

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

Agente de servicio de Firestore

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

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

El agente de servicio de Firestore necesita acceder al segmento de Cloud Storage que se usa en una operación de exportación o importación. Si tu segmento de Cloud Storage está en el mismo proyecto que tu base de datos de Firestore, el agente de servicio de Firestore podrá acceder al segmento de forma predeterminada.

Si el segmento de Cloud Storage está en otro proyecto, debes dar acceso al agente de servicio de Firestore al segmento de Cloud Storage.

Asignar roles al agente de servicio

Puede usar la herramienta de línea de comandos gsutil para asignar uno de los roles que se indican a continuación. Por ejemplo, para asignar el rol Administrador de almacenamiento al agente de servicio de Firestore, ejecuta lo siguiente:

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

Sustituye PROJECT_NUMBER por el número de tu proyecto, que se usa para asignar un nombre al agente de servicio de Firestore. Para ver el nombre del agente de servicio, consulta Ver el nombre del agente de servicio.

También puedes asignar este rol mediante la Google Cloud consola.

Ver el nombre del agente de servicio

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

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

   Ir a Bases de datos

2. Seleccione la base de datos que necesite de la lista de bases de datos.

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

4. Consulta la cuenta de autorización junto a la etiqueta Las tareas de importación o exportación se ejecutan como.

Operaciones de exportación

En el caso de las operaciones de exportación que impliquen un segmento de otro proyecto, modifique los permisos del segmento para asignar uno de los siguientes roles de gestión de identidades y accesos al agente de servicio del modo Datastore del proyecto que contenga su base de datos en modo Datastore:

• Administrador de Storage
• Propietario (rol básico)

También puedes crear un rol personalizado de gestión de identidades y accesos con permisos ligeramente diferentes a los que contienen los roles indicados anteriormente:

• storage.buckets.get
• storage.objects.create
• storage.objects.delete
• storage.objects.list

Operaciones de importación

En las operaciones de importación que impliquen un segmento de Cloud Storage de otro proyecto, modifica los permisos del segmento para asignar uno de los siguientes roles de Cloud Storage al agente de servicio del modo Datastore del proyecto que contenga tu base de datos en modo Datastore:

• Administrador de Storage
• Lector de objetos de Storage y Lector de segmentos heredados de Storage

También puedes crear un rol personalizado de gestión de identidades y accesos con los siguientes permisos:

• storage.buckets.get
• storage.objects.get

Iniciar operaciones de importación y exportación gestionadas

En esta sección se describe cómo iniciar una operación de exportación o importación gestionada.

Exportar todas las entidades

 gcloud firestore export gs://bucket-name --async --database=DATABASE

POST https://datastore.googleapis.com/v1/projects/project-id:export

{
  "outputUrlPrefix": "gs://bucket-name",
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id:export"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id:export" | Select-Object -Expand Content

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}

Exportar tipos o espacios de nombres específicos

Para exportar un subconjunto específico de tipos o espacios de nombres, proporcione un filtro de entidades con valores para los tipos y los IDs de espacio de nombres. Cada solicitud está limitada a 100 combinaciones de filtros de entidades, donde cada combinación de tipo y espacio de nombres filtrados cuenta como un filtro independiente para alcanzar este límite.

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE