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

این صفحه نحوه استفاده از بازیابی نقطه‌ای در زمان (PITR) را برای حفظ و بازیابی داده‌ها در Cloud Firestore با سازگاری MongoDB شرح می‌دهد.

برای درک مفاهیم PITR، به بازیابی در نقطه زمانی مراجعه کنید.

مجوزها

برای دریافت مجوزهای لازم برای مدیریت تنظیمات PITR، از مدیر سیستم خود بخواهید که نقش‌های IAM زیر را در پروژه‌ای که می‌خواهید PITR در آن فعال شود، به شما اعطا کند:

• مالک انبار داده ابری ( roles/datastore.owner )

برای نقش‌های سفارشی، مطمئن شوید که مجوزهای زیر اعطا شده است:

• برای فعال کردن PITR هنگام ایجاد پایگاه داده: datastore.databases.create
• برای به‌روزرسانی تنظیمات PITR در پایگاه داده موجود: datastore.databases.update ، datastore.databases.list
• برای انجام خواندن از داده‌های PITR: datastore.databases.get ، datastore.entities.get ، datastore.entities.list
• برای خروجی گرفتن از داده‌های PITR: datastore.databases.export
• برای وارد کردن داده‌های PITR: datastore.databases.import
• برای کپی کردن یک پایگاه داده: datastore.databases.clone

قبل از اینکه شروع کنی

قبل از شروع استفاده از PITR به نکات زیر توجه کنید:

• شما نمی‌توانید بلافاصله پس از فعال کردن PITR، خواندن مطالب هفت روز گذشته را شروع کنید.
• اگر می‌خواهید PITR را هنگام ایجاد پایگاه داده فعال کنید، باید از دستور gcloud firestore databases create استفاده کنید. فعال کردن PITR هنگام ایجاد پایگاه داده با استفاده از کنسول Google Cloud پشتیبانی نمی‌شود.
• Cloud Firestore با سازگاری MongoDB پس از فعال کردن PITR، شروع به حفظ نسخه‌ها از نقطه‌ای به بعد می‌کند.
• پس از غیرفعال کردن PITR، نمی‌توانید داده‌های PITR را در پنجره PITR بخوانید.
• اگر بلافاصله پس از غیرفعال کردن PITR، آن را دوباره فعال کنید، داده‌های PITR قبلی دیگر در دسترس نخواهند بود. هرگونه داده PITR که قبل از غیرفعال کردن PITR ایجاد شده باشد، پس از تاریخ انقضای PITR حذف خواهد شد.
• اگر در یک ساعت گذشته به‌طور تصادفی داده‌ها را حذف کرده‌اید و PITR غیرفعال است، می‌توانید با فعال کردن PITR ظرف یک ساعت پس از حذف، داده‌های خود را بازیابی کنید.
• هرگونه عملیات خواندن روی داده‌های منقضی‌شده‌ی PITR با شکست مواجه می‌شود.

فعال کردن PITR

قبل از استفاده از PITR، صورتحساب را برای پروژه Google Cloud خود فعال کنید . فقط پروژه‌های Google Cloud که صورتحساب آنها فعال است می‌توانند از قابلیت PITR استفاده کنند.

برای فعال کردن PITR برای پایگاه داده خود:

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

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

دوره نگهداری و اولین زمان نسخه را دریافت کنید

gcloud firestore databases describe --database=DATABASE_ID

    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

خواندن داده‌های 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)}
);

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

کلون از یک پایگاه داده

شما می‌توانید یک پایگاه داده موجود را در یک زمان مشخص در یک پایگاه داده جدید کلون کنید:

• پایگاه داده کلون شده، یک پایگاه داده جدید است که در همان مکان پایگاه داده منبع ایجاد خواهد شد.

  برای ایجاد یک کلون، Cloud Firestore از داده‌های بازیابی نقطه‌ای (PITR) پایگاه داده منبع استفاده می‌کند. پایگاه داده کلون شده شامل تمام داده‌ها و شاخص‌ها است.

• به طور پیش‌فرض، پایگاه داده کلون شده به همان روش پایگاه داده منبع، با استفاده از رمزگذاری پیش‌فرض گوگل یا رمزگذاری CMEK رمزگذاری می‌شود. می‌توانید نوع رمزگذاری متفاوتی را مشخص کنید یا از کلید متفاوتی برای رمزگذاری CMEK استفاده کنید.

• مهر زمانی دارای جزئیات یک دقیقه‌ای است و یک نقطه زمانی در گذشته، در دوره تعریف شده توسط پنجره PITR را مشخص می‌کند:

  • اگر PITR برای پایگاه داده شما فعال باشد، می‌توانید هر دقیقه‌ای در ۷ روز گذشته (یا کمتر اگر PITR کمتر از ۷ روز پیش فعال شده باشد) را انتخاب کنید.
  • اگر PITR فعال نباشد، می‌توانید هر دقیقه‌ای از یک ساعت گذشته را انتخاب کنید.
  • می‌توانید اولین مهر زمانی که می‌توانید انتخاب کنید را در توضیحات پایگاه داده خود بررسی کنید.

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

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

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

صادرات و واردات از داده‌های PITR

شما می‌توانید با استفاده از دستور gcloud firestore export ، پایگاه داده خود را از داده‌های PITR به Cloud Storage صادر کنید. می‌توانید داده‌های PITR را که در آن مهر زمانی یک دقیقه کامل در هفت روز گذشته است، اما نه زودتر از earliestVersionTime صادر کنید. اگر داده‌ها دیگر در مهر زمانی مشخص شده وجود نداشته باشند، عملیات صادرات با شکست مواجه می‌شود.

عملیات خروجی PITR از همه فیلترها، از جمله خروجی گرفتن از همه اسناد و خروجی گرفتن از مجموعه‌های خاص، پشتیبانی می‌کند.

1. پایگاه داده را اکسپورت کنید و پارامتر snapshot-time را به مهر زمانی بازیابی انتخاب شده اختصاص دهید.

   جی‌کلاود

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

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

   کجا،

   • BUCKET_NAME_PATH - یک باکت معتبر Cloud Storage با پیشوند مسیر اختیاری که فایل‌های خروجی در آن ذخیره می‌شوند.
   • PITR_TIMESTAMP - یک مهر زمانی PITR بر اساس جزئیات دقیقه، برای مثال، 2023-05-26T10:20:00.00Z یا 2023-10-19T10:30:00.00-07:00 .
   • COLLECTION_IDS - فهرستی از شناسه‌های مجموعه یا شناسه‌های گروه‌های مجموعه، برای مثال 'specific-collection-group1','specific-collection-group2' .
   • NAMESPACE_IDS - فهرستی از شناسه‌های فضای نام، برای مثال - 'customer','orders' .

   قبل از خروجی گرفتن از داده‌های PITR به نکات زیر توجه کنید:

   • مهر زمانی را با فرمت RFC 3339 مشخص کنید. برای مثال، 2023-05-26T10:20:00.00Z یا 2023-10-19T10:30:00.00-07:00 .
   • مطمئن شوید که برچسب زمانی که مشخص می‌کنید، یک دقیقه کامل در هفت روز گذشته باشد، اما نه زودتر از earliestVersionTime . اگر داده‌ها دیگر در برچسب زمانی مشخص شده وجود نداشته باشند، خطایی ایجاد می‌شود. برچسب زمانی باید یک دقیقه کامل باشد، حتی اگر زمان مشخص شده در یک ساعت گذشته باشد.
   • برای صادرات ناموفق PITR هزینه‌ای از شما دریافت نمی‌شود.

2. به یک پایگاه داده وارد کنید.

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