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

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

Permisos

Para obtener los permisos que necesita para administrar la configuración de la PITR, pídele al administrador que te otorgue los siguientes roles de IAM en el proyecto en el que quieres habilitar la PITR:

• Propietario de Cloud Datastore (roles/datastore.owner)

Para los roles personalizados, asegúrate de que se otorguen los siguientes permisos:

• Para habilitar la PITR cuando creas una base de datos: datastore.databases.create
• Para actualizar la configuración de la PITR en una base de datos existente: datastore.databases.update y datastore.databases.list
• Para realizar lecturas desde datos de la PITR: datastore.databases.get, datastore.entities.get, datastore.entities.list
• Para exportar los datos de la PITR, sigue estos pasos: datastore.databases.export
• Para importar datos de la PITR, sigue estos pasos: datastore.databases.import

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.
• Cloud Firestore 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 funcionalidad de la PITR.

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

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

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

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

gcloud firestore databases describe --database=DATABASE_ID

    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/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

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.

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

  const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

  const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
  )

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

Importa y exporta datos de PITR

Puedes exportar tu base de datos a Cloud Storage a partir de los datos de PITR 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 la PITR admite todos los filtros, incluida la exportación de todos los documentos y la exportación de colecciones específicas.

1. Exporta la base de datos y especifica el parámetro snapshot-time en la marca de tiempo de recuperación deseada.

   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: Es un bucket de Cloud Storage válido con un prefijo de ruta 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: Una lista de los IDs de colección o de grupos de colecciones, por ejemplo, 'specific-collection-group1','specific-collection-group2'.
   • NAMESPACE_IDS: Una lista de IDs de espacio de nombres, por ejemplo, 'customer','orders'.

   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 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. La marca de tiempo debe ser un minuto entero, incluso si la hora especificada corresponde a la última hora.
   • No se te cobra por una exportación de la PITR con errores.

2. Importa a una base de datos

   Sigue los pasos que se indican en Importa todos los documentos para importar la base de datos exportada. Si ya existe un documento en tu base de datos, se reemplazará.