Menggunakan pemulihan point-in-time (PITR)
Halaman ini menjelaskan cara menggunakan pemulihan point-in-time (PITR) untuk mempertahankan dan memulihkan data di Firestore.
Untuk memahami konsep PITR, lihat Pemulihan point-in-time.
Izin
Untuk mendapatkan izin yang diperlukan untuk mengelola setelan PITR, minta administrator untuk memberi Anda peran IAM Cloud Datastore Owner (roles/datastore.owner
) pada project yang setelan PITR-nya ingin Anda aktifkan.
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.
Peran yang telah ditentukan ini berisi izin yang diperlukan untuk mengelola setelan PITR. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:
Izin yang diperlukan
Izin berikut diperlukan untuk mengelola setelan PITR:
-
Untuk mengaktifkan PITR saat membuat database:
datastore.databases.create
-
Untuk memperbarui setelan PITR pada database yang ada:
datastore.databases.update
,datastore.databases.list
-
Untuk melakukan pembacaan dari data PITR:
datastore.databases.get
,datastore.entities.get
,datastore.entities.list
-
Untuk mengekspor data PITR:
datastore.databases.export
-
Untuk mengimpor data PITR:
datastore.databases.import
Anda mung juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaanlainnya.
Sebelum memulai
Perhatikan poin-poin berikut sebelum Anda mulai menggunakan PITR:
- Anda tidak dapat mulai membaca dari tujuh hari yang lalu segera setelah Anda mengaktifkan PITR.
- Jika ingin mengaktifkan PITR saat membuat database, Anda harus menggunakan perintah
gcloud firestore databases create
. Mengaktifkan PITR saat membuat database menggunakan Konsol Google Cloud tidak didukung. - Firestore mulai mempertahankan versi dari awal setelah mengaktifkan PITR.
- Setelah menonaktifkan PITR, Anda tidak dapat membaca data PITR selama periode PITR.
- Jika Anda mengaktifkan kembali PITR segera setelah menonaktifkannya, data PITR sebelumnya tidak lagi tersedia. Setiap data PITR yang dibuat sebelum menonaktifkan PITR akan dihapus setelah tanggal habis masa berlaku PITR.
- Jika Anda tidak sengaja menghapus data dalam satu jam terakhir dan PITR dinonaktifkan, Anda dapat memulihkan data dengan mengaktifkan PITR dalam waktu satu jam setelah penghapusan.
- Setiap pembacaan yang dilakukan pada data PITR yang sudah tidak berlaku akan gagal.
Mengaktifkan PITR
Sebelum menggunakan PITR, aktifkan penagihan untuk project Google Cloud Anda. Hanya project Google Cloud dengan penagihan aktif yang dapat menggunakan fungsi PITR.
Untuk mengaktifkan PITR untuk database Anda:
Konsol
Di konsol Google Cloud, buka halaman Databases.
Pilih database yang diperlukan dari daftar database.
Di menu navigasi, klik Pemulihan dari Bencana.
Klik Edit untuk mengedit setelan.
Centang kotak Aktifkan pemulihan point-in-time, lalu klik Simpan.
Mengaktifkan PITR akan menimbulkan biaya penyimpanan. Lihat Harga untuk informasi selengkapnya.
Untuk menonaktifkan PITR, hapus centang pada kotak Enable point-in-time recovery dari halaman Disaster Recovery di konsol Google Cloud.
gcloud
Aktifkan PITR selama pembuatan database dengan perintah gcloud firestore databases create
sebagai berikut:
gcloud firestore databases create\
--location=LOCATION\
[--database=DATABASE_ID; default="(default)"]\
[--type=TYPE; default="firestore-native"]\
--enable-pitr
Ganti nilai sebagai berikut:
Location
- lokasi tempat Anda ingin membuat database.DATABASE_ID
- ditetapkan ke ID database atau (default).TYPE
- ditetapkan ke firestore-native.
Anda dapat menonaktifkan PITR menggunakan perintah gcloud firestore databases update
sebagai berikut:
gcloud firestore databases update\
[--database=DATABASE_ID; default="(default)"]\
--no-enable-pitr
Ganti nilai sebagai berikut:
DATABASE_ID
- ditetapkan ke ID database atau (default).
Mendapatkan periode retensi data dan waktu versi paling awal
Konsol
Di konsol Google Cloud, buka halaman Databases.
Pilih database yang diperlukan dari daftar database.
Di menu navigasi, klik Pemulihan dari Bencana.
Di bagian Settings, perhatikan Retention period dan Earliest version time.
- Periode retensi: periode saat Firestore menyimpan semua versi data untuk database. Nilainya adalah satu jam saat PITR dinonaktifkan dan tujuh hari saat PITR diaktifkan.
- Waktu versi paling awal: stempel waktu paling awal saat data versi lama dapat dibaca di periode PITR. Nilai ini terus-menerus diperbarui oleh Firestore dan menjadi tidak berlaku saat dikueri. Jika Anda menggunakan nilai ini untuk memulihkan data, pastikan untuk memperhitungkan waktu sejak saat nilai dikueri hingga saat Anda memulai pemulihan.
- Pemulihan point-in-time: menampilkan
Enabled
, jika PITR diaktifkan. Jika PITR dinonaktifkan, Anda akan melihatDisabled
.
gcloud
Jalankan perintah gcloud firestore databases describe sebagai berikut:
gcloud firestore databases describe --database=DATABASE_ID
Ganti DATABASE_ID
dengan ID database atau default
.
Berikut output-nya:
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
dalam hal ini,
earliestVersionTime
- stempel waktu data PITR paling awal yang disimpan.pointInTimeRecoveryEnablement
: menampilkanPOINT_IN_TIME_RECOVERY_ENABLED
, jika PITR diaktifkan. Jika PITR dinonaktifkan, Anda akan melihatPOINT_IN_TIME_RECOVERY_DISABLED
atau kolompointInTimeRecoveryEnablement
mungkin tidak ditampilkan.versionRetentionPeriod
- jangka waktu data PITR dipertahankan dalam milidetik. Nilainya dapat berupa satu jam saat PITR dinonaktifkan atau tujuh hari jika PITR diaktifkan.
Membaca data PITR
Anda dapat membaca data PITR menggunakan library klien, metode REST API, atau konektor FirestoreIO Apache Beam.
Library klien
Java
Anda harus menggunakan transaksi ReadOnly
untuk membaca data PITR. Anda tidak dapat langsung menentukan readTime
dalam operasi baca.
Lihat Transaksi dan operasi tulis dalam batch untuk informasi selengkapnya.
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();
Node
Anda harus menggunakan transaksi ReadOnly
untuk membaca data PITR. Anda tidak dapat langsung menentukan readTime
dalam operasi baca.
Lihat Transaksi dan operasi tulis dalam batch untuk informasi selengkapnya.
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)}
)
REST API
Pembacaan PITR didukung di semua metode baca Firestore, yaitu get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery, dan partitionQuery.
Untuk melakukan pembacaan menggunakan metode REST, coba salah satu opsi berikut:
Dalam permintaan metode baca Anda, teruskan nilai
readTime
sebagai stempel waktu PITR yang didukung dalam metodereadOptions
. Stempel waktu PITR dapat berupa stempel waktu presisi mikrodetik dalam satu jam terakhir, atau stempel waktu satu menit setelah satu jam terakhir, tetapi tidak lebih awal dariearliestVersionTime
.Gunakan parameter
readTime
bersama dengan metodeBeginTransaction
sebagai bagian dari transaksiReadOnly
untuk beberapa pembacaan PITR.
Apache Beam
Gunakan konektor FirestoreIO Apache Beam untuk membaca atau menulis dokumen di database Firestore dalam skala besar dengan Dataflow.
Pembacaan PITR didukung dalam metode baca berikut di konektor Firestore. Metode baca ini mendukung
metode withReadTime(@Nullable Instant readTime)
yang Anda gunakan yang dapat digunakan untuk
membaca PITR:
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
Java
Kode berikut dapat digunakan dengan contoh kode pipeline Dataflow untuk operasi baca atau tulis massal. Contoh ini menggunakan metode withReadTime(@Nullable Instant readTime)
untuk pembacaan 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())
...
Untuk mengetahui daftar lengkap contoh readTime
di pipeline Dataflow, lihat repositori GitHub.
Mengekspor dan mengimpor dari data PITR
Anda dapat mengekspor database ke Cloud Storage dari data PITR menggunakan perintah gcloud firestore export
. Anda dapat mengekspor data PITR dengan stempel waktu satu menit dalam tujuh hari terakhir, tetapi tidak lebih awal dari earliestVersionTime
. Jika data tidak lagi ada di stempel waktu yang ditentukan, operasi ekspor akan gagal.
Operasi ekspor PITR mendukung semua filter, termasuk ekspor semua dokumen dan ekspor koleksi tertentu.
Ekspor database, dengan menentukan parameter
snapshot-time
ke stempel waktu pemulihan yang diinginkan.gcloud
Jalankan perintah berikut untuk mengekspor database ke bucket Anda.
gcloud firestore export gs://[BUCKET_NAME_PATH] \ --snapshot-time=[PITR_TIMESTAMP] \ --collection-ids=[COLLECTION_IDS] \ --namespace-ids=[NAMESPACE_IDS]
Dengan,
BUCKET_NAME_PATH
- bucket Cloud Storage yang valid dengan awalan jalur opsional tempat file ekspor disimpan.PITR_TIMESTAMP
- stempel waktu PITR pada tingkat perincian menit, misalnya,2023-05-26T10:20:00.00Z
atau2023-10-19T10:30:00.00-07:00
.COLLECTION_IDS
- daftar ID koleksi atau ID kelompok koleksi, misalnya-'specific collection group1'
,'specific collection group2'
.NAMESPACE_IDS
- daftar ID namespace, misalnya-'customer'
,'orders'
.
Perhatikan hal-hal berikut sebelum mengekspor data PITR:
- Tentukan stempel waktu dalam format RFC 3339.
Misalnya,
2023-05-26T10:20:00.00Z
atau2023-10-19T10:30:00.00-07:00
. - Pastikan stempel waktu yang Anda tentukan adalah stempel waktu keseluruhan satu menit dalam tujuh hari terakhir, tetapi tidak lebih awal dari
earliestVersionTime
. Jika data sudah tidak ada di stempel waktu yang ditentukan, akan terjadi error. Stempel waktu harus satu menit penuh, meskipun waktu yang ditentukan berada dalam satu jam terakhir. - Anda tidak akan ditagih untuk ekspor PITR yang gagal.
Mengimpor ke database.
Gunakan langkah-langkah di bagian Mengimpor semua dokumen untuk mengimpor database yang telah diekspor. Jika ada dokumen yang sudah ada dalam database Anda, dokumen tersebut akan ditimpa.