Questa pagina è stata tradotta dall'API Cloud Translation.

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 del data store Cloud (roles/datastore.owner) nel progetto di cui vuoi attivare le impostazioni PITR. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per gestire le impostazioni PITR. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

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

Tieni presente i seguenti punti prima di iniziare a utilizzare PITR:

Non puoi iniziare a leggere da sette giorni prima del momento attuale subito dopo aver attivato la PITR.
Se vuoi attivare la RPI quando crei un database, devi utilizzare il comando gcloud firestore databases create. Attivazione del PITR durante la creazione di un database utilizzando la console Google Cloud non è supportata.
La modalità Datastore inizia a conservare le versioni da quel momento in poi dopo aver attivato il PITR.
Dopo aver disabilitato PITR, non puoi leggere i dati PITR nella finestra PITR.
Se riattivi il PITR subito dopo averlo disattivato, i dati PITR precedenti non è più disponibile. Tutti i dati PITR creati prima della disattivazione del PITR verranno eliminati dopo la data di scadenza del PITR.
Se hai eliminato accidentalmente dati nell'ultima ora e il PITR è disattivato, puoi ripristinare i tuoi dati abilitando il PITR entro un'ora dall'eliminazione.
Qualsiasi lettura eseguita sui dati PITR scaduti non va a buon fine.

Abilita PITR

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

Per attivare il PITR per il tuo database:

Console

Nella console Google Cloud, 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 il recupero in un determinato momento e poi fai clic su Salva.

L'abilitazione di PITR comporta costi di archiviazione. Consulta la sezione Prezzi per ulteriori informazioni.

Per disattivare il PITR, deseleziona la casella di controllo Abilita il recupero point-in-time nella pagina del ripristino di emergenza 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 posizione in cui vuoi creare il database.
DATABASE_ID: impostato sull'ID database o su (predefinito).
TYPE: impostata sulla modalità datastore.

Puoi disabilitare il PITR 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 su (predefinito).

Visualizzare il periodo di conservazione e la prima ora della versione

Console

Nella console Google Cloud, 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 del Periodo di conservazione e della 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 è un'ora se il PITR è disabilitato e sette giorni se è abilitato.
- Data della versione precedente: il timestamp precedente a partire dal quale è possibile leggere le versioni precedenti dei dati nella finestra PITR. Questo valore viene aggiornato continuamente dalla modalità Datastore e diventa inattivo nel momento in cui viene eseguita la query. Se lo utilizzi 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: viene visualizzato Enabled se il recupero PITR è abilitato. Se il PITR è disattivato, 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.

Questo è 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 la funzionalità PITR è attivata. Se il PITR è 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 è disattivato oppure sette giorni se il PITR è abilitato.

Leggere 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

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 il codice di esempio 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 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:

Nella richiesta del metodo di lettura, passa il valore readTime come timestamp PITR supportato nel metodo readOptions. Un timestamp PITR può essere un timestamp con precisione in microsecondi nell'ora precedente o un timestamp di un minuto intero oltre l'ora precedente, ma non precedente al earliestVersionTime.
Utilizza il parametro readTime insieme al metodo BeginTransaction all'interno 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) nell'oggetto DatastoreV1.Read. Tutte le letture successive utilizzando l'oggetto DatastoreV1.Read vengono lette 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.

Esportazione e importazione dai dati PITR

Puoi esportare il tuo database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export. Puoi esportare i dati PITR in cui il timestamp è un timestamp intero di minuti gli ultimi sette giorni, ma non prima di 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 di tipi o spazi dei nomi specifici.

Esporta il database specificando il parametro snapshot-time con il timestamp di recupero richiesto.
gcloud
Esegui il comando seguente 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 vengono archiviati i file di esportazione.
- PITR_TIMESTAMP: un timestamp PITR con granularità in minuti, 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' e '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 in RFC 3339 standard. 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 compreso negli ultimi sette giorni, ma non precedente al giorno earliestVersionTime. Se i dati non esistono più al timestamp specificato, verrà visualizzato un errore. Il timestamp deve essere un minuto intero, anche se l'orario specificato rientra nell'ultima ora.
- Non ti verrà addebitato alcun importo per un'esportazione PITR non riuscita.
Importazione in un database.

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