Travailler avec la récupération ponctuelle (PITR)

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

Pour comprendre les concepts PITR, consultez Récupération à un moment précis .

Autorisations

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

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

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

  • Pour activer PITR 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 des données PITR : datastore.databases.get , datastore.entities.get , datastore.entities.list
  • Pour exporter des données PITR : datastore.databases.export
  • Pour importer des données PITR : datastore.databases.import

Avant que tu commences

Notez les points suivants avant de commencer à utiliser PITR :

  • Vous ne pouvez pas commencer à lire sept jours auparavant immédiatement après avoir activé PITR.
  • Si vous souhaitez activer PITR lorsque vous créez une base de données, vous devez utiliser la commande gcloud firestore databases create . L'activation de PITR lors de la création d'une base de données à l'aide de la console GCP n'est pas prise en charge.
  • Cloud Firestore commence à conserver les versions à partir du point suivant après avoir activé PITR.
  • Vous ne pouvez pas lire les données PITR dans la fenêtre PITR après avoir désactivé PITR.
  • Si vous réactivez PITR immédiatement après l'avoir désactivé, les données PITR passées ne sont plus disponibles. Toutes les données PITR créées avant la désactivation du PITR seront supprimées après la date d'expiration du PITR.
  • Si vous avez accidentellement supprimé des données au cours de la dernière heure et que PITR est désactivé, vous pouvez restaurer vos données en activant PITR dans l'heure suivant la suppression.
  • Toute lecture effectuée sur des données PITR expirées échoue.

Activer PITR

Avant d'utiliser PITR, activez la facturation pour votre projet Google Cloud . Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser la fonctionnalité PITR.

Pour activer PITR pour votre base de données :

Console

  1. Dans la console Google Cloud Platform, accédez à la page Bases de données .

    Aller aux bases de données

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Récupération après sinistre .

  4. Cliquez sur Modifier pour modifier les paramètres.

  5. Cochez la case Activer la récupération à un moment précis , puis cliquez sur Enregistrer .

L’activation de PITR entraînerait des coûts de stockage. Voir Tarifs pour plus d’informations.

Pour désactiver PITR, décochez la case Activer la récupération à un moment donné sur la page Récupération après sinistre de la console GCP.

gcloud

Activez PITR lors de la création de la base de données avec la commande gcloud firestore databases create comme suit :

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

Remplacez les valeurs comme suit :

  • Location - emplacement où vous souhaitez créer votre base de données.
  • DATABASE_ID - défini sur l'ID de la base de données ou (par défaut).
  • TYPE - défini sur Firestore-native.

Vous pouvez désactiver PITR à l'aide de la commande gcloud firestore databases update comme suit :

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

Remplacez les valeurs comme suit :

  • DATABASE_ID - défini sur l'ID de la base de données ou (par défaut).

Obtenez la période de conservation et l'heure de la première version

Console

  1. Dans la console Google Cloud Platform, accédez à la page Bases de données .

    Aller aux bases de données

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Récupération après sinistre .

  4. Dans la section Paramètres , notez la Période de rétention et l'Heure de la première version .

    • Période de conservation : la période pendant laquelle Cloud Firestore conserve toutes les versions des données de la base de données. La valeur est d'une heure lorsque PITR est désactivé et de sept jours lorsque PITR est activé.
    • Heure de la première version : l'horodatage le plus ancien auquel les anciennes versions des données peuvent être lues dans la fenêtre PITR. Cette valeur est continuellement mise à jour par Cloud Firestore et devient obsolète dès qu'elle est interrogée. Si vous utilisez cette valeur pour récupérer des données, assurez-vous de prendre en compte le temps écoulé entre le moment où la valeur est interrogée et le moment où vous lancez la récupération.
    • Récupération à un moment précis : affiche Enabled si PITR est activé. Si PITR est désactivé, vous verrez Disabled .

gcloud

Exécutez la commande gcloud Firestore Databases DESCRIPTION comme suit :

gcloud firestore databases describe --database=DATABASE_ID

Remplacez DATABASE_ID par l'ID de la base de données ou default .

Voici le résultat :

    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

où,

  • earliestVersionTime - horodatage des premières données PITR stockées.
  • pointInTimeRecoveryEnablement : affiche POINT_IN_TIME_RECOVERY_ENABLED , si PITR est activé. Si PITR est désactivé, soit vous verrez POINT_IN_TIME_RECOVERY_DISABLED , soit le champ pointInTimeRecoveryEnablement pourrait ne pas être affiché.
  • versionRetentionPeriod - période de temps pendant laquelle les données PITR sont conservées en millisecondes. La valeur peut être d'une heure lorsque PITR est désactivé ou de sept jours si PITR est activé.

Lire les données PITR

Vous pouvez lire les données PITR à l'aide des bibliothèques clientes, des méthodes API REST ou du connecteur FirestoreIO Apache Beam.

Bibliothèques clientes

Java

Vous devez utiliser la transaction ReadOnly pour lire les données PITR. Vous ne pouvez pas spécifier directement readTime dans les lectures. Voir Transactions et écritures par lots pour plus d'informations.

  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();

Nœud

Vous devez utiliser une transaction ReadOnly pour lire les données PITR. Vous ne pouvez pas spécifier directement readTime dans les lectures. Voir Transactions et écritures par lots pour plus d'informations.

  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)}
  )

API REST

Les lectures PITR sont prises en charge dans toutes les méthodes de lecture Cloud Firestore, à savoir get , list , batchGet , listCollectionIds , listDocuments , runQuery , runAggregationQuery et partitionQuery .

Pour effectuer une lecture à l'aide des méthodes REST, essayez l'une des options suivantes :

  1. Dans la demande de votre méthode de lecture, transmettez la valeur readTime comme horodatage PITR pris en charge dans la méthode readOptions . Un horodatage PITR peut être soit un horodatage de précision à la microseconde au cours de l'heure écoulée, soit un horodatage d'une minute entière au-delà de l'heure écoulée, mais pas avant le earliestVersionTime .

  2. Utilisez le paramètre readTime avec la méthode BeginTransaction dans le cadre d'une transaction ReadOnly pour plusieurs lectures PITR.

Faisceau Apache

Utilisez le connecteur Cloud FirestoreIO Apache Beam pour lire ou écrire des documents dans une base de données Cloud Firestore à grande échelle avec Dataflow.

Les lectures PITR sont prises en charge dans la méthode de lecture suivante du connecteur Cloud FirestoreIO. Ces méthodes de lecture prennent en charge la méthode withReadTime(@Nullable Instant readTime) que vous pouvez utiliser pour les lectures PITR :

Java

Le code suivant peut être utilisé avec l' exemple de code de pipeline Dataflow pour les opérations de lecture ou d'écriture groupées. L’exemple utilise la méthode withReadTime(@Nullable Instant readTime) pour les lectures PITR.

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

Pour obtenir la liste complète des exemples readTime dans le pipeline Dataflow, consultez le dépôt Github .

Exporter et importer à partir de données PITR

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

L'opération d'exportation PITR prend en charge 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 avec 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 : un bucket Cloud Storage valide avec un préfixe de chemin facultatif dans lequel les fichiers d'exportation sont stockés.
    • PITR_TIMESTAMP - un horodatage PITR à la granularité minute, par exemple, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00 .
    • COLLECTION_IDS - une liste d'identifiants de collection ou d'identifiants de groupe de collections, par exemple 'specific collection group1' , 'specific collection group2' .
    • NAMESPACE_IDS - une liste d'ID d'espace de noms, par exemple 'customer' , 'orders' .

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

    • Spécifiez l'horodatage au format RFC 3339 . Par exemple, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00 .
    • Assurez-vous que l'horodatage que vous spécifiez correspond à une minute entière au cours des sept derniers jours, mais pas avant le earliestVersionTime . Si les données n'existent plus à l'horodatage spécifié, une erreur est générée. L'horodatage doit être d'une minute entière, même si l'heure spécifiée se situe dans l'heure écoulée.
    • Vous n’êtes pas facturé pour un échec d’exportation PITR.

  2. Importer dans une base de données.

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