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

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

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

مجوزها

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

  • Cloud Datastore Owner ( 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

قبل از شروع

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

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

PITR را فعال کنید

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

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

کنسول

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

    به پایگاه داده بروید

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

  3. در منوی پیمایش، روی Disaster Recovery کلیک کنید.

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

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

فعال کردن PITR هزینه های ذخیره سازی را به همراه خواهد داشت. برای اطلاعات بیشتر به قیمت مراجعه کنید.

برای غیرفعال کردن PITR، کادر بررسی فعال کردن بازیابی نقطه در زمان را از صفحه Disaster Recovery در کنسول Google Cloud پاک کنید.

gcloud

PITR را در حین ایجاد پایگاه داده با دستور gcloud firestore databases create به شرح زیر فعال کنید:

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

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

  • LOCATION - مکانی که می خواهید پایگاه داده خود را در آن ایجاد کنید.
  • DATABASE_ID - روی شناسه پایگاه داده یا (پیش‌فرض) تنظیم کنید.
  • TYPE - روی firestore-native تنظیم شده است.

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

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

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

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

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

کنسول

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

    به پایگاه داده بروید

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

  3. در منوی پیمایش، روی Disaster Recovery کلیک کنید.

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

    • دوره نگهداری : دوره ای که در آن Cloud Firestore تمام نسخه های داده ها را برای پایگاه داده حفظ می کند. زمانی که PITR غیرفعال است، مقدار یک ساعت و زمانی که PITR فعال است، هفت روز است.
    • Earliest version time : اولین مهر زمانی که در آن می توان نسخه های قدیمی داده ها را در پنجره PITR خواند. این مقدار به طور مداوم توسط Cloud Firestore به روز می شود و در لحظه ای که پرس و جو می شود بیات می شود. اگر از این مقدار برای بازیابی داده‌ها استفاده می‌کنید، مطمئن شوید که زمان از لحظه درخواست مقدار تا لحظه شروع بازیابی را در نظر بگیرید.
    • بازیابی نقطه در زمان : در صورت فعال بودن PITR، Enabled نشان می دهد. اگر PITR غیرفعال باشد، Disabled مشاهده خواهید کرد.

gcloud

دستور توصیف پایگاه داده gcloud firestore را به صورت زیر اجرا کنید:

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 فعال است، هفت روز باشد.

داده های PITR را بخوانید

می‌توانید داده‌های PITR را با استفاده از کتابخانه‌های سرویس گیرنده، روش‌های REST API یا رابط FirestoreIO Apache Beam بخوانید.

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

جاوا

برای خواندن داده های PITR باید از تراکنش ReadOnly استفاده کنید. شما نمی توانید به طور مستقیم readTime در خواندن ها مشخص کنید. برای اطلاعات بیشتر به تراکنش‌ها و نوشته‌های دسته‌ای مراجعه کنید. 

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

گره

برای خواندن داده های PITR باید از تراکنش ReadOnly استفاده کنید. شما نمی توانید به طور مستقیم readTime در خواندن ها مشخص کنید. برای اطلاعات بیشتر به تراکنش‌ها و نوشته‌های دسته‌ای مراجعه کنید. 

  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 استفاده کنید.

پرتو آپاچی

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

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

جاوا

کد زیر را می توان با مثال کد خط لوله Dataflow برای عملیات خواندن یا نوشتن انبوه استفاده کرد. مثال از روش withReadTime(@Nullable Instant readTime) برای خواندن 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())
  ...

برای لیست کاملی از نمونه های readTime در خط لوله Dataflow، به مخزن Github مراجعه کنید.

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

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

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

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

    gcloud

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

    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. وارد کردن به پایگاه داده

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