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
Nella console di Google Cloud Platform, vai alla pagina Database .
Selezionare il database richiesto dall'elenco dei database.
Nel menu di navigazione, fare clic su Disaster Recovery .
Fare clic su Modifica per modificare le impostazioni.
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
Nella console di Google Cloud Platform, vai alla pagina Database .
Selezionare il database richiesto dall'elenco dei database.
Nel menu di navigazione, fare clic su Disaster Recovery .
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, vedraiDisabled
.
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
: mostraPOINT_IN_TIME_RECOVERY_ENABLED
, se PITR è abilitato. Se PITR è disabilitato, vedraiPOINT_IN_TIME_RECOVERY_DISABLED
oppure il campopointInTimeRecoveryEnablement
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:
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 al microsecondo nell'ultima ora o un timestamp di un minuto intero oltre l'ora passata, ma non prima diearliestVersionTime
.Utilizzare il parametro
readTime
insieme al metodoBeginTransaction
come parte di una transazioneReadOnly
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:
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
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.
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 esempio2023-05-26T10:20:00.00Z
o2023-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
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 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.
-
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.