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 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 de récupération à un instant donné, 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 de récupération à un instant donné. 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 restauration à un instant donné. 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 de restauration à un instantané :

Pour activer la récupération PITR lors de la création d'une base de données : datastore.databases.create
Pour mettre à jour les paramètres de la récupération 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,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
Pour exporter les 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

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 précédentes de récupération à un moment précis 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 restaurer vos données 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 à un moment précis, activez la facturation pour votre projet Google Cloud. Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser la fonctionnalité de restauration à un instant donné.

Pour activer la récupération PITR pour votre base de données :

Console

Dans la console Google Cloud , accédez à la page Bases 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 instant T entraîne des frais de stockage. Consultez la page Tarifs pour en savoir plus.

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 restauration à un instant donné 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 (par défaut).
TYPE : défini sur "datastore-mode".

Vous pouvez désactiver la récupération à un instant donné à 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).

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

Console

Dans la console Google Cloud , accédez à la page Bases 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.
- Période de conservation : période pendant laquelle le mode Datastore conserve toutes les versions des 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 de sept jours lorsqu'elle est activée.
- Heure de la version la plus ancienne : code temporel le plus ancien auquel les versions antérieures des données peuvent être lues dans la période de récupération à un moment précis. Cette valeur est mise à jour en continu par le mode Datastore et devient obsolète au moment où elle est interrogée. Si vous utilisez cette valeur pour récupérer des données, veillez à tenir compte du moment où la valeur est interrogée jusqu'au moment où vous lancez la récupération.
- Récupération à un moment précis : affiche Enabled si la récupération à un moment précis est activée. Si la récupération PITR est désactivée, le message 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 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: DATASTORE_MODE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

où :

earliestVersionTime : code temporel des données PITR les plus anciennes stockées.
pointInTimeRecoveryEnablement : affiche POINT_IN_TIME_RECOVERY_ENABLED si la récupération à un instant T est activée. Si la récupération à un instant T est désactivée, vous verrez POINT_IN_TIME_RECOVERY_DISABLED ou le champ pointInTimeRecoveryEnablement ne s'affichera peut-être pas.
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 de récupération 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 méthode readTime dans la classe ReadOption pour lire les données PITR. Vous ne pouvez pas utiliser la transaction ReadOnly pour effectuer des lectures. Pour en savoir plus, consultez l'exemple de code ReadOption.

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

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

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

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

Pour obtenir la liste complète des exemples readTime, consultez le dépôt GitHub.

Python

Utilisez la lecture PITR dans le SDK Python en mode Datastore à l'aide de la méthode readTime ou utilisez la transaction ReadOnly avec readTime pour effectuer des lectures.

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

Pour obtenir la liste complète des exemples readTime, consultez le dépôt GitHub.

API REST

Les lectures PITR sont compatibles avec les méthodes de lecture du mode Datastore V1, à savoir lookup, runQuery et runAggregationQuery.

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

Dans la requête de votre méthode de lecture, transmettez la valeur readTime en tant qu'horodatage PITR compatible dans la méthode readOptions. Un code temporel PITR peut être un code temporel d'une précision de l'ordre de la microseconde au cours de l'heure précédente ou un code temporel d'une minute entière au-delà de l'heure précédente, mais pas avant le 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 Apache Beam d'E/S en mode Datastore pour lire ou écrire des entités dans une base de données en mode Datastore à grande échelle avec Dataflow.

Spécifiez la méthode withReadTime(Instant readTime) sur l'objet DatastoreV1.Read. Toutes les lectures ultérieures à l'aide de l'objet DatastoreV1.Read sont effectuées à partir du même readTime.

Java

Le code suivant montre comment utiliser la méthode withReadTime pour les lectures PITR.

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

Pour obtenir la liste complète des exemples withReadTime, consultez le dépôt GitHub.

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 créer un clone, Firestore utilise les données de récupération à un moment précis 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 autre type de chiffrement 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.

Console

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

Accéder à la page "Bases de données"
Cliquez sur Afficher plus sur la ligne du tableau correspondant à la base de données que vous souhaitez cloner. Cliquez sur Cloner. La boîte de dialogue Créer un clone s'affiche.
Dans la boîte de dialogue Créer un clone, fournissez les paramètres permettant de cloner la base de données :
1. Dans le champ Indiquez un ID pour le clone, saisissez un ID de base de données pour la nouvelle base de données clonée. Cet ID de base de données ne doit pas être associé à une base de données existante.
2. Dans le champ Cloner à partir de, sélectionnez un moment précis à utiliser pour le clonage. L'heure sélectionnée correspond à un code temporel de récupération à un moment précis, à la minute près.
Cliquez sur Créer un clone.

gcloud

Exécutez la commande gcloud alpha firestore databases clone pour cloner une base de données :

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

Remplacez les éléments suivants :

SOURCE_DATABASE : nom de la base de données existante que vous souhaitez cloner. Le nom utilise le format projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.
PITR_TIMESTAMP : code temporel PITR au format RFC 3339, avec une précision à la minute près. Par exemple, 2025-06-01T10:20:00.00Z ou 2025-06-01T10:30:00.00-07:00.
DESTINATION_DATABASE_ID : ID de base de données pour une nouvelle base de données clonée. Cet ID de base de données ne doit pas être associé à une base de données existante.

Exemple :

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

Modifier la configuration du chiffrement de la base de données clonée

Par défaut, la base de données clonée aura la même configuration de chiffrement que la base de données source. Pour modifier la configuration du chiffrement, utilisez l'argument --encryption-type :

(Par défaut) use-source-encryption : utilisez la même configuration de chiffrement que la base de données source.
google-default-encryption : utiliser le chiffrement par défaut de Google.
customer-managed-encryption : utiliser le chiffrement CMEK. Spécifiez un ID de clé dans l'argument --kms-key-name.

L'exemple suivant montre comment configurer le chiffrement CMEK pour la base de données clonée :

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/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 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 est compatible avec tous les filtres, y compris l'exportation de toutes les entités et l'exportation de genres ou d'espaces de noms spécifiques.

Exportez la base de données en spécifiant le paramètre snapshot-time sur l'horodatage 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 : un 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 d'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').
Il est également possible d'exporter un sous-ensemble spécifique de genres et/ou d'espaces de noms à l'aide d'un filtre d'entité.

Avant d'exporter des données PITR, tenez compte des points suivants :
- 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 est un horodatage à la 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é, 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.
- Aucuns frais ne vous seront facturés en cas d'échec de l'exportation PITR.
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. Il est également possible d'importer un sous-ensemble spécifique de genres et/ou d'espaces de noms avec un filtre d'entité.

Utiliser la récupération à un moment précis (PITR) Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Autorisations

Autorisations requises

Avant de commencer

Activer la récupération PITR

Console

gcloud

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

Console

gcloud

Lire les données de récupération PITR

Bibliothèques clientes

Java

Python

API REST

Apache Beam

Java

Cloner à partir d'une base de données

Console

gcloud

Modifier la configuration du chiffrement de la base de données clonée

Exporter et importer des données PITR

gcloud

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