Lavorare con 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.

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 Ruolo IAM Proprietario Cloud Datastore (roles/datastore.owner) nel progetto di cui vuoi abilitare 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 vedere le autorizzazioni esatte obbligatorie, 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
  • Per esportare i dati PITR: datastore.databases.export
  • Per importare i dati PITR: datastore.databases.import

Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati 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 nel passato subito dopo aver abilitare PITR.
  • Se vuoi abilitare PITR quando crei un database, devi utilizzare il metodo Comando gcloud firestore databases create. Attivazione del PITR durante la creazione di un database utilizzando la console Google Cloud non è supportata.
  • Firestore inizia a conservare le versioni dal momento in poi dopo l'attivazione di 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 di PITR verranno vengano eliminate 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 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 Ripristino di emergenza.

  4. Fai clic su Modifica per modificare le impostazioni.

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

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

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

gcloud

Abilita 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: posizione in cui vuoi creare il database.
  • DATABASE_ID: impostato sull'ID database o (predefinito).
  • TYPE: impostata su nativa del firestore.

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

Visualizzare il periodo di conservazione e la prima ora della versione

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 Ripristino di emergenza.

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

    • Periodo di conservazione: il periodo in cui Firestore conserva tutte le versioni dei dati per il database. Il valore è un'ora quando il PITR è è disattivato e sette giorni in cui PITR è abilitato.
    • Ora della versione precedente: il primo timestamp relativo alle versioni precedenti i dati possono essere letti nella finestra PITR. Questo valore viene aggiornato continuamente di Firestore e diventa inattivo nel momento in cui viene eseguita una query. Se stai utilizzando questo valore per recuperare i dati, assicurati di tenere conto del tempo dal momento in cui viene eseguita la query sul valore al momento in cui avvii e il ripristino di emergenza.
    • Recupero point-in-time: mostra Enabled se PITR sia abilitato. Se il PITR è disattivato, vedrai Disabled.

gcloud

Esegui il comando gcloud firestore logs 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: FIRESTORE_NATIVE
    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 sia abilitato. Se il PITR è disattivato, vedrai POINT_IN_TIME_RECOVERY_DISABLED o pointInTimeRecoveryEnablement potrebbero non essere visualizzati.
  • versionRetentionPeriod: periodo di tempo in cui i dati PITR vengono conservati in millisecondi. Il valore può essere un'ora se il PITR è disattivato o 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

Devi utilizzare la transazione ReadOnly per leggere i dati PITR. Non puoi specificare direttamente readTime nelle letture. Per ulteriori informazioni, consulta la sezione Transazioni e scritture in 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 la sezione Transazioni e scritture in 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 metodi di lettura Firestore, che sono 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, passa il valore readTime come timestamp PITR supportato nel metodo readOptions. Un timestamp PITR può essere un timestamp di precisione in microsecondi nell'ultima ora o un timestamp di un minuto intero dopo l'ultima ora, ma non precedente a 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 FirestoreIO per leggere o scrivere documenti in un database Firestore su larga scala con Dataflow.

Le letture PITR sono supportate nel seguente metodo di lettura della Connettore FirestoreIO. Questi metodi di lettura supportano withReadTime(@Nullable Instant readTime) metodo che puoi usare per il PITR indica:

Java

Il codice seguente può essere utilizzato con il codice della pipeline Dataflow di esempio per operazioni collettive di lettura o scrittura. 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 di esempi di readTime nella pipeline Dataflow, consulta il repository GitHub.

Esportazione e importazione da 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 sono più esiste in corrispondenza del timestamp specificato, l'operazione di esportazione non va a buon fine.

L'operazione di esportazione PITR supporta tutti i filtri, inclusa l'esportazione di tutti i documenti e l'esportazione di raccolte specifiche.

  1. Esporta il database, specificando il parametro snapshot-time nel timestamp di recupero desiderato.

    gcloud

    Esegui questo comando per esportare il database nel tuo 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 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' e 'specific collection group2'.
    • NAMESPACE_IDS: un elenco di ID spazio dei nomi, ad esempio 'customer','orders'.

    Prima di esportare i dati PITR, tieni presente quanto segue:

    • 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 intero di minuti negli ultimi sette giorni, ma non prima del earliestVersionTime. Se i dati non esistono più al livello viene generato un errore. Il timestamp deve essere un minuto intero, anche se l'orario specificato rientra nell'ultima ora.
    • Non ti viene addebitato alcun costo per un'esportazione PITR non riuscita.

  2. Importa in un database.

    Segui i passaggi descritti in Importa tutti i documenti per importare esportato. Se esiste già un documento nel database, verranno sovrascritti.