کار با بازیابی نقطه‌ای (PITR)

کنسول

1. در کنسول Google Cloud، به صفحه پایگاه‌های داده بروید.

   رفتن به پایگاه‌های داده

2. پایگاه داده موردنیاز را از فهرست پایگاه‌های داده انتخاب کنید.

3. در منو پیمایش، روی بازیابی پس‌از فاجعه کلیک کنید.

4. برای ویرایش تنظیمات، روی ویرایش کلیک کنید.

5. چارگوش انتخاب فعال کردن بازیابی نقطه‌زمانی را انتخاب کنید و سپس روی ذخیره کلیک کنید.

فعال کردن PITR هزینه فضای ذخیره‌سازی به‌همراه دارد. برای اطلاعات بیشتر، قیمت‌گذاری را ببینید.

برای غیرفعال کردن PITR، چارگوش انتخاب فعال کردن بازیابی نقطه‌زمانی را در صفحه «بازیابی پس‌از فاجعه» در کنسول Google Cloud پاک کنید.

gcloud

بااستفاده از gcloud firestore databases create و فرمان --enable-ptir، بازیابی نقطه‌زمانی را درطول ایجاد پایگاه داده فعال کنید:

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --type=firestore-native\
  --enable-pitr

مقادیر را به‌صورت زیر جایگزین کنید:

• ‫LOCATION - مکانی که می‌خواهید پایگاه داده‌تان را در آن ایجاد کنید.
• DATABASE_ID - روی شناسه پایگاه داده تنظیم شده است.

می‌توانید PITR را بااستفاده از فرمان gcloud firestore databases update به‌صورت زیر غیرفعال کنید:

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

مقادیر را به‌صورت زیر جایگزین کنید:

• ‫DATABASE_ID - روی شناسه پایگاه داده یا (پیش‌فرض) تنظیم شده است.

کنسول

1. در کنسول Google Cloud، به صفحه پایگاه‌های داده بروید.

   رفتن به پایگاه‌های داده

2. پایگاه داده موردنیاز را از فهرست پایگاه‌های داده انتخاب کنید.

3. در منو پیمایش، روی بازیابی پس‌از فاجعه کلیک کنید.

4. در بخش تنظیمات، به دوره نگهداری و زمان قدیمی‌ترین نسخه توجه کنید.

   • دوره نگهداری: دوره‌ای که Cloud Firestore همه نسخه‌های داده را برای پایگاه داده نگهداری می‌کند. وقتی PITR غیرفعال باشد، این مقدار یک ساعت است و وقتی PITR فعال باشد، این مقدار هفت روز است.
   • زمان قدیمی‌ترین نسخه: قدیمی‌ترین مُهر زمانی که در آن نسخه‌های قدیمی‌تر داده‌ها را می‌توان در پنجره «بازیابی نقطه‌زمانی» خواند. این مقدار به‌طور مداوم توسط Cloud Firestore به‌روز می‌شود و به‌محض اینکه مورد پُرسمان قرار می‌گیرد، قدیمی می‌شود. اگر از این مقدار برای بازیابی داده‌ها استفاده می‌کنید، حتماً زمان بین لحظه پرسمان مقدار تا لحظه شروع بازیابی را درنظر بگیرید.
   • بازیابی نقطه زمانی: اگر PITR فعال باشد، Enabled را نشان می‌دهد. اگر PITR غیرفعال باشد، Disabled را خواهید دید.

gcloud

فرمان gcloud firestore databases describe را به‌صورت زیر اجرا کنید:

gcloud firestore databases describe --database=DATABASE_ID

DATABASE_ID را با شناسه پایگاه داده یا '(default)' جایگزین کنید.

خروجی این است:

    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

کجا،

• ‫earliestVersionTime: مُهر زمان قدیمی‌ترین داده‌های PITR ذخیره‌شده.
• pointInTimeRecoveryEnablement: اگر PITR فعال باشد، POINT_IN_TIME_RECOVERY_ENABLED را نشان می‌دهد. اگر PITR غیرفعال باشد، یا POINT_IN_TIME_RECOVERY_DISABLED را می‌بینید یا ممکن است فیلد pointInTimeRecoveryEnablement نمایش داده نشود.
• ‫versionRetentionPeriod: دوره زمانی که داده‌های PITR برحسب میلی‌ثانیه حفظ می‌شوند. اگر PITR غیرفعال باشد، این مقدار می‌تواند یک ساعت باشد و اگر PITR فعال باشد، این مقدار می‌تواند هفت روز باشد.

کتابخانه‌های مشتری

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

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 در همه روش‌های خواندن Cloud Firestore پشتیبانی می‌شود، که عبارتند از: get،‏ list،‏ batchGet، listCollectionIds،‏ listDocuments، runQuery،‏ runAggregationQuery، و partitionQuery.

برای انجام خواندن بااستفاده از روش‌های REST، یکی از گزینه‌های زیر را امتحان کنید:

1. در درخواست روش خواندن، مقدار readTime را به‌عنوان مُهر زمان PITR پشتیبانی‌شده در روش readOptions ارسال کنید. مُهر زمان PITR می‌تواند مُهر زمان با دقت میکروثانیه در ساعت گذشته یا مُهر زمان دقیقه کامل فراتر از ساعت گذشته باشد، اما نباید زودتر از earliestVersionTime باشد.

2. از پارامتر readTime همراه با روش BeginTransaction به‌عنوان بخشی از تراکنش ReadOnly برای چندین خواندن PITR استفاده کنید.

Apache Beam

از رابط Cloud FirestoreIO Apache Beam برای خواندن یا نوشتن اسناد در پایگاه داده Cloud Firestore در مقیاس بزرگ با Dataflow استفاده کنید.

خواندن‌های PITR در روش خواندن زیر از رابط Cloud FirestoreIO پشتیبانی می‌شود. این روش‌های خواندن از روش withReadTime(@Nullable Instant readTime) پشتیبانی می‌کنند که می‌توانید برای خواندن‌های PITR استفاده کنید:

• FirestoreV1.BatchGetDocuments
• FirestoreV1.ListCollectionIds
• FirestoreV1.ListDocuments
• FirestoreV1.PartitionQuery

• FirestoreV1.RunQuery

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

برای فهرست کامل نمونه‌های readTime در خط لوله Dataflow، مخزن GitHub را ببینید.

کنسول

کنسول Firebase از شبیه‌سازی پایگاه داده پشتیبانی نمی‌کند. می‌توانید از دستورالعمل‌های Google Cloud CLI برای شبیه‌سازی پایگاه‌های داده استفاده کنید.

gcloud

برای شبیه‌سازی پایگاه داده، از فرمان gcloud firestore databases clone استفاده کنید:

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

موارد زیر را جایگزین کنید:

• ‫SOURCE_DATABASE: نام پایگاه داده موجودی که می‌خواهید کلون کنید. نام از قالب projects/PROJECT_ID/databases/SOURCE_DATABASE_ID استفاده می‌کند.

• PITR_TIMESTAMP: مُهر زمان «بازیابی نقطه‌زمانی» در قالب RFC 3339، با جزئیات دقیقه‌ای. برای مثال: 2025-06-01T10:20:00.00Z یا 2025-06-01T10:30:00.00-07:00.

• DESTINATION_DATABASE_ID: شناسه پایگاه داده برای پایگاه داده کلون‌شده جدید. این شناسه پایگاه داده نباید با پایگاه داده موجودی مرتبط باشد.

مثال:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

اگر می‌خواهید هنگام شبیه‌سازی پایگاه داده به برخی‌از برچسب‌ها متصل شوید، از فرمان قبلی با پرچم --tags استفاده کنید که فهرست اختیاری جفت‌های «کلید=مقدار» برچسب‌ها برای اتصال است.

مثال:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--tags=key1=value1,key2=value2

به‌طور پیش‌فرض، پایگاه داده کلون‌شده همان پیکربندی رمزگذاری پایگاه داده منبع را خواهد داشت. برای تغییر پیکربندی رمزگذاری، از آرگومان --encryption-type استفاده کنید:

• (پیش‌فرض) use-source-encryption: از همان پیکربندی رمزگذاری پایگاه داده منبع استفاده کنید.
• google-default-encryption: از رمزگذاری پیش‌فرض Google استفاده کنید.
• ‫customer-managed-encryption: از رمزگذاری CMEK استفاده کنید. شناسه کلید را در آرگومان --kms-key-name مشخص کنید.

مثال زیر نحوه پیکربندی رمزگذاری CMEK را برای پایگاه داده شبیه‌سازی‌شده نشان می‌دهد:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

واسط خط فرمان Firebase

برای شبیه‌سازی پایگاه داده، از فرمان firebase firestore:databases:clone استفاده کنید:

firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'

موارد زیر را جایگزین کنید:

• ‫SOURCE_DATABASE: نام پایگاه داده موجودی که می‌خواهید کلون کنید. نام از قالب projects/PROJECT_ID/databases/SOURCE_DATABASE_ID استفاده می‌کند.

• DESTINATION_DATABASE: نام پایگاه داده برای پایگاه داده کلون‌شده جدید. نام از قالب projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID استفاده می‌کند. این نام پایگاه داده نباید با پایگاه داده موجودی مرتبط باشد.

• PITR_TIMESTAMP: مُهر زمان «بازیابی نقطه‌زمانی» در قالب RFC 3339، با جزئیات دقیقه‌ای. برای مثال: 2025-06-01T10:20:00.00Z یا 2025-06-01T10:30:00.00-07:00. اگر مشخص نشده باشد، عکس آنی انتخاب‌شده زمان فعلی خواهد بود که به دقیقه گرد شده است.

به‌طور پیش‌فرض، پایگاه داده کلون‌شده همان پیکربندی رمزگذاری پایگاه داده منبع را خواهد داشت. برای تغییر پیکربندی رمزگذاری، از آرگومان --encryption-type استفاده کنید:

• (پیش‌فرض) USE_SOURCE_ENCRYPTION: از همان پیکربندی رمزگذاری پایگاه داده منبع استفاده کنید.
• GOOGLE_DEFAULT_ENCRYPTION: از رمزگذاری پیش‌فرض Google استفاده کنید.
• ‫CUSTOMER_MANAGED_ENCRYPTION: از رمزگذاری CMEK استفاده کنید. شناسه کلید را در آرگومان --kms-key-name مشخص کنید.

مثال زیر نحوه پیکربندی رمزگذاری CMEK را برای پایگاه داده شبیه‌سازی‌شده نشان می‌دهد:

firebase firestore:databases:clone \
'projects/example-project/databases/(default)' \
'projects/example-project/databases/example-dest-db' \
--snapshot-time 'PITR_TIMESTAMP' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION