Trabaja con la recuperación de un momento determinado (PITR)

En esta página, se describe cómo usar la recuperación de un momento determinado (PITR) para retener y recuperar datos en Firestore en modo Datastore.

Para comprender los conceptos de la PITR, consulta Recuperación de un momento determinado.

Permisos

A fin de obtener los permisos que necesitas para administrar la configuración de la PITR, pídele a tu administrador que te otorgue el rol de IAM Propietario de Cloud Datastore (roles/datastore.owner) en el proyecto cuya configuración de PITR deseas habilitar. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Este rol predefinido contiene los permisos necesarios para administrar la configuración de la PITR. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para administrar la configuración de la PITR:

Para habilitar la PITR cuando creas una base de datos, usa este comando: datastore.databases.create .
Para actualizar la configuración de la PITR en la base de datos existente, sigue estos pasos: datastore.databases.update,datastore.databases.list
Para realizar operaciones de lectura desde los datos de la PITR, usa este comando: datastore.databases.get,datastore.entities.get,datastore.entities.list,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
Para exportar los datos de la PITR, sigue estos pasos: datastore.databases.export
Para importar datos de la PITR, haz lo siguiente: datastore.databases.import

Es posible que también puedas obtener estos permisos con funciones personalizadas o con otras funciones predefinidas.

Antes de comenzar

Ten en cuenta los siguientes puntos antes de comenzar a usar la PITR:

No puedes comenzar a leer desde siete días en el pasado inmediatamente después de habilitar la PITR.
Si quieres habilitar la PITR cuando creas una base de datos, debes usar el comando gcloud firestore databases create. No se admite la habilitación de la PITR mientras se crea una base de datos con la consola de Google Cloud.
El modo Datastore comienza a retener versiones a partir de un momento después de habilitar la PITR.
No puedes leer los datos de la PITR en la ventana de la PITR después de inhabilitarla.
Si vuelves a habilitar la PITR inmediatamente después de inhabilitarla, los datos de la PITR anteriores ya no estarán disponibles. Cualquier dato de la PITR creado antes de inhabilitar la PITR se borrará después de la fecha de vencimiento de la PITR.
Si borraste datos de forma accidental en la última hora y la PITR está inhabilitada, puedes habilitar la PITR dentro de la hora posterior a la eliminación para restablecer los datos.
Cualquier lectura realizada en datos de PITR vencidos falla.

Habilita la PITR

Antes de usar la PITR, 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 PITR.

Sigue estos pasos para habilitar la PITR en tu base de datos:

Console

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

Ir a Bases de datos
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haga clic en Recuperación ante desastres.
Haz clic en Editar para editar la configuración.
Selecciona la casilla de verificación Habilitar la recuperación de un momento determinado y, luego, haz clic en Guardar.

Habilitar la PITR genera costos de almacenamiento. Consulta Precios para obtener más información.

Para inhabilitar la PITR, desmarca la casilla de verificación Habilitar la recuperación de un momento determinado de la página Recuperación ante desastres en la consola de Google Cloud.

gcloud

Habilita la PITR durante la creación de la base de datos con el comando gcloud firestore databases create de la siguiente manera:

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

Reemplaza los valores de la siguiente manera:

LOCATION: La ubicación en la que quieres crear tu base de datos.
DATABASE_ID: Se establece en el ID de la base de datos o en “(predeterminado)”.
TYPE: Se establece en modo almacén de datos.

Puedes inhabilitar la PITR con el comando gcloud firestore databases update de la siguiente manera:

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

Reemplaza los valores de la siguiente manera:

DATABASE_ID: Se establece en el ID de la base de datos o en “(predeterminado)”.

Obtén el período de retención y la fecha de la versión más antigua

Console

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

Ir a Bases de datos
Selecciona la base de datos requerida de la lista.
En el menú de navegación, haga clic en Recuperación ante desastres.
En la sección Configuración, observa el Período de retención y la Fecha de la versión más antigua.
- Período de retención: Es el período en el que el modo Datastore retiene todas las versiones de los datos de la base de datos. El valor es una hora cuando la PITR está inhabilitada y siete días cuando está habilitada.
- Hora de la versión más antigua: La marca de tiempo más temprana en la que se pueden leer las versiones anteriores de los datos en la ventana de PITR. El modo Datastore actualiza este valor de forma continua y se vuelve obsoleto en el momento en que se consulta. Si usas este valor para recuperar datos, asegúrate de tener en cuenta el tiempo desde el momento en que se consulta el valor hasta el momento en que inicias la recuperación.
- Recuperación de un momento determinado: Muestra Enabled si la PITR está habilitada. Si la PITR está inhabilitada, verás Disabled.

gcloud

Ejecuta el comando gcloud firestore databases describe de la siguiente manera:

gcloud firestore databases describe --database=DATABASE_ID

Reemplaza DATABASE_ID por el ID de la base de datos o default.

Esta es la salida:

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: DATASTORE_MODE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

En este ejemplo:

earliestVersionTime: Es la marca de tiempo de los primeros datos de PITR almacenados.
pointInTimeRecoveryEnablement: Muestra POINT_IN_TIME_RECOVERY_ENABLED si la PITR está habilitada. Si la PITR está inhabilitada, verás POINT_IN_TIME_RECOVERY_DISABLED o es posible que no se muestre el campo pointInTimeRecoveryEnablement.
versionRetentionPeriod: Período en el que los datos de PITR se retienen en milisegundos. El valor puede ser una hora cuando la PITR está inhabilitada o siete días si la PITR está habilitada.

Lee datos de la PITR

Puedes leer datos de la PITR con las bibliotecas cliente, los métodos de la API de REST o el conector de Apache Beam de FirestoreIO.

Bibliotecas cliente

Java

Debes usar el método readTime en la clase ReadOption para leer los datos de la PITR. No puedes usar la transacción ReadOnly para realizar lecturas. Consulta el código de muestra de ReadOption para obtener más información.

  Datastore datastore = ...
  Timestamp timestamp = ...

  // lookup
  Key key = ...
  Entity entity = datastore.get(key, ReadOption.readTime(timestamp));

  // runQuery
  Query<Entity> query = ...
  QueryResults<Entity> queryResult = datastore.run(query, ReadOption.readTime(timestamp));

  // runAggregationQuery
  AggregationQuery countAggregationQuery = ...
  Long count = getOnlyElement(datastore.runAggregation(countAggregationQuery, ReadOption.readTime(timestamp))).get("total_count");

Para obtener una lista completa de ejemplos de readTime, consulta el repositorio de GitHub.

Python

Usa la lectura de PITR en el SDK de Python en modo Datastore con el método readTime o usa la transacción ReadOnly con readTime para realizar lecturas.

  from datetime import datetime, timezone

  read_time = datetime.now(tz=timezone.utc)

  key = …
  # read without PITR read time
  entity = client.get(key)

  # read with PITR read time
  entity = client.get(key, read_time=read_time)

  # PITR read using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      entity = client.get(key)

  query = client.query…
  # run query without PITR read time
  iterator = query.fetch()

  # run query with PITR read time
  iterator = query.fetch(read_time=read_time)

  # PITR read query using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      iterator = query.fetch()

Para obtener una lista completa de ejemplos de readTime, consulta el repositorio de GitHub.

API de REST

Las lecturas de PITR son compatibles con los métodos de lectura de modo Datastore V1, que son lookup, runQuery y runAggregationQuery.

Para realizar una lectura con los métodos de REST, prueba una de las siguientes opciones:

En tu solicitud de método de lectura, pasa el valor readTime como una marca de tiempo de PITR compatible en el método readOptions. Una marca de tiempo de PITR puede ser una marca de tiempo de precisión de microsegundos en la última hora o una marca de tiempo de un minuto entero más allá de la última hora, pero no antes que la earliestVersionTime.
Usa el parámetro readTime junto con el método BeginTransaction como parte de una transacción ReadOnly para varias lecturas de PITR.

Apache Beam

Usa el conector de E/S de Apache Beam en modo Datastore para leer o escribir entidades en una base de datos en modo Datastore a gran escala con Dataflow.

Especifica el método withReadTime(Instant readTime) en el objeto DatastoreV1.Read. Todas las lecturas posteriores que usan el objeto DatastoreV1.Read leen desde el mismo readTime.

Java

En el siguiente código, se muestra cómo usar el método withReadTime para las lecturas de PITR.

  com.google.datastore.v1.Query query = ...
    Instant readTime = Instant.ofEpochSecond(1684098540L);

    DatastoreV1.Read read =
            DatastoreIO.v1()
                .read()
                .withProjectId(project)
                .withQuery(query)
                .withNamespace(namespace)
                .withReadTime(readTime);

    PCollection<Entity> entities = pipeline.apply(read);
    ...

Para obtener una lista completa de ejemplos de withReadTime, consulta el repositorio de GitHub.

Importa y exporta datos de PITR

Puedes exportar tu base de datos a Cloud Storage desde datos de PITR coherentes 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 PITR admite todos los filtros, incluida la exportación de todas las entidades y la exportación de tipos o espacios de nombres específicos.

Exporta la base de datos y especifica el parámetro snapshot-time en la marca de tiempo de recuperación requerida.
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,
- BUCKET_NAME_PATH: Un bucket de Cloud Storage válido con un prefijo de ruta de acceso opcional en el que se almacenan los archivos de exportación.
- 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 o 2023-10-19T10:30:00.00-07:00.
- COLLECTION_IDS: Es una lista de los IDs de colección o de grupos de colecciones, por ejemplo, 'specific collection group1','specific collection group2'.
- NAMESPACE_IDS: Es una lista de IDs de espacio de nombres, por ejemplo, 'customer', 'orders'.
También se admite la exportación de un subconjunto específico de categorías o espacios de nombres con un filtro de entidad.

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, 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
- Asegúrate de que la marca de tiempo que especifiques sea una marca de tiempo de un minuto completo dentro de los últimos siete días, pero no antes que el earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, recibirás un error. La marca de tiempo debe ser un minuto entero, incluso si la hora especificada corresponde a la última hora.
- No se te cobrará por una exportación de PITR fallida.
Importa a una base de datos

Sigue los pasos que se indican en Importa todas las entidades para importar tu base de datos exportada. Si ya existe una entidad en tu base de datos, se reemplazará. También se admite la importación de un subconjunto específico de tipos o espacios de nombres con un filtro de entidad.