توضح هذه الصفحة كيفية استخدام الاسترداد في الوقت المناسب (PITR) للاحتفاظ بالبيانات واستعادتها في Cloud Firestore.
لفهم مفاهيم PITR، راجع استرداد النقطة الزمنية .
الأذونات
للحصول على الأذونات التي تحتاجها لإدارة إعدادات PITR، اطلب من المسؤول أن يمنحك أدوار IAM التالية في المشروع الذي تريد تمكين PITR فيه:
- مالك مخزن البيانات السحابي (
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.
- إذا كنت تريد تمكين PITR عند إنشاء قاعدة بيانات، فيجب عليك استخدام أمر
gcloud firestore databases create
. لا يتم دعم تمكين PITR أثناء إنشاء قاعدة بيانات باستخدام وحدة تحكم GCP. - يبدأ Cloud Firestore في الاحتفاظ بالإصدارات من النقطة فصاعدًا بعد تمكين PITR.
- لا يمكنك قراءة بيانات PITR في نافذة PITR بعد تعطيل PITR.
- إذا قمت بإعادة تمكين PITR فورًا بعد تعطيله، فلن تعد بيانات PITR السابقة متاحة. سيتم حذف أي بيانات PITR تم إنشاؤها قبل تعطيل PITR بعد تاريخ انتهاء صلاحية PITR.
- إذا قمت بحذف البيانات عن طريق الخطأ في الساعة الماضية وتم تعطيل PITR، فيمكنك استعادة بياناتك عن طريق تمكين PITR خلال ساعة واحدة من الحذف.
- تفشل أي قراءة يتم إجراؤها على بيانات PITR منتهية الصلاحية.
تمكين بيتر
قبل استخدام PITR، قم بتمكين الفوترة لمشروع Google Cloud الخاص بك . يمكن فقط لمشاريع Google Cloud التي تم تمكين الفوترة فيها استخدام وظيفة PITR.
لتمكين PITR لقاعدة البيانات الخاصة بك:
وحدة التحكم
في Google Cloud Platform Console، انتقل إلى صفحة قواعد البيانات .
قم باختيار قاعدة البيانات المطلوبة من قائمة قواعد البيانات.
في قائمة التنقل، انقر فوق التعافي من الكوارث .
انقر فوق "تحرير" لتحرير الإعدادات.
حدد خانة الاختيار تمكين الاسترداد في الوقت المناسب ، ثم انقر فوق حفظ .
قد يؤدي تمكين PITR إلى تحمل تكاليف التخزين. انظر التسعير لمزيد من المعلومات.
لتعطيل PITR، قم بإلغاء تحديد خانة الاختيار تمكين الاسترداد في الوقت المناسب من صفحة التعافي من الكوارث في وحدة تحكم GCP.
com.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 Platform Console، انتقل إلى صفحة قواعد البيانات .
قم باختيار قاعدة البيانات المطلوبة من قائمة قواعد البيانات.
في قائمة التنقل، انقر فوق التعافي من الكوارث .
في قسم الإعدادات ، لاحظ فترة الاحتفاظ وأقدم وقت للإصدار .
- فترة الاستبقاء : الفترة التي يحتفظ فيها Cloud Firestore بجميع إصدارات البيانات الخاصة بقاعدة البيانات. القيمة هي ساعة واحدة عند تعطيل PITR وسبعة أيام عند تمكين PITR.
- وقت الإصدار الأقدم : الطابع الزمني الأقدم الذي يمكن من خلاله قراءة الإصدارات الأقدم من البيانات في نافذة PITR. يتم تحديث هذه القيمة بشكل مستمر بواسطة Cloud Firestore وتصبح قديمة لحظة الاستعلام عنها. إذا كنت تستخدم هذه القيمة لاسترداد البيانات، فتأكد من مراعاة الوقت من لحظة الاستعلام عن القيمة إلى لحظة بدء الاسترداد.
- استرداد النقطة الزمنية : يظهر
Enabled
، إذا تم تمكين PITR. إذا تم تعطيل PITR، فسترىDisabled
.
com.gcloud
قم بتشغيل قواعد بيانات gcloud firestore التي تصف الأمر كما يلي:
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/(default)
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. إذا تم تعطيل PITR، فسوف ترى إماPOINT_IN_TIME_RECOVERY_DISABLED
أو قد لا يتم عرض حقلpointInTimeRecoveryEnablement
. -
versionRetentionPeriod
- الفترة الزمنية التي يتم خلالها الاحتفاظ ببيانات PITR بالمللي ثانية. يمكن أن تكون القيمة ساعة واحدة عند تعطيل 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
يتم دعم قراءات PITR في جميع أساليب القراءة في Cloud Firestore، وهي get و list و bachGet و listCollectionIds و listDocuments و runQuery و runAggregationQuery و partitionQuery .
لإجراء قراءة باستخدام أساليب REST، جرب أحد الخيارات التالية:
في طلب أسلوب القراءة الخاص بك، قم بتمرير قيمة
readTime
كطابع زمني PITR مدعوم في أسلوبreadOptions
. يمكن أن يكون الطابع الزمني PITR إما طابعًا زمنيًا بدقة ميكروثانية خلال الساعة الماضية أو طابعًا زمنيًا لدقيقة كاملة بعد الساعة الماضية، ولكن ليس قبل أقدم إصدار منearliestVersionTime
.استخدم معلمة
readTime
مع أسلوبBeginTransaction
كجزء من معاملةReadOnly
لقراءات PITR المتعددة.
أباتشي شعاع
استخدم موصل 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
إلى الطابع الزمني للاسترداد المطلوب.com.gcloud
قم بتشغيل الأمر التالي لتصدير قاعدة البيانات إلى مجموعتك.
gcloud firestore export gs://[BUCKET_NAME_PATH] \ --snapshot-time=[PITR_TIMESTAMP] \ --collection-ids=[COLLECTION_IDS] \ --namespace-ids=[NAMESPACE_IDS]
أين،
-
BUCKET_NAME_PATH
- مجموعة تخزين سحابية صالحة مع بادئة مسار اختيارية حيث يتم تخزين ملفات التصدير. -
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 الفاشل.
-
استيراد إلى قاعدة بيانات.
استخدم الخطوات الواردة في استيراد كافة المستندات لاستيراد قاعدة البيانات المصدرة. إذا كان هناك أي مستند موجود بالفعل في قاعدة بياناتك، فسيتم استبداله.