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

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

للتعرّف على مفاهيم PITR، يمكنك الاطّلاع على الاسترداد في نقطة زمنية.

الأذونات

للحصول على الأذونات اللازمة لإدارة إعدادات PITR، اطلب من المشرف منحك أدوار إدارة الهوية والوصول (IAM) التالية في المشروع الذي تريد تفعيل PITR فيه:

  • مالك Cloud Datastore (roles/datastore.owner)

بالنسبة إلى الأدوار المخصّصة، تأكَّد من منح الأذونات التالية:

  • لتفعيل ميزة "الاستعادة إلى نقطة زمنية" عند إنشاء قاعدة بيانات، اتّبِع الخطوات التالية: datastore.databases.create
  • لتعديل إعدادات الاسترداد في نقطة زمنية على قاعدة بيانات حالية: datastore.databases.update،datastore.databases.list
  • لإجراء عمليات قراءة من بيانات الاسترداد في نقطة زمنية محددة: datastore.databases.get،datastore.entities.get،datastore.entities.list
  • لتصدير بيانات PITR، اتّبِع الخطوات التالية: datastore.databases.export
  • لاستيراد بيانات الاستعادة إلى نقطة زمنية معيّنة، اتّبِع الخطوات التالية: datastore.databases.import

قبل البدء

يُرجى ملاحظة النقاط التالية قبل البدء في استخدام ميزة "الاستعادة إلى نقطة زمنية":

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

تفعيل PITR

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

لتفعيل ميزة "الاستعادة إلى نقطة زمنية" لقاعدة البيانات، اتّبِع الخطوات التالية:

وحدة التحكم

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

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

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

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

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

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

يؤدي تفعيل ميزة "الاسترداد في نقطة زمنية" إلى تكبُّد تكاليف التخزين. يمكنك الاطّلاع على الأسعار لمزيد من المعلومات.

لإيقاف ميزة "الاسترداد في نقطة زمنية"، أزِل العلامة من مربّع الاختيار تفعيل ميزة "الاسترداد في نقطة زمنية" من صفحة "التعافي من الكوارث" في Google Cloud Console.

gcloud

فعِّل ميزة "الاسترداد في نقطة زمنية" أثناء إنشاء قاعدة البيانات باستخدام الأمرَين gcloud firestore databases create و--enable-ptir على النحو التالي:

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

استبدِل القيم على النحو التالي:

  • LOCATION: الموقع الجغرافي الذي تريد إنشاء قاعدة البيانات فيه
  • DATABASE_ID: تم ضبطه على رقم تعريف قاعدة البيانات.

يمكنك إيقاف ميزة "الاستعادة إلى نقطة زمنية" باستخدام الأمر gcloud firestore databases update على النحو التالي:

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

استبدِل القيم على النحو التالي:

  • DATABASE_ID - اضبطه على معرّف قاعدة البيانات أو (تلقائي).

الحصول على فترة الاحتفاظ بالبيانات ووقت أقدم نسخة

وحدة التحكم

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

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

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

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

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

    • فترة الاحتفاظ بالبيانات: هي الفترة التي يحتفظ فيها Cloud Firestore بجميع إصدارات البيانات لقاعدة البيانات. القيمة هي ساعة واحدة عندما تكون ميزة "استعادة البيانات إلى نقطة زمنية" غير مفعَّلة، وسبعة أيام عندما تكون مفعَّلة.
    • وقت الإصدار الأقدم: هو الطابع الزمني الأقدم الذي يمكن فيه قراءة الإصدارات الأقدم من البيانات في فترة استرداد البيانات في نقطة زمنية محددة. يتم تعديل هذه القيمة باستمرار بواسطة Cloud Firestore وتصبح قديمة في اللحظة التي يتم فيها طلبها. إذا كنت تستخدم هذه القيمة لاسترداد البيانات، احرص على احتساب الوقت من لحظة طلب القيمة إلى لحظة بدء عملية الاسترداد.
    • الاسترداد في نقطة زمنية: يعرض Enabled في حال تفعيل ميزة الاسترداد في نقطة زمنية. إذا كانت ميزة "الاستعادة إلى نقطة زمنية" غير مفعَّلة، سيظهر لك 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 باستخدام مكتبات البرامج أو طرق REST API أو موصّل FirestoreIO Apache Beam.

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

Java

يجب استخدام المعاملة 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. يمكن أن يكون الطابع الزمني لعملية الاستعادة إلى نقطة زمنية محددة طابعًا زمنيًا بدقة الميكرو ثانية خلال الساعة الماضية أو طابعًا زمنيًا لدقيقة كاملة بعد الساعة الماضية، ولكن ليس قبل earliestVersionTime.

  2. استخدِم المَعلمة readTime مع الطريقة BeginTransaction كجزء من معاملة ReadOnly لعمليات قراءة متعددة من PITR.

Apache Beam

استخدِم Cloud Firestoreموصّل IO Apache Beam لقراءة المستندات أو كتابتها في قاعدة بيانات Cloud Firestore على نطاق واسع باستخدام Dataflow.

تتوفّر عمليات القراءة في نقطة زمنية محددة في طريقة القراءة التالية الخاصة بـ Cloud Firestoreموصل الإدخال/الإخراج. تتيح طرق القراءة هذه استخدام طريقة withReadTime(@Nullable Instant readTime) التي يمكنك استخدامها لعمليات القراءة في PITR:

Java

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

تصدير البيانات واستيرادها من بيانات الاسترداد في نقطة زمنية محددة

يمكنك تصدير قاعدة البيانات إلى Cloud Storage من بيانات الاسترداد في نقطة زمنية باستخدام الأمر 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: طابع زمني لاستعادة البيانات إلى نقطة زمنية محددة بدقة الدقيقة، مثلاً 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. إذا لم تعُد البيانات متوفرة في الطابع الزمني المحدّد، سيحدث خطأ. يجب أن يكون الطابع الزمني دقيقة كاملة، حتى إذا كان الوقت المحدّد ضمن الساعة الماضية.
    • لا يتم تحصيل رسوم منك مقابل عملية تصدير غير ناجحة لاستعادة البيانات في نقطة زمنية محددة.

  2. استيراد إلى قاعدة بيانات

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