Utilizzare il recupero point-in-time (PITR)

In questa pagina viene descritto come utilizzare il recupero point-in-time (PITR) per conservare e recuperare i dati in Cloud Firestore.

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 i seguenti ruoli IAM nel progetto in cui vuoi abilitare PITR:

  • Cloud Datastore Owner (roles/datastore.owner)

Per i ruoli personalizzati, assicurati che siano concesse 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
  • Per esportare i dati PITR: datastore.databases.export
  • Per importare i dati PITR: datastore.databases.import
  • Per clonare un database: datastore.databases.clone

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 quando crei un database, devi utilizzare il comando gcloud firestore databases create. L'abilitazione di PITR durante la creazione di un database utilizzando la console Google Cloud non è supportata.
  • Cloud Firestore 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 progetto Google Cloud. Solo i progetti Google Cloud con la fatturazione abilitata possono utilizzare la funzionalità PITR.

Per abilitare 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 dei database.

  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 recupero point-in-time e poi fai clic su Salva.

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

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

gcloud

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

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --type=firestore-native\
  --enable-pitr

Sostituisci i valori come segue:

  • LOCATION - la località in cui vuoi creare il database.
  • DATABASE_ID - impostalo su un ID database.

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

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

Sostituisci i valori come segue:

  • DATABASE_ID - impostalo sull'ID database o su `'(default)'`.

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

Console

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

    Vai a Database

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

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

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

    • Periodo di conservazione: il periodo in cui Cloud Firestore 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 da Cloud Firestore 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/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    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 FirestoreIO Apache Beam.

Librerie client

Java

Devi utilizzare la transazione ReadOnly per leggere i dati PITR. Non puoi specificare direttamente readTime nelle letture. Per ulteriori informazioni, consulta Transazioni e scritture batch.

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

Nodo

Devi utilizzare una transazione ReadOnly per leggere i dati PITR. Non puoi specificare direttamente readTime nelle letture. Per ulteriori informazioni, consulta Transazioni e scritture batch.

const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

API REST

Le letture PITR sono supportate in tutti i Cloud Firestore metodi di lettura, ovvero get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery e partitionQuery.

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 in microsecondi nell'ultima ora o un timestamp di un minuto intero oltre l'ultima ora, ma non precedente a earliestVersionTime.

  2. Utilizza il parametro readTime insieme al metodo BeginTransaction come parte di una transazione ReadOnly per più letture PITR.

Apache Beam

Utilizza il connettore Cloud FirestoreIO Apache Beam per leggere o scrivere documenti in un database Cloud Firestore su larga scala con Dataflow.

Le letture PITR sono supportate nel seguente metodo di lettura del Cloud FirestoreIO connector. Questi metodi di lettura supportano il metodo withReadTime(@Nullable Instant readTime) che puoi utilizzare per le letture PITR:

Java

Il seguente codice può essere utilizzato con il codice della pipeline Dataflow di esempio per le operazioni di lettura o scrittura collettiva. L'esempio utilizza il metodo withReadTime(@Nullable Instant readTime) per le letture PITR.

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

Per un elenco completo degli esempi di readTime nella pipeline Dataflow, consulta il repository GitHub.

Clona da un database

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

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

    Per creare un clone, Cloud 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 momento nel passato, nel periodo definito dalla finestra PITR:

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

Console

Firebase console non supporta la clonazione dei database. Puoi utilizzare le istruzioni per Google Cloud CLI per clonare i database.

Google Cloud CLI

gcloud

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

gcloud 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 in formato RFC 3339, con granularità di un 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 firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

Se vuoi eseguire il binding ad alcuni tag durante la clonazione di un database, utilizza il comando precedente con il flag --tags, che è un elenco facoltativo di coppie KEY=VALUE di tag a cui eseguire il binding.

Esempio:

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

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

  • (Impostazione predefinita) 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 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'