توضّح هذه الصفحة كيفية استخدام ميزة "استرداد نقطة في الوقت" (PITR) للاحتفاظ بالبيانات واستردادها في Cloud Firestore.
لفهم مفاهيم استرداد نقطة في الوقت، راجِع مقالة استرداد نقطة في الوقت.
الأذونات
للحصول على الأذونات التي تحتاجها لإدارة إعدادات PITR، اطلب من المشرف منحك أدوار إدارة الهوية والوصول (IAM) التالية في المشروع الذي تريد تفعيل PITR فيه:
- Cloud Datastore Owner (
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 عند إنشاء قاعدة بيانات، عليك استخدام الأمر
gcloud firestore databases create
. لا يمكن تفعيل ميزة PITR أثناء إنشاء قاعدة بيانات باستخدام Google Cloud Console. - يبدأ Cloud Firestore في الاحتفاظ بالإصدارات من هذه النقطة فصاعدًا بعد تفعيل ميزة "استرداد نقطة في الوقت".
- لا يمكنك قراءة بيانات PITR في نافذة PITR بعد إيقاف ميزة PITR.
- في حال إعادة تفعيل ميزة "استرداد نقطة في الوقت" مباشرةً بعد إيقافها، لن تعود بيانات "استرداد نقطة في الوقت" السابقة متوفرة. سيتم حذف أي بيانات PITR تم إنشاؤها قبل إيقاف ميزة PITR بعد تاريخ انتهاء صلاحيتها.
- إذا حذفت البيانات عن طريق الخطأ في آخر ساعة وكانت ميزة "استرداد نقطة في الوقت" غير مفعَّلة، يمكنك استعادة بياناتك من خلال تفعيلها في غضون ساعة واحدة من الحذف.
- تَتعذّر أي عملية قراءة يتم إجراؤها على بيانات PITR المنتهية الصلاحية.
تفعيل ميزة PITR
قبل استخدام ميزة PITR، عليك تفعيل الفوترة لمشروعك على Google Cloud. لا يمكن استخدام وظيفة PITR إلا في مشاريع Google Cloud التي تم تفعيل الفوترة فيها.
لتفعيل ميزة PITR لقاعدة بياناتك:
وحدة التحكم
في وحدة تحكّم Google Cloud، انتقِل إلى صفحة القواعد البيانات.
اختَر قاعدة البيانات المطلوبة من قائمة قواعد البيانات.
في قائمة التنقّل، انقر على استرداد البيانات في حالات الكوارث.
انقر على تعديل لتعديل الإعدادات.
ضَع علامة في مربّع الاختيار تفعيل ميزة "استرداد نقطة في الوقت"، ثم انقر على حفظ.
سيؤدي تفعيل ميزة PITR إلى تحمُّل تكاليف التخزين. اطّلِع على الأسعار للحصول على مزيد من المعلومات.
لإيقاف ميزة "استرداد نقطة في الوقت"، أزِل العلامة من مربّع الاختيار تفعيل استرداد نقطة في الوقت في صفحة "استرداد الكوارث" في "وحدة تحكّم Google Cloud".
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
- تم ضبطه على firestore-native.
يمكنك إيقاف ميزة PITR باستخدام الأمر gcloud firestore databases update
على النحو التالي:
gcloud firestore databases update\
[--database=DATABASE_ID; default="(default)"]\
--no-enable-pitr
استبدِل القيم على النحو التالي:
-
DATABASE_ID
- يتم ضبطه على معرّف قاعدة البيانات أو (تلقائي).
الحصول على فترة الاحتفاظ بالبيانات ووقت أقرب إصدار
وحدة التحكم
في وحدة تحكّم Google Cloud، انتقِل إلى صفحة القواعد البيانات.
اختَر قاعدة البيانات المطلوبة من قائمة قواعد البيانات.
في قائمة التنقّل، انقر على استرداد البيانات في حالات الكوارث.
في قسم الإعدادات، دوِّن فترة الاحتفاظ بالبيانات ووقت أقدم إصدار.
- فترة الاحتفاظ بالبيانات: هي الفترة التي تحتفظ فيها Cloud Firestore بجميع إصدارات البيانات الخاصة بقاعدة البيانات. تكون القيمة ساعة واحدة عند إيقاف ميزة PITR وتفعيلها لمدة سبعة أيام.
- وقت أقدم إصدار: هو الطابع الزمني الأقدم الذي يمكن فيه قراءة الإصدارات الأقدم من البيانات في نافذة 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
، إذا كان الاحتفاظ بنقاط إعادة التخصيص مفعّلاً. في حال إيقاف ميزة PITR، سيظهر لك إماPOINT_IN_TIME_RECOVERY_DISABLED
أو قد لا يظهر الحقلpointInTimeRecoveryEnablement
.versionRetentionPeriod
: الفترة الزمنية التي يتم الاحتفاظ ببيانات PITR خلالها بالمللي ثانية. يمكن أن تكون القيمة ساعة واحدة عندما تكون ميزة PITR غير مفعّلة أو سبعة أيام إذا كانت مفعّلة.
قراءة بيانات PITR
يمكنك قراءة بيانات PITR باستخدام مكتبات العملاء أو طرق واجهة برمجة التطبيقات REST API أو موصّل FirestoreIO Apache Beam.
مكتبات العملاء
جافا
يجب استخدام معاملة 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
تتوفّر عمليات القراءة في "استرداد الخدمات المؤقتة للبيانات" في جميع طرق القراءة في Cloud Firestore، وهي: get وlist وbatchGet و listCollectionIds وlistDocuments و runQuery وrunAggregationQuery و partitionQuery.
لإجراء عملية قراءة باستخدام طرق REST، جرِّب أحد الخيارَين التاليَين:
في طلب طريقة القراءة، نقْل القيمة
readTime
كطابع زمني متوافق لميزة PITR في طريقةreadOptions
. يمكن أن يكون الطابع الزمني لميزة PITR إما طابعًا زمنيًا بدقة الميكرو ثانية خلال الساعة الماضية أو طابعًا زمنيًا كاملاً بالدقيقة بعد الساعة الماضية، ولكن ليس قبلearliestVersionTime
.استخدِم المَعلمة
readTime
مع الطريقةBeginTransaction
كجزء من معاملةReadOnly
لإجراء عمليات قراءة متعددة من خلال ميزة PITR.
Apache Beam
استخدِم موصِّل Cloud FirestoreIO Apache Beam لقراءة المستندات أو كتابتها في قاعدة بيانات Cloud Firestore على نطاق واسع باستخدام Dataflow.
تتوفّر عمليات القراءة في PITR في طريقة القراءة التالية لموصّل
Cloud FirestoreIO. تتوافق طرق القراءة هذه مع withReadTime(@Nullable Instant readTime)
التي يمكنك استخدامها لعمليات قراءة PITR:
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
جافا
يمكن استخدام الرمز البرمجي التالي مع مثال على رمز مسار بيانات 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 جميع الفلاتر، بما في ذلك تصدير جميع المستندات وتصدير مجموعات معيّنة.
تصدِّر قاعدة البيانات، مع تحديد المَعلمة
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 تعذّرت.
الاستيراد إلى قاعدة بيانات
اتّبِع الخطوات الواردة في مقالة استيراد كل المستندات لاستيراد قاعدة بياناتك المصدَّرة. إذا كان هناك أي مستند متوفّر في قاعدة بياناتك، سيتم استبداله.