استخدام ميزة الاسترداد في الوقت المناسب (PITR)

توضّح هذه الصفحة كيفية استخدام ميزة "استرداد نقطة في الوقت" (PITR) للاحتفاظ بالبيانات واستردادها في Cloud Firestore.

لفهم مفاهيم استرداد نقطة في الوقت، راجِع مقالة استرداد نقطة في الوقت.

الأذونات

للحصول على الأذونات التي تحتاجها لإدارة إعدادات 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 عند إنشاء قاعدة بيانات، عليك استخدام الأمر gcloud firestore databases create. لا يمكن تفعيل ميزة PITR أثناء إنشاء قاعدة بيانات باستخدام Google Cloud Console.
• يبدأ Cloud Firestore في الاحتفاظ بالإصدارات من هذه النقطة فصاعدًا بعد تفعيل ميزة "استرداد نقطة في الوقت".
• لا يمكنك قراءة بيانات PITR في نافذة PITR بعد إيقاف ميزة PITR.
• في حال إعادة تفعيل ميزة "استرداد نقطة في الوقت" مباشرةً بعد إيقافها، لن تعود بيانات "استرداد نقطة في الوقت" السابقة متوفرة. سيتم حذف أي بيانات PITR تم إنشاؤها قبل إيقاف ميزة PITR بعد تاريخ انتهاء صلاحيتها.
• إذا حذفت البيانات عن طريق الخطأ في آخر ساعة وكانت ميزة "استرداد نقطة في الوقت" غير مفعَّلة، يمكنك استعادة بياناتك من خلال تفعيل ميزة "استرداد نقطة في الوقت" في غضون ساعة واحدة من الحذف.
• تؤدي أي عملية قراءة يتم إجراؤها على بيانات PITR المنتهية الصلاحية إلى تعذّر إكمالها.

تفعيل ميزة PITR

قبل استخدام ميزة PITR، عليك تفعيل الفوترة لمشروعك على Google Cloud. لا يمكن استخدام وظيفة PITR إلا في مشاريع Google Cloud التي تم تفعيل الفوترة فيها.

لتفعيل ميزة PITR لقاعدة بياناتك:

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

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --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

يمكنك قراءة بيانات PITR باستخدام مكتبات العملاء أو طرق REST API أو موصّل FirestoreIO Apache Beam.

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

التصدير والاستيراد من بيانات PITR

يمكنك تصدير قاعدة بياناتك إلى Cloud Storage من بيانات PITR باستخدام الأمر gcloud firestore export. يمكنك تصدير بيانات 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. استيرادها إلى قاعدة بيانات

   اتّبِع الخطوات الواردة في مقالة استيراد كل المستندات لاستيراد قاعدة بياناتك المصدَّرة. إذا كان هناك أي مستند متوفّر في قاعدة بياناتك، سيتم استبداله.