Utiliser la récupération à un moment précis (PITR)

Cette page explique comment utiliser la récupération à un moment précis (PITR) pour conserver et récupérer les données dans Cloud Firestore.

Pour comprendre les concepts de la récupération à un moment précis, consultez la section Récupération à un moment précis.

Autorisations

Pour obtenir les autorisations nécessaires pour gérer les paramètres de PITR, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet pour lequel vous souhaitez activer PITR :

• Propriétaire Cloud Datastore (roles/datastore.owner)

Pour les rôles personnalisés, assurez-vous que les autorisations suivantes sont accordées:

• Pour activer la récupération à un moment précis lors de la création d'une base de données: datastore.databases.create
• Pour mettre à jour les paramètres PITR sur une base de données existante : datastore.databases.update,datastore.databases.list
• Pour effectuer des lectures à partir de données PITR: datastore.databases.get, datastore.entities.get et datastore.entities.list
• Pour exporter des données PITR: datastore.databases.export
• Pour importer des données PITR: datastore.databases.import

Avant de commencer

Veuillez noter les points suivants avant de commencer à utiliser la récupération à un moment précis:

• Vous ne pouvez pas commencer la lecture depuis les sept derniers jours immédiatement après avoir activer la récupération à un moment précis.
• Si vous souhaitez activer la récupération à un moment précis lors de la création d'une base de données, vous devez utiliser gcloud firestore databases create. L'activation de PITR lors de la création d'une base de données à l'aide de la console Google Cloud n'est pas possible.
• Cloud Firestore commence à conserver les versions à partir de ce point après en activant la récupération à un moment précis.
• Vous ne pouvez pas lire les données PITR dans la fenêtre PITR après avoir désactivé la PITR.
• Si vous réactivez la récupération à un moment précis immédiatement après l'avoir désactivée, les données n'est plus disponible. Toutes les données PITR créées avant la désactivation de la récupération PITR seront supprimées après la date d'expiration de la récupération PITR.
• Si vous avez supprimé accidentellement des données au cours de la dernière heure et que la récupération à un moment précis est désactivée, vous pouvez restaurer vos données en activant la récupération à un moment précis dans l'heure qui suit la suppression.
• Toute lecture de données PITR arrivées à expiration échoue.

Activer la récupération PITR

Avant d'utiliser la récupération à un moment précis, activez la facturation pour votre projet. Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser la fonctionnalité PITR.

Pour activer la récupération à un moment précis pour votre base de données:

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

Obtenir la durée de conservation et la date et l'heure de la première version

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

Lire les données PITR

Vous pouvez lire les données PITR à l'aide des bibliothèques clientes, des méthodes de l'API REST ou du connecteur Apache Beam 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())
  ...

Exporter et importer des données PITR

Vous pouvez exporter votre base de données vers Cloud Storage à partir de données PITR à l'aide de la commande gcloud firestore export. Vous pouvez exporter des données PITR dont le code temporel est un horodatage d'une minute entière dans au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données ne sont plus existe à l'horodatage spécifié, l'opération d'exportation échoue.

L'opération d'exportation PITR est compatible avec tous les filtres, y compris l'exportation de tous les documents et l'exportation de collections spécifiques.

1. Exportez la base de données en spécifiant le paramètre snapshot-time vers l'horodatage de récupération souhaité.

   gcloud

   Exécutez la commande suivante pour exporter la base de données vers votre bucket.

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Où :

   • BUCKET_NAME_PATH : bucket Cloud Storage valide avec un préfixe de chemin facultatif où les fichiers d'exportation sont stockés.
   • PITR_TIMESTAMP : code temporel PITR au niveau de la minute, par exemple 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS : liste d'ID de collections ou d'ID de groupe de collections (par exemple, 'specific collection group1','specific collection group2').
   • NAMESPACE_IDS : liste d'ID d'espaces de noms, par exemple 'customer','orders'.

   Notez les points suivants avant d'exporter des données PITR :

   • Spécifiez le code temporel dans le document RFC 3339 de sortie. Par exemple, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • Assurez-vous que le code temporel que vous spécifiez est un code temporel d'une minute entière au cours des sept derniers jours, mais pas avant earliestVersionTime Si les données n'existent plus à l'emplacement du code temporel, une erreur est générée. Le code temporel doit correspondre à une minute entière, même si l'heure spécifiée est comprise dans la dernière heure.
   • L'échec de l'exportation PITR ne vous est pas facturé.

2. Importez des données dans une base de données.

   Suivez la procédure Importer tous les documents pour importer votre exportée. Si un document existe déjà dans votre base de données, il sera être écrasées.