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

ملائم لإصدار Cloud Firestore Standard وإصدار Cloud Firestore Enterprise.

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

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

الأذونات

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

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

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

  • لتفعيل ميزة "الاستعادة إلى نقطة زمنية" عند إنشاء قاعدة بيانات، اتّبِع الخطوات التالية: 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
  • لاستنساخ قاعدة البيانات: datastore.databases.clone

قبل البدء

لاحظ النقاط التالية قبل البدء في استخدام PITR:

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

قراءة بيانات الاستعادة إلى نقطة زمنية

يمكنك قراءة بيانات الاسترداد في نقطة زمنية باستخدام مكتبات البرامج أو طرق 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 في جميع طرق القراءة المتوافقة مع MongoDB في 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 المتوافق مع MongoDB Apache Beam لقراءة المستندات أو كتابتها في قاعدة بيانات Cloud Firestore المتوافقة مع MongoDB على نطاق واسع باستخدام Dataflow.

تتوفّر عمليات القراءة باستخدام ميزة PITR في طريقة القراءة التالية الخاصة بموصل Cloud Firestore المتوافق مع MongoDB. تتيح طرق القراءة هذه استخدام طريقة 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 Firestore بيانات الاسترداد في نقطة زمنية محددة (PITR) لقاعدة البيانات المصدر. تتضمّن قاعدة البيانات المستنسَخة جميع البيانات والفهارس.

  • بشكلٍ تلقائي، سيتم تشفير قاعدة البيانات المستنسَخة بالطريقة نفسها التي تم بها تشفير قاعدة البيانات المصدر، وذلك باستخدام التشفير التلقائي من Google أو تشفير CMEK. يمكنك تحديد نوع تشفير مختلف أو استخدام مفتاح مختلف لتشفير CMEK.

  • يتم تحديد الطابع الزمني بدقة تصل إلى دقيقة واحدة، ويشير إلى نقطة زمنية في الماضي، ضمن الفترة المحدّدة من خلال فترة الاسترداد في نقطة زمنية:

    • إذا كانت ميزة &quot;الاسترداد إلى نقطة زمنية&quot; مفعّلة لقاعدة البيانات، يمكنك اختيار أي دقيقة في آخر 7 أيام (أو أقل إذا تم تفعيل الميزة قبل أقل من 7 أيام).
    • إذا لم تكن ميزة "استعادة البيانات إلى نقطة زمنية" مفعّلة، يمكنك اختيار أي دقيقة في الساعة الماضية.
    • يمكنك الاطّلاع على الطابع الزمني الأقدم الذي يمكنك اختياره في وصف قاعدة البيانات.

وحدة التحكم

لا تتيح وحدة تحكّم Firebase استنساخ قواعد البيانات. يمكنك استخدام تعليمات Google Cloud CLI لاستنساخ قواعد البيانات.

gcloud

استخدِم الأمر gcloud firestore databases clone لاستنساخ قاعدة بيانات:

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

استبدِل ما يلي:

  • SOURCE_DATABASE: اسم قاعدة البيانات الحالية التي تريد استنساخها يستخدم الاسم التنسيق projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

  • PITR_TIMESTAMP: a طابع زمني لاستعادة البيانات في نقطة زمنية محددة بالتنسيق RFC 3339، بدقة تصل إلى دقيقة. على سبيل المثال: 2025-06-01T10:20:00.00Z أو 2025-06-01T10:30:00.00-07:00.

  • DESTINATION_DATABASE_ID: a معرّف قاعدة بيانات لقاعدة بيانات مستنسَخة جديدة. يجب ألا يكون معرّف قاعدة البيانات هذا مرتبطًا بقاعدة بيانات حالية.

مثال:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

إذا كنت تريد الربط ببعض العلامات أثناء استنساخ قاعدة بيانات، استخدِم الأمر السابق مع العلامة --tags، وهي قائمة اختيارية من أزواج العلامات KEY=VALUE للربط.

مثال:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--tags=key1=value1,key2=value2

بشكلٍ تلقائي، سيكون لقاعدة البيانات المستنسَخة إعدادات التشفير نفسها التي تتوفّر في قاعدة البيانات المصدر. لتغيير إعدادات التشفير، استخدِم وسيطة --encryption-type:

  • (تلقائي) use-source-encryption: استخدام إعدادات التشفير نفسها المستخدَمة في قاعدة البيانات المصدر
  • google-default-encryption: استخدام تشفير Google التلقائي
  • customer-managed-encryption: استخدام التشفير باستخدام "مفتاح التشفير الذي يديره العميل" حدِّد رقم تعريف مفتاح في الوسيطة --kms-key-name.

يوضّح المثال التالي كيفية ضبط تشفير CMEK لقاعدة البيانات المستنسخة:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Firebase CLI

استخدِم الأمر firebase firestore:databases:clone لاستنساخ قاعدة بيانات:

firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'

استبدِل ما يلي:

  • SOURCE_DATABASE: اسم قاعدة البيانات الحالية التي تريد استنساخها يستخدم الاسم التنسيق projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

  • DESTINATION_DATABASE: اسم قاعدة بيانات لقاعدة بيانات مستنسخة جديدة. يستخدم الاسم التنسيق projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID. يجب ألا يكون اسم قاعدة البيانات هذا مرتبطًا بقاعدة بيانات حالية.

  • PITR_TIMESTAMP: a طابع زمني لاستعادة البيانات في نقطة زمنية محددة بالتنسيق RFC 3339، بدقة تصل إلى دقيقة. على سبيل المثال: 2025-06-01T10:20:00.00Z أو 2025-06-01T10:30:00.00-07:00. في حال عدم تحديدها، ستكون اللقطة المختارة هي الوقت الحالي، مع تقريبه إلى أقرب دقيقة.

بشكلٍ تلقائي، سيكون لقاعدة البيانات المستنسَخة إعدادات التشفير نفسها التي تتوفّر في قاعدة البيانات المصدر. لتغيير إعدادات التشفير، استخدِم وسيطة --encryption-type:

  • (تلقائي) USE_SOURCE_ENCRYPTION: استخدام إعدادات التشفير نفسها المستخدَمة في قاعدة البيانات المصدر
  • GOOGLE_DEFAULT_ENCRYPTION: استخدام تشفير Google التلقائي
  • CUSTOMER_MANAGED_ENCRYPTION: استخدام التشفير باستخدام "مفتاح التشفير الذي يديره العميل" حدِّد رقم تعريف مفتاح في الوسيطة --kms-key-name.

يوضّح المثال التالي كيفية ضبط تشفير CMEK لقاعدة البيانات المستنسخة:

firebase firestore:databases:clone \
'projects/example-project/databases/(default)' \
'projects/example-project/databases/example-dest-db' \
--snapshot-time 'PITR_TIMESTAMP' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION

القيود

لا تنسخ عملية الاستنساخ App Engine بيانات البحث أو كيانات تخزين البيانات الثنائية الكبيرة من قاعدة بيانات (default). هذه البيانات صالحة فقط لقاعدة بيانات (default)، ولن تكون مفيدة إذا استنسخت من (default) إلى قاعدة بيانات لا تتوافق مع هذه البيانات، لذا يتم استبعادها من النسخ المستنسخة.

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

يمكنك تصدير قاعدة البيانات إلى Cloud Storage من بيانات PITR باستخدام الأمر gcloud firestore export. يمكنك تصدير بيانات PITR التي يكون الطابع الزمني فيها طابعًا زمنيًا لدقيقة كاملة خلال الأيام السبعة الماضية، ولكن ليس قبل earliestVersionTime. إذا لم تعُد البيانات متوفّرة في الطابع الزمني المحدّد، ستتعذّر عملية التصدير.

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

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

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