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 del recupero point-in-time, 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 attivare PITR durante la creazione di un database:
datastore.databases.create
-
Per aggiornare le impostazioni PITR nel 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 ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Prima di iniziare
Tieni presente quanto segue prima di iniziare a utilizzare la 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
. L'attivazione del PITR durante la creazione di un database utilizzando la console Google Cloud non è supportata. - Firestore inizia a conservare le versioni da quel momento in poi dopo aver attivato il PITR.
- Non puoi leggere i dati PITR nella finestra PITR dopo aver disattivato la funzionalità.
- Se riattivi PITR immediatamente dopo averlo disattivato, i dati PITR precedenti non sono più disponibili. Tutti 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 recuperarli attivando il PITR entro un'ora dall'eliminazione.
- Qualsiasi lettura eseguita sui dati PITR scaduti non va a buon fine.
Attivare PITR
Prima di utilizzare la copia incrementale del piano di recupero, attiva la fatturazione per il tuo progetto Google Cloud. 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.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Disaster Recovery.
Fai clic su Modifica per modificare le impostazioni.
Seleziona la casella di controllo Abilita il recupero in un determinato momento e fai clic su Salva.
L'attivazione di PITR comporta costi di archiviazione. Per ulteriori informazioni, consulta la sezione Prezzi.
Per disattivare il PITR, deseleziona la casella di controllo Abilita il recupero point-in-time nella pagina Disaster Recovery della 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
: impostato su firestore-native.
Puoi disattivare la copia incrementale in tempo reale 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).
Ottenere il periodo di conservazione e l'ora della versione più recente
Console
Nella console Google Cloud, vai alla pagina Database.
Seleziona il database richiesto dall'elenco dei database.
Nel menu di navigazione, fai clic su Disaster Recovery.
Nella sezione Impostazioni, prendi nota di Periodo di conservazione e Ora della versione più antica.
- Periodo di conservazione: il periodo in cui Firestore conserva tutte le versioni dei dati per il database. Il valore è un'ora se il PITR è disabilitato e sette giorni se è abilitato.
- Ora versione più vecchia: il timestamp più antico a cui è possibile leggere le versioni precedenti dei dati nella finestra PITR. Questo valore viene aggiornato continuamente da Firestore e diventa obsoleto nel momento in cui viene eseguita la query. Se utilizzi questo valore 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, viene visualizzatoDisabled
.
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 con '(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/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
dove
earliestVersionTime
: timestamp dei dati PITR più antichi archiviati.pointInTimeRecoveryEnablement
: mostraPOINT_IN_TIME_RECOVERY_ENABLED
se la funzionalità PITR è attivata. Se il PITR è disattivato, vedraiPOINT_IN_TIME_RECOVERY_DISABLED
o il campopointInTimeRecoveryEnablement
potrebbe non essere visualizzato.versionRetentionPeriod
: periodo di tempo per cui i dati PITR vengono conservati in millisecondi. Il valore può essere un'ora se il PITR è disattivato o sette giorni se è attivato.
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 la transazione ReadOnly
. Non puoi specificare direttamente readTime
nelle letture.
Per ulteriori informazioni, consulta Transazioni e scritture collettive.
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
Per leggere i dati PITR, devi utilizzare una transazione ReadOnly
. Non puoi specificare direttamente readTime
nelle letture.
Per ulteriori informazioni, consulta Transazioni e scritture collettive.
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 Firestore, ovvero get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery e partitionQuery.
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 metodoreadOptions
. 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 giornoearliestVersionTime
.Utilizza il parametro
readTime
insieme al metodoBeginTransaction
all'interno di una transazioneReadOnly
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 del connettore FirestoreIO. Questi metodi di lettura supportano il metodo withReadTime(@Nullable Instant readTime)
che puoi utilizzare per le letture PITR:
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
Java
Il codice seguente può essere utilizzato con il codice di esempio della pipeline Dataflow per le operazioni di lettura o scrittura collettiva. 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 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 intero di un minuto 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 di raccolte specifiche.
Esporta il database specificando il parametro
snapshot-time
con il timestamp di recupero desiderato.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à a livello di minuto, ad esempio2023-05-26T10:20:00.00Z
o2023-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
o2023-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 precedente al giorno
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 è compresa nell'ora precedente. - Non ti viene addebitato alcun costo per un'esportazione PITR non riuscita.
Importazione in un database.
Segui la procedura descritta in Importare tutti i documenti per importare il database esportato. Se nel database esiste già un documento, verrà sovrascritto.