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

وحدة التحكم

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

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

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

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

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

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

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

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

gcloud

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

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

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

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

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

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

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

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

وحدة التحكم

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

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

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

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

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

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

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

  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

تتوفّر عمليات قراءة PITR في جميع طرق قراءة 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.

تتوفّر عمليات قراءة PITR في طريقة القراءة التالية لموصّل 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: طابع زمني لعملية PITR بتنسيق 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: استخدام تشفير CMEK حدِّد رقم تعريف مفتاح في الوسيطة --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: طابع زمني لعملية PITR بتنسيق 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: استخدام تشفير CMEK حدِّد رقم تعريف مفتاح في الوسيطة --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