Utilizzare il recupero point-in-time (PITR)
In questa pagina viene descritto come utilizzare il recupero point-in-time (PITR) per conservare e recuperare i dati in Firestore.
Per comprendere i concetti del PITR, consulta la sezione 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
) per il progetto di cui vuoi abilitare le impostazioni PITR.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene le autorizzazioni necessarie per gestire le impostazioni PITR. Per visualizzare le autorizzazioni necessarie, 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 le 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 essere in grado di ottenere queste autorizzazioni con i ruoli personalizzati o altri ruoli predefiniti.
Prima di iniziare
Prima di iniziare a utilizzare PITR, tieni presente quanto segue:
- Non puoi iniziare a leggere da sette giorni nel passato subito dopo aver abilitato PITR.
- Se vuoi abilitare il 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 Google Cloud non è supportata. - Firestore inizia a conservare le versioni dal momento in poi dopo l'abilitazione di PITR.
- Una volta disattivato, non puoi leggere i dati PITR nella finestra PITR.
- Se lo riattivi subito dopo averlo disattivato, i dati PITR precedenti non saranno più disponibili. Tutti i dati PITR creati prima di disabilitare PITR verranno eliminati dopo la data di scadenza del PITR.
- Se hai eliminato accidentalmente dati nell'ultima ora e il PITR è disattivato, puoi ripristinarli attivando PITR entro un'ora dall'eliminazione.
- Qualsiasi lettura eseguita su dati PITR scaduti non riesce.
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:
Console
Nella console Google Cloud, vai alla pagina 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 Attiva il 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 disattivare il PITR, deseleziona la casella di controllo Abilita il ripristino point-in-time nella pagina Ripristino di emergenza nella 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 (valore predefinito).TYPE
: impostato su nativo 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 (valore predefinito).
Recuperare il periodo di conservazione e l'ora della versione meno 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 Ripristino di emergenza.
Nella sezione Impostazioni, prendi nota del Periodo di conservazione e della Data e ora della versione precedente.
- Periodo di conservazione: il periodo in cui Firestore conserva tutte le versioni dei dati per il database. Il valore è un'ora quando PITR è disabilitato e sette giorni quando PITR è abilitato.
- Data/ora versione precedente: il timestamp più recente in cui le versioni precedenti dei dati possono essere lette nella finestra PITR. Questo valore viene aggiornato continuamente da Firestore e diventa inattivo nel momento in cui viene eseguita la query. Se utilizzi questo valore per recuperare i dati, assicurati di tenere conto del tempo dal momento in cui viene eseguita la query sul valore a quello in cui avvii il recupero.
- Recupero point-in-time: mostra
Enabled
, se il PITR è attivo. Se PITR è disattivato, verrà visualizzatoDisabled
.
gcloud
Esegui il comando gcloud firestore Publishers describe come segue:
gcloud firestore databases describe --database=DATABASE_ID
Sostituisci DATABASE_ID
con l'ID 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
: mostraPOINT_IN_TIME_RECOVERY_ENABLED
, se PITR è abilitato. Se il PITR è disattivato, verrà visualizzatoPOINT_IN_TIME_RECOVERY_DISABLED
oppure il campopointInTimeRecoveryEnablement
potrebbe non essere visualizzato.versionRetentionPeriod
: periodo di tempo in millisecondi durante il quale i dati PITR vengono conservati. Il valore può essere di un'ora se il PITR è disattivato o di sette giorni se il PITR è attivato.
Lettura 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 Transazioni e operazioni di scrittura 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 Transazioni e operazioni di scrittura 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 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 di precisione in microsecondi nell'ultima ora o un timestamp di un minuto intero oltre l'ultima ora, ma non precedente alearliestVersionTime
.Utilizza il parametro
readTime
insieme al metodoBeginTransaction
come parte 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 Firestore. 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 seguente codice può essere utilizzato con il codice pipeline di 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.
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 di minuti interi negli ultimi sette giorni, ma non precedente a 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.
Esporta il database, specificando il parametro
snapshot-time
con il timestamp di recupero desiderato.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 di percorso facoltativo in cui sono archiviati i file di esportazione.PITR_TIMESTAMP
: un timestamp PITR alla granularità dei minuti, 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'
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 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 relativo agli ultimi sette giorni, ma non precedente a
earliestVersionTime
. Se i dati non esistono più nel timestamp specificato, viene generato un errore. Il timestamp deve essere un minuto intero, anche se l'ora specificata rientra nell'ultima ora. - Non ti viene addebitato alcun costo per un'esportazione PITR non riuscita.
Importa in un database.
Segui i passaggi descritti in Importare tutti i documenti per importare il database esportato. Se nel database è già presente un documento, questo verrà sovrascritto.