استخدام ميزة الاسترداد في الوقت المناسب (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 لقاعدة بياناتك:

وحدة التحكم

  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة قواعد البيانات.

    الانتقال إلى قواعد البيانات

  2. اختَر قاعدة البيانات المطلوبة من قائمة قواعد البيانات.

  3. في قائمة التنقّل، انقر على استرداد البيانات في حالات الكوارث.

  4. انقر على تعديل لتعديل الإعدادات.

  5. ضَع علامة في مربّع الاختيار تفعيل ميزة "استرداد البيانات في نقطة زمنية معيّنة"، ثم انقر على حفظ.

سيؤدي تفعيل ميزة PITR إلى تحمُّل تكاليف التخزين. اطّلِع على الأسعار للحصول على مزيد من المعلومات.

لإيقاف ميزة "استرداد نقطة في الوقت"، أزِل العلامة من مربّع الاختيار تفعيل استرداد نقطة في الوقت من صفحة "استرداد الكوارث" في "وحدة تحكّم 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. في قائمة التنقّل، انقر على استرداد البيانات في حالات الكوارث.

  4. في قسم الإعدادات، دوِّن فترة الاحتفاظ بالبيانات ووقت أقدم إصدار.

    • فترة الاحتفاظ بالبيانات: هي الفترة التي تحتفظ فيها Cloud Firestore بجميع إصدارات البيانات في قاعدة البيانات. تكون القيمة ساعة واحدة عند إيقاف ميزة PITR وتفعيلها لمدة سبعة أيام.
    • وقت أقدم إصدار: هو الطابع الزمني الأقدم الذي يمكن فيه قراءة الإصدارات الأقدم من البيانات في نافذة PITR. يتم تعديل هذه القيمة باستمرار من قِبل Cloud Firestore وتصبح قديمة في اللحظة التي يتم فيها طلبها. إذا كنت تستخدم هذه القيمة لاسترداد البيانات، احرص على احتساب الوقت من اللحظة التي يتم فيها طلب القيمة إلى اللحظة التي تبدأ فيها عملية الاسترداد.
    • استرداد البيانات في نقطة زمنية معيّنة: يعرض 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: تعرِض POINT_IN_TIME_RECOVERY_ENABLED، إذا كانت ميزة "استرداد معلومات المستخدمين عند إيقاف الخدمة" مفعّلة. في حال إيقاف ميزة PITR، سيظهر لك إما POINT_IN_TIME_RECOVERY_DISABLED أو قد لا يظهر الحقل pointInTimeRecoveryEnablement.
  • ‫versionRetentionPeriod: الفترة الزمنية التي يتم الاحتفاظ ببيانات PITR خلالها بالمللي ثانية يمكن أن تكون القيمة ساعة واحدة عندما تكون ميزة PITR غير مفعّلة أو سبعة أيام إذا كانت مفعّلة.

قراءة بيانات PITR

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

مكتبات العملاء

جافا

يجب استخدام معاملة ReadOnly لقراءة بيانات PITR. لا يمكنك تحديد 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();

العقدة

يجب استخدام معاملة ReadOnly لقراءة بيانات PITR. لا يمكنك تحديد 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

تتوفّر عمليات القراءة في 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:

جافا

يمكن استخدام الرمز البرمجي التالي مع مثال على رمز مسار بيانات 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

يمكنك تصدير قاعدة بياناتك إلى 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. استيرادها إلى قاعدة بيانات

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