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

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

لفهم مفاهيم PITR، يُرجى الاطّلاع على الاسترداد في الوقت المناسب.

الأذونات

للحصول على الأذونات اللازمة لإدارة إعدادات PITR، اطلب من المشرف منحك أدوار "إدارة الهوية وإمكانية الوصول" التالية في المشروع الذي تريد تفعيل 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

قبل البدء

يُرجى مراعاة النقاط التالية قبل بدء استخدام 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، انتقِل إلى صفحة قواعد البيانات.

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

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

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

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

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

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

لإيقاف 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 - تم ضبطه على أنّه أصلي في متجر النار.

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

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

استبدل القيم كما يلي:

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

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

وحدة التحكم

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

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

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

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

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

    • فترة الاحتفاظ بالبيانات: الفترة التي يحتفظ فيها "Cloud Firestore" جميع إصدارات البيانات الخاصة بقاعدة البيانات. القيمة هي ساعة واحدة عندما يكون PITR وسبعة أيام عندما يتم تمكين PITR.
    • أقرب وقت للإصدار: أقدم طابع زمني يتم فيه عرض الإصدارات الأقدم من يمكن قراءة البيانات في نافذة PITR. يتم تعديل هذه القيمة باستمرار. بواسطة Cloud Firestore ويصبح قديمة عند الاستعلام عنه. إذا كنت تستخدم هذه القيمة لاسترداد البيانات، فتأكد من حساب الوقت من اللحظة التي يتم الاستعلام فيها عن القيمة عن اللحظة التي تبدأ فيها الاسترداد.
    • الاسترداد في الوقت المناسب: يعرض هذا المقياس Enabled، في حال كان PITR. مفعّلة. إذا تم إيقاف PITR، سترى Disabled

gcloud

شغِّل الأمر gcloud firestoreDatabases descriptions (وصف قواعد بيانات 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/(default)
    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. مفعّلة. في حال إيقاف PITR، ستظهر POINT_IN_TIME_RECOVERY_DISABLED أو pointInTimeRecoveryEnablement قد لا يتم عرضه.
  • versionRetentionPeriod - الفترة الزمنية التي يتم خلالها الاحتفاظ ببيانات PITR بالمللي ثانية. يمكن أن تكون القيمة ساعة واحدة عندما يكون 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، listCollectionId، listDocuments runQuery وrunAggregationQuery و partitionQuery.

لإجراء قراءة باستخدام طرق REST، جرِّب أحد الخيارات التالية:

  1. في طلب طريقة القراءة، اضبط القيمة readTime كطابع زمني PITR متوافق في الطريقة readOptions. يمكن أن يكون الطابع الزمني لـ PITR إما طابعًا زمنيًا للدقة بالميكرو ثانية خلال الساعة الماضية أو طابعًا زمنيًا لدقيقة كاملة بعد الساعة الماضية، ولكن ليس قبل earliestVersionTime.

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

شعاع Apache

يمكنك استخدام موصل Cloud FirestoreIO 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

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

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