مشاركة عبر

استكشاف أخطاء Python وإصلاحها في Azure Functions

  • مقالة

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

إشعار

يتم دعم نموذج برمجة Python v2 فقط في وقت تشغيل وظائف 4.x. لمزيد من المعلومات، راجع نظرة عامة على إصدارات وقت تشغيل Azure Functions.

فيما يلي أقسام استكشاف الأخطاء وإصلاحها للمشكلات الشائعة في وظائف Python:

على وجه التحديد مع نموذج v2، فيما يلي بعض المشكلات المعروفة والحلول البديلة الخاصة بها:

تتضمن إرشادات استكشاف الأخطاء وإصلاحها العامة لوظائف Python ما يلي:

استكشاف الأخطاء وإصلاحها: ModuleNotFoundError

يساعدك هذا القسم في استكشاف الأخطاء المتعلقة بالوحدة في تطبيق وظائف Python وإصلاحها. عادةً ما تؤدي هذه الأخطاء إلى ظهور رسالة خطأ Azure Functions التالية:

الاستثناء: ModuleNotFoundError: لا توجد وحدة نمطية تسمى "module_name".

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

عرض ملفات المشروع

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

  • إذا كان تطبيق الوظائف يحتوي WEBSITE_RUN_FROM_PACKAGE على إعداد تطبيق وكانت قيمته عنوان URL، فنزل الملف عن طريق نسخ عنوان URL ولصقه في المستعرض.
  • إذا تم WEBSITE_RUN_FROM_PACKAGE تعيين تطبيق الدالة إلى 1، فانتقل إلى https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages وقم بتنزيل الملف من أحدث href عنوان URL.
  • إذا لم يكن تطبيق الوظائف يحتوي على أي من إعدادات التطبيق السابقة، فانتقل إلى https://<app-name>.scm.azurewebsites.net/api/settings وابحث عن عنوان URL ضمن SCM_RUN_FROM_PACKAGE. قم بتنزيل الملف عن طريق نسخ عنوان URL ولصقه في المستعرض.
  • إذا حلت الاقتراحات المشكلة، فانتقل إلى https://<app-name>.scm.azurewebsites.net/DebugConsole واعرض المحتوى ضمن /home/site/wwwroot.

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

تشخيص خطأ ModuleNotFoundError

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

لا يمكن العثور على الحزمة

انتقل إلى .python_packages/lib/python3.6/site-packages/<package-name> أو .python_packages/lib/site-packages/<package-name>. إذا كان مسار الملف غير موجود، فمن المحتمل أن يكون هذا المسار المفقود هو السبب الجذري.

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

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

لم يتم حل الحزمة باستخدام عجلة Linux المناسبة

انتقل إلى .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info أو .python_packages/lib/site-packages/<package-name>-<version>-dist-info. استخدم محرر النصوص المفضل لديك لفتح ملف المستخدم الفائق وتحقق من قسم العلامة:. قد تكون المشكلة أن قيمة العلامة لا تحتوي على linux.

تعمل وظائف Python فقط على Linux في Azure. يعمل وقت تشغيل الوظائف v2.x على Debian Stretch، ويتم تشغيل وقت تشغيل v3.x على Debian Buster. من المتوقع أن تحتوي البيانات الاصطناعية على برامج Linux الثنائية المناسبة. عند استخدام العلامة --build local في Core Tools أو أدوات تابعة لجهة خارجية أو أدوات قديمة، قد يؤدي ذلك إلى استخدام الثنائيات القديمة.

للتخفيف من المشكلة، راجع تمكين الإنشاء عن بعد أو إنشاء تبعيات أصلية.

الحزمة غير متوافقة مع إصدار مترجم Python

انتقل إلى .python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info أو .python_packages/lib/site-packages/<package-name>-<version>-dist-info. في محرر النص، افتح ملف METADATA وتحقق من قسم Classifiers: . إذا كان القسم لا يحتوي على Python :: 3أو Python :: 3.8Python :: 3.6Python :: 3.7Python :: 3.9، فإن إصدار الحزمة إما قديم جدا أو، على الأرجح، إنه خارج الصيانة بالفعل.

يمكنك التحقق من إصدار Python لتطبيق الوظيفة من مدخل Azure. انتقل إلى صفحة مورد نظرة عامة على تطبيق الوظائف للعثور على إصدار وقت التشغيل. يدعم إصدار وقت التشغيل إصدارات Python كما هو موضح في نظرة عامة على إصدارات وقت تشغيل Azure Functions.

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

تتعارض الحزمة مع حزم أخرى

إذا تحققت من حل الحزمة بشكل صحيح باستخدام عجلات Linux المناسبة، فقد يكون هناك تعارض مع الحزم الأخرى. في حزم معينة، قد توضح وثائق PyPi الوحدات النمطية غير المتوافقة. على سبيل المثال، في azure 4.0.0، تجد العبارة التالية:

هذه الحزمة غير متوافقة مع azure-storage. إذا قمت بتثبيت azure-storage، أو إذا قمت بتثبيت azure 1.x/2.x ولم تقم بإلغاء تثبيت azure-storage، يجب إلغاء تثبيت azure-storage أولا.

يمكنك العثور على الوثائق الخاصة بإصدار الحزمة في https://pypi.org/project/<package-name>/<package-version>.

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

تدعم الحزمة أنظمة Windows وmacOS الأساسية فقط

افتح requirements.txt باستخدام محرر نصوص وتحقق من الحزمة في https://pypi.org/project/<package-name>. تعمل بعض الحزم فقط على أنظمة Windows وmacOS الأساسية. على سبيل المثال، يعمل pywin32 على Windows فقط.

Module Not Found قد لا يحدث الخطأ عند استخدام Windows أو macOS للتطوير المحلي. ولكن فشلت الحزمة في الاستيراد في Azure Functions، والتي تستخدم Linux في وقت التشغيل. من المحتمل أن تكون هذه المشكلة ناتجة عن استخدام pip freeze لتصدير البيئة الظاهرية إلى requirements.txt من جهاز Windows أو macOS أثناء تهيئة المشروع.

للتخفيف من المشكلة، راجع استبدال الحزمة بما يعادلها أو requirements.txt الحرف اليدوية.

تخفيف خطأ ModuleNotFoundError

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

تمكين الإنشاء عن بعد

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

تأكد من تثبيت أحدث إصدار من ملحق Azure Functions لـ Visual Studio Code. تحقق من وجود ملف .vscode/settings.json وأنه يحتوي على الإعداد "azureFunctions.scmDoBuildDuringDeployment": true. إذا لم يكن الأمر كذلك، فأنشئ الملف مع azureFunctions.scmDoBuildDuringDeployment تمكين الإعداد، ثم أعد نشر المشروع.

إنشاء تبعيات أصلية

تأكد من تثبيت أحدث إصدارات كل من Docker وAzure Functions Core Tools . انتقل إلى مجلد مشروع الوظيفة المحلي، واستخدم func azure functionapp publish <app-name> --build-native-deps للنشر.

تحديث الحزمة إلى أحدث إصدار

في أحدث إصدار حزمة من https://pypi.org/project/<package-name>، تحقق من قسم Classifiers: . يجب أن تكون الحزمة OS Independent، أو متوافقة مع POSIX أو POSIX :: Linux في نظام التشغيل. أيضا، يجب أن تحتوي لغة البرمجة على: Python :: 3أو Python :: 3.6أو Python :: 3.8Python :: 3.7أو أو .Python :: 3.9

إذا كانت عناصر الحزمة هذه صحيحة، يمكنك تحديث الحزمة إلى أحدث إصدار عن طريق تغيير السطر <package-name>~=<latest-version> في requirements.txt.

إنشاء requirements.txt

يستخدم بعض المطورين pip freeze > requirements.txt لإنشاء قائمة بحزم Python لبيئات تطويرهم. على الرغم من أن هذه الملاءمة يجب أن تعمل في معظم الحالات، يمكن أن توجد مشكلات في سيناريوهات النشر عبر الأنظمة الأساسية، مثل تطوير الوظائف محلياً على Windows أو macOS، وليس النشر في تطبيق وظيفة يعمل على Linux. في هذا السيناريو، يمكن أن يقدم pip freeze تبعيات خاصة بنظام التشغيل غير متوقعة أو تبعيات لبيئة التطوير المحلية. يمكن لهذه التبعيات كسر تطبيق وظائف Python عند تشغيله على Linux.

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

استبدل الحزمة بقيم مقابلة

أولا، ألق نظرة على أحدث إصدار من الحزمة في https://pypi.org/project/<package-name>. عادة ما تحتوي هذه الحزمة على صفحة GitHub الخاصة بها. انتقل إلى قسم المشكلات على GitHub وابحث لمعرفة ما إذا كانت المشكلة قد تم إصلاحها. إذا تم إصلاحها، فقم بتحديث الحزمة إلى أحدث إصدار.

في بعض الأحيان، قد تكون الحزمة قد تم دمجها في مكتبة Python القياسية (مثل pathlib). إذا كان الأمر كذلك، لأننا نقدم توزيع Python معينا في Azure Functions (Python 3.6 وPython 3.7 وPython 3.8 وPython 3.9)، يجب إزالة الحزمة الموجودة في ملف requirements.txt.

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

تعطيل علامة عزل التبعية

تعيين إعداد التطبيق PYTHON_ISOLATE_WORKER_DEPENDENCIES إلى قيمة 0.

استكشاف الأخطاء وإصلاحها: لا يمكن استيراد "cygrpc"

يساعدك هذا القسم على استكشاف الأخطاء المتعلقة ب 'cygrpc' وإصلاحها في تطبيق وظائف Python. عادةً ما تؤدي هذه الأخطاء إلى ظهور رسالة خطأ Azure Functions التالية:

يتعذر استيراد الاسم 'cygrpc' من 'grpc._cython'

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

تشخيص الخطأ المرجعي "cygrpc"

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

مترجم Python لا يتطابق مع بنية نظام التشغيل

يحدث عدم التطابق هذا على الأرجح بسبب تثبيت مترجم Python بالإصدار 32 بت على نظام التشغيل 64 بت.

إذا كنت تعمل على نظام تشغيل x64، فتأكد من أن مترجم Python الإصدار 3.6 أو 3.7 أو 3.8 أو 3.9 هو أيضا على إصدار 64 بت.

يمكنك التحقق من بت مترجم Python عن طريق تشغيل الأوامر التالية:

على Windows في PowerShell، قم بتشغيل py -c 'import platform; print(platform.architecture()[0])'.

على غلاف يشبه Unix، قم بتشغيل python3 -c 'import platform; print(platform.architecture()[0])'.

إذا كان هناك عدم تطابق بين بت مترجم Python وبنية نظام التشغيل، فقم بتنزيل مترجم Python مناسب من Python Software Foundation.

مترجم Python غير مدعوم من قبل Azure Functions Python Worker

يدعم Azure Functions Python Worker إصدارات Python معينة فقط.

تحقق لمعرفة ما إذا كان مترجم Python يطابق الإصدار المتوقع من خلال py --version Windows أو python3 --version في أنظمة تشبه Unix. تأكد من أن نتيجة الإرجاع هي أحد إصدارات Python المدعومة.

إذا كان إصدار مترجم Python لا يفي بمتطلبات Azure Functions، فبادر بدلا من ذلك بتنزيل إصدار مترجم Python الذي تدعمه Functions من Python Software Foundation.

استكشاف الأخطاء وإصلاحها: تم إنهاء python باستخدام التعليمات البرمجية 137

عادةً ما تحدث أخطاء الرمز 137 بسبب مشكلات نفاد الذاكرة في تطبيق وظيفة Python. نتيجة لذلك، تحصل على رسالة خطأ Azure Functions التالية:

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: تم إنهاء python باستخدام التعليمات البرمجية 137

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

لتحليل ازدحام الذاكرة في تطبيق الوظائف، راجع ملف تعريف تطبيق وظائف Python في بيئة التطوير المحلية.

استكشاف الأخطاء وإصلاحها: تم إنهاء python باستخدام التعليمات البرمجية 139

يساعدك هذا القسم في استكشاف الأخطاء المتعلقة بخطأ التجزئة في تطبيق وظائف Python وإصلاحها. عادةً ما تؤدي هذه الأخطاء إلى ظهور رسالة خطأ Azure Functions التالية:

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: تم إنهاء python باستخدام التعليمات البرمجية 139

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

تراجع من حزم الجهات الخارجية

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

إلغاء الانتقاء من ملف .pkl تالف

إذا كان تطبيق الوظائف يستخدم مكتبة Python pickle لتحميل كائن Python من ملف .pkl ، فمن المحتمل أن يحتوي الملف على سلسلة بايت مشوهة أو مرجع عنوان غير صالح. للاسترداد من هذه المشكلة، حاول التعليق على الدالة pickle.load() .

تضارب اتصال Pyodbc

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

فشل مشغلات المزامنة

يمكن أن يكون الخطأ Sync triggers failed ناتجا عن عدة مشكلات. أحد الأسباب المحتملة هو التعارض بين التبعيات المعرفة من قبل العميل والوحدات النمطية المضمنة في Python عند تشغيل وظائفك في خطة App Service. لمزيد من المعلومات، راجع إدارة الحزم.

استكشاف الأخطاء وإصلاحها: تعذر تحميل الملف أو التجميع

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

هذه رسالة مثال لهذا الخطأ:

DurableTask.Netherite.AzureFunctions: تعذر تحميل الملف أو التجميع 'Microsoft.Azure.WebJobs.Extensions.DurableTask, Version=2.0.0.0, Culture=neutral, PublicKeyToken=014045d636e89289'.
لا يستطيع النظام العثور على الملف المحدد."

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

func host start --verbose

من المحتمل أنك ترى مشكلة التخزين المؤقت هذه عندما ترى سجل تحميل ملحق مثل Loading startup extension <> هذا لا يتبعه Loaded extension <>.

لحل هذه المشكلة:

  1. ابحث عن .azure-functions-core-tools المسار عن طريق تشغيل:

    func GetExtensionBundlePath

  2. حذف دليل .azure-functions-core-tools.

    rm -r <insert path>/.azure-functions-core-tools

يتم إعادة إنشاء دليل ذاكرة التخزين المؤقت عند تشغيل Core Tools مرة أخرى.

استكشاف الأخطاء وإصلاحها: غير قادر على حل اتصال Azure Storage

قد ترى هذا الخطأ في الإخراج المحلي كرسالة التالية:

Microsoft.Azure.WebJobs.Extensions.DurableTask: غير قادر على حل اتصال تخزين Azure المسمى "التخزين".
لا يمكن أن تكون القيمة خالية. (المعلمة 'الموفر')

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

  • استخدم محاكي تخزين مثل Azurite. هذا الخيار جيد عندما لا تخطط لاستخدام حساب تخزين في تطبيق الدالة الخاص بك.

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

لم يتم العثور على الوظائف بعد التوزيع

هناك العديد من مشكلات البناء الشائعة التي يمكن أن تتسبب في عدم العثور على وظائف Python من قبل المضيف بعد نشر ناجح على ما يبدو:

  • يجب تشغيل تجمع الوكلاء على Ubuntu لضمان استعادة الحزم بشكل صحيح من خطوة الإنشاء. تأكد من أن قالب التوزيع يتطلب بيئة Ubuntu للبناء والنشر.

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

    pip install --target="./FunctionApp1/.python_packages/lib/site-packages" -r ./FunctionApp1/requirements.txt

  • يجب أن يقوم القالب بإنشاء حزمة توزيع يمكن تحميلها في /home/site/wwwroot. في Azure Pipelines، يتم ذلك بواسطة ArchiveFiles المهمة.

مشكلات التطوير في مدخل Microsoft Azure

عند استخدام مدخل Microsoft Azure، خذ بعين الاعتبار هذه المشكلات المعروفة والحلول البديلة الخاصة بها:

  • هناك قيود عامة لكتابة التعليمات البرمجية للدالة في المدخل. لمزيد من المعلومات، راجع قيود التطوير في مدخل Microsoft Azure.
  • لحذف دالة من تطبيق دالة في المدخل، قم بإزالة التعليمات البرمجية للدالة من الملف نفسه. لا يعمل الزر Delete لإزالة الدالة عند استخدام نموذج برمجة Python v2.
  • عند إنشاء دالة في المدخل، قد يتم إعلامك باستخدام أداة مختلفة للتطوير. هناك عدة سيناريوهات حيث لا يمكنك تحرير التعليمات البرمجية الخاصة بك في المدخل، بما في ذلك عند اكتشاف خطأ في بناء الجملة. في هذه السيناريوهات، استخدم Visual Studio Code أو Azure Functions Core Tools لتطوير ونشر التعليمات البرمجية للدالة.

الخطوات التالية

إذا لم تتمكن من حل المشكلة، فاتصل بفريق Azure Functions:

الإبلاغ عن مشكلة لم يتم حلها