مشاركة عبر

أفضل ممارسات هندسة البرمجيات لدفاتر الملاحظات

  • مقالة

توفر هذه المقالة معاينة عملية توضح كيفية تطبيق أفضل ممارسات هندسة البرامج على دفاتر ملاحظات Azure Databricks، بما في ذلك التحكم في الإصدار ومشاركة التعليمات البرمجية والاختبار والتكامل المستمر والتسليم أو النشر المستمر اختياريا (CI/CD).

في هذه الإرشادات التفصيلية، سوف تقوم بما يلي:

  • أضف دفاتر الملاحظات إلى مجلدات Azure Databricks Git للتحكم في الإصدار.
  • استخراج أجزاء من التعليمات البرمجية من أحد دفاتر الملاحظات إلى وحدة نمطية قابلة للمشاركة.
  • اختبار التعليمات البرمجية المشتركة.
  • تشغيل دفاتر الملاحظات من مهمة Azure Databricks.
  • تطبيق CI/CD اختياريا على التعليمات البرمجية المشتركة.

المتطلبات

لإكمال هذه المعاينة، يجب توفير الموارد التالية:

  • مستودع بعيد مع موفر Git يدعمه Databricks. تستخدم معاينة هذه المقالة GitHub. تفترض هذه المعاينة أن لديك مستودع GitHub باسم best-notebooks متوفر. (يمكنك إعطاء المستودع الخاص بك اسما مختلفا. إذا قمت بذلك، استبدل best-notebooks باسم المستودع الخاص بك خلال هذه المعاينة.) إنشاء مستودع GitHub إذا لم يكن لديك واحد بالفعل.

    إشعار

    إذا قمت بإنشاء مستودع جديد، فتأكد من تهيئة المستودع بملف واحد على الأقل، على سبيل المثال README ملف.

  • مساحة عمل Azure Databricks. إنشاء مساحة عمل إذا لم يكن لديك مساحة عمل بالفعل.

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

الخطوة 1: إعداد مجلدات Databricks Git

في هذه الخطوة، يمكنك توصيل مستودع GitHub الحالي بمجلدات Azure Databricks Git في مساحة عمل Azure Databricks الحالية.

لتمكين مساحة العمل الخاصة بك من الاتصال بم مستودع GitHub الخاص بك، يجب أولا توفير مساحة العمل الخاصة بك ببيانات اعتماد GitHub الخاصة بك، إذا لم تكن قد فعلت ذلك بالفعل.

الخطوة 1.1: توفير بيانات اعتماد GitHub

  1. انقر فوق اسم المستخدم في الجزء العلوي الأيسر من مساحة العمل، ثم انقر فوق الإعدادات في القائمة المنسدلة.
  2. في الشريط الجانبي الإعدادات ، ضمن المستخدم، انقر فوق حسابات مرتبطة.
  3. ضمن تكامل Git، لموفر Git، حدد GitHub.
  4. انقر فوق الرمز المميز للوصول الشخصي.
  5. بالنسبة إلى اسم المستخدم أو البريد الإلكتروني لموفر Git، أدخل اسم مستخدم GitHub الخاص بك.
  6. بالنسبة إلى الرمز المميز، أدخل رمز الوصول الشخصي GitHub (الكلاسيكي) الخاص بك. يجب أن يكون لهذا الرمز المميز للوصول الشخصي (الكلاسيكي) أذونات المستودع وسير العمل .
  7. انقر فوق حفظ.

الخطوة 1.2: الاتصال بم مستودع GitHub

  1. على الشريط الجانبي لمساحة العمل، انقر فوق مساحة العمل.
  2. في مستعرض مساحة العمل، قم بتوسيع Workspace > Users.
  3. انقر بزر الماوس الأيمن فوق مجلد اسم المستخدم، ثم انقر فوق إنشاء > مجلد Git.
  4. في مربع الحوار إنشاء مجلد Git:
    1. بالنسبة إلى عنوان URL لمستودع Git، أدخل نسخة GitHub مع عنوان URL ل HTTPS لمستودع GitHub الخاص بك. تفترض هذه المقالة أن عنوان URL الخاص بك ينتهي ب best-notebooks.git، على سبيل المثال https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. بالنسبة لموفر Git، حدد GitHub.
    3. اترك اسم مجلد Git معينا على اسم المستودع الخاص بك، على سبيل المثال best-notebooks.
    4. انقر فوق إنشاء مجلد Git.

الخطوة 2: استيراد دفتر الملاحظات وتشغيله

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

الخطوة 2.1: إنشاء فرع عمل في المستودع

في هذه البداية الفرعية، يمكنك إنشاء فرع باسم eda في المستودع الخاص بك. يمكنك هذا الفرع من العمل على الملفات والرمز بشكل مستقل عن فرع المستودع main الخاص بك، وهو أفضل ممارسة لهندسة البرامج. (يمكنك إعطاء فرعك اسما مختلفا.)

إشعار

في بعض المستودعات، main قد تتم تسمية master الفرع بدلا من ذلك. إذا كان الأمر كذلك، فاستبدله main master خلال هذه المعاينة.

تلميح

إذا لم تكن على دراية بالعمل في فروع Git، فشاهد Git Branches - الفروع في باختصار على موقع Git على الويب.

  1. يجب أن يكون مجلد Git من الخطوة 1.2 مفتوحا. إذا لم يكن الأمر كما هو، فقم بتوسيع Workspace Users في الشريط الجانبي Workspace>، ثم قم بتوسيع مجلد اسم المستخدم الخاص بك، وانقر فوق مجلد Git الخاص بك.

  2. إلى جانب اسم المجلد ضمن مسار التنقل في مساحة العمل، انقر فوق زر فرع Git الرئيسي .

  3. في مربع الحوار أفضل دفاتر الملاحظات ، انقر فوق الزر إنشاء فرع .

    إشعار

    إذا كان المستودع الخاص بك يحمل اسما آخر غير best-notebooks، فسيكون عنوان مربع الحوار هذا مختلفا، هنا وفي جميع أنحاء هذه المعاينة.

  4. أدخل eda، وانقر فوق إنشاء.

  5. أغلق مربع الحوار هذا.

الخطوة 2.2: استيراد دفتر الملاحظات إلى المستودع

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

  • نسخ ملف CSV من مستودع GitHub owid/covid-19-data إلى مجموعة في مساحة العمل الخاصة بك. يحتوي ملف CSV هذا على بيانات عامة حول المستشفيات COVID-19 ومقاييس العناية المركزة من جميع أنحاء العالم.
  • يقرأ محتويات ملف CSV في pandas DataFrame.
  • تصفية البيانات لتحتوي على مقاييس من الولايات المتحدة فقط.
  • يعرض رسما للبيانات.
  • يحفظ Pandas DataFrame كواجهة برمجة تطبيقات Pandas على Spark DataFrame.
  • إجراء تنقية البيانات على واجهة برمجة تطبيقات Pandas على Spark DataFrame.
  • يكتب Pandas API على Spark DataFrame كجدول Delta في مساحة العمل الخاصة بك.
  • عرض محتويات جدول Delta.

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

  1. من مجلد Git لأفضل دفاتر الملاحظات، انقر فوق إنشاء > مجلد.
  2. في مربع الحوار مجلد جديد، أدخل notebooks، ثم انقر فوق إنشاء.
  3. من مجلد دفاتر الملاحظات، انقر فوق الكباب، ثم استيراد.
  4. في مربع الحوار استيراد :

    1. ل Import from، حدد URL.

    2. أدخل عنوان URL للمحتويات الأولية لدفتر الملاحظات covid_eda_raw في databricks/notebook-best-practices المستودع في GitHub. للحصول على عنوان URL هذا: i. انتقل إلى https://github.com/databricks/notebook-best-practices. ‫2. notebooks انقر فوق المجلد. 3. covid_eda_raw.py انقر فوق الملف. 4. انقر فوق Raw. 5. انسخ عنوان URL الكامل من شريط عناوين مستعرض الويب إلى مربع الحوار استيراد .

      إشعار

      يعمل مربع الحوار استيراد مع عناوين URL ل Git للمستودعات العامة فقط.

    3. انقر فوق استيراد.

الخطوة 2.3: تشغيل دفتر الملاحظات

  1. إذا لم يكن دفتر الملاحظات معروضا بالفعل، فافتح مجلد دفاتر الملاحظات ، ثم انقر فوق دفتر الملاحظات covid_eda_raw داخل المجلد.
  2. حدد نظام المجموعة لإرفاق دفتر الملاحظات هذا به. للحصول على إرشادات حول إنشاء نظام مجموعة، راجع إنشاء نظام مجموعة.
  3. انقر فوق تشغيل الكل.
  4. انتظر حتى يتم تشغيل دفتر الملاحظات.

بعد انتهاء تشغيل دفتر الملاحظات، يجب أن تشاهد في دفتر الملاحظات رسما للبيانات بالإضافة إلى أكثر من 600 صف من البيانات الأولية في جدول Delta. إذا لم يكن نظام المجموعة قيد التشغيل بالفعل عند بدء تشغيل دفتر الملاحظات هذا، فقد يستغرق بدء تشغيل نظام المجموعة عدة دقائق قبل عرض النتائج.

الخطوة 2.4: إيداع دفتر الملاحظات ودمجه

في هذه البداية الفرعية، يمكنك حفظ عملك حتى الآن في مستودع GitHub الخاص بك. ثم تقوم بدمج دفتر الملاحظات من فرع العمل الخاص بك في فرع المستودع main الخاص بك.

  1. إلى جانب اسم دفتر الملاحظات، انقر فوق زر فرع eda Git.
  2. في مربع الحوار أفضل دفاتر الملاحظات ، في علامة التبويب تغييرات ، تأكد من تحديد دفاتر الملاحظات /covid_eda_raw.py الملف.
  3. بالنسبة لرسالة الالتزام (مطلوب)، أدخل Added raw notebook.
  4. بالنسبة للوصف (اختياري) ، أدخل This is the first version of the notebook.
  5. انقر فوق Commit & Push.
  6. انقر فوق ارتباط طلب السحب في إنشاء طلب سحب على موفر git الخاص بك في الشعار.
  7. في GitHub، أنشئ طلب السحب، ثم ادمج طلب السحب في main الفرع.
  8. مرة أخرى في مساحة عمل Azure Databricks، أغلق مربع حوار أفضل دفاتر الملاحظات إذا كان لا يزال يظهر.

الخطوة 3: نقل التعليمات البرمجية إلى وحدة نمطية مشتركة

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

الخطوة 3.1: إنشاء فرع عمل آخر في المستودع

  1. إلى جانب اسم دفتر الملاحظات، انقر فوق زر فرع eda Git.
  2. في مربع الحوار أفضل دفاتر الملاحظات ، انقر فوق سهم القائمة المنسدلة بجوار فرع eda ، وحدد main.
  3. انقر فوق الزر سحب. إذا تمت مطالبتك بمتابعة السحب، فانقر فوق تأكيد.
  4. انقر فوق الزر إنشاء فرع.
  5. أدخل first_modules، ثم انقر فوق إنشاء. (يمكنك إعطاء فرعك اسما مختلفا.)
  6. أغلق مربع الحوار هذا.

الخطوة 3.2: استيراد دفتر الملاحظات إلى المستودع

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

  1. من مستعرض مساحة العمل، انقر بزر الماوس الأيمن فوق مجلد دفاتر الملاحظات، ثم انقر فوق استيراد.
  2. في مربع الحوار استيراد :

    1. ل Import from، حدد URL.

    2. أدخل عنوان URL للمحتويات الأولية لدفتر الملاحظات covid_eda_modular في databricks/notebook-best-practices المستودع في GitHub. للحصول على عنوان URL هذا: i. انتقل إلى https://github.com/databricks/notebook-best-practices. ‫2. notebooks انقر فوق المجلد. 3. covid_eda_modular.py انقر فوق الملف. 4. انقر فوق Raw. 5. انسخ عنوان URL الكامل من شريط عناوين مستعرض الويب إلى مربع الحوار استيراد دفاتر الملاحظات .

      إشعار

      يعمل مربع الحوار استيراد دفاتر الملاحظات مع عناوين URL ل Git للمستودعات العامة فقط.

    3. انقر فوق استيراد.

الخطوة 3.3: إضافة وظائف التعليمات البرمجية المشتركة الداعمة لدفتر الملاحظات

  1. من مستعرض مساحة العمل، انقر بزر الماوس الأيمن فوق مجلد Git لأفضل دفاتر الملاحظات، ثم انقر فوق إنشاء > مجلد.

  2. في مربع الحوار مجلد جديد، أدخل covid_analysis، ثم انقر فوق إنشاء.

  3. من المجلد covid_analysis انقر فوق إنشاء > ملف.

  4. في مربع الحوار اسم ملف جديد، أدخل transforms.py، ثم انقر فوق إنشاء ملف.

  5. في نافذة محرر transforms.py ، أدخل التعليمات البرمجية التالية:

    import pandas as pd

# Filter by country code.
def filter_country(pdf, country="USA"):
  pdf = pdf[pdf.iso_code == country]
  return pdf

# Pivot by indicator, and fill missing values.
def pivot_and_clean(pdf, fillna):
  pdf["value"] = pd.to_numeric(pdf["value"])
  pdf = pdf.fillna(fillna).pivot_table(
    values="value", columns="indicator", index="date"
  )
  return pdf

# Create column names that are compatible with Delta tables.
def clean_spark_cols(pdf):
  pdf.columns = pdf.columns.str.replace(" ", "_")
  return pdf

# Convert index to column (works with pandas API on Spark, too).
def index_to_col(df, colname):
  df[colname] = df.index
  return df

تلميح

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

الخطوة 3.4: إضافة تبعيات التعليمات البرمجية المشتركة

تحتوي التعليمات البرمجية السابقة على العديد من تبعيات حزمة Python لتمكين تشغيل التعليمات البرمجية بشكل صحيح. في هذه البداية الفرعية، تقوم بتعريف تبعيات الحزمة هذه. يؤدي الإعلان عن التبعيات إلى تحسين إمكانية إعادة الإنتاج باستخدام إصدارات محددة بدقة من المكتبات.

  1. من مستعرض مساحة العمل، انقر بزر الماوس الأيمن فوق مجلد Git لأفضل دفاتر الملاحظات، ثم انقر فوق إنشاء > ملف.

    إشعار

    تريد أن ينتقل الملف الذي يسرد تبعيات الحزمة إلى جذر مجلد Git، وليس إلى دفاتر الملاحظات أو مجلدات covid_analysis.

  2. في مربع الحوار اسم ملف جديد، أدخل requirements.txt، ثم انقر فوق إنشاء ملف.

  3. في نافذة محرر requirements.txt ، أدخل التعليمات البرمجية التالية:

    إشعار

    requirements.txt إذا لم يكن الملف مرئيا، فقد تحتاج إلى تحديث مستعرض الويب الخاص بك.

    -i https://pypi.org/simple
attrs==21.4.0
cycler==0.11.0
fonttools==4.33.3
iniconfig==1.1.1
kiwisolver==1.4.2
matplotlib==3.5.1
numpy==1.22.3
packaging==21.3
pandas==1.4.2
pillow==9.1.0
pluggy==1.0.0
py==1.11.0
py4j==0.10.9.3
pyarrow==7.0.0
pyparsing==3.0.8
pyspark==3.2.1
pytest==7.1.2
python-dateutil==2.8.2
pytz==2022.1
six==1.16.0
tomli==2.0.1
wget==3.2

    إشعار

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

يجب أن تبدو بنية المستودع الآن كما يلي:

|-- covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
└── requirements.txt

الخطوة 3.5: تشغيل دفتر الملاحظات المعاد بناء التعليمات البرمجية

في هذه البداية الفرعية، يمكنك تشغيل دفتر الملاحظات covid_eda_modular ، الذي يستدعي التعليمات البرمجية المشتركة في covid_analysis/transforms.py.

  1. من مستعرض مساحة العمل، انقر فوق دفتر الملاحظات covid_eda_modular داخل مجلد دفاتر الملاحظات.
  2. حدد نظام المجموعة لإرفاق دفتر الملاحظات هذا به.
  3. انقر فوق تشغيل الكل.
  4. انتظر حتى يتم تشغيل دفتر الملاحظات.

بعد انتهاء تشغيل دفتر الملاحظات، يجب أن تشاهد في دفتر الملاحظات نتائج مماثلة لدفتر الملاحظات covid_eda_raw : رسم للبيانات بالإضافة إلى أكثر من 600 صف من البيانات الأولية في جدول Delta. الفرق الرئيسي مع دفتر الملاحظات هذا هو استخدام عامل تصفية مختلف (بدلا iso_code من DZA USA). إذا لم يكن نظام المجموعة قيد التشغيل بالفعل عند بدء تشغيل دفتر الملاحظات هذا، فقد يستغرق بدء تشغيل نظام المجموعة عدة دقائق قبل عرض النتائج.

  1. إلى جانب اسم دفتر الملاحظات، انقر فوق زر فرع first_modules Git.
  2. في مربع الحوار أفضل دفاتر الملاحظات ، في علامة التبويب تغييرات ، تأكد من تحديد ما يلي:
    • requirements.txt
    • covid_analysis/transforms.py
    • دفاتر الملاحظات/covid_eda_modular.py
  3. بالنسبة لرسالة الالتزام (مطلوب)، أدخل Added refactored notebook.
  4. بالنسبة للوصف (اختياري) ، أدخل This is the second version of the notebook.
  5. انقر فوق Commit & Push.
  6. انقر فوق ارتباط طلب السحب في إنشاء طلب سحب على موفر git الخاص بك في الشعار.
  7. في GitHub، أنشئ طلب السحب، ثم ادمج طلب السحب في main الفرع.
  8. مرة أخرى في مساحة عمل Azure Databricks، أغلق مربع حوار أفضل دفاتر الملاحظات إذا كان لا يزال يظهر.

الخطوة 4: اختبار التعليمات البرمجية المشتركة

في هذه الخطوة، يمكنك اختبار التعليمات البرمجية المشتركة من الخطوة الأخيرة. ومع ذلك، تريد اختبار هذه التعليمة البرمجية دون تشغيل دفتر الملاحظات covid_eda_modular نفسه. وذلك لأنه إذا فشل تشغيل التعليمات البرمجية المشتركة، فمن المحتمل أن يفشل دفتر الملاحظات نفسه في التشغيل أيضا. تريد التقاط حالات الفشل في التعليمات البرمجية المشتركة أولا قبل فشل دفتر الملاحظات الرئيسي في النهاية لاحقا. تقنية الاختبار هذه هي أفضل ممارسة لهندسة البرمجيات.

تلميح

للحصول على أساليب إضافية لاختبار دفاتر الملاحظات، بالإضافة إلى اختبار دفاتر ملاحظات R وSc scala، راجع اختبار الوحدة لدفاتر الملاحظات.

الخطوة 4.1: إنشاء فرع عمل آخر في المستودع

  1. إلى جانب اسم دفتر الملاحظات، انقر فوق زر فرع first_modules Git.
  2. في مربع الحوار أفضل دفاتر الملاحظات ، انقر فوق سهم القائمة المنسدلة بجوار فرع first_modules ، وحدد main.
  3. انقر فوق الزر سحب. إذا تمت مطالبتك بمتابعة السحب، فانقر فوق تأكيد.
  4. انقر فوق إنشاء فرع.
  5. أدخل first_tests، ثم انقر فوق إنشاء. (يمكنك إعطاء فرعك اسما مختلفا.)
  6. أغلق مربع الحوار هذا.

الخطوة 4.2: إضافة الاختبارات

في هذه البداية الفرعية، يمكنك استخدام إطار عمل pytest لاختبار التعليمات البرمجية المشتركة. في هذه الاختبارات، يمكنك تأكيد ما إذا تم تحقيق نتائج اختبار معينة. إذا نتج عن أي اختبار نتيجة غير متوقعة، فإن هذا الاختبار المعين يفشل في التأكيد وبالتالي يفشل الاختبار نفسه.

  1. من مستعرض مساحة العمل، انقر بزر الماوس الأيمن فوق مجلد Git، ثم انقر فوق إنشاء > مجلد.

  2. في مربع الحوار مجلد جديد، أدخل tests، ثم انقر فوق إنشاء.

  3. من مجلد الاختبارات، انقر فوق إنشاء > ملف.

  4. في مربع الحوار اسم ملف جديد، أدخل testdata.csv، ثم انقر فوق إنشاء ملف.

  5. في نافذة محرر testdata.csv ، أدخل بيانات الاختبار التالية:

    entity,iso_code,date,indicator,value
United States,USA,2022-04-17,Daily ICU occupancy,
United States,USA,2022-04-17,Daily ICU occupancy per million,4.1
United States,USA,2022-04-17,Daily hospital occupancy,10000
United States,USA,2022-04-17,Daily hospital occupancy per million,30.3
United States,USA,2022-04-17,Weekly new hospital admissions,11000
United States,USA,2022-04-17,Weekly new hospital admissions per million,32.8
Algeria,DZA,2022-04-18,Daily ICU occupancy,1010
Algeria,DZA,2022-04-18,Daily ICU occupancy per million,4.5
Algeria,DZA,2022-04-18,Daily hospital occupancy,11000
Algeria,DZA,2022-04-18,Daily hospital occupancy per million,30.9
Algeria,DZA,2022-04-18,Weekly new hospital admissions,10000
Algeria,DZA,2022-04-18,Weekly new hospital admissions per million,32.1

  6. من مجلد الاختبارات، انقر فوق إنشاء > ملف.

  7. في مربع الحوار اسم ملف جديد، أدخل transforms_test.py، ثم انقر فوق إنشاء ملف.

  8. في نافذة محرر transforms_test.py ، أدخل رمز الاختبار التالي. تستخدم هذه الاختبارات التركيبات القياسية pytest بالإضافة إلى pandas DataFrame المقلد في الذاكرة:

    # Test each of the transform functions.
import pytest
from textwrap import fill
import os
import pandas as pd
import numpy as np
from covid_analysis.transforms import *
from pyspark.sql import SparkSession

@pytest.fixture
def raw_input_df() -> pd.DataFrame:
  """
  Create a basic version of the input dataset for testing, including NaNs.
  """
  return pd.read_csv('tests/testdata.csv')

@pytest.fixture
def colnames_df() -> pd.DataFrame:
  df = pd.DataFrame(
    data=[[0,1,2,3,4,5]],
    columns=[
      "Daily ICU occupancy",
      "Daily ICU occupancy per million",
      "Daily hospital occupancy",
      "Daily hospital occupancy per million",
      "Weekly new hospital admissions",
      "Weekly new hospital admissions per million"
    ]
  )
  return df

# Make sure the filter works as expected.
def test_filter(raw_input_df):
  filtered = filter_country(raw_input_df)
  assert filtered.iso_code.drop_duplicates()[0] == "USA"

# The test data has NaNs for Daily ICU occupancy; this should get filled to 0.
def test_pivot(raw_input_df):
  pivoted = pivot_and_clean(raw_input_df, 0)
  assert pivoted["Daily ICU occupancy"][0] == 0

# Test column cleaning.
def test_clean_cols(colnames_df):
  cleaned = clean_spark_cols(colnames_df)
  cols_w_spaces = cleaned.filter(regex=(" "))
  assert cols_w_spaces.empty == True

# Test column creation from index.
def test_index_to_col(raw_input_df):
  raw_input_df["col_from_index"] = raw_input_df.index
  assert (raw_input_df.index == raw_input_df.col_from_index).all()

يجب أن تبدو بنية المستودع الآن كما يلي:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

الخطوة 4.3: تشغيل الاختبارات

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

إشعار

تشغيل pytest تشغيل كافة الملفات التي تتبع أسماؤها النموذج test_*.py أو /*_test.py في الدليل الحالي ودلائله الفرعية.

  1. من مستعرض مساحة العمل، انقر بزر الماوس الأيمن فوق مجلد دفاتر الملاحظات، ثم انقر فوق استيراد.
  2. في مربع الحوار استيراد دفاتر الملاحظات :

    1. ل Import from، حدد URL.

    2. أدخل عنوان URL للمحتويات الأولية لدفتر الملاحظات run_unit_tests في databricks/notebook-best-practices المستودع في GitHub. للحصول على عنوان URL هذا: i. انتقل إلى https://github.com/databricks/notebook-best-practices. ‫2. notebooks انقر فوق المجلد. 3. run_unit_tests.py انقر فوق الملف. 4. انقر فوق Raw. 5. انسخ عنوان URL الكامل من شريط عناوين مستعرض الويب إلى مربع الحوار استيراد دفاتر الملاحظات .

      إشعار

      يعمل مربع الحوار استيراد دفاتر الملاحظات مع عناوين URL ل Git للمستودعات العامة فقط.

    3. انقر فوق استيراد.

  3. حدد نظام المجموعة لإرفاق دفتر الملاحظات هذا به.
  4. انقر فوق تشغيل الكل.
  5. انتظر حتى يتم تشغيل دفتر الملاحظات.

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

يجب أن تبدو بنية المستودع الآن كما يلي:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py
  1. إلى جانب اسم دفتر الملاحظات، انقر فوق زر فرع first_tests Git.
  2. في مربع الحوار أفضل دفاتر الملاحظات ، في علامة التبويب تغييرات ، تأكد من تحديد ما يلي:
    • الاختبارات/transforms_test.py
    • دفاتر الملاحظات/run_unit_tests.py
    • الاختبارات/testdata.csv
  3. بالنسبة لرسالة الالتزام (مطلوب)، أدخل Added tests.
  4. بالنسبة للوصف (اختياري) ، أدخل These are the unit tests for the shared code..
  5. انقر فوق Commit & Push.
  6. انقر فوق ارتباط طلب السحب في إنشاء طلب سحب على موفر git الخاص بك في الشعار.
  7. في GitHub، أنشئ طلب السحب، ثم ادمج طلب السحب في main الفرع.
  8. مرة أخرى في مساحة عمل Azure Databricks، أغلق مربع حوار أفضل دفاتر الملاحظات إذا كان لا يزال يظهر.

الخطوة 5: إنشاء مهمة لتشغيل دفاتر الملاحظات

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

الخطوة 5.1: إنشاء مهمة مهمة لتشغيل دفتر ملاحظات الاختبار

  1. على الشريط الجانبي لمساحة العمل، انقر فوق مهام سير العمل.
  2. على علامة التبويب وظائف ، انقر فوق إنشاء مهمة.
  3. قم بتحرير اسم المهمة لتكون covid_report.
  4. بالنسبة إلى اسم المهمة، أدخل run_notebook_tests.
  5. بالنسبة إلى النوع، حدد دفتر الملاحظات.
  6. بالنسبة إلى Source، حدد Git provider.
  7. انقر فوق إضافة مرجع git.
  8. في مربع الحوار معلومات Git:
    1. بالنسبة إلى عنوان URL لمستودع Git، أدخل نسخة GitHub مع عنوان URL ل HTTPS لمستودع GitHub الخاص بك. تفترض هذه المقالة أن عنوان URL الخاص بك ينتهي ب best-notebooks.git، على سبيل المثال https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. بالنسبة لموفر Git، حدد GitHub.
    3. لمرجع Git (الفرع / العلامة / التثبيت)، أدخل main.
    4. بجوار مرجع Git (الفرع / العلامة / الالتزام)، حدد الفرع.
    5. انقر فوق تأكيد.
  9. بالنسبة إلى Path، أدخل notebooks/run_unit_tests. لا تقم بإضافة .py ملحق الملف.
  10. بالنسبة لنظام المجموعة، حدد نظام المجموعة من الخطوة السابقة.
  11. انقر فوق إنشاء مهمة.

إشعار

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

الخطوة 5.2: إنشاء مهمة مهمة لتشغيل دفتر الملاحظات الرئيسي

  1. انقر فوق الأيقونة + إضافة مهمة .
  2. تظهر قائمة منبثقة. حدِّد Notebook.
  3. بالنسبة إلى اسم المهمة، أدخل run_main_notebook.
  4. بالنسبة إلى النوع، حدد دفتر الملاحظات.
  5. بالنسبة إلى Path، أدخل notebooks/covid_eda_modular. لا تقم بإضافة .py ملحق الملف.
  6. بالنسبة لنظام المجموعة، حدد نظام المجموعة من الخطوة السابقة.
  7. تحقق من أن يعتمد على القيمة هي run_notebook-tests.
  8. انقر فوق إنشاء مهمة.

الخطوة 5.3 تشغيل المهمة

  1. انقر فوق تشغيل الآن.

  2. في النافذة المنبثقة، انقر فوق عرض التشغيل.

    إشعار

    إذا اختفت النافذة المنبثقة بسرعة كبيرة، فقم بما يلي:

    1. على الشريط الجانبي في بيئة علوم البيانات والهندسة أو Databricks التعلم الآلي، انقر فوق مهام سير العمل.
    2. على علامة التبويب تشغيل الوظيفة، انقر فوق قيمة وقت البدء لأحدث مهمة مع covid_report في عمود الوظائف.

  3. للاطلاع على نتائج المهمة، انقر فوق لوحة run_notebook_tests أو لوحة run_main_notebook أو كليهما. النتائج على كل لوحة هي نفسها كما لو قمت بتشغيل دفاتر الملاحظات بنفسك، واحدا تلو الآخر.

إشعار

تم تشغيل هذه الوظيفة عند الطلب. لإعداد هذه الوظيفة للتشغيل بشكل منتظم، راجع إضافة جدول وظيفة.

(اختياري) الخطوة 6: إعداد المستودع لاختبار التعليمات البرمجية وتشغيل دفتر الملاحظات تلقائيا كلما تغيرت التعليمات البرمجية

في الخطوة السابقة، استخدمت وظيفة لاختبار التعليمات البرمجية المشتركة تلقائيا وتشغيل دفاتر الملاحظات في نقطة زمنية أو على أساس متكرر. ومع ذلك، قد تفضل تشغيل الاختبارات تلقائيا عند دمج التغييرات في مستودع GitHub الخاص بك، باستخدام أداة CI/CD مثل GitHub Actions.

الخطوة 6.1: إعداد وصول GitHub إلى مساحة العمل الخاصة بك

في هذه الخطوة الفرعية، يمكنك إعداد سير عمل GitHub Actions الذي يقوم بتشغيل المهام في مساحة العمل كلما تم دمج التغييرات في المستودع الخاص بك. يمكنك القيام بذلك عن طريق منح GitHub رمزا مميزا فريدا ل Azure Databricks للوصول.

لأسباب أمنية، يمنعك Databricks من منح رمز الوصول الشخصي لمستخدم مساحة عمل Azure Databricks إلى GitHub. بدلا من ذلك، توصي Databricks بمنح GitHub رمزا مميزا لمعرف Microsoft Entra مقترنا بكيان خدمة معرف Microsoft Entra. للحصول على إرشادات، راجع قسم Azure في صفحة Run Databricks Notebook GitHub Action في GitHub Actions Marketplace.

هام

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

الخطوة 6.2: إضافة سير عمل إجراءات GitHub

في هذه البداية الفرعية، يمكنك إضافة سير عمل GitHub Actions لتشغيل دفتر الملاحظات run_unit_tests كلما كان هناك طلب سحب إلى المستودع.

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

  1. في موقع الويب الخاص بم repo GitHub، انقر فوق علامة التبويب Code .

  2. انقر فوق السهم الموجود بجانب الرئيسي لتوسيع القائمة المنسدلة تبديل الفروع أو العلامات .

  3. في مربع البحث عن فرع أو إنشائه، أدخل adding_github_actions.

  4. انقر فوق إنشاء فرع: adding_github_actions من "main".

  5. انقر فوق إضافة ملف > إنشاء ملف جديد.

  6. لتسمية الملف، أدخل .github/workflows/databricks_pull_request_tests.yml.

  7. في نافذة المحرر، أدخل التعليمات البرمجية التالية. تستخدم هذه التعليمة البرمجية خطاف pull_request من إجراء تشغيل دفتر ملاحظات Databricks GitHub لتشغيل دفتر الملاحظات run_unit_tests .

    في التعليمة البرمجية التالية، استبدل:

    name: Run pre-merge Databricks tests

on:
  pull_request:

env:
  # Replace this value with your workspace instance name.
  DATABRICKS_HOST: https://<your-workspace-instance-name>

jobs:
  unit-test-notebook:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repo
        uses: actions/checkout@v2
      - name: Run test notebook
        uses: databricks/run-notebook@main
        with:
          databricks-token: <your-access-token>

          local-notebook-path: notebooks/run_unit_tests.py

          existing-cluster-id: <your-cluster-id>

          git-commit: "${{ github.event.pull_request.head.sha }}"

          # Grant all users view permission on the notebook's results, so that they can
          # see the result of the notebook, if they have related access permissions.
          access-control-list-json: >
            [
              {
                "group_name": "users",
                "permission_level": "CAN_VIEW"
              }
            ]
          run-name: "EDA transforms helper module unit tests"

  8. انقر فوق Commit changes.

  9. في مربع الحوار Commit changes ، أدخل Create databricks_pull_request_tests.yml في رسالة Commit

  10. حدد Commit مباشرة إلى فرع adding_github_actions وانقر فوق Commit changes.

  11. في علامة التبويب التعليمات البرمجية، انقر فوق مقارنة طلب السحب، ثم قم بإنشاء طلب السحب.

  12. في صفحة طلب السحب، انتظر حتى تعرض الأيقونة الموجودة بجانب Run pre-merge Databricks tests / unit-test-notebook (pull_request) علامة اختيار خضراء. (قد يستغرق ظهور الأيقونة بضع لحظات.) إذا كانت هناك علامة X حمراء بدلا من علامة اختيار خضراء، فانقر فوق تفاصيل لمعرفة السبب. إذا لم تعد الأيقونة أو التفاصيل تظهر، فانقر فوق إظهار كافة عمليات التحقق.

  13. إذا ظهرت علامة الاختيار الخضراء، فدمج طلب السحب في main الفرع.

(اختياري) الخطوة 7: تحديث التعليمات البرمجية المشتركة في GitHub لتشغيل الاختبارات

في هذه الخطوة، يمكنك إجراء تغيير على التعليمات البرمجية المشتركة ثم دفع التغيير إلى مستودع GitHub الخاص بك، والذي يقوم على الفور بتشغيل الاختبارات تلقائيا، استنادا إلى إجراء GitHub من الخطوة السابقة.

الخطوة 7.1: إنشاء فرع عمل آخر في المستودع

  1. من مستعرض مساحة العمل، افتح مجلد Git لأفضل دفاتر الملاحظات.
  2. إلى جانب اسم المجلد، انقر فوق زر فرع first_tests Git.
  3. في مربع الحوار أفضل دفاتر الملاحظات ، انقر فوق سهم القائمة المنسدلة بجوار فرع first_tests ، وحدد main.
  4. انقر فوق الزر سحب. إذا تمت مطالبتك بمتابعة السحب، فانقر فوق تأكيد.
  5. + انقر فوق الزر (إنشاء فرع).
  6. أدخل trigger_tests، ثم انقر فوق إنشاء. (يمكنك إعطاء فرعك اسما مختلفا.)
  7. أغلق مربع الحوار هذا.

الخطوة 7.2: تغيير التعليمات البرمجية المشتركة

  1. من مستعرض مساحة العمل، في مجلد Git لأفضل دفاتر الملاحظات، انقر فوق ملف covid_analysis/transforms.py.

  2. تغيير السطر الثالث من هذا الملف:

    # Filter by country code.

    إلى هذا:

    # Filter by country code. If not specified, use "USA."

الخطوة 7.3: تحقق من التغيير لتشغيل الاختبارات

  1. إلى جانب اسم الملف، انقر فوق زر فرع trigger_tests Git.
  2. في مربع الحوار أفضل دفاتر الملاحظات ، في علامة التبويب تغييرات ، تأكد من تحديد covid_analysis/transforms.py .
  3. بالنسبة لرسالة الالتزام (مطلوب)، أدخل Updated comment.
  4. بالنسبة للوصف (اختياري) ، أدخل This updates the comment for filter_country.
  5. انقر فوق Commit & Push.
  6. انقر فوق ارتباط طلب السحب في إنشاء طلب سحب على موفر git الخاص بك في الشعار، ثم قم بإنشاء طلب السحب في GitHub.
  7. في صفحة طلب السحب، انتظر حتى تعرض الأيقونة الموجودة بجانب Run pre-merge Databricks tests / unit-test-notebook (pull_request) علامة اختيار خضراء. (قد يستغرق ظهور الأيقونة بضع لحظات.) إذا كانت هناك علامة X حمراء بدلا من علامة اختيار خضراء، فانقر فوق تفاصيل لمعرفة السبب. إذا لم تعد الأيقونة أو التفاصيل تظهر، فانقر فوق إظهار كافة عمليات التحقق.
  8. إذا ظهرت علامة الاختيار الخضراء، فدمج طلب السحب في main الفرع.