إنشاء أول دالة دائمة باستخدام Python

Durable Functions هو امتداد ل Azure Functions يتيح لك كتابة وظائف ذات حالة في بيئة بلا خادم. يدير الامتداد الحالة ونقاط الفحص ويعيد تشغيلها لك.

في هذه المقالة، نتعلم طريقة استخدام ملحق Visual Studio Code Azure Functions لإنشاء دالة "hello world" دائمة واختبارها محلية. تنسق هذه الوظيفة وتسلسل الاستدعاءات معًا إلى الوظائف الأخرى. يمكنك بعد ذلك نشر التعليمات البرمجية للوظيفة في Azure.

المتطلبات الأساسية

لإكمال هذا البرنامج التعليمي:

• ثبّت Visual Studio Code.

• تثبيت ملحق Azure Functions لـVisual Studio Code.

• تأكد من حصولك على أحدث إصدار من Azure Functions Core Tools.

• تتطلب الدوال الدائمة حساب تخزين في Azure. تحتاج إلى شتراك Azure.

• تأكد من تثبيت الإصدار 3.7 أو 3.8 أو 3.9 أو 3.10 من Python .

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

إنشاء مشروعك المحلي

في هذا القسم، يمكن استخدامVisual Studio Code لإنشاء مشروع Azure Functions محلي.

1. في Visual Studio Code، اضغط على F1 (أو Ctrl/Cmd+Shift+P) لفتح لوحة الأوامر. في لوحة الأوامر، ابحث عن Azure Functions: Create New Project... واختره.

   

2. اختيار موقع مجلد فارغ للمشروع، واختيار تحديد.

1. اتبع المطالبات وأدخل المعلومات التالية:

   المطالبة	قيمة	‏‏الوصف
   تحديد اللغة الخاصة بمشروع تطبيق الدالة	Python	إنشاء مشروع Python Functions محلياً.
   تحديد إصدار	وظائف Azure Functions v4	سيظهر لك هذا الخيار فقط عندما لا تكون الأدوات الأساسية مثبتة مسبقاً. في هذه الحالة، تُثبت الأدوات الأساسية في المرة الأولى التي يُشغل فيها التطبيق.
   إصدار Python	Python 3.7 أو 3.8 أو 3.9 أو 3.10	سيقوم Visual Studio Code بإنشاء بيئة ظاهرية باستخدام الإصدار الذي تحدده.
   تحديد قالب للدالة الأولى لمشروعك	تخطي حالياً
   تحديد طريقة فتح مشروعك	فتحه في النافذة الحالية	أعد فتح Visual Studio Code في المجلد الذي اخترته.

1. اتبع المطالبات وأدخل المعلومات التالية:

   المطالبة	قيمة	‏‏الوصف
   تحديد لغة	Python (نموذج البرمجة V2)	إنشاء مشروع وظائف Python محلي باستخدام نموذج البرمجة V2.
   تحديد إصدار	وظائف Azure Functions v4	سيظهر لك هذا الخيار فقط عندما لا تكون الأدوات الأساسية مثبتة مسبقاً. في هذه الحالة، تُثبت الأدوات الأساسية في المرة الأولى التي يُشغل فيها التطبيق.
   إصدار Python	Python 3.7 أو 3.8 أو 3.9 أو 3.10	سيقوم Visual Studio Code بإنشاء بيئة ظاهرية باستخدام الإصدار الذي تحدده.
   تحديد طريقة فتح مشروعك	فتحه في النافذة الحالية	أعد فتح Visual Studio Code في المجلد الذي اخترته.

يثبت Visual Studio Code أدوات Azure Functions Core إن لزم الأمر ذلك. كما أنها تُشنأ مشروعاً لتطبيق دالة في مجلد. يحتوي هذا المشروع على ملفي التكوين host.json وlocal.settings.json.

كما يُنشأ ملف requirements.txt في مجلد الجذر. وهو يحدد حزم Python اللازمة لتشغيل تطبيق الوظائف الخاص بك.

تثبيت نموذج azure-functions-durable من PyPI

عند إنشاء المشروع، ينشئ ملحق Azure Functions Visual Studio Code تلقائيًا بيئة ظاهرية باستخدام إصدار Python المحدد. يجب عليك تنشيط البيئة الظاهرية في محطة طرفية وتثبيت بعض التبعيات التي تتطلبها Azure Functions وDurable Functions.

1. فتح الملف requirements.txt في المحرر وتغيير محتواه إلى ما يلي:

   azure-functions
   azure-functions-durable
   

2. فتح المحطة الطرفية المتكاملة للمحرر في المجلد الحالي ( Ctrl + Shift + `).

3. في المحطة المتكاملة، تنشيط البيئة الظاهرية في المجلد الحالي:

   Linux

   source .venv/bin/activate
   

   MacOS

   source .venv/bin/activate
   

   Windows

   .venv\scripts\activate
   

4. في المحطة المتكاملة حيث تُنشط البيئة الظاهرية، استخدام النقطة لتثبيت الحزم التي حددتها للتو.

   python -m pip install -r requirements.txt
   

إنشاء دوالك الخاصة

يحتوي تطبيق "Durable Functions" الأساسي على ثلاث دوال:

• دالة المنسق - تصف سير عمل ينسق الدوال الأخرى.
• دالة النشاط - تستدعيها "دالة المنسق"، وتُنفذ العمل، وتُرجع قيمة بشكل اختياري.
• دالة العميل - هي دالة عادية من Azure Function وتبدأ بدالة منسق. يستخدم هذا المثال دالة HTTP المشغلة.

دالة المنسق

يمكن استخدام قالب لإنشاء تعليمة برمجية لدالة دائمة في مشروعك.

1. في لوحة الأوامر، ابحث عن Azure Functions: Create Function... واختره.

2. اتبع المطالبات وأدخل المعلومات التالية:

   المطالبة	قيمة	‏‏الوصف
   تحديد قالب لدالتك	منسق Durable Functions	إنشاء تنسيق Durable Functions
   منح الدالة اسماً	HelloOrchestrator	اسم دالتك الدائمة

لقد قمت بإضافة منسق لتنسيق وظائف النشاط. افتح HelloOrchestrator/__init__.py لرؤية دالة المنسق. كل استدعاء لـ context.call_activity يستدعي دالة نشاط باسم Hello.

بعد ذلك، تُضاف دالة النشاط Hello المشار إليها.

دالة النشاط

1. في لوحة الأوامر، ابحث عن Azure Functions: Create Function... واختره.

2. اتبع المطالبات وأدخل المعلومات التالية:

   المطالبة	قيمة	‏‏الوصف
   تحديد قالب لدالتك	نشاط Durable Functions	إنشاء دالة نشاط
   منح الدالة اسماً	أهلا	اسم دالة النشاط لديك

لقد اُضيفت دالة النشاط Hello التي يستدعيها المنسق. افتح Hello/__init__.py لترى أنها تحمل اسمًا باعتبارها إدخالاً وترجع باعتبارها تحية. دالة النشاط هي المكان الذي ستقوم فيه بتنفيذ إجراءات، مثل إجراء استدعاء لقاعدة بيانات أو إجراء عملية حسابية.

وأخيراً، ستضيف دالة تشغيل HTTP التي تبدأ التنسيق.

دالة العميل (بادئ HTTP)

1. في لوحة الأوامر، ابحث عن Azure Functions: Create Function... واختره.

2. اتبع المطالبات وأدخل المعلومات التالية:

   المطالبة	قيمة	‏‏الوصف
   تحديد قالب لدالتك	بادئ Durable Functions HTTP	إنشاء دالة بادئ HTTP
   منح الدالة اسماً	DurableFunctionsHttpStart	اسم وظيفة العميل
   مستوى التخويل	مجهول	لأغراض العرض التوضيحي، السماح باستدعاء الدالة دون مصادقة

وأخيراً، ستضيف دالة مشغلة بـ HTTP التي تبدأ التنسيق. افتح DurableFunctionsHttpStart/__init__.py لترى أنها تستخدم client.start_new لتبدأ تزامنًا جديدًا. بعد ذلك، الدالة ستستخدم client.create_check_status_response لإرجاع استجابة HTTP تحتوي على عناوين URL التي يمكن استخدامها لمراقبة التنسيق الجديد وإدارته.

لديك الآن تطبيق "Durable Functions" يمكن تشغيله محلياً وتوزيعه في Azure.

المتطلبات

يتطلب الإصدار 2 من نموذج برمجة Python الحد الأدنى من الإصدارات التالية:

• Azure Functions Runtime v4.16+
• Azure Functions Core Tools v4.0.5095+ (إذا كان يعمل محليا)
• azure-functions-durable v1.2.4+

تمكين نموذج البرمجة v2

إعداد التطبيق التالي مطلوب لتشغيل نموذج البرمجة v2:

• الاسم: AzureWebJobsFeatureFlags
• القيمة: EnableWorkerIndexing

إذا كنت تعمل محليا باستخدام Azure Functions Core Tools، فيجب عليك إضافة هذا الإعداد إلى ملفك local.settings.json . إذا كنت تعمل في Azure، فاتبع هذه الخطوات باستخدام الأداة التي تختارها:

Azure CLI

استبدل <FUNCTION_APP_NAME> و <RESOURCE_GROUP_NAME> باسم تطبيق الوظائف ومجموعة الموارد، على التوالي.

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings AzureWebJobsFeatureFlags=EnableWorkerIndexing

Azure PowerShell

استبدل <FUNCTION_APP_NAME> و <RESOURCE_GROUP_NAME> باسم تطبيق الوظائف ومجموعة الموارد، على التوالي.

Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"AzureWebJobsFeatureFlags" = "EnableWorkerIndexing"}

تعليمة VS الظاهرية

1. تأكد من تثبيت ملحق Azure Functions ل VS Code
2. اضغط على F1 لفتح لوحة الأوامر. في لوحة الأوامر، ابحث عن Azure Functions: Add New Setting... واختره.
3. اختر تطبيق الاشتراك والدالة عند مطالبتك
4. للحصول على الاسم، اكتب AzureWebJobsFeatureFlags واضغط على مفتاح الإدخال Enter.
5. للحصول على القيمة، اكتب EnableWorkerIndexing واضغط على مفتاح الإدخال Enter.

لإنشاء تطبيق Durable Functions أساسي باستخدام أنواع الوظائف الثلاثة هذه، استبدل محتويات function_app.py برمز Python التالي.

import azure.functions as func
import azure.durable_functions as df

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

# An HTTP-Triggered Function with a Durable Functions Client binding
@myApp.route(route="orchestrators/{functionName}")
@myApp.durable_client_input(client_name="client")
async def http_start(req: func.HttpRequest, client):
    function_name = req.route_params.get('functionName')
    instance_id = await client.start_new(function_name)
    response = client.create_check_status_response(req, instance_id)
    return response

# Orchestrator
@myApp.orchestration_trigger(context_name="context")
def hello_orchestrator(context):
    result1 = yield context.call_activity("hello", "Seattle")
    result2 = yield context.call_activity("hello", "Tokyo")
    result3 = yield context.call_activity("hello", "London")

    return [result1, result2, result3]

# Activity
@myApp.activity_trigger(input_name="city")
def hello(city: str):
    return f"Hello {city}"

راجع الجدول أدناه للحصول على شرح لكل دالة والغرض منها في العينة.

الطريقة	‏‏الوصف
hello_orchestrator	دالة المنسق، التي تصف سير العمل. في هذه الحالة، يبدأ التنسيق، ويستدعي ثلاث دالات في تسلسل، ويعيد النتائج مرتبة من كافة الدالات الثلاث في قائمة.
hello	دالة النشاط، التي تنفذ العمل الذي يتم تنسيقه. ترجع الدالة تحية بسيطة إلى المدينة التي تم تمريرها كوسيطة.
http_start	تظهر دالة تشغيل بروتوكول نقل النص الفائق التي تبدأ تشغيل مثيل التنسيق وإعادة الاستجابة لحالة التحقق.

إشعار

تدعم Durable Functions أيضا مخططات Python V2. لاستخدامها، ستحتاج إلى تسجيل وظائف المخطط باستخدام azure-functions-durableBlueprint الفئة ، كما هو موضح هنا. يمكن بعد ذلك تسجيل المخطط الناتج كالمعتاد. راجع نموذجنا للحصول على مثال.

اختبِر الدالة محليًا

تسمح لك الأدوات الأساسية لدوال Azure بتشغيل مشروع دوال Azure على جهاز الحاسوب بغرض التطوير المحلي لديك. في حالة عدم التثبيت، فتُطالب بتثبيت هذه الأدوات في المرة الأولى التي تبدأ فيها دالة من Visual Studio Code.

1. لاختبار دالتك، قم بتعيين نقطة توقف في التعليمة البرمجية لدالة نشاط Hello (Hello/__init__.py). اضغط F5 أو حدد Debug: Start Debuggingمن لوحة الأوامر لبدء مشروع تطبيق الدالة. تُعرج نتائج الأدوات الأساسية في لوحة Terminal.

1. لاختبار الدالة الخاصة بك، قم بتعيين نقطة توقف في التعليمات البرمجية لدالة hello النشاط. اضغط F5 أو حدد Debug: Start Debuggingمن لوحة الأوامر لبدء مشروع تطبيق الدالة. تُعرج نتائج الأدوات الأساسية في لوحة Terminal.

إشعار

لمزيد من المعلومات حول تصحيح الأخطاء، راجع Durable Functions Diagnostics.

2. يتطلب Durable Functions حسابًا في Azure Storage. عندما يطالبك Visual Studio Code بتحديد حساب تخزين، اختر Select storage account.

   

3. بعد المطالبات، أدخل المعلومات التالية لإنشاء حساب تخزين جديد في Azure:

   المطالبة	قيمة	‏‏الوصف
   حدد الاشتراك	اسم الاشتراك	حدد اشتراكك في Azure.
   تحديد حساب تخزين	إنشاء حساب تخزين جديد
   إدخال اسم حساب التخزين الجديد	اسم مميز	اسم حساب التخزين المطلوب إنشاؤه
   تحديد مجموعة موارد	اسم مميز	اسم مجموعة الموارد المطلوب إنشاؤها
   تحديد موقع	المنطقة	تحديد منطقة قريبة منك

4. في لوحة Terminal، نسخ نقطة النهاية لعنوان URL الخاص بدالتك التي تعمل محلياً.

   

5. باستخدام المستعرض، أو أداة مثل Postman أو cURL، ترسل طلب HTTP POST إلى نقطة نهاية عنوان URL. استبدال الجزء الأخير باسم دالة المُنسق (HelloOrchestrator). يجب أن يكون عنوان URL مشابهًا لـ http://localhost:7071/api/orchestrators/HelloOrchestrator.

   الاستجابة هي النتيجة الأولية من الدالة HTTP مما يتيح معرفة أن التنسيق الدائم قد بدأ بنجاح. إنها لم تصل بعد إلى النتيجة النهائية للتنسيق. تتضمن الاستجابة بعض عناوين URL المفيدة. أما الآن، دعونا نستعلم عن حالة التنسيق.

5. باستخدام المستعرض، أو أداة مثل Postman أو cURL، ترسل طلب HTTP POST إلى نقطة نهاية عنوان URL. استبدال الجزء الأخير باسم دالة المُنسق (hello_orchestrator). يجب أن يكون عنوان URL مشابهًا لـ http://localhost:7071/api/orchestrators/hello_orchestrator.

   الاستجابة هي النتيجة الأولية من الدالة HTTP مما يتيح معرفة أن التنسيق الدائم قد بدأ بنجاح. إنها لم تصل بعد إلى النتيجة النهائية للتنسيق. تتضمن الاستجابة بعض عناوين URL المفيدة. أما الآن، دعونا نستعلم عن حالة التنسيق.

2. انسخ قيمة عنوان URL في statusQueryGetUri والصقها في شريط عناوين المتصفح ونفذ الطلب. بدلاً من ذلك، يمكن أيضًا الاستمرار في استخدام Postman لإصدار طلب GET.

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

{
    "name": "HelloOrchestrator",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}

{
    "name": "hello_orchestrator",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}

7. لإيقاف تصحيح الأخطاء، اضغط على Shift + F5 في Visual Studio Code.

بعد التحقق من عمل الدالة بشكل صحيح على جهاز الحاسوب المحلي، حان الوقت لنشر المشروع على Azure.

تسجيل الدخول إلى Azure

قبل أن تتمكن من إنشاء موارد Azure أو نشر تطبيقك، يجب عليك تسجيل الدخول إلى Azure.

1. إذا لم تُسجل الدخول بالفعل، فاختر رمز Azure في شريط "النشاط". ثم في منطقة "الموارد"، اختر "تسجيل الدخول إلى Azure...".

   

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

2. اخترعند مطالبتك في مستعرض حساب Azure الخاص بك، ثم سجل الدخول باستخدام بيانات اعتماد حساب Azure. في حال إنشاء حساب جديد، يمكنك تسجيل الدخول بعد إنشاء حسابك.

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

إنشاء تطبيق الوظائف في Azure

يمكنك، في هذا القسم، إنشاء تطبيق وظائف وموارد ذات الصلة في اشتراك Azure.

1. حدد رمز Azure في شريط "النشاط". ثم في منطقة "الموارد"، حدد الرمز + وحدد الخيار "إنشاء تطبيق الوظائف في Azure".

   

2. قدِّم المعلومات التالية في المطالبات:

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

   يعرض الملحق حالة الموارد الفردية في أثناء إنشائها في Azure في لوحة Azure: سجل النشاط.

   

3. يتم، عند الانتهاء من الإنشاء، إنشاء موارد Azure التالية في الاشتراك. تسمى الموارد استنادًا إلى اسم تطبيق الوظائف الخاص بك:

   • مجموعة الموارد، وهي حاوية منطقية للموارد ذات الصلة.
   • حساب التخزين بخدمة Azure: هو مورد تخزين يحتفظ بالحالة ومعلومات أخرى حول المشروع.
   • تطبيق الوظيفة، الذي يوفر البيئة لتنفيذ التعليمة البرمجية للوظيفة. يتيح لك تطبيق الوظيفة تجميع الوظائف كوحدة منطقية لإدارة الموارد وتوزيعها ومشاركتها بشكل أسهل مع نفس خطة المضيف.
   • خطة «خدمة التطبيقات» التي تحدد المضيف الأساسي لتطبيق الوظائف.
   • مثيل Application Insights متصل بتطبيق الوظائف الذي يتتبع استخدام الوظائف في التطبيق.

   يعرض تنبيه بعد إنشاء تطبيق الوظيفة وتطبيق حزمة التوزيع.

   تلميح

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

نشر المشروع في Azure

هام

يستبدل التوزيع إلى تطبيق وظائف موجود دائمًا محتويات هذا التطبيق في Azure.

1. في منطقة الموارد لنشاط Azure، حدد موقع مورد تطبيق الدالة الذي أنشأته للتو، وانقر بزر الماوس الأيمن فوق المورد، وحدد Deploy to function app....

2. عند مطالبتك بالكتابة فوق عمليات التوزيع السابقة، حدد Deploy لنشر التعليمات البرمجية للدالة إلى مورد تطبيق الوظائف الجديد.

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

   

اختبر الدالة في Azure

1. انسخ عنوان URL لمشغل بروتوكول نقل النص الفائق من لوحة الإخراج. يجب أن يكون عنوان URL الذي يستدعي الدالة التي شُغلت بواسطة HTTP بهذا التنسيق: https://<functionappname>.azurewebsites.net/api/orchestrators/HelloOrchestrator

1. انسخ عنوان URL لمشغل بروتوكول نقل النص الفائق من لوحة الإخراج. يجب أن يكون عنوان URL الذي يستدعي الدالة التي شُغلت بواسطة HTTP بهذا التنسيق: https://<functionappname>.azurewebsites.net/api/orchestrators/hello_orchestrator

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

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

لقد استخدمت Visual Studio Code لإنشاء تطبيق دوال دائمة تستخدم Python ونشره.

التعرف على أنماط الدوال الدائمة الشائعة