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.

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 Cloud Datastore (roles/datastore.owner) nel progetto per 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:

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Prima di iniziare

Prima di iniziare a utilizzare il PITR, tieni presente quanto segue:

• Non puoi iniziare a leggere da sette giorni prima immediatamente dopo aver attivato il PITR.
• Se vuoi attivare il PITR quando crei un database, devi utilizzare il comando gcloud firestore databases create. L'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 cui viene attivato il recupero point-in-time.
• Dopo aver disattivato PITR, non puoi leggere i dati PITR nella finestra PITR.
• Se riattivi PITR immediatamente dopo averlo disattivato, i dati PITR passati non sono più disponibili. I dati PITR creati prima della disattivazione del PITR verranno eliminati dopo la data di scadenza del PITR.
• Se hai eliminato accidentalmente dei dati nell'ultima ora e il PITR è disattivato, puoi ripristinarli attivando il PITR entro un'ora dall'eliminazione.
• Qualsiasi lettura eseguita su dati PITR scaduti non riesce.

Abilita PITR

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

Per abilitare il PITR per il tuo database:

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

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

gcloud firestore databases describe --database=DATABASE_ID

    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

Lettura dei dati PITR

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

  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();

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)}
);

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

Esportare e importare dai dati PITR

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

1. Esporta il database specificando il parametro snapshot-time per il timestamp di recupero scelto.

   gcloud

   Esegui questo 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 del 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','specific-collection-group2'.
   • NAMESPACE_IDS: un elenco di ID spazio dei nomi, ad esempio 'customer','orders'.

   Tieni presente quanto segue prima di esportare i dati PITR:

   • Specifica 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 negli ultimi sette giorni, ma non precedente al 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 è nell'ultima ora.
   • L'esportazione PITR non riuscita non comporta alcun addebito.

2. Importa in un database.

   Segui i passaggi descritti in Importare tutti i documenti per importare il database esportato. Se nel database esiste già un documento, questo verrà sovrascritto.