原生模式下的 Cloud Firestore 企业版现已推出！了解详情。

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

الأذونات

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

مالك Cloud Datastore‏ (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
لاستنساخ قاعدة بيانات: datastore.databases.clone

قبل البدء

يُرجى ملاحظة النقاط التالية قبل البدء في استخدام ميزة "الاستعادة في نقطة زمنية محدّدة":

لا يمكنك بدء القراءة من سبعة أيام في الماضي فورًا بعد تفعيل ميزة "الاستعادة في نقطة زمنية محدّدة".
إذا أردت تفعيل ميزة PITR عند إنشاء قاعدة بيانات، عليك استخدام الأمر gcloud firestore databases create. لا يمكن تفعيل ميزة PITR أثناء إنشاء قاعدة بيانات باستخدام وحدة تحكّم Google Cloud.
يبدأ Cloud Firestore في الاحتفاظ بالإصدارات من النقطة التالية بعد تفعيل ميزة "الاستعادة في نقطة زمنية محدّدة".
لا يمكنك قراءة بيانات PITR في نافذة PITR بعد إيقاف PITR.
إذا أعدت تفعيل ميزة "الاستعادة في نقطة زمنية محدّدة" بعد إيقافها مباشرةً، لن تكون بيانات الميزة السابقة متاحة. سيتم حذف أي بيانات PITR تم إنشاؤها قبل إيقاف PITR بعد تاريخ انتهاء صلاحية PITR.
إذا حذفت بيانات عن طريق الخطأ في آخر ساعة وتم إيقاف ميزة "الاستعادة في نقطة زمنية محدّدة"، يمكنك استعادة بياناتك من خلال تفعيل الميزة في غضون ساعة واحدة من الحذف.
وتتعذّر أي عملية قراءة يتم إجراؤها على بيانات PITR منتهية الصلاحية.

تفعيل ميزة "الاستعادة في نقطة زمنية محدّدة"

قبل استخدام ميزة "الاستعادة في نقطة زمنية محدّدة"، عليك تفعيل الفوترة لمشروعك على Google Cloud. يمكن فقط لمشاريع على السحابة الإلكترونية من Google Cloud التي تم تفعيل الفوترة فيها استخدام وظيفة PITR.

لتفعيل ميزة PITR لقاعدة بياناتك، اتّبِع الخطوات التالية:

وحدة التحكم

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

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

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

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

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: يتم ضبطه على معرّف قاعدة البيانات أو (تلقائي).

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

وحدة التحكم

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

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

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

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

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

Apache Beam

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

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

Java

يمكن استخدام الرمز التالي مع مثال على رمز مسار البيانات لعمليات القراءة أو الكتابة المجمّعة. يستخدم المثال طريقة 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.
يتم تحديد الطابع الزمني بدقة دقيقة واحدة، ويشير إلى نقطة زمنية في الماضي، في الفترة التي تحدّدها نافذة الاستعادة في نقطة زمنية معيّنة:
- إذا كانت ميزة PITR مفعَّلة لقاعدة بياناتك، يمكنك اختيار أي دقيقة في آخر 7 أيام (أو أقل إذا تم تفعيل ميزة PITR قبل أقل من 7 أيام).
- إذا لم تكن ميزة PITR مفعَّلة، يمكنك اختيار أي دقيقة في الساعة السابقة.
- يمكنك الاطّلاع على أقدم طابع زمني يمكنك اختياره في وصف قاعدة بياناتك.

وحدة التحكم

لا تتيح وحدة تحكُّم 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 في حال عدم تحديد هذه القيمة، ستكون اللقطة المحدّدة هي الوقت الحالي، مع التقريب إلى أقرب دقيقة.

(تلقائي) 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

القيود

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

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

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

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

صدِّر قاعدة البيانات مع تحديد المَعلمة 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:
- فعِّل ميزة "الاستعادة في نقطة زمنية محدّدة" في قاعدة بياناتك. في حال إيقاف ميزة "الاستعادة في نقطة زمنية محدّدة"، سيتعذّر التصدير في طابع زمني للّقطة، حتى للطوابع الزمنية خلال الساعة الماضية بعد earliestVersionTime. تُرجع عملية التصدير الخطأ Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp.
- حدِّد الطابع الزمني بالتنسيق RFC 3339. على سبيل المثال، 2023-05-26T10:20:00.00Z أو 2023-10-19T10:30:00.00-07:00.
- تأكَّد من أنّ الطابع الزمني الذي تحدّده هو طابع زمني بالدقيقة الكاملة خلال آخر سبعة أيام، ولكن ليس قبل earliestVersionTime. إذا لم تعُد البيانات متوفّرة في الطابع الزمني المحدّد، سيتم إنشاء خطأ. يجب أن يكون الطابع الزمني دقيقة كاملة، حتى إذا كان الوقت المحدّد ضمن الساعة الماضية.
- لا يتم تحصيل رسوم منك مقابل عملية تصدير غير ناجحة باستخدام ميزة PITR.
استيراد البيانات إلى قاعدة بيانات

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

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

الأذونات

قبل البدء

تفعيل ميزة "الاستعادة في نقطة زمنية محدّدة"

وحدة التحكم

gcloud

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

وحدة التحكم

gcloud

قراءة بيانات PITR

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

Java

العقدة

REST API

Apache Beam

Java

الاستنساخ من قاعدة بيانات

وحدة التحكم

gcloud

Firebase CLI

القيود

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

gcloud

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