تطوير وظيفة على Azure Databricks باستخدام حزم أصول Databricks

مقالة
10/05/2024

تحتوي حزم أصول Databricks، المعروفة أيضا ببساطة باسم الحزم، على البيانات الاصطناعية التي تريد نشرها وإعدادات موارد Azure Databricks مثل الوظائف التي تريد تشغيلها، وتمكنك من التحقق من صحتها ونشرها وتشغيلها برمجيا. راجع ما هي حزم أصول Databricks؟.

توضح هذه المقالة كيفية إنشاء حزمة لإدارة وظيفة برمجيا. راجع جدولة مهام سير العمل وتنسيقها. يتم إنشاء الحزمة باستخدام قالب حزمة Databricks Asset Bundles الافتراضي ل Python، والذي يتكون من دفتر ملاحظات مقترن بتعريف مهمة لتشغيلها. ثم تحقق من صحة المهمة المنشورة ونشرها وتشغيلها في مساحة عمل Azure Databricks.

تلميح

إذا كانت لديك وظائف موجودة تم إنشاؤها باستخدام واجهة مستخدم وظائف Azure Databricks أو واجهة برمجة التطبيقات التي تريد نقلها إلى الحزم، فيجب عليك تعريفها في ملفات تكوين المجموعة. توصي Databricks بإنشاء مجموعة أولا باستخدام الخطوات أدناه ثم التحقق من عمل المجموعة. يمكنك بعد ذلك إضافة تعريفات مهمة إضافية ودفاتر ملاحظات ومصادر أخرى إلى المجموعة. راجع إضافة تعريف وظيفة موجود إلى مجموعة.

المتطلبات

Databricks CLI الإصدار 0.218.0 أو أعلى. للتحقق من الإصدار المثبت من Databricks CLI، قم بتشغيل الأمر databricks -v. لتثبيت Databricks CLI، راجع تثبيت Databricks CLI أو تحديثه.
يجب أن تحتوي مساحة عمل Databricks البعيدة على ملفات مساحة عمل ممكنة. راجع ما هي ملفات مساحة العمل؟.

إنشاء مجموعة باستخدام قالب مشروع

أولا، قم بإنشاء مجموعة باستخدام قالب Databricks Asset Bundles الافتراضي Python. لمزيد من المعلومات حول قوالب المجموعة، راجع قوالب مشروع مجموعة أصول Databricks.

إذا كنت ترغب في إنشاء حزمة من البداية، فشاهد إنشاء مجموعة يدويا.

الخطوة 1: إعداد المصادقة

في هذه الخطوة، يمكنك إعداد المصادقة بين Databricks CLI على جهاز التطوير ومساحة عمل Azure Databricks. تفترض هذه المقالة أنك تريد استخدام مصادقة OAuth من مستخدم إلى جهاز (U2M) وملف تعريف تكوين Azure Databricks المطابق المسمى DEFAULT للمصادقة.

إشعار

مصادقة U2M مناسبة لتجربة هذه الخطوات في الوقت الفعلي. بالنسبة إلى مهام سير العمل التلقائية بالكامل، توصي Databricks باستخدام مصادقة OAuth من جهاز إلى جهاز (M2M) بدلا من ذلك. راجع إرشادات إعداد مصادقة M2M في المصادقة.

استخدم Databricks CLI لبدء إدارة الرمز المميز OAuth محليا عن طريق تشغيل الأمر التالي لكل مساحة عمل هدف.

في الأمر التالي، استبدل <workspace-url> بعنوان URL الخاص ب Azure Databricks لكل مساحة عمل، على سبيل المثال https://adb-1234567890123456.7.azuredatabricks.net.
```
databricks auth login --host <workspace-url>
```
يطالبك Databricks CLI بحفظ المعلومات التي أدخلتها كملف تعريف تكوين Azure Databricks. اضغط Enter لقبول اسم ملف التعريف المقترح، أو أدخل اسم ملف تعريف جديد أو موجود. تتم الكتابة فوق أي ملف تعريف موجود بنفس الاسم بالمعلومات التي أدخلتها. يمكنك استخدام ملفات التعريف لتبديل سياق المصادقة بسرعة عبر مساحات عمل متعددة.

للحصول على قائمة بأي ملفات تعريف موجودة، في محطة طرفية منفصلة أو موجه أوامر، استخدم Databricks CLI لتشغيل الأمر databricks auth profiles. لعرض الإعدادات الموجودة لملف تعريف معين، قم بتشغيل الأمر databricks auth env --profile <profile-name>.
في مستعرض الويب الخاص بك، أكمل الإرشادات التي تظهر على الشاشة لتسجيل الدخول إلى مساحة عمل Azure Databricks.
لعرض قيمة رمز OAuth المميز الحالي لملف التعريف والطوابع الزمنية لانتهاء الصلاحية القادمة للرمز المميز، قم بتشغيل أحد الأوامر التالية:
- databricks auth token --host <workspace-url>
- databricks auth token -p <profile-name>
- databricks auth token --host <workspace-url> -p <profile-name>
إذا كان لديك ملفات تعريف متعددة بنفس --host القيمة، فقد تحتاج إلى تحديد --host الخيارات و -p معا لمساعدة Databricks CLI في العثور على معلومات الرمز المميز OAuth المتطابقة الصحيحة.

الخطوة 2: تهيئة الحزمة

تهيئة مجموعة باستخدام قالب مشروع مجموعة Python الافتراضي.

استخدم المحطة الطرفية أو موجه الأوامر للتبديل إلى دليل على جهاز التطوير المحلي الذي سيحتوي على مجموعة القالب التي تم إنشاؤها.
استخدم Databricks CLI لتشغيل bundle init الأمر:
```
databricks bundle init
```
بالنسبة إلى Template to use، اترك القيمة الافتراضية للضغط default-python على Enter.
بالنسبة إلى Unique name for this project، اترك القيمة الافتراضية ل my_project، أو اكتب قيمة مختلفة، ثم اضغط Enterعلى . يحدد هذا اسم الدليل الجذر لهذه الحزمة. يتم إنشاء هذا الدليل الجذر في دليل العمل الحالي.
بالنسبة إلى Include a stub (sample) notebook، حدد yes واضغط Enterعلى .
بالنسبة إلى Include a stub (sample) DLT pipeline، حدد no واضغط Enterعلى . هذا يرشد Databricks CLI إلى عدم تعريف نموذج مسار Delta Live Tables في مجموعتك.
بالنسبة إلى Include a stub (sample) Python package، حدد no واضغط Enterعلى . هذا يوجه Databricks CLI إلى عدم إضافة نموذج ملفات حزمة عجلة Python أو إرشادات البناء ذات الصلة إلى مجموعتك.

الخطوة 3: استكشاف المجموعة

لعرض الملفات التي أنشأها القالب، قم بالتبديل إلى الدليل الجذر للحزمة التي تم إنشاؤها حديثا. تتضمن الملفات ذات الاهتمام الخاص ما يلي:

databricks.yml: يحدد هذا الملف الاسم البرمجي للحزمة، ويتضمن مرجعا إلى تعريف الوظيفة، ويحدد إعدادات حول مساحة العمل الهدف.
resources/<project-name>_job.yml: يحدد هذا الملف إعدادات المهمة، بما في ذلك مهمة دفتر ملاحظات افتراضية.
src/notebook.ipynb: هذا الملف هو نموذج دفتر ملاحظات يقوم، عند تشغيله، ببساطة بتهيئة مجموعة بيانات موزعة مرنة تحتوي على الأرقام من 1 إلى 10.

لتخصيص الوظائف، تتوافق التعيينات في إعلان الوظيفة مع حمولة الطلب، المعبر عنها بتنسيق YAML، لعملية إنشاء الوظيفة كما هو موثق في POST /api/2.1/jobs/create في مرجع REST API.

تلميح

يمكنك تحديد الإعدادات لمجموعات الوظائف الجديدة ودمجها وتجاوزها في الحزم باستخدام التقنيات الموضحة في تجاوز إعدادات نظام المجموعة في Databricks Asset Bundles.

الخطوة 4: التحقق من صحة ملف تكوين حزمة المشروع

في هذه الخطوة، يمكنك التحقق مما إذا كان تكوين المجموعة صالحا.

من الدليل الجذر، استخدم Databricks CLI لتشغيل bundle validate الأمر، كما يلي:
```
databricks bundle validate
```
إذا تم إرجاع ملخص لتكوين المجموعة، فنجح التحقق من الصحة. إذا تم إرجاع أي أخطاء، قم بإصلاح الأخطاء، ثم كرر هذه الخطوة.

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

الخطوة 5: نشر المشروع المحلي إلى مساحة العمل البعيدة

في هذه الخطوة، يمكنك نشر دفتر الملاحظات المحلي إلى مساحة عمل Azure Databricks البعيدة وإنشاء مهمة Azure Databricks داخل مساحة العمل الخاصة بك.

من جذر المجموعة، استخدم Databricks CLI لتشغيل bundle deploy الأمر كما يلي:
```
databricks bundle deploy -t dev
```
تحقق مما إذا كان قد تم نشر دفتر الملاحظات المحلي: في الشريط الجانبي لمساحة عمل Azure Databricks، انقر فوق مساحة العمل.
انقر في مجلد Users ><your-username>> .bundle >><project-name>dev > files > src. يجب أن يكون دفتر الملاحظات في هذا المجلد.
تحقق مما إذا كانت المهمة قد تم إنشاؤها: في الشريط الجانبي لمساحة عمل Azure Databricks، انقر فوق مهام سير العمل.
في علامة التبويب المهام ، انقر فوق [dev <your-username>] <project-name>_job.
انقر فوق علامة التبويب المهام. يجب أن تكون هناك مهمة واحدة: notebook_task.

إذا قمت بإجراء أي تغييرات على مجموعتك بعد هذه الخطوة، فيجب عليك تكرار الخطوات من 4 إلى 5 للتحقق مما إذا كان تكوين الحزمة لا يزال صالحا ثم إعادة نشر المشروع.

الخطوة 6: تشغيل المشروع المنشور

في هذه الخطوة، يمكنك تشغيل مهمة Azure Databricks في مساحة العمل الخاصة بك من سطر الأوامر.

من الدليل الجذر، استخدم Databricks CLI لتشغيل bundle run الأمر، كما يلي، استبدال <project-name> باسم مشروعك من الخطوة 2:
```
databricks bundle run -t dev <project-name>_job
```
انسخ قيمة Run URL التي تظهر في المحطة الطرفية الخاصة بك والصق هذه القيمة في مستعرض الويب لفتح مساحة عمل Azure Databricks. راجع عرض وتشغيل مهمة تم إنشاؤها باستخدام مجموعة أصول Databricks
في مساحة عمل Azure Databricks، بعد اكتمال مهمة الوظيفة بنجاح وإظهار شريط عنوان أخضر، انقر فوق مهمة المهمة لمشاهدة النتائج.

إذا قمت بإجراء أي تغييرات على مجموعتك بعد هذه الخطوة، فيجب عليك تكرار الخطوات من 4 إلى 6 للتحقق مما إذا كان تكوين الحزمة لا يزال صالحا، وإعادة نشر المشروع، وتشغيل المشروع المعاد توزيعه.

الخطوة 7: التنظيف

في هذه الخطوة، يمكنك حذف دفتر الملاحظات المنشور والمهمة من مساحة العمل الخاصة بك.

من الدليل الجذر، استخدم Databricks CLI لتشغيل bundle destroy الأمر، كما يلي:
```
databricks bundle destroy -t dev
```
تأكيد طلب حذف الوظيفة: عند مطالبتك بتدمير الموارد بشكل دائم، اكتب y واضغط Enterعلى .
تأكيد طلب حذف دفتر الملاحظات: عند مطالبتك بتدمير المجلد المنشور مسبقا وكافة ملفاته بشكل دائم، اكتب y واضغط Enterعلى .
إذا كنت تريد أيضا حذف الحزمة من جهاز التطوير الخاص بك، يمكنك الآن حذف الدليل المحلي من الخطوة 2.

إضافة تعريف وظيفة موجود إلى مجموعة

يمكنك استخدام وظيفة موجودة كأساس لتعريف وظيفة في ملف تكوين مجموعة. للحصول على تعريف وظيفة موجود، يمكنك استرداده يدويا باستخدام واجهة المستخدم، أو يمكنك إنشاؤه برمجيا باستخدام Databricks CLI.

للحصول على معلومات حول تعريف الوظيفة في الحزم، راجع الوظيفة.

الحصول على تعريف وظيفة موجود باستخدام واجهة المستخدم

للحصول على تمثيل YAML لتعريف وظيفة موجود من واجهة مستخدم مساحة عمل Azure Databricks:

في الشريط الجانبي لمساحة عمل Azure Databricks، انقر فوق مهام سير العمل.
على علامة التبويب وظائف، انقر فوق ارتباط الاسم الخاص بوظيفتك.
إلى جانب الزر تشغيل الآن، انقر فوق الكباب، ثم انقر فوق التبديل إلى التعليمات البرمجية (YAML).
أضف YAML الذي نسخته إلى ملف الحزمة databricks.yml الخاصة بك، أو أنشئ ملف تكوين لمهمتك في resources دليل مشروع الحزمة الخاص بك وقم بالإشارة إليه من ملفك databricks.yml . راجع (/dev-tools/bundles/settings.md#resources).
قم بتنزيل وإضافة أي ملفات ودفاتر ملاحظات Python المشار إليها في المهمة الحالية إلى مصدر مشروع المجموعة. عادة ما تكون بيانات المجموعة الاصطناعية src في الدليل في مجموعة.

تلميح

يمكنك تصدير دفتر ملاحظات موجود من مساحة عمل Azure Databricks إلى .ipynb التنسيق بالنقر فوق File > Export > IPython Notebook من واجهة مستخدم دفتر ملاحظات Azure Databricks.

بعد إضافة دفاتر الملاحظات وملفات Python والبيانات الاصطناعية الأخرى إلى المجموعة، تأكد من أن تعريف وظيفتك يشير إليها بشكل صحيح. على سبيل المثال، لدفتر ملاحظات باسم hello.ipynb موجود في src دليل الحزمة:
```
resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ../src/hello.ipynb
```

إنشاء تعريف وظيفة موجود باستخدام Databricks CLI

لإنشاء تكوين حزمة برمجيا لوظيفة موجودة:

استرجع معرف الوظيفة الحالية من اللوحة الجانبية تفاصيل المهمة للوظيفة في واجهة مستخدم الوظائف، أو استخدم الأمر Databricks CLI databricks jobs list .
bundle generate job قم بتشغيل الأمر Databricks CLI، مع تعيين معرف الوظيفة:
```
databricks bundle generate job --existing-job-id 6565621249
```
ينشئ هذا الأمر ملف تكوين حزمة للوظيفة في مجلد الحزمة resources وينزل أي بيانات اصطناعية مرجعية src إلى المجلد.

تلميح

إذا كنت تستخدم bundle deployment bind أولا لربط مورد في حزمة واحدة في مساحة العمل، يتم تحديث المورد في مساحة العمل استنادا إلى التكوين المحدد في المجموعة التي يرتبط بها بعد التالي bundle deploy. للحصول على معلومات حول bundle deployment bind، راجع ربط موارد المجموعة.

تكوين وظيفة تستخدم حساب بلا خادم

توضح الأمثلة التالية تكوينات المجموعة لإنشاء وظيفة تستخدم حساب بلا خادم.

لاستخدام الحوسبة بلا خادم لتشغيل مهمة تتضمن مهام دفتر الملاحظات، احذف job_clusters التكوين من ملف تكوين المجموعة.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

لاستخدام الحوسبة بلا خادم لتشغيل مهمة تتضمن مهام Python، قم بتضمين environments التكوين.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

راجع تشغيل وظيفة Azure Databricks باستخدام حساب بلا خادم لسير العمل.

مشاركة عبر