Belirli bir noktadan önceyi kurtarma (PITR) ile çalışma

Bu sayfada, Cloud Firestore'teki verileri saklamak ve kurtarmak için belirli bir noktadan önceyi kurtarma (PITR) özelliğinin nasıl kullanılacağı açıklanmaktadır.

Belirli bir noktadan önceyi kurtarma kavramlarını anlamak için Belirli bir noktadan önceyi kurtarma başlıklı makaleyi inceleyin.

İzinler

PITR ayarlarını yönetmek için gereken izinleri almak üzere yöneticinizden, PITR'yi etkinleştirmek istediğiniz projede size aşağıdaki IAM rollerini vermesini isteyin:

  • Cloud Datastore Sahibi (roles/datastore.owner)

Özel roller için aşağıdaki izinlerin verildiğinden emin olun:

  • Veritabanı oluştururken PITR'yi etkinleştirmek için: datastore.databases.create
  • Mevcut veritabanında PITR ayarlarını güncellemek için: datastore.databases.update,datastore.databases.list
  • PITR verilerinden okuma yapmak için: datastore.databases.get,datastore.entities.get,datastore.entities.list
  • PITR verilerini dışa aktarmak için: datastore.databases.export
  • PITR verilerini içe aktarmak için: datastore.databases.import

Başlamadan önce

PITR'yi kullanmaya başlamadan önce aşağıdaki noktaları göz önünde bulundurun:

  • PITR'yi etkinleştirdikten hemen sonra yedi gün öncesine ait kayıtları okumaya başlayamazsınız.
  • Bir veritabanı oluştururken PITR'yi etkinleştirmek istiyorsanız gcloud firestore databases create komutunu kullanmanız gerekir. Google Cloud konsolunu kullanarak veritabanı oluştururken PITR'yi etkinleştirme işlemi desteklenmez.
  • Cloud Firestore, PITR'yi etkinleştirdikten sonra o noktadan itibaren sürümleri saklamayı başlar.
  • PITR'yi devre dışı bıraktıktan sonra PITR penceresindeki PITR verilerini okuyamazsınız.
  • PITR'yi devre dışı bıraktıktan hemen sonra yeniden etkinleştirirseniz geçmiş PITR verileri artık kullanılamaz. PITR devre dışı bırakılmadan önce oluşturulan tüm PITR verileri, PITR'nin geçerlilik bitiş tarihinden sonra silinir.
  • Son bir saat içinde yanlışlıkla veri sildiyseniz ve PITR devre dışıysa silme işleminden sonraki bir saat içinde PITR'yi etkinleştirerek verilerinizi geri yükleyebilirsiniz.
  • Süresi dolmuş PITR verilerinde yapılan tüm okuma işlemleri başarısız olur.

PITR'yi etkinleştirme

PITR'yi kullanmadan önce Google Cloud projeniz için faturalandırmayı etkinleştirin. Yalnızca faturalandırma özelliği etkinleştirilmiş Google Cloud projeleri PITR işlevini kullanabilir.

Veritabanı için PITR'yi etkinleştirmek üzere:

Konsol

  1. Google Cloud Console'da Veritabanları sayfasına gidin.

    Veritabanları'na gidin

  2. Veritabanları listesinden gerekli veritabanını seçin.

  3. Gezinme menüsünde Afet Kurtarma'yı tıklayın.

  4. Ayarları düzenlemek için Düzenle'yi tıklayın.

  5. Belirli bir zamana ait kurtarma işlemini etkinleştir onay kutusunu işaretleyin ve Kaydet'i tıklayın.

PITR'nin etkinleştirilmesi depolama alanı maliyetlerine neden olur. Daha fazla bilgi için Fiyatlandırma'yı inceleyin.

Belirli bir noktadan önceyi kurtarma özelliğini devre dışı bırakmak için Google Cloud Console'daki Afet Kurtarma sayfasında Belirli bir noktadan önceyi kurtarmayı etkinleştir onay kutusunu temizleyin.

gcloud

Aşağıdaki şekilde gcloud firestore databases create komutuyla veritabanı oluşturma işlemi sırasında PITR'yi etkinleştirin:

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

Değerleri aşağıdaki gibi değiştirin:

  • Location: Veritabanınızı oluşturmak istediğiniz konum.
  • DATABASE_ID: Veritabanı kimliğine veya (varsayılan) olarak ayarlanır.
  • TYPE: firestore-native olarak ayarlanır.

PITR'yi gcloud firestore databases update komutunu kullanarak aşağıdaki gibi devre dışı bırakabilirsiniz:

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

Değerleri aşağıdaki gibi değiştirin:

  • DATABASE_ID: Veritabanı kimliğine veya (varsayılan) olarak ayarlanır.

Saklama süresini ve en erken sürüm zamanını öğrenme

Konsol

  1. Google Cloud Console'da Veritabanları sayfasına gidin.

    Veritabanlarına git

  2. Veritabanları listesinden gerekli veritabanını seçin.

  3. Gezinme menüsünde Afet Kurtarma'yı tıklayın.

  4. Ayarlar bölümünde Saklama süresi ve En erken sürüm süresi'ne dikkat edin.

    • Saklama süresi: Cloud Firestore'nin veritabanı verilerinin tüm sürümlerini sakladığı dönemdir. Bu değer, PITR devre dışıyken bir saat, PITR etkinken yedi gündür.
    • En eski sürüm zamanı: Verilerin eski sürümlerinin PITR aralığında okunabildiği en erken zaman damgası. Bu değer Cloud Firestore tarafından sürekli olarak güncellenir ve sorgulandığı anda güncelliğini yitirir. Verileri kurtarmak için bu değeri kullanıyorsanız değerin sorgulandığı andan kurtarma işlemini başlattığınız ana kadar geçen süreyi hesaba kattığınızdan emin olun.
    • Belirli bir noktadan önceyi kurtarma: PITR etkinse Enabled gösterilir. PITR devre dışıysa Disabled simgesini görürsünüz.

gcloud

gcloud firestore databases describe komutunu aşağıdaki gibi çalıştırın:

gcloud firestore databases describe --database=DATABASE_ID

DATABASE_ID yerine veritabanı kimliğini veya default değerini girin.

Çıkış şu şekildedir:

    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

Burada:

  • earliestVersionTime: Depolanan en eski PITR verilerinin zaman damgası.
  • pointInTimeRecoveryEnablement: PITR etkinse POINT_IN_TIME_RECOVERY_ENABLED değerini gösterir. PITR devre dışıysa POINT_IN_TIME_RECOVERY_DISABLED değerini görürsünüz veya pointInTimeRecoveryEnablement alanı gösterilmeyebilir.
  • versionRetentionPeriod: PITR verilerinin milisaniye cinsinden saklandığı dönem. Değer, PITR devre dışıyken bir saat veya PITR etkinleştirildiğinde yedi gün olabilir.

PITR verilerini okuma

İstemci kitaplıklarını, REST API yöntemlerini veya FirestoreIO Apache Beam bağlayıcısını kullanarak PITR verilerini okuyabilirsiniz.

İstemci kitaplıkları

Java

PITR verilerini okumak için ReadOnly işlemini kullanmanız gerekir. Okuma işlemlerinde doğrudan readTime belirtemezsiniz. Daha fazla bilgi için İşlemler ve toplu yazmalar başlıklı makaleyi inceleyin.

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

Düğüm

PITR verilerini okumak için bir ReadOnly işlemi kullanmanız gerekir. Okuma işlemlerinde doğrudan readTime belirtemezsiniz. Daha fazla bilgi için İşlemler ve toplu yazmalar başlıklı makaleyi inceleyin.

  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

PITR okumaları, get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery ve partitionQuery olan tüm Cloud Firestore okuma yöntemlerinde desteklenir.

REST yöntemlerini kullanarak okuma işlemi gerçekleştirmek için aşağıdaki seçeneklerden birini deneyin:

  1. Okuma yöntemi isteğinizde, readTime değerini readOptions yönteminde desteklenen bir PITR zaman damgası olarak iletin. PITR zaman damgası, son bir saat içinde mikrosaniye hassasiyetinde bir zaman damgası veya son bir saatten sonraki bir tam dakikalık zaman damgası olabilir ancak earliestVersionTime'ten önce olamaz.

  2. Birden fazla PITR okuması için readTime parametresini BeginTransaction yöntemiyle birlikte bir ReadOnly işlemi kapsamında kullanın.

Apache Beam

Dataflow ile Cloud Firestore veritabanında büyük ölçekte belge okumak veya yazmak için Cloud FirestoreIO Apache Beam bağlayıcısını kullanın.

PITR okumaları, Cloud FirestoreIO bağlayıcısının aşağıdaki okuma yönteminde desteklenir. Aşağıdaki okuma yöntemleri, PITR okumaları için kullanabileceğiniz withReadTime(@Nullable Instant readTime) yöntemini destekler:

Java

Aşağıdaki kod, toplu okuma veya yazma işlemleri için örnek Dataflow ardışık düzen kodu ile kullanılabilir. Örnekte, PITR okumaları için withReadTime(@Nullable Instant readTime) yöntemi kullanılmaktadır.

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

Dataflow ardışık düzenindeki readTime örneklerinin tam listesi için GitHub deposuna göz atın.

PITR verilerini dışa ve içe aktarma

gcloud firestore export komutunu kullanarak veritabanınızı PITR verilerinden Cloud Storage'e aktarabilirsiniz. Zaman damgasının son yedi gün içinde tam dakikalık bir zaman damgası olduğu ancak earliestVersionTime tarihinden önce olmadığı PITR verilerini dışa aktarabilirsiniz. Belirtilen zaman damgasında artık veri yoksa dışa aktarma işlemi başarısız olur.

PITR dışa aktarma işlemi, tüm dokümanların dışa aktarılması ve belirli koleksiyonların dışa aktarılması da dahil olmak üzere tüm filtreleri destekler.

  1. snapshot-time parametresini istenen kurtarma zaman damgasıyla belirterek veritabanını dışa aktarın.

    gcloud

    Veritabanını paketinize aktarmak için aşağıdaki komutu çalıştırın.

    gcloud firestore export gs://[BUCKET_NAME_PATH] \
        --snapshot-time=[PITR_TIMESTAMP] \
        --collection-ids=[COLLECTION_IDS] \
        --namespace-ids=[NAMESPACE_IDS]
    

    Yer,

    • BUCKET_NAME_PATH: Dışa aktarılan dosyaların depolandığı, isteğe bağlı bir yol ön eki içeren geçerli bir Cloud Storage paketi.
    • PITR_TIMESTAMP: Dakika düzeyinde bir PITR zaman damgası (ör. 2023-05-26T10:20:00.00Z veya 2023-10-19T10:30:00.00-07:00).
    • COLLECTION_IDS: Koleksiyon kimliklerinin veya koleksiyon grubu kimliklerinin listesi (ör. 'specific collection group1','specific collection group2').
    • NAMESPACE_IDS - 'customer','orders' gibi ad alanı kimliklerinin listesi.

    PITR verilerini dışa aktarmadan önce aşağıdaki noktaları göz önünde bulundurun:

    • Zaman damgasını RFC 3339 biçiminde belirtin. Örneğin, 2023-05-26T10:20:00.00Z veya 2023-10-19T10:30:00.00-07:00.
    • Belirttiğiniz zaman damgasının son yedi gün içindeki tam dakikalık bir zaman damgası olduğundan, ancak earliestVersionTime tarihinden önce olmadığından emin olun. Belirtilen zaman damgasında artık veri yoksa hata oluşur. Belirtilen zaman son bir saat içinde olsa bile zaman damgası tam bir dakika olmalıdır.
    • Başarısız PITR dışa aktarma işlemi için ücretlendirilmezsiniz.
  2. Veritabanına aktarın.

    Dışa aktarılan veritabanınızı içe aktarmak için Tüm belgeleri içe aktarma bölümündeki adımları uygulayın. Veritabanınızda mevcut bir belge varsa bu belgenin üzerine yazılır.