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

يمكنك استخدام خدمة التصدير والاستيراد المُدارة للتعافي من الحذف غير المقصود للبيانات وتصدير البيانات للمعالجة بلا إنترنت. يمكنك تصدير جميع المستندات أو مجموعات معيّنة فقط. وبالمثل، يمكنك استيراد جميع البيانات من عملية تصدير أو مجموعات معيّنة فقط. يمكن استيراد البيانات التي تم تصديرها من قاعدة بيانات 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. لا يمكنك استخدام حزمة "يدفع مقدّم الطلب" أو حزمة Rapid لعمليات التصدير والاستيراد.

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

   • أدوار 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 Console. يمكنك أيضًا الاطّلاع على ما إذا كانت قاعدة بياناتك تستخدم وكيل خدمة Cloud Firestore أو حساب خدمة App Engine القديم.

1. اطّلِع على حساب التفويض بجانب تصنيف Import/Export jobs run as (تشغيل مهام الاستيراد/التصدير باسم).

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

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

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

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

  بدء Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

• ثبِّت حزمة تطوير برامج 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 كما هو.

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

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

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

  يُسمح باستيراد البيانات إلى قاعدة بيانات 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'

التصدير من طابع زمني لـ PITR

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

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

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

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

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

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

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

تتم إضافة البادئة 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 قد يحذف محرّك بحث Google هذا المقياس إذا لم يتمكّن من تقديم تقدير.

• يعرض 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.

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

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

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

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

التصدير إلى BigQuery

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

عند تحميل بيانات Cloud Firestore إلى BigQuery، يتم تمثيل أنواع بيانات BSON باستخدام نوع البيانات STRING.

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

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

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

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

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

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

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

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

protoc --decode_raw < export0.export_metadata