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 en mode Datastore.

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

Autorisations

Pour obtenir les autorisations nécessaires pour gérer les paramètres PITR, demandez à votre administrateur de vous accorder le rôle IAM Propriétaire Cloud Datastore (roles/datastore.owner) sur le projet dont vous souhaitez activer les paramètres PITR. Pour en savoir plus sur l'attribution de rôles, consultez 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 restauration à un instant donné. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

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

Avant de commencer

Avant de commencer à utiliser la récupération à un instant donné, notez les points suivants :

• Vous ne pouvez pas commencer à lire les données à partir d'un point dans le temps remontant à sept jours immédiatement après avoir activé la récupération PITR.
• Si vous souhaitez activer la récupération à un instant donné lorsque vous créez une base de données, vous devez utiliser la commande gcloud firestore databases create. L'activation de la récupération à un moment précis lors de la création d'une base de données à l'aide de la console Google Cloud n'est pas possible.
• Le mode Datastore commence à conserver les versions à partir du moment où la récupération à un moment précis est activée.
• Vous ne pouvez pas lire les données PITR dans la fenêtre PITR après avoir désactivé la récupération 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 de récupération à un moment précis précédentes ne sont plus disponibles. 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é des données par erreur au cours de la dernière heure et que la récupération à un moment précis est désactivée, vous pouvez les restaurer en l'activant dans l'heure suivant la 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 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 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 période de conservation et la date 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: DATASTORE_MODE
    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.

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

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

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

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

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

  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 entities = pipeline.apply(read);
    ...

Cloner à partir d'une base de données

Vous pouvez cloner une base de données existante à un code temporel sélectionné dans une nouvelle base de données :

• La base de données clonée est une nouvelle base de données qui sera créée au même emplacement que la base de données source.

  Pour cloner une base de données, Firestore utilise les données de récupération à un moment précis (PITR) de la base de données source. La base de données clonée inclut toutes les données et tous les index.

• Par défaut, la base de données clonée sera chiffrée de la même manière que la base de données source, à l'aide du chiffrement par défaut de Google ou du chiffrement CMEK. Vous pouvez spécifier un type de chiffrement différent ou utiliser une autre clé pour le chiffrement CMEK.

• L'horodatage a une précision d'une minute et spécifie un point dans le temps dans le passé, au cours de la période définie par la fenêtre PITR :

  • Si la récupération PITR est activée pour votre base de données, vous pouvez sélectionner n'importe quelle minute des sept derniers jours (ou moins si la récupération PITR a été activée il y a moins de sept jours).
  • Si la récupération à un moment précis n'est pas activée, vous pouvez sélectionner n'importe quelle minute de l'heure précédente.
  • Vous pouvez consulter le code temporel le plus ancien que vous pouvez sélectionner dans la description de votre base de données.

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Exporter et importer des 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 le code temporel est un code temporel entier (en minutes) au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données correspondant au code temporel spécifié n'existent plus, l'opération d'exportation échoue.

L'opération d'exportation PITR est compatible avec tous les filtres, y compris l'exportation de toutes les entités et l'exportation de types ou d'espaces de noms spécifiques.

1. Exportez la base de données en spécifiant le paramètre snapshot-time vers le code temporel de récupération requis.

   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ù les fichiers d'exportation sont stockés.
   • PITR_TIMESTAMP : code temporel PITR à la minute près, par exemple 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS : liste des ID de collections ou 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'.

   Vous pouvez également exporter un sous-ensemble spécifique de types et d'espaces de noms avec un filtre d'entités. Pour en savoir plus, consultez Exporter des types ou des espaces de noms spécifiques.

   Avant d'exporter des données PITR, tenez compte des points suivants :

   • Spécifiez le code temporel 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 est un code temporel entier (à la minute près) au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données n'existent plus à l'horodatage spécifié, vous obtenez une erreur. 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 seront pas facturées.

2. Importez dans une base de données.

   Suivez la procédure décrite dans Importer toutes les entités pour importer votre base de données exportée. Si une entité existe déjà dans votre base de données, elle sera écrasée. Vous pouvez également importer un sous-ensemble spécifique de types ou d'espaces de noms avec un filtre d'entités. Pour en savoir plus, consultez Importer des types ou des espaces de noms spécifiques.