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

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

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

قبل البدء

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

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

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

   • أدوار التوافق مع MongoDB في Cloud Firestore: Owner أو Cloud Datastore Owner أو Cloud Datastore Import Export Admin

   • أدوار Cloud Storage: Owner أو Storage Admin

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

تستخدم عمليات التصدير والاستيراد وكيل خدمة 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.

عرض اسم وكيل الخدمة

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

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

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

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

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

• يمكنك الوصول إلى gcloud من وحدة تحكّم Google Cloud باستخدام Cloud Shell.

  بدء Cloud Shell

  تأكَّد من ضبط gcloud للمشروع الصحيح:

  gcloud config set project [PROJECT_ID]
  

• ثبِّت حزمة تطوير البرامج (SDK) من Google Cloud وابدأ إعدادها.

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

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

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

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

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

• يجب أن يتطابق اسم ملف .overall_export_metadata مع اسم المجلد الرئيسي:

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

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

• يتعذّر إجراء عملية استيراد إلى قاعدة بيانات متوافقة مع MongoDB في Cloud Firestore من عملية تصدير تتضمّن مجموعات فرعية لأنّ المجموعات الفرعية غير متاحة في قاعدة بيانات متوافقة مع MongoDB في Cloud Firestore.

• يتعذّر استيراد البيانات إلى قاعدة بيانات إصدار Standard من Cloud Firestore من عملية تصدير تتضمّن أنواع BSON، لأنّ أنواع BSON غير متاحة في إصدار Standard من Cloud Firestore.

• لا يمكن استيراد البيانات من مساحات الأسماء غير التلقائية (Datastore API) إلى Cloud Firestore مع قاعدة بيانات متوافقة مع MongoDB.

  لا يُسمح باستيراد ملفات بيانات تحتوي على مساحات أسماء غير تلقائية إلى قاعدة بيانات متوافقة مع MongoDB في Cloud Firestore إلا إذا كانت عملية التصدير تتضمّن فلتر --namespace-ids مع مساحة الاسم التلقائية. يتم استيراد البيانات من مساحة الاسم التلقائية فقط.

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

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

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

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

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

الاستيراد من عملية تصدير تتضمّن بيانات PITR

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

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

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

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

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

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

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

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

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

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

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

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

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

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

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

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

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

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

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

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

gcloud firestore operations list

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

gcloud firestore operations describe [OPERATION_NAME]

تقدير وقت الإكمال

يعرض طلب معرفة حالة عملية تستغرق وقتًا طويلاً المقياسَين workEstimated وworkCompleted. يتم عرض كل مقياس من هذه المقاييس في شكل عدد وحدات بايت وعدد كيانات:

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

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

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

إلغاء عملية

gcloud firestore operations cancel [OPERATION_NAME]

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

حذف عملية

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

gcloud firestore operations delete [OPERATION_NAME]

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

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

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

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

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

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

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

التصدير إلى BigQuery

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

عند تحميل بيانات متوافقة مع MongoDB في Cloud Firestore إلى BigQuery، يتم تمثيل أنواع بيانات BSON بنوع البيانات STRING.

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

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

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

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

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

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

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

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

protoc --decode_raw < export0.export_metadata