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

وحدة التحكم

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

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

  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();

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 API

تتوفّر عمليات القراءة من ميزة "الاسترداد في نقطة زمنية معيّنة" في جميع طرق القراءة Cloud Firestore، وهي get وlist وbatchGet و listCollectionIds وlistDocuments و runQuery وrunAggregationQuery و partitionQuery.

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

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

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

Apache Beam

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

تتوفّر عمليات القراءة من ميزة "الاسترداد في نقطة زمنية معيّنة" في طريقة القراءة التالية لأداة ربط Cloud FirestoreIO. تتوافق طرق القراءة هذه مع طريقة withReadTime(@Nullable Instant readTime) التي يمكنك استخدامها لعمليات القراءة من ميزة "الاسترداد في نقطة زمنية معيّنة":

• ‫FirestoreV1.BatchGetDocuments
• ‫FirestoreV1.ListCollectionIds
• ‫FirestoreV1.ListDocuments
• ‫FirestoreV1.PartitionQuery

• ‫FirestoreV1.RunQuery

  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.

وحدة التحكم

لا تتيح وحدة تحكُّم 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: طابع زمني لميزة "الاسترداد في نقطة زمنية معيّنة" بتنسيق RFC 3339، بدقة تصل إلى دقيقة مثلاً: 2025-06-01T10:20:00.00Z أو 2025-06-01T10:30:00.00-07:00

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

مثال:

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.

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

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: طابع زمني لميزة "الاسترداد في نقطة زمنية معيّنة" بتنسيق 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.

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

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