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

يمكنك استخدام Cloud Firestore خدمة التصدير والاستيراد المُدارة للتعافّي من حذف البيانات عن طريق الخطأ ولتصدير البيانات لمعالجتها بلا إنترنت. يمكنك تصدير جميع المستندات أو مجموعات معيّنة فقط. وبالمثل، يمكنك استيراد جميع البيانات من عملية تصدير أو مجموعات معيّنة فقط. يمكن استيراد البيانات المصدَّرة من قاعدة بيانات Cloud Firestore واحدة إلى قاعدة بيانات Cloud Firestore أخرى. يمكنك أيضًا تحميل Cloud Firestore عمليات التصدير إلى BigQuery.

توضّح هذه الصفحة كيفية تصدير وتصدير مستندات Cloud Firestore باستخدام خدمة التصدير والاستيراد المُدارة وCloud Storage. تتوفّر خدمة التصدير والاستيراد المُدارة في Cloud Firestore من خلال أداة سطر الأوامر gcloud وواجهة برمجة التطبيقات Cloud Firestore (REST وRPC).

قبل البدء

لكي تتمكّن من استخدام خدمة التصدير والاستيراد المُدارة، عليك إكمال المهام التالية:

  1. فعِّل الفوترة لمشروعك على Google Cloud. لا يمكن استخدام وظيفة التصدير والاستيراد إلا في Google Cloud المشاريع التي تم تفعيل الفوترة فيها.
  2. أنشئ حزمة Cloud Storage لمشروعك في موقع جغرافي قريب من موقع جغرافي Cloud Firestore لقاعدة بياناتك. لا يمكنك استخدام حزمة "يدفع المرسِل" لإجراء عمليات التصدير والاستيراد.

  3. تأكَّد من أنّ حسابك يتضمّن الأذونات اللازمة لتطبيق Cloud Firestore وCloud Storage. إذا كنت مالك المشروع، سيتوفّر لحسابك الأذونات المطلوبة. بخلاف ذلك، تمنحك الأدوار التالية الأذونات اللازمة لإجراء عمليات التصدير والاستيراد وللوصول إلى Cloud Storage:

أذونات موظّف خدمة

تستخدِم عمليات التصدير والاستيراد وكيل خدمة Cloud Firestore لمنح الإذن بعمليات Cloud Storage. يستخدم موظّف خدمة Cloud Firestore اتفاقية التسمية التالية:

موظّف خدمة Cloud Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

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

يتطلّب موظّف خدمة Cloud Firestore الوصول إلى حزمة Cloud Storage المستخدَمة في عملية تصدير أو استيراد. إذا كانت حزمة Cloud Storage في المشروع نفسه الذي تتوفّر فيه قاعدة بيانات Cloud Firestore ، يمكن لمسؤول خدمة Cloud Firestore الوصول إلى الحزمة تلقائيًا.

إذا كانت حزمة Cloud Storage في مشروع آخر، يجب منح موظّف خدمة Cloud Firestore إذن الوصول إلى حزمة Cloud Storage.

منح أدوار لوكيل الدعم

يمكنك استخدام أداة سطر الأوامر gsutil لتحديد أحد الأدوار أدناه. على سبيل المثال، لتعيين دور "مشرف مساحة التخزين" إلى موظّف خدمة Cloud Firestore، نفِّذ ما يلي:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

استبدِل PROJECT_NUMBER برقم مشروعك الذي يُستخدَم لتسمية موظّف خدمة Cloud Firestore. لعرض اسم موظّف خدمة الدعم، اطّلِع على عرض اسم موظّف خدمة الدعم.

بدلاً من ذلك، يمكنك منح هذا الدور باستخدام Google Cloud Console.

عرض اسم موظّف الدعم

يمكنك الاطّلاع على الحساب الذي تستخدمه عمليات الاستيراد والتصدير لمنح الإذن بالطلبات من صفحة الاستيراد/التصدير في وحدة تحكّم Google Cloud. يمكنك أيضًا الاطّلاع على ما إذا كانت قاعدة بياناتك تستخدم Cloud Firestore وكيل الخدمة أو حساب الخدمة القديم App Engine.

  1. اطّلِع على حساب التفويض بجانب التصنيف عمليات الاستيراد/التصدير التي يتم تنفيذها باسم.

يحتاج موظّف الدعم إلى دور Storage Admin في حزمة Cloud Storage لاستخدامها في عملية التصدير أو الاستيراد.

إعداد gcloud لمشروعك

يمكنك بدء عمليات الاستيراد والتصدير من خلال وحدة تحكّم Google Cloud أو أداة سطر الأوامر gcloud. لاستخدام gcloud، عليك إعداد أداة سطر الأوامر والربط بمشروعك بإحدى الطريقتَين التاليتَين:

تصدير البيانات

تعمل عملية التصدير على نسخ المستندات في قاعدة بياناتك إلى مجموعة من الملفات في حزمة Cloud Storage. تجدر الإشارة إلى أنّ عملية التصدير ليست لقطة قاعدة بيانات دقيقة تم أخذها في وقت بدء التصدير. قد يتضمّن التصدير التغييرات التي تم إجراؤها أثناء تنفيذ العملية.

تصدير كل المستندات

Google Cloud Console

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

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

  5. انقر على الخيار تصدير قاعدة البيانات بالكامل.

  6. أسفل اختيار الوجهة، أدخِل اسم حزمة Cloud Storage أو استخدِم الزر تصفّح لاختيار حزمة.

  7. انقر على تصدير.

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

gcloud

استخدِم الأمر firestore export لتصدير كل المستندات في قاعدة بياناتك، مع استبدال [BUCKET_NAME] باسم ملف التمهيد Cloud Storage. أضِف العلامة --async لمنع أداة gcloud من الانتظار إلى أن تكتمل العملية.

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

استبدِل ما يلي:

  • BUCKET_NAME: يمكنك تنظيم عمليات التصدير عن طريق إضافة بادئة ملف بعد اسم الحزمة، على سبيل المثال BUCKET_NAME/my-exports-folder/export-name. إذا لم تقدِّم بادئة ملف، تنشئ خدمة التصدير المُدارة بادئة استنادًا إلى الطابع الزمني الحالي.

  • DATABASE: اسم قاعدة البيانات التي تريد تصدير المستندات منها بالنسبة إلى قاعدة البيانات التلقائية، استخدِم --database='(default)'.

بعد بدء عملية تصدير، لا يؤدي إغلاق المحطة إلى إلغاء العملية، راجِع إلغاء عملية.

تصدير مجموعات معيّنة

Google Cloud Console

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

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

  5. انقر على الخيار تصدير مجموعة مجموعات واحدة أو أكثر. استخدِم القائمة المنسدلة لاختيار مجموعة مجموعات مجموعات واحدة أو أكثر.

  6. أسفل اختيار الوجهة، أدخِل اسم حزمة Cloud Storage أو استخدِم الزر تصفّح لاختيار حزمة.

  7. انقر على تصدير.

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

gcloud

لتصدير مجموعات مجموعات معيّنة، استخدِم العلامة --collection-ids. لا تُصدِّر العملية سوى مجموعات المجموعات التي تحتوي على معرّفات المجموعات المحدّدة. تتضمّن مجموعة المجموعات جميع المجموعات والمجموعات الفرعية (في أي مسار) التي تحمل معرّف المجموعة المحدّد.

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
--database=[DATABASE]

على سبيل المثال، يمكنك تصميم مجموعة restaurants في قاعدة بيانات foo لتضمين مجموعات فرعية متعدّدة، مثل ratings أو reviews أو outlets. لتصدير مجموعتَي restaurants وreviews المحدّدتين، سيظهر الأمر على النحو التالي:

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

التصدير من طابع زمني لميزة "استرداد نقطة في الوقت"

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

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

  1. تصدِّر قاعدة البيانات، مع تحديد المَعلمة snapshot-time على الطابع الزمني المطلوب للاسترداد.

    gcloud

    نفِّذ الأمر التالي لتصدير قاعدة البيانات إلى حزمة التخزين.

    gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP] \
    --collection-ids=[COLLECTION_IDS] \
    --namespace-ids=[NAMESPACE_IDS]

    مع أطيب التحيّات،

    • ‫PITR_TIMESTAMP: طابع زمني لميزة PITR بدقة دقيقة إلى الدقيقة، على سبيل المثال، 2023-05-26T10:20:00.00Z

    يُرجى مراعاة النقاط التالية قبل تصدير بيانات PITR:

    • حدِّد الطابع الزمني بتنسيق RFC 3339. على سبيل المثال، 2020-09-01T23:59:30.234233Z.
    • تأكَّد من أنّ الطابع الزمني الذي تحدّده هو طابع زمني كامل للدقيقة خلال آخر سبعة أيام، ولكن ليس قبل earliestVersionTime. إذا لم تعُد البيانات متوفّرة في الطابع الزمني المحدّد، يتمّ إنشاء خطأ.
    • لا يتم تحصيل رسوم منك مقابل عملية تصدير PITR تعذّرت.

استيراد البيانات

بعد تصدير الملفات في Cloud Storage، يمكنك استيراد المستندات في تلك الملفات مرة أخرى إلى مشروعك أو إلى مشروع آخر. يُرجى مراعاة النقاط التالية حول عمليات الاستيراد:

  • عند استيراد البيانات، يتم تعديل الفهارس المطلوبة باستخدام تعريفات الفهرس الحالية في قاعدة بياناتك. لا تحتوي عملية التصدير على تعريفات الفهرس.

  • لا تحدّد عمليات الاستيراد معرّفات مستندات جديدة. تستخدِم عمليات الاستيراد المعرّفات التي تم تسجيلها في وقت التصدير. أثناء استيراد مستند، يتم حجز رقم تعريفه لمنع تعارض أرقام التعريف. إذا كان هناك مستند يحمل المعرّف نفسه، يؤدي الادخال إلى استبدال المستند الحالي.

  • إذا لم يتأثّر مستند في قاعدة بياناتك بعملية استيراد، سيظل في قاعدة بياناتك بعد عملية الاستيراد.

  • لا تؤدي عمليات الاستيراد إلى تشغيل Cloud Functions. يتلقّى مستمعو اللقطات تعديلات متعلّقة بعمليات الاستيراد.

  • يجب أن يتطابق اسم ملف .overall_export_metadata مع اسم ملفه родительским المهمّ:

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

    إذا نقلت ملفات الإخراج الناتجة عن عملية تصدير أو نسختها، عليك إبقاء اسمَي الملفَّين PARENT_FOLDER_NAME و.overall_export_metadata كما هو.

استيراد جميع المستندات من عملية تصدير

Google Cloud Console

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

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

  5. في حقل اسم الملف، أدخِل اسم ملف .overall_export_metadata من عملية تصدير مكتملة. يمكنك استخدام الزر تصفّح لمساعدتك في اختيار الملف.

  6. انقر على استيراد.

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

gcloud

استخدِم الأمر firestore import لاستيراد المستندات من عملية تصدير سابقة.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

استبدِل ما يلي:

  • BUCKET_NAME/EXPORT_PREFIX: موقع ملفاتك المصدَّرة

  • ‫DATABASE: اسم قاعدة البيانات بالنسبة إلى قاعدة البيانات التلقائية، استخدِم --database='(default)'.

على سبيل المثال:

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

يمكنك تأكيد مكان ملفات التصدير في متصفح Cloud Storage في وحدة تحكّم Google Cloud:

فتح متصفّح Cloud Storage

بعد بدء عملية استيراد، لا يؤدي إغلاق المحطة إلى إلغاء العملية، راجِع إلغاء عملية.

استيراد مجموعات محدّدة

Google Cloud Console

لا يمكنك اختيار مجموعات معيّنة في وحدة التحكّم. استخدِم gcloud بدلاً من ذلك.

gcloud

لاستيراد مجموعات مجموعات معيّنة من مجموعة من ملفات التصدير، استخدِم العلامة --collection-ids. تستورد العملية مجموعات المجموعات التي تتضمّن معرّفات المجموعات المحدّدة فقط. تتضمّن مجموعة المجموعات جميع المجموعات والمجموعات الفرعية (في أي مسار) التي تحتوي على معرّف المجموعة المحدّد. حدِّد اسم قاعدة البيانات باستخدام العلامة --database. بالنسبة إلى قاعدة البيانات التلقائية، استخدِم --database='(default)'.

لا يتيح تصدير مجموعات مجموعات معيّنة إلا استيراد مجموعات مجموعات معيّنة. لا يمكنك استيراد مجموعات معيّنة من عملية تصدير لجميع المستندات.

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

استيراد بيانات تم تصديرها من خلال ميزة "استرداد نقطة في الوقت"

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

إدارة عمليات التصدير والاستيراد

بعد بدء عملية تصدير أو استيراد، يحدّد Cloud Firestore اسمًا فريدًا للّعبة. يمكنك استخدام اسم العملية لحذفها أو إلغائها أو التحقّق من حالتها.

تتم إضافة البادئة projects/[PROJECT_ID]/databases/(default)/operations/ إلى أسماء العمليات، على سبيل المثال:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

ومع ذلك، يمكنك حذف البادئة عند تحديد اسم عملية لسمَتَي describe وcancel وdelete.

إدراج جميع عمليات التصدير والاستيراد

Google Cloud Console

يمكنك الاطّلاع على قائمة بعمليات التصدير والاستيراد الأخيرة في صفحة الاستيراد/التصدير في Google Cloud Console.

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

gcloud

استخدِم الأمر operations list للاطّلاع على جميع عمليات التصدير والاستيراد الجارية والمكتملة مؤخرًا:

gcloud firestore operations list

التحقّق من حالة العملية

Google Cloud Console

يمكنك الاطّلاع على حالة عملية تصدير أو استيراد حديثة في صفحة الاستيراد/التصدير في وحدة تحكّم Google Cloud.

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

gcloud

استخدِم الأمر operations describe لعرض حالة عملية تصدير أو استيراد.

gcloud firestore operations describe [OPERATION_NAME]

تقدير وقت الإنجاز

يؤدي طلب حالة عملية طويلة الأمد إلى عرض المقياسين workEstimated وworkCompleted. يتم عرض كلّ من هذه المقاييس في كلّ من عدد وحدات البايت وعدد الكيانات:

  • workEstimated تعرِض إجمالي عدد البايتات والمستندات المقدَّر الذي ستعالجه العملية. قد تحذف Cloud Firestore هذا المقياس إذا تعذّر عليها إجراء تقدير.

  • تعرِض workCompleted عدد البايتات والمستندات التي تمت معالجتها حتى الآن. بعد اكتمال العملية، تعرض القيمة إجمالي عدد البايت والمستندات التي تمت معالجتها فعليًا، وقد يكون أكبر من قيمةworkEstimated.

اقسم workCompleted على workEstimated للحصول على تقدير تقريبي للتقدّم. قد يكون هذا التقدير غير دقيق، لأنّه يعتمد على جمع الإحصاءات متأخّرًا.

إلغاء عملية

Google Cloud Console

يمكنك إلغاء عملية تصدير أو استيراد جارية في صفحة الاستيراد/التصدير في Google Cloud Console.

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

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

جدول عمليات الاستيراد والتصدير الأخيرة في وحدة التحكّم يعرض عملية استيراد بيانات جارية مع خيار "إلغاء" لإيقاف العملية

gcloud

استخدِم الأمر operations cancel لإيقاف عملية جارية:

gcloud firestore operations cancel [OPERATION_NAME]

لا يؤدي إلغاء عملية جارية إلى التراجع عن العملية. في حال إلغاء عملية تصدير، لن يتم حذف المستندات التي سبق أن تم تصديرها في Cloud Storage، وفي حال إلغاء عملية استيراد، لن يتم إلغاء التعديلات التي سبق أن تم إجراؤها على قاعدة بياناتك. لا يمكنك استيراد عملية تصدير مكتملة جزئيًا.

حذف عملية

استخدِم الأمر gcloud firestore operations delete لإزالة عملية من قائمة العمليات الأخيرة. لن يؤدي هذا الأمر إلى حذف تصدير الملفات من Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

الفوترة والأسعار لعمليات التصدير والاستيراد

عليك تفعيل الفوترة لمشروعك على Google Cloud قبل استخدام خدمة التصدير والاستيراد المُدارة.

يتم تحصيل رسوم من عمليات التصدير والاستيراد لقراءة المستندات وكتابتها بالأسعار المدرَجة في أسعار Cloud Firestore. تؤدي عمليات التصدير إلى إجراء عملية قراءة واحدة لكل مستند يتم تصديره. تؤدي عمليات الاستيراد إلى إجراء عملية كتابة واحدة لكل مستند مستورَد.

يتم احتساب ملفات الإخراج المخزّنة في Cloud Storage ضمن تكاليف تخزين بيانات Cloud Storage.

لا تُحتسَب تكاليف عمليات التصدير والاستيراد ضمن حدود إنفاقك. لن تؤدي عمليات التصدير أو الاستيراد إلى تشغيل تنبيهات Google Cloud الميزانية إلا بعد اكتمالها. وبالمثل، يتم تطبيق عمليات القراءة والكتابة التي يتم إجراؤها أثناء عملية تصدير أو استيراد على الحصة اليومية بعد اكتمال العملية. لن تؤثّر عمليات التصدير والاستيراد في الاستخدام المعروض في قسم "الاستخدام" في وحدة التحكّم.

عرض تكاليف التصدير والاستيراد

تطبِّق عمليات التصدير والاستيراد التصنيف goog-firestoremanaged:exportimport على العمليات التي يتمّ تحصيل رسومها. في صفحة تقارير "الفوترة في السحابة الإلكترونية"، يمكنك استخدام هذا التصنيف لعرض التكاليف المرتبطة بعمليات الاستيراد والتصدير:

يمكنك الوصول إلى التصنيف goog-firestoremanaged من قائمة الفلاتر.

التصدير إلى BigQuery

يمكنك تحميل البيانات من عملية تصدير Cloud Firestore إلى BigQuery، ولكن فقط إذا حدّدت فلتر collection-ids. اطّلِع على مقالة تحميل البيانات من عمليات تصدير Cloud Firestore.

الحد الأقصى لعدد الأعمدة هو BigQuery

BigQuery تفرض حدًا أقصى يبلغ 10,000 عمود لكل جدول. تُنشئ عمليات تصدير Cloud Firestore مخطّط جدول BigQuery لكل مجموعة مجموعات. في هذا المخطّط، يصبح كل اسم حقل فريد ضمن مجموعة مجموعات عمودًا في المخطّط.

إذا تجاوز مخطّط BigQuery لمجموعة المجموعات 10,000 عمود، تحاول عملية Cloud Firestore التصدير البقاء ضمن الحد الأقصى للأعمدة من خلال التعامل مع حقول الخريطة على أنّها وحدات بايت. إذا أدّت عملية التحويل هذه إلى خفض عدد الأعمدة إلى أقل من 10,000، يمكنك تحميل البيانات إلى BigQuery، ولكن لا يمكنك طلب البحث في الحقول الفرعية ضمن حقول الخريطة. إذا استمر عدد الأعمدة في تجاوز 10,000، لا تؤدي عملية التصدير إلى توليد مخطّط BigQuery لمجموعة المجموعة ولا يمكنك تحميل data إلى BigQuery.

تصدير ملفات التنسيق والبيانات الوصفية

يستخدم الناتج من عملية التصدير المُدارة تنسيق سجلّات LevelDB.

ملفات البيانات الوصفية

تُنشئ عملية التصدير ملف بيانات وصفية لكل مجموعة مجموعات تحدّدها. عادةً ما يتم تسمية ملفات البيانات الوصفية باسم ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

ملفات البيانات الوصفية هي وحدات تخزين بروتوكول، ويمكنك فك ترميزها باستخدام compilingprotoc compiler. على سبيل المثال، يمكنك فك ترميز ملف بيانات وصفية لتحديد مجموعات المجموعات التي تحتوي عليها ملفات التصدير:

protoc --decode_raw < export0.export_metadata

نقل موظّف خدمة

يستخدم Cloud Firestore وكيل خدمة Cloud Firestore لتفويض عمليات الاستيراد والتصدير بدلاً من استخدام حساب الخدمة App Engine. يستخدم وكيل الخدمة وحساب الخدمة اصطلاحات التسمية التالية:

موظّف خدمة Cloud Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

سبق أن استخدم Cloud Firestore حساب الخدمة التلقائي App Engine بدلاً من وكيل الخدمة Cloud Firestore. إذا كانت قاعدة بياناتك لا تزال تستخدم حساب الخدمة App Engine لاستيراد البيانات أو تصديرها، ننصحك باتّباع التعليمات الواردة في هذا القسم لنقل بياناتك إلى استخدام وكيل الخدمة Cloud Firestore.

حساب خدمة App Engine
PROJECT_ID@appspot.gserviceaccount.com

يُفضَّل استخدام موظّف خدمة Cloud Firestore لأنّه مخصّص لـ Cloud Firestore. تتم مشاركة حساب الخدمة App Engine مع أكثر من خدمة واحدة.

عرض حساب التفويض

يمكنك الاطّلاع على الحساب الذي تستخدمه عمليات الاستيراد والتصدير لمنح الإذن بالطلبات من صفحة الاستيراد/التصدير في وحدة تحكّم Google Cloud. يمكنك أيضًا معرفة ما إذا كانت قاعدة بياناتك تستخدم Cloud Firestore وكيل الخدمة.

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

  4. اطّلِع على حساب التفويض بجانب التصنيف عمليات الاستيراد/التصدير التي يتم تنفيذها باسم.

إذا كان مشروعك لا يستخدم وكيل خدمة Cloud Firestore، يمكنك نقل البيانات إلى وكيل خدمة Cloud Firestore باستخدام أيٍّ من التقنيات التالية:

يُفضّل استخدام التقنية الأولى من هذه التقنيات لأنّها تحصر نطاق أثر التغيير في مشروع Cloud Firestore واحد. لا يُنصح باستخدام التقنية الثانية لأنّها لا تنقل أذونات حزمة Cloud Storage الحالية. ومع ذلك، فإنّه يقدّم امتثالًا للأمان على مستوى المؤسسة.

نقل البيانات من خلال التحقّق من أذونات حزمة Cloud Storage وتعديلها

تتضمّن عملية نقل البيانات خطوتَين:

  1. عدِّل أذونات حزمة Cloud Storage. يُرجى الاطّلاع على القسم التالي للاطّلاع على التفاصيل.
  2. أكِّد نقل البيانات مع موظّف خدمة Cloud Firestore.

أذونات حزمة وكيل الخدمة

بالنسبة إلى أي عمليات تصدير أو استيراد تستخدِم حزمة Cloud Storage في مشروع آخر، عليك منح موظّف خدمة Cloud Firestore الأذونات الخاصة بهذه الحزمة. على سبيل المثال، تحتاج العمليات التي تنقل البيانات إلى مشروع آخر إلى الوصول إلى حزمة في هذا المشروع الآخر. بخلاف ذلك، تَتعذّر هذه العمليات بعد نقل البيانات إلى Cloud Firestore مساعد الخدمة.

لا تتطلّب عمليات استيراد سير العمل وتصديرها التي تظل ضمن المشروع نفسه إجراء تغييرات على الأذونات. يمكن لوكيل خدمة Cloud Firestore الوصول إلى الحزم في المشروع نفسه تلقائيًا.

عدِّل أذونات حِزم Cloud Storage من مشاريع أخرى لمنح العميل إذن بالوصول إلى service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com موظّف الدعم. امنح موظّف الدعم الدور Firestore Service Agent.

يمنح دور Firestore Service Agent أذونات القراءة والكتابة لحزمة Cloud Storage. إذا كنت بحاجة إلى منح أذونات قراءة أو كتابة فقط، استخدِم دورًا مخصّصًا.

تساعدك عملية نقل البيانات الموضّحة في القسم التالي في تحديد Cloud Storage الحِزم التي قد تتطلّب تعديلات على الأذونات.

نقل مشروع إلى "وكيل خدمة Firestore"

أكمِل الخطوات التالية لنقل البيانات من حساب الخدمة App Engine إلى وكيل الخدمة Cloud Firestore. بعد اكتمال عملية نقل البيانات، لا يمكن قلبها.

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

  4. إذا لم يتم نقل مشروعك إلى Cloud Firestore موظّف خدمة، سيظهر لك بانر يصف عملية النقل وزر التحقّق من حالة الحزمة. تساعدك الخطوة التالية في تحديد أخطاء الأذونات المحتملة وإصلاحها.

    انقر على التحقّق من حالة الحزمة.

    ستظهر قائمة تتضمّن خيار إكمال عملية نقل البيانات و قائمة بـ Cloud Storage حزمة. قد يستغرق الأمر بضع دقائق لتحميل القائمة.

    تتضمّن هذه القائمة الحِزم التي تم استخدامها مؤخرًا في عمليات الاستيراد والتصدير، ولكنّها لا تمنح حاليًا أذونات القراءة والكتابة لوكيل خدمة Cloud Firestore.

  5. دوِّن الاسم الأساسي لوكيل خدمة Cloud Firestore في مشروعك. يظهر اسم موظّف خدمة الدعم ضمن التصنيف موظّف خدمة الدعم الذي سيتم منحه إذن الوصول.

  6. بالنسبة إلى أي حزمة في القائمة ستستخدمها لإجراء عمليات استيراد أو تصدير في المستقبل، أكمِل الخطوات التالية:

    1. في صف جدول الحزمة هذا، انقر على إصلاح. يؤدي ذلك إلى فتح صفحة أذونات الحزمة في علامة تبويب جديدة.

    2. انقر على إضافة.
    3. في حقل المشرفون الجدد، أدخِل اسم Cloud Firestore موظّف الدعم.
    4. في حقل اختيار دور، اختَر موظّفو الدعم > موظّف دعم Firestore.
    5. انقر على حفظ.
    6. ارجع إلى علامة التبويب التي تتضمّن صفحة Cloud Firestore الاستيراد/التصدير.
    7. كرِّر هذه الخطوات مع الحِزم الأخرى في القائمة. احرص على الاطّلاع على جميع صفحات القائمة.

  7. انقر على نقل البيانات إلى وكيل خدمة Firestore. إذا كان لا يزال لديك حِزم تتضمّن عمليات تحقّق من الأذونات تنتهي بالفشل، عليك تأكيد عملية نقل البيانات بالنقر على نقل البيانات.

    سيصلك تنبيه لإعلامك عند اكتمال عملية نقل البيانات. لا يمكن التراجع عن عملية نقل البيانات.

عرض حالة نقل البيانات

للتحقّق من حالة نقل بيانات مشروعك:

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

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

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

  3. في قائمة التنقّل، انقر على استيراد/تصدير.

  4. ابحث عن المستخدم الرئيسي بجانب التصنيف عمليات الاستيراد/التصدير التي يتم تنفيذها باسم.

    إذا كان المشرف هو service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com، يعني ذلك أنّه سبق نقل مشروعك إلى Cloud Firestore موظّف خدمة. لا يمكن التراجع عن عملية نقل البيانات.

    إذا لم يتم نقل المشروع، سيظهر بانر في أعلى الصفحة مع زر التحقّق من حالة الحزمة. راجِع مقالة النقل إلى وكيل خدمة Firestore لإكمال عملية النقل.

إضافة قيد سياسة على مستوى المؤسسة

  • اضبط القيود التالية في سياسة مؤسستك:

    طلب وكيل خدمة Firestore للاستيراد/التصدير (firestore.requireP4SAforImportExport).

    يتطلّب هذا القيد أن تستخدم عمليات الاستيراد والتصدير موظّف خدمة Cloud Firestore لمنح الأذونات للطلبات. لضبط هذا القيد، يُرجى الاطّلاع على إنشاء سياسات المؤسسة وإدارتها .

لا يؤدي تطبيق قيد السياسة التنظيمية هذا إلى منح أذونات حزمة Cloud Storage المناسبة تلقائيًا لموظّف خدمة Cloud Firestore.

إذا أدّى القيد إلى حدوث أخطاء في الأذونات لأي سير عمل استيراد أو تصدير، يمكنك إيقافه للعودة إلى استخدام حساب الخدمة التلقائي. بعد التحقّق من أذونات ملف التخزين Cloud Storage وتعديلها، يمكنك تفعيل القيود مرة أخرى.