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 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 de 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 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 PITR. 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

Notez les points suivants avant de commencer à utiliser PITR:

• Vous ne pouvez pas commencer à lire des données remontant à sept jours en arrière immédiatement après avoir activé la récupération 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 Google Cloud n'est pas possible.
• Le mode Datastore commence à conserver les versions à partir du moment où vous activez la récupération PITR.
• 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 PITR 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é 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 suivant la suppression.
• Toute lecture effectuée sur des données PITR expirées échoue.

Activer la récupération 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 la récupération PITR 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 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<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");

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

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

1. Exportez la base de données en spécifiant le paramètre snapshot-time vers 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 : 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 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 genres et/ou d'espaces de noms à l'aide d'un filtre d'entité.

   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 est un code temporel entier de la minute au cours des sept derniers jours, mais pas antérieur à 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.

2. Importez-les 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. L'importation d'un sous-ensemble spécifique de genres et/ou d'espaces de noms à l'aide d'un filtre d'entité est également possible.