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 Cloud Datastore (roles/datastore.owner) nel progetto di cui vuoi attivare 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 attivare 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 il PITR, tieni presente quanto segue:

• Non puoi iniziare a leggere da sette giorni prima immediatamente dopo aver attivato il PITR.
• Se vuoi attivare il PITR quando crei un database, devi utilizzare il comando gcloud firestore databases create. L'attivazione del PITR durante la creazione di un database utilizzando la console Google Cloud non è supportata.
• La modalità Datastore inizia a conservare le versioni dal momento in poi dopo l'attivazione del recupero point-in-time.
• Non puoi leggere i dati PITR nella finestra PITR dopo aver disattivato PITR.
• Se riattivi PITR immediatamente dopo averlo disattivato, i dati PITR passati non sono più disponibili. I dati PITR creati prima della disattivazione del PITR verranno eliminati dopo la data di scadenza del PITR.
• Se hai eliminato accidentalmente dei dati nell'ultima ora e il PITR è disattivato, puoi ripristinarli attivando il PITR entro un'ora dall'eliminazione.
• Qualsiasi lettura eseguita su dati PITR scaduti non riesce.

Abilita PITR

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

Per abilitare il PITR per il tuo database:

Console

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

   Vai a Database

2. Seleziona il database richiesto dall'elenco.

3. Nel menu di navigazione, fai clic su Disaster Recovery.

4. Fai clic su Modifica per modificare le impostazioni.

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

L'abilitazione del PITR comporta costi di archiviazione. Per ulteriori informazioni, consulta la sezione Prezzi.

Per disattivare il recupero point-in-time, deseleziona la casella di controllo Abilita recupero point-in-time dalla pagina Disaster Recovery nella console Google Cloud .

gcloud

Attiva PITR durante la creazione del database con il comando gcloud firestore databases create 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 (impostazione predefinita).
• TYPE - set to datastore-mode.

Puoi disattivare il ripristino temporizzato utilizzando il comando gcloud firestore databases 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 (impostazione predefinita).

Ottenere il periodo di conservazione e l'ora della prima versione

Console

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

   Vai a Database

2. Seleziona il database richiesto dall'elenco.

3. Nel menu di navigazione, fai clic su Disaster Recovery.

4. Nella sezione Impostazioni, prendi nota del Periodo di conservazione e dell'Ora della versione meno 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 il PITR è disabilitato e di sette giorni quando è abilitato.
   • Ora della prima versione: il primo timestamp in cui è possibile leggere le versioni precedenti dei 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 che intercorre tra il momento in cui viene eseguita la query sul valore e il momento in cui avvii il recupero.
   • Recupero point-in-time: mostra Enabled, se il recupero point-in-time è abilitato. Se il recupero point-in-time è disattivato, vedrai Disabled.

gcloud

Esegui il comando gcloud firestore databases describe nel seguente modo:

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 primi dati PITR archiviati.
• pointInTimeRecoveryEnablement: mostra POINT_IN_TIME_RECOVERY_ENABLED, se PITR è abilitato. Se il recupero temporaneo è disattivato, vedrai POINT_IN_TIME_RECOVERY_DISABLED o il campo pointInTimeRecoveryEnablement potrebbe non essere visualizzato.
• versionRetentionPeriod - periodo di tempo per il quale i dati PITR vengono conservati in millisecondi. Il valore può essere un'ora se il PITR è disabilitato o sette giorni se il PITR è abilitato.

Lettura dei dati PITR

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

Librerie client

Nota: puoi leggere i dati PITR nelle librerie client server, ovvero Go, Java, Node.js, PHP e Python.

Java

Per leggere i dati PITR, devi utilizzare il metodo readTime nella classe ReadOption. Non puoi utilizzare la transazione ReadOnly per eseguire letture. Per ulteriori informazioni, consulta l'codice campione 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.

Python

Utilizza la lettura PITR nell'SDK Python in 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()

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

Per un elenco completo di esempi di readTime, consulta il repository GitHub.

API REST

Le letture PITR sono supportate nei metodi di lettura della versione 1 della modalità Datastore, ovvero lookup, runQuery e runAggregationQuery.

Per eseguire una lettura utilizzando i metodi REST, prova una delle seguenti opzioni:

1. Nella richiesta del metodo di lettura, trasmetti il valore readTime come timestamp PITR supportato nel metodo readOptions. Un timestamp PITR può essere un timestamp con precisione al microsecondo nell'ultima ora o un timestamp di un minuto intero oltre l'ultima ora, ma non precedente al giorno earliestVersionTime.

2. Utilizza il parametro readTime insieme al metodo BeginTransaction nell'ambito di una transazione ReadOnly per più letture PITR.

Apache Beam

Utilizza il connettore Apache Beam IO in modalità Datastore per leggere o scrivere entità in un database in modalità Datastore su larga scala con Dataflow.

Specifica il metodo withReadTime(Instant readTime) sull'oggetto DatastoreV1.Read. Tutte le letture successive che utilizzano l'oggetto DatastoreV1.Read vengono eseguite dallo stesso readTime.

Java

Il seguente codice mostra come utilizzare il metodo withReadTime per le letture 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);
    ...

Per un elenco completo di esempi di withReadTime, consulta il repository GitHub.

Clonare da un database

Anteprima — Database cloning

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Puoi clonare un database esistente in un nuovo database in un timestamp selezionato:

• Il database clonato è un nuovo database che verrà creato nella stessa posizione del database di origine.

  Per creare un clone, Firestore utilizza i dati di recupero point-in-time (PITR) del database di origine. Il database clonato include tutti i dati e gli indici.

• Per impostazione predefinita, il database clonato verrà criptato nello stesso modo del database di origine, utilizzando la crittografia predefinita di Google o la crittografia CMEK. Puoi specificare un tipo di crittografia diverso o utilizzare una chiave diversa per la crittografia CMEK.

• Il timestamp ha una granularità di un minuto e specifica un punto nel tempo nel passato, nel periodo definito dalla finestra PITR:

  • Se il PITR è abilitato per il tuo database, puoi selezionare qualsiasi minuto degli ultimi 7 giorni (o meno se il PITR è stato abilitato meno di 7 giorni fa).
  • Se il PITR non è abilitato, puoi selezionare qualsiasi minuto dell'ultima ora.
  • Puoi controllare il timestamp meno recente che puoi scegliere nella descrizione del database.

Nota: per clonare i database, il tuo Account Google deve disporre dell'autorizzazione IAM datastore.databases.clone.

Console

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

   Vai a Database

2. Fai clic su Visualizza altro nella riga della tabella per il database che vuoi clonare. Fai clic su Clona. Viene visualizzata la finestra di dialogo Crea un clone.

3. Nella finestra di dialogo Crea una clonazione, fornisci i parametri per la clonazione del database:

   1. Nel campo Assegna un ID al clone, inserisci un ID database per un nuovo database clonato. Questo ID database non deve essere associato a un database esistente.

   2. Nel campo Clona da, seleziona un momento specifico da utilizzare per la clonazione. L'ora selezionata corrisponde a un timestamp PITR con granularità al minuto.

4. Fai clic su Crea clone.

Nota: il database clonato avrà la stessa configurazione di crittografia del database di origine. Se vuoi specificare una configurazione di crittografia diversa per il database clonato, puoi utilizzare i comandi Google Cloud CLI.

gcloud

Utilizza il comando gcloud alpha firestore databases clone per clonare un database:

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

Sostituisci quanto segue:

• SOURCE_DATABASE: il nome del database di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• PITR_TIMESTAMP: un timestamp PITR nel formato RFC 3339, con granularità al minuto. Ad esempio: 2025-06-01T10:20:00.00Z o 2025-06-01T10:30:00.00-07:00.

• DESTINATION_DATABASE_ID: un ID database per un nuovo database clonato. Questo ID database non deve essere associato a un database esistente.

Esempio:

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'

Modifica la configurazione della crittografia del database clonato

Per impostazione predefinita, il database clonato avrà la stessa configurazione di crittografia del database di origine. Per modificare la configurazione della crittografia, utilizza l'argomento --encryption-type:

• (Predefinito) use-source-encryption: utilizza la stessa configurazione di crittografia del database di origine.
• google-default-encryption: utilizza la crittografia predefinita di Google.
• customer-managed-encryption: utilizza la crittografia CMEK. Specifica un ID chiave nell'argomento --kms-key-name.

L'esempio seguente mostra come configurare la crittografia CMEK per il database clonato:

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'

Esportare e importare dai dati PITR

Puoi esportare il database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export. Puoi esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero negli ultimi sette giorni, ma non prima del giorno earliestVersionTime. Se i dati non esistono più al timestamp specificato, l'operazione di esportazione non va a buon fine.

L'operazione di esportazione PITR supporta tutti i filtri, inclusa l'esportazione di tutte le entità e l'esportazione di tipi o spazi dei nomi specifici.

1. Esporta il database, specificando il parametro snapshot-time con il timestamp di ripristino richiesto.

   gcloud

   Esegui questo comando per esportare il database nel bucket.

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Dove,

   • BUCKET_NAME_PATH: un bucket Cloud Storage valido con un prefisso del percorso facoltativo in cui sono archiviati i file di esportazione.
   • PITR_TIMESTAMP: un timestamp PITR con granularità al minuto, ad esempio 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS: un elenco di ID raccolta o ID gruppo di raccolte, ad esempio 'specific collection group1','specific collection group2'.
   • NAMESPACE_IDS: un elenco di ID spazio dei nomi, ad esempio 'customer','orders'.

   È supportata anche l'esportazione di un sottoinsieme specifico di tipi e/o spazi dei nomi con un filtro delle entità.

   Tieni presente quanto segue prima di esportare i dati PITR:

   • Specifica il timestamp nel formato RFC 3339. Ad esempio, 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
   • Assicurati che il timestamp specificato sia un timestamp di un minuto intero degli ultimi sette giorni, ma non precedente a earliestVersionTime. Se i dati non esistono più al timestamp specificato, riceverai un errore. Il timestamp deve essere un minuto intero, anche se l'ora specificata rientra nell'ultima ora.
   • Non ti verrà addebitato alcun costo per un'esportazione PITR non riuscita.

2. Importa in un database.

   Segui i passaggi descritti in Importare tutte le entità per importare il database esportato. Se un'entità esiste già nel tuo database, verrà sovrascritta. È supportata anche l'importazione di un sottoinsieme specifico di tipi e/o spazi dei nomi con un filtro delle entità.