Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Nella Google Cloud console, vai alla pagina Database.

Vai a Database
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Ripristino di emergenza.
Fai clic su Modifica per modificare le impostazioni.
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

Nella Google Cloud console, vai alla pagina Database.

Vai a Database
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Ripristino di emergenza.
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()

  # 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][GitHub-python].

API REST

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

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

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.
Utilizza il parametro readTime insieme al metodo BeginTransaction come parte di una [ReadOnly transaction][readonly] per più letture PITR.

Apache Beam

Utilizza il connettore Apache Beam IO della 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][datastore-read]. Tutte le letture successive che utilizzano l'oggetto DatastoreV1.Read leggono 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][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, 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

Nella Google Cloud console, vai alla pagina Database.

Vai a Database
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.
Nella finestra di dialogo Crea un clone, fornisci i parametri per la clonazione del database:
1. Nel campo Assegna un ID al clone, 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 da utilizzare per la clonazione. L'ora selezionata corrisponde a un timestamp PITR, con granularità al minuto.
Fai clic su Crea clone.

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à 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 firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

Modifica la configurazione di crittografia del database clonato

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:

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

Esporta e importa da dati PITR

Puoi esportare il database in Cloud Storage dai dati PITR utilizzando il comando [gcloud firestore export][sdk]. Puoi esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero negli ultimi sette giorni, ma non precedente a earliestVersionTime. Se i dati non esistono più al timestamp specificato, l'operazione di esportazione non riesce.

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.

Esporta il database, specificando il parametro snapshot-time nel timestamp di recupero richiesto.
gcloud
Esegui il seguente 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 di percorso facoltativo in cui vengono 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 di entità.

Prima di esportare i dati PITR, tieni presente i seguenti punti:
- Specifica il timestamp in 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 negli ultimi sette giorni, ma non precedente a earliestVersionTime. Se i dati non esistono più al timestamp specificato, riceverai un errore. Il timestamp deve essere di un minuto intero, anche se l'ora specificata rientra nell'ultima ora.
- Non ti verrà addebitato alcun costo per un'esportazione PITR non riuscita.
Importa in un database.

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

[GitHub]: https://github.com/apache/beam/blob/master/sdks/java/io/google-cloud-platform/src/test/java/org/apache/beam/sdk/io/gcp/datastore/V1ReadIT.java [GitHub-java]: https://github.com/googleapis/java-datastore/blob/main/google-cloud-datastore/src/test/java/com/google/cloud/datastore/it/ITDatastoreTest.java [GitHub-python]: https://github.com/googleapis/python-datastore/blob/main/tests/system/test_read_consistency.py [lookup]: /datastore/docs/reference/data/rest/v1/projects/lookup [runQuery]: /datastore/docs/reference/data/rest/v1/projects/runQuery [runAggregationQuery]: /datastore/docs/reference/data/rest/v1/projects/runAggregationQuery [readonly]: /java/docs/reference/google-cloud-datastore/latest/com.google.datastore.v1#transactionoptions.readonly [import-export]: /datastore/docs/export-import-entities#importing_all_entities [update]: https://cloud.google.com/sdk/gcloud/reference/firestore/databases/update [datastore-read]: https://beam.apache.org/releases/javadoc/current/org/apache/beam/sdk/io/gcp/datastore/DatastoreV1.Read.html [readoption]: https://github.com/googleapis/java-datastore/blob/main/google-cloud-datastore/src/main/java/com/google/cloud/datastore/ReadOption.java [import-kind]: /datastore/docs/export-import-entities#importing_specific_kinds_or_namespaces [sdk]: /sdk/gcloud/reference/firestore/export

Utilizzare il recupero point-in-time (PITR) Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Autorizzazioni

Autorizzazioni obbligatorie

Prima di iniziare

Abilita PITR

Console

gcloud

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

Console

gcloud

Leggi i dati PITR

Librerie client

Java

Python

API REST

Apache Beam

Java

Clona da un database

Console

gcloud

Modifica la configurazione di crittografia del database clonato

Esporta e importa da dati PITR

gcloud

Utilizzare il recupero point-in-time (PITR)