Utilizzo del ripristino point-in-time (PITR)

Questa pagina descrive come utilizzare il ripristino point-in-time (PITR) per conservare e ripristinare i dati in Cloud Firestore.

Per comprendere i concetti PITR, vedere Ripristino point-in-time .

Autorizzazioni

Per ottenere le autorizzazioni necessarie per gestire le impostazioni PITR, chiedi al tuo amministratore di concederti i seguenti ruoli IAM sul progetto in cui desideri abilitare PITR:

  • Proprietario del cloud datastore ( 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 dati PITR: datastore.databases.import

Prima di iniziare

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

  • Non puoi iniziare a leggere da sette giorni nel passato immediatamente dopo aver abilitato PITR.
  • Se desideri 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 GCP non è supportata.
  • Cloud Firestore inizia a conservare le versioni dal momento in poi dopo aver abilitato PITR.
  • Non è possibile leggere i dati PITR nella finestra PITR dopo aver disabilitato PITR.
  • Se riattivi PITR immediatamente dopo averlo disabilitato, i dati PITR precedenti non saranno più disponibili. Tutti i dati PITR creati prima della disattivazione di PITR verranno eliminati dopo la data di scadenza del PITR.
  • Se hai eliminato accidentalmente i dati nell'ultima ora e PITR è disabilitato, puoi ripristinare i dati abilitando PITR entro un'ora dall'eliminazione.
  • Qualsiasi lettura eseguita su dati PITR scaduti fallisce.

Abilita PITR

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

Per abilitare PITR per il tuo database:

Consolle

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

    Vai a Database

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

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

  4. Fare clic su Modifica per modificare le impostazioni.

  5. Selezionare la casella di controllo Abilita ripristino temporizzato , quindi fare clic su Salva .

L'abilitazione di PITR comporterebbe costi di archiviazione. Vedi Prezzi per ulteriori informazioni.

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

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 desideri creare il tuo database.
  • DATABASE_ID : impostato sull'ID del database o (impostazione predefinita).
  • TYPE : impostato su firestore nativo.

Puoi disabilitare 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 del database o (impostazione predefinita).

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

Consolle

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

    Vai a Database

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

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

  4. Nella sezione Impostazioni , prendi nota del Periodo di conservazione e dell'ora della prima versione .

    • Periodo di conservazione : il periodo in cui Cloud Firestore conserva tutte le versioni dei dati per il database. Il valore è un'ora quando PITR è disabilitato e sette giorni quando PITR è 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 da Cloud Firestore e diventa obsoleto nel momento in cui viene interrogato. Se stai utilizzando questo valore per recuperare i dati, assicurati di tenere conto del tempo che intercorre dal momento in cui il valore viene richiesto al momento in cui avvii il ripristino.
    • Recupero point-in-time : mostra Enabled , se PITR è abilitato. Se PITR è disabilitato, vedrai Disabled .

gcloud

Esegui il comando gcloud firestore databases description come segue:

gcloud firestore databases describe --database=DATABASE_ID

Sostituisci DATABASE_ID con l'ID del 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: 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 è abilitato. Se PITR è disabilitato, vedrai POINT_IN_TIME_RECOVERY_DISABLED oppure il campo pointInTimeRecoveryEnablement potrebbe non essere visualizzato.
  • versionRetentionPeriod : periodo di tempo in millisecondi per il quale i dati PITR vengono conservati. Il valore può essere un'ora quando PITR è disabilitato o sette giorni se PITR è abilitato.

Leggi i dati PITR

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

Librerie clienti

Giava

È necessario utilizzare la transazione ReadOnly per leggere i dati PITR. Non è possibile specificare direttamente readTime nelle letture. Per ulteriori informazioni, vedere 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

È necessario utilizzare una transazione ReadOnly per leggere i dati PITR. Non è possibile specificare direttamente readTime nelle letture. Per ulteriori informazioni, vedere 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 di Cloud Firestore, ovvero get , list , batchGet , listCollectionIds , listDocuments , runQuery , runAggregationQuery e partitionQuery .

Per eseguire una lettura utilizzando i metodi REST, provare 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 con precisione al microsecondo nell'ultima ora o un timestamp di un minuto intero oltre l'ora passata, ma non prima di earliestVersionTime .

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

Fascio Apache

Utilizza il connettore Apache Beam di Cloud FirestoreIO 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 connettore Cloud FirestoreIO. Questi metodi di lettura supportano il metodo withReadTime(@Nullable Instant readTime) che puoi utilizzare per le letture PITR:

Giava

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

Esporta e importa da dati PITR

Puoi esportare il tuo database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export . È possibile esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero negli ultimi sette giorni, ma non prima di 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 tutti i documenti e l'esportazione di raccolte specifiche.

  1. Esportare il database, specificando il parametro snapshot-time nel timestamp di ripristino desiderato.

    gcloud

    Esegui il comando seguente 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 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 di raccolta o ID di gruppi di raccolta, ad esempio 'specific collection group1' , 'specific collection group2' .
    • NAMESPACE_IDS : un elenco di ID dello spazio dei nomi, ad esempio 'customer' , 'orders' .

    Tieni presenti i seguenti punti prima di esportare i dati PITR:

    • Specificare 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 prima di earliestVersionTime . Se i dati non esistono più al timestamp specificato, viene generato 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.

    Utilizzare i passaggi in Importare tutti i documenti per importare il database esportato. Se qualche documento esiste già nel database, verrà sovrascritto.