Utilizzare il recupero point-in-time (PITR)

Questa pagina descrive come utilizzare il recupero point-in-time (PITR) per conservare e recuperare i dati in Firestore in modalità Datastore.

Per comprendere i concetti di PITR, consulta Recupero point-in-time.

Autorizzazioni

Per ottenere le autorizzazioni necessarie per gestire le impostazioni PITR, chiedi all'amministratore di concederti il ruolo IAM Proprietario di Cloud Datastore (roles/datastore.owner) sul progetto di cui vuoi abilitare le impostazioni PITR. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per gestire le impostazioni PITR. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per gestire le impostazioni PITR sono necessarie le seguenti autorizzazioni:

  • Per abilitare PITR durante la creazione di un database: datastore.databases.create
  • Per aggiornare le impostazioni PITR sul database esistente: datastore.databases.update,datastore.databases.list
  • Per eseguire letture dai dati PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
  • Per esportare i dati PITR: datastore.databases.export
  • Per importare i dati PITR: datastore.databases.import

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Prima di iniziare

Prima di iniziare a utilizzare PITR, tieni presente i seguenti punti:

  • Non puoi iniziare a leggere da sette giorni prima immediatamente dopo aver abilitato PITR.
  • Se vuoi abilitare PITR durante la creazione di un database, devi utilizzare il comando gcloud firestore databases create. L'abilitazione di PITR durante la creazione di un database utilizzando la Google Cloud console non è supportata.
  • La modalità Datastore inizia a conservare le versioni dal momento in cui abiliti PITR.
  • Non puoi leggere i dati PITR nella finestra PITR dopo aver disabilitato PITR.
  • Se riabiliti PITR immediatamente dopo averlo disabilitato, i dati PITR precedenti non sono più disponibili. Tutti i dati PITR creati prima della disabilitazione di PITR verranno eliminati dopo la data di scadenza di PITR.
  • Se hai eliminato accidentalmente i dati nell'ultima ora e PITR è disabilitato, puoi ripristinarli abilitando PITR entro un'ora dall'eliminazione.
  • Qualsiasi lettura eseguita sui dati PITR scaduti non riesce.

Abilita PITR

Prima di utilizzare PITR, abilita la fatturazione per il tuo Google Cloud progetto. Solo i progetti con la fatturazione abilitata possono utilizzare la funzionalità PITR. Google Cloud

Per abilitare PITR per il tuo database:

Console

  1. Nella Google Cloud console, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Ripristino di emergenza.

  4. Fai clic su Modifica per modificare le impostazioni.

  5. Seleziona la casella di controllo Abilita recupero point-in-time e poi fai clic su Salva.

L'abilitazione di PITR comporta costi di archiviazione. Per maggiori informazioni, consulta la pagina Prezzi.

Per disabilitare PITR, deseleziona la casella di controllo Abilita recupero point-in-time dalla pagina Ripristino di emergenza nella Google Cloud console.

gcloud

Abilita PITR durante la creazione del database con il gcloud firestore databases create comando come segue:

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

Sostituisci i valori come segue:

  • LOCATION - la località in cui vuoi creare il database.
  • DATABASE_ID - impostato sull'ID database o (predefinito).
  • TYPE - impostato su datastore-mode.

Puoi disabilitare PITR utilizzando il comando [gcloud firestore databases update][update] come segue:

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

Sostituisci i valori come segue:

  • DATABASE_ID - impostato sull'ID database o (predefinito).

Recupera il periodo di conservazione e l'ora della versione più recente

Console

  1. Nella Google Cloud console, vai alla pagina Database.

    Vai a Database

  2. Seleziona il database richiesto dall'elenco dei database.

  3. Nel menu di navigazione, fai clic su Ripristino di emergenza.

  4. Nella sezione Impostazioni, prendi nota di Periodo di conservazione e Ora della versione più recente.

    • Periodo di conservazione: il periodo in cui la modalità Datastore conserva tutte le versioni dei dati per il database. Il valore è di un'ora quando PITR è disabilitato e di sette giorni quando PITR è abilitato.
    • Ora della versione più recente: il timestamp più recente in cui è possibile leggere le versioni precedenti di dati nella finestra PITR. Questo valore viene aggiornato continuamente dalla modalità Datastore e diventa obsoleto nel momento in cui viene eseguita una query. Se utilizzi questo valore per recuperare i dati, assicurati di tenere conto del tempo trascorso dal momento in cui viene eseguita la query sul valore al momento in cui avvii il recupero.
    • Recupero point-in-time: mostra Enabled se PITR è abilitato. Se PITR è disabilitato, vedrai Disabled.

gcloud

Esegui il comando gcloud firestore databases describe come segue:

gcloud firestore databases describe --database=DATABASE_ID

Sostituisci DATABASE_ID con l'ID database o (default).

Ecco l'output:

    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

dove

  • earliestVersionTime - timestamp dei dati PITR più recenti archiviati.
  • pointInTimeRecoveryEnablement: mostra POINT_IN_TIME_RECOVERY_ENABLED se PITR è abilitato. Se PITR è disabilitato, vedrai POINT_IN_TIME_RECOVERY_DISABLED oppure il campo pointInTimeRecoveryEnablement potrebbe non essere visualizzato.
  • versionRetentionPeriod - periodo di tempo per cui i dati PITR vengono conservati in millisecondi. Il valore può essere di un'ora quando PITR è disabilitato o di sette giorni se PITR è abilitato.

Leggi i dati PITR

Puoi leggere i dati PITR utilizzando le librerie client, i metodi dell'API REST o il connettore Apache Beam FirestoreIO.

Librerie client

Java

Devi utilizzare il metodo readTime nella classe ReadOption per leggere i dati PITR. Non puoi utilizzare la transazione ReadOnly per eseguire le letture. Per maggiori informazioni, consulta il codice campione [ReadOption][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");

Per un elenco completo di esempi di readTime, consulta il [repository GitHub][GitHub-java].

Python

Utilizza la lettura PITR nell'SDK Python della modalità Datastore utilizzando il metodo readTime o la transazione ReadOnly con readTime per eseguire le letture.

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