Cette page a été traduite par l'API Cloud Translation.

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 des données dans Firestore.

Pour comprendre les concepts de récupération à un moment précis, 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 le Propriétaire Cloud Datastore (roles/datastore.owner) pour le projet dont vous souhaitez activer les paramètres de récupération à un moment précis. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour gérer les paramètres de récupération à un moment précis. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour gérer les paramètres PITR:

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

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 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 Google Cloud n'est pas possible.
Firestore commence à conserver les versions à partir de ce point 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 PITR précédentes ne sont plus disponibles. Toutes les données PITR créées avant de désactiver la PITR seront être supprimées après la date d'expiration de la récupération à un moment précis.
Si vous avez accidentellement supprimé 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 peut restaurer vos données en activant la récupération à un moment précis dans l'heure qui suit leur suppression.
Toute lecture effectuée sur des données PITR expirées é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 PITR pour votre base de données :

Console

Dans la console Google Cloud, accédez à la page Base de données.

Accéder à la page "Bases de données"
Sélectionnez la base de données requise dans la liste des bases de données.
Dans le menu de navigation, cliquez sur Reprise après sinistre.
Cliquez sur Modifier pour modifier les paramètres.
Cochez la case Activer la récupération à un moment précis, puis cliquez sur Enregistrer.

L'activation de la récupération à un moment précis entraîne des coûts de stockage. Reportez-vous à la page Tarifs pour plus de détails.

Pour désactiver la récupération à un moment précis, décochez la case Activer la récupération à un moment précis sur la page "Reprise après sinistre" de la console Google Cloud.

gcloud

Activez la récupération à un moment précis lors de la création de la base de données à l'aide de 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 (valeur par défaut).
TYPE : défini sur Firestore natif.

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 (valeur par défaut).

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

Console

Dans la console Google Cloud, accédez à la page Base de données.

Accéder à la page "Bases de données"
Sélectionnez la base de données requise dans la liste des bases de données.
Dans le menu de navigation, cliquez sur Reprise après sinistre.
Dans la section Paramètres, notez la durée de conservation et la date de la première version.
- Durée de conservation : période pendant laquelle Firestore conserve toutes les versions de données de la base de données. La valeur est d'une heure lorsque la récupération à un moment précis est désactivée et sept jours lorsque la récupération à un moment précis est activée.
- Heure de la version la plus ancienne : horodatage le plus ancien à partir duquel les anciennes versions des données peuvent être lues dans la période de récupération PITR. Cette valeur est mise à jour en continu par Firestore et deviennent obsolètes dès qu'elles sont interrogées. Si vous utilisent cette valeur pour récupérer des données, veillez à prendre en compte au moment où la valeur est interrogée jusqu'au moment où vous lancez la la récupération.
- Récupération à un moment précis: affiche Enabled si la récupération à un moment précis est activé. Si la récupération PITR est désactivée, l'option Disabled s'affiche.

gcloud

Exécutez la commande gcloud firestore databases describe comme suit:

gcloud firestore databases describe --database=DATABASE_ID

Remplacez DATABASE_ID par l'ID de la base de données ou par 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 données PITR les plus anciennes stockées.
pointInTimeRecoveryEnablement : affiche POINT_IN_TIME_RECOVERY_ENABLED si la récupération PITR est activée. Si la PITR est désactivée, POINT_IN_TIME_RECOVERY_DISABLED s'affiche ou le champ pointInTimeRecoveryEnablement n'est pas affiché.
versionRetentionPeriod : période pendant laquelle les données PITR sont conservées en millisecondes. La valeur peut être d'une heure lorsque la récupération PITR est désactivée ou de sept jours si elle est activée.

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 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. Pour en savoir plus, consultez la page Transactions et écritures par lot.

  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. Pour en savoir plus, consultez la page Transactions et écritures par lot.

  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 compatibles avec toutes les méthodes de lecture 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 :

Dans votre requête de méthode de lecture, transmettez la valeur readTime en tant que code temporel PITR compatible dans la méthode readOptions. Un code temporel PITR peut être un code temporel précis à la microseconde au cours de la dernière heure ou un code temporel d'une minute entière au-delà de la dernière heure, mais pas avant l'earliestVersionTime.
Utilisez le paramètre readTime avec la méthode BeginTransaction dans le cadre d'une transaction ReadOnly pour plusieurs lectures PITR.

Apache Beam

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

Les lectures PITR sont compatibles avec la méthode de lecture suivante du connecteur FirestoreIO. Ces méthodes de lecture sont compatibles La méthode withReadTime(@Nullable Instant readTime) que vous pouvez utiliser pour la récupération à un moment précis lit:

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 de données PITR à l'aide de la commande gcloud firestore export. Vous pouvez exporter des données PITR dont le code temporel correspond à une minute entière 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.

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 d'accès facultatif où sont stockés les fichiers d'exportation.
- PITR_TIMESTAMP : code temporel PITR avec une précision de minute, par exemple 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
- COLLECTION_IDS : liste d'ID de collection ou d'ID de groupe de collection, 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 les 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 le code temporel que vous spécifiez correspond à 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'horodatage spécifié, une erreur est générée. Le code temporel doit être une minute entière, même si l'heure spécifiée est dans l'heure précédente.
- Les exportations PITR ayant échoué ne vous sont pas facturées.
Importez-les 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.