استخدام ميزة الاسترداد في الوقت المناسب (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 Platform.
  • تبدأ 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 Platform، انتقِل إلى صفحة قواعد البيانات.

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

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

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

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

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

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

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

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 Platform، انتقِل إلى صفحة قواعد البيانات.

    الانتقال إلى 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.

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

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

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

شعاع Apache

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

تتوافق قراءات PITR مع طريقة القراءة التالية لموصل Cloud FirestoreIO. تتوافق طُرق القراءة التالية مع طريقة 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.

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

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