دليل مرجعي للمطورين Azure Functions لتطبيقات Python

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

يركز هذا الدليل تحديدا على بناء Azure Functions المبنية على Python ويساعدك على:

• أنشئ وشغل تطبيقات الوظائف محليا
• فهم نموذج برمجة Python
• نظم وقم بتكوين تطبيقك
• نشر ومراقبة تطبيقك في Azure
• تطبيق أفضل الممارسات للتوسع والأداء

هل تبحث عن نظرة عامة مفاهيمية؟ انظر مرجع المطور Azure Functions .

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

الشروع

اختر البيئة التي تناسب سير عملك وادخل إلى Azure Functions for Python:

• Visual Studio Code البداية السريعة
• بداية سريعة لأدوات النواة

بناء تطبيق الوظائف الخاص بك

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

نموذج البرمجة

تدعم الدوال نسختين من نموذج البرمجة Python:

إصدار	Description
2.x	استخدم نهج الديكور لتعريف المحفزات والربط مباشرة في ملف كود Python الخاص بك. تقوم بتنفيذ كل دالة كطريقة عالمية بدون حالة في function_app.py ملف أو ملف مخطط مرجعي. يوصى بإصدار هذا الطراز لتطبيقات Python الجديدة.
1.x	تحدد المحفزات والروابط لكل وظيفة في ملف منفصل function.json . تقوم بتنفيذ كل وظيفة كطريقة عالمية بلا حالة في ملف كود Python الخاص بك. يدعم هذا الإصدار من النموذج التطبيقات القديمة.

تستهدف هذه المقالة نسخة محددة من نموذج Python. اختر النسخة التي تريدها في أعلى المقال.

Important

استخدم نموذج البرمجة v2 لنهج قائم على الديكور لتعريف المحفزات والروابط مباشرة في كودك.

في نموذج البرمجة Python v1، تعرف كل دالة كطريقة عالمية بلا حالة main() داخل ملف يسمى __init__.py. يتم تكوين محفزات وربط الدالة بشكل منفصل في function.json ملف، وتستخدم قيم الربط name كمعلمات في طريقتك main() .

مثال

إليك دالة بسيطة تستجيب لطلب HTTP:

# __init__.py
def main(req):
    user = req.params.get('user')
    return f'Hello, {user}!'

إليكم الملف المقابل function.json :

{
    "scriptFile": "__init__.py",
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "type": "http",
            "direction": "out",
            "name": "$return"
        }
    ]
}

المفاهيم الرئيسية

• تحتوي الدالة على مشغل HTTP واحد.
• يحتوي كائن HttpRequest على رؤوس الطلبات، ومعلمات الاستعلام، ومعلمات المسار، وجسم الرسالة. تحصل هذه الدالة على قيمة name معامل الاستعلام من params معامل كائن HttpRequest .
• لإرسال اسم في هذا المثال، قم بإضافة ?name={name} رابط الدالة المكشوفة. على سبيل المثال، إذا كان يعمل محليا، قد يبدو الرابط الكامل ك http://localhost:7071/api/http_trigger?name=Test. لأمثلة باستخدام الربطات، انظر المحفزات والربطات.

استخدم azure-functions حزمة تطوير البرمجيات وأضف تعليقات للأنواع لتحسين دعم IntelliSense والمحرر:

# __init__.py
import azure.functions as func

def http_trigger(req: func.HttpRequest) -> str:

# requirements.txt
azure-functions

المكتبة azure-functions

توفر مكتبة azure-functions Python الأنواع الأساسية المستخدمة للتفاعل مع وقت التشغيل Azure Functions. لرؤية جميع الأنواع والطرق المتاحة، قم بزيارة azure-functions واجهة برمجة التطبيقات (API). يمكن لكود الوظيفة الخاص بك أن يستخدم azure-functions ل:

• الوصول إلى بيانات إدخال الزناد (على سبيل المثال، HttpRequest، TimerRequest)
• إنشاء قيم الإخراج (مثل HttpResponse)
• التفاعل مع بيانات السياق والربط التي توفرها وقت التشغيل

إذا كنت تستخدم azure-functions في تطبيقك، يجب أن يكون متضمرا ضمن تبعيات مشروعك.

Note

مكتبة azure-functions تحدد سطح البرمجة ل Python Azure Functions، لكنها ليست مجموعة تطوير تطوير متعددة الأغراض. استخدمه تحديدا لتأليف وتشغيل الوظائف ضمن وقت تشغيل Azure Functions.

نقطة إدخال بديلة

يمكنك تغيير السلوك الافتراضي لدالة عن طريق تحديد الخصائص و scriptFileentryPoint في function.json الملف. على سبيل المثال، الملف التالي function.json يوجه وقت التشغيل لاستخدام طريقة custom_entry() في ملف main.py كنقطة دخول لدالة Azure الخاصة بك.

{
  "scriptFile": "main.py",
  "entryPoint": "custom_entry",
  "bindings": [
      ...
  ]
}

هيكل المجلد

استخدم الهيكل التالي لمشروع Python Azure Functions:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── my_first_function/       # Function directory
│   └── __init__.py          # Function code file
│   └── function.json        # Function binding configuration file
│
├── my_second_function/
│   └── __init__.py  
│   └── function.json 
│
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

الملفات والمجلدات الرئيسية

ملف / مجلد	Description	مطلوب لتشغيل التطبيق في Azure
my_first_function/	دليل لوظيفة واحدة.	✅
__init__.py/	السكربت الرئيسي حيث my_first_function يتم تعريف رمز الدالة.	✅
function.json/	يحتوي على تكوين الربط للدالة my_first_function .	✅
host.json	تكوين عام لجميع الوظائف في التطبيق.	✅
requirements.txt	Python الاعتماديات المثبتة أثناء النشر عند استخدام remote build.	❌ (موصى به لإدارة الطرود)
local.settings.json	إعدادات وأسرار التطبيق المحلية فقط (لم تنشر أبدا).	❌ (مطلوب للتطوير المحلي)
.funcignore	يحدد الملفات والمجلدات لاستبعادها من النشر (على سبيل المثال، .venv/، tests/، local.settings.json).	❌ (مستحسن)
.venv/	البيئة الافتراضية المحلية ل Python (مستثناة من النشر).	❌
.vscode/	إعداد المحرر ل Visual Studio Code. غير مطلوب للنشر.	❌
shared/	يحتفظ بكود المساعدة المشترك عبر مشروع تطبيق الوظائف	❌
additional_functions/	يستخدم لتنظيم الشيفرة المعيارية—عادة مع المخططات.	❌
tests/	اختبارات الوحدة لتطبيق الوظائف الخاص بك. لم ينشر على Azure.	❌
Dockerfile	يحدد حاوية مخصصة للنشر.	❌

في نموذج البرمجة v2 Python، يستخدم Azure Functions نهج decorator لتعريف المحفزات والروابط مباشرة في الكود الخاص بك. يتم تنفيذ كل دالة كطريقة عالمية بلا حالة داخل function_app.py ملف.

مثال

إليك دالة بسيطة تستجيب لطلب HTTP:

import azure.functions as func

app = func.FunctionApp()

@app.route("hello")
def http_trigger(req):
    user = req.params.get("user")
    return f"Hello, {user}!"

# requirements.txt
azure-functions

المفاهيم الرئيسية

• يقوم الكود باستيراد الحزمة azure-functions ويستخدم الديكورات والأنواع لتعريف تطبيق الدالة.
• تحتوي الدالة على مشغل HTTP واحد.
• يحتوي كائن HttpRequest على رؤوس الطلبات، ومعلمات الاستعلام، ومعلمات المسار، وجسم الرسالة. تحصل هذه الدالة على قيمة name معامل الاستعلام من params معامل كائن HttpRequest .
• لإرسال اسم في هذا المثال، قم بإضافة ?name={name} رابط الدالة المكشوفة. على سبيل المثال، إذا كان يعمل محليا، قد يبدو الرابط الكامل ك http://localhost:7071/api/http_trigger?name=Test. لأمثلة باستخدام الربطات، انظر المحفزات والربطات.

المكتبة azure-functions

مكتبة azure-functions Python هي جزء أساسي من نموذج البرمجة Azure Functions. يوفر الديكورين، وأنواع الزناد والربط، وكائنات الطلب/الاستجابة المستخدمة لتعريف والتفاعل مع الدوال أثناء التشغيل. لرؤية جميع الأنواع والمزينين المتاحين، قم بزيارة azure-functions واجهة برمجة التطبيقات (API). كود تطبيق الوظائف الخاص بك يعتمد على هذه المكتبة ل:

• تعريف جميع الدوال باستخدام الكائن FunctionApp
• إعلان المحفزات والروابط (على سبيل المثال، @app.route، @app.timer_trigger)
• الوصول إلى المدخلات والمخرجات النوعية (مثل HttpRequest و HttpResponseو و Out')

يجب أن تكون مدرجة azure-functions ضمن تبعيات مشروعك. لمعرفة المزيد، راجع إدارة الحزم.

Note

مكتبة azure-functions تحدد سطح البرمجة ل Python Azure Functions، لكنها ليست مجموعة تطوير تطوير متعددة الأغراض. استخدمه تحديدا لتأليف وتشغيل الوظائف ضمن وقت تشغيل Azure Functions.

استخدم تعليقات الأنواع لتحسين دعم IntelliSense والمحرر:

def http_trigger(req: func.HttpRequest) -> str:

التنظيم باستخدام المخططات

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

لتعريف وتسجيل مخطط:

1. حدد مخططا في ملف Python آخر، مثل http_blueprint.py:

   import azure.functions as func
   
   bp = func.Blueprint()
   
   @bp.route(route="default_template")
   def default_template(req: func.HttpRequest) -> func.HttpResponse:
       return func.HttpResponse("Hello World!")
   

2. سجل المخطط في الملف الرئيسي function_app.py :

   import azure.functions as func
   from http_blueprint import bp
   
   app = func.FunctionApp()
   app.register_functions(bp)
   

باستخدام المخططات، يمكنك:

• قسم تطبيقك إلى وحدات قابلة لإعادة الاستخدام
• احتفظ بالوظائف ذات الصلة مجمعة حسب الملف أو الميزة
• قم بتوسيع أو مشاركة المخططات عبر المشاريع

Note

Durable Functions يدعم أيضا المخططات باستخدام azure-functions-durable. عرض عينة →

هيكل المجلد

استخدم الهيكل التالي لمشروع Python Azure Functions:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── function_app.py          # Main function entry point (decorator model)
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

الملفات والمجلدات الرئيسية

ملف / مجلد	Description	مطلوب لتشغيل التطبيق في Azure
function_app.py	السكربت الرئيسي حيث يتم تعريف Azure Functions وTriggers باستخدام الديكوريتورز.	✅
host.json	تكوين عام لجميع الوظائف في التطبيق.	✅
requirements.txt	Python الاعتماديات المثبتة أثناء النشر عند استخدام remote build.	❌ (موصى به لإدارة الطرود)
local.settings.json	إعدادات وأسرار التطبيق المحلية فقط (لم تنشر أبدا).	❌ (مطلوب للتطوير المحلي)
.funcignore	يحدد الملفات والمجلدات لاستبعادها من النشر (على سبيل المثال، .venv/، tests/، local.settings.json).	❌ (مستحسن)
.venv/	البيئة الافتراضية المحلية ل Python (مستثناة من النشر).	❌
.vscode/	إعداد المحرر ل Visual Studio Code. غير مطلوب للنشر.	❌
shared/	يحتفظ بكود المساعدة المشترك عبر مشروع تطبيق الوظائف	❌
additional_functions/	يستخدم لتنظيم الشيفرة المعيارية—عادة مع المخططات.	❌
tests/	اختبارات الوحدة لتطبيق الوظائف الخاص بك. لم ينشر على Azure.	❌
Dockerfile	يحدد حاوية مخصصة للنشر.	❌

[ملاحظة!] قم بتضمين requirements.txt ملف عند النشر باستخدام البناء عن بعد. إذا لم تستخدم البناء عن بعد أو ترغب في استخدام ملف آخر لتعريف تبعيات التطبيقات، يمكنك إجراء بناء محلي ونشر التطبيق مع تبعيات معدة مسبقا.

للحصول على إرشادات حول اختبار الوحدات، راجع اختبار الوحدة. لنشر الحاويات، انظر النشر مع الحاويات المخصصة.

---

المشغلات وعمليات الربط

يستخدم Azure Functions triggers لبدء تنفيذ الدوال وbindings لربط كودك بخدمات أخرى مثل التخزين، الطوابير، وقواعد البيانات. في نموذج البرمجة Python v2، تعلن الروابط باستخدام الديكورات.

يوجد نوعان رئيسيان من الربطات:

• المحفزات (المدخل الذي يبدأ الوظيفة)
• المدخلات والمخرجات (مصادر بيانات إضافية أو وجهات أخرى)

لمزيد من المعلومات حول المحفزات والروابط المتاحة، انظر Triggers and Bindings في Azure Functions.

مثال: مشغل مؤقت مع إدخال كتلة

هذه الدالة:

• المحفزات كل 10 دقائق
• يقرأ من كتلة باستخدام روابط نوع SDK
• تخزين النتائج مؤقتا وكتابته في ملف مؤقت

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob
import logging
import tempfile

CACHED_BLOB_DATA = None

app = func.FunctionApp()

@app.function_name(name="TimerTriggerWithBlob")
@app.schedule(schedule="0 */10 * * * *", arg_name="mytimer")
@app.blob_input(arg_name="client",
                path="PATH/TO/BLOB",
                connection="BLOB_CONNECTION_SETTING")
def timer_trigger_with_blob(mytimer: func.TimerRequest,
                            client: blob.BlobClient,
                            context: func.Context) -> None:
    global CACHED_BLOB_DATA
    if CACHED_BLOB_DATA is None:
        # Download blob and save as a global variable
        CACHED_BLOB_DATA = client.download_blob().readall()

        # Create temp file prefix
        my_prefix = context.invocation_id
        temp_file = tempfile.NamedTemporaryFile(prefix=my_prefix)
        temp_file.write(CACHED_BLOB_DATA)
        logging.info(f"Cached data written to {temp_file.name}")

المفاهيم الرئيسية

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

مثال: مشغل HTTP مع إدخال قاعدة بيانات كوزموس وإخراج مركز الأحداث

هذه الدالة:

• المحفزات في طلب HTTP
• يقرأ من قاعدة بيانات كوزموس
• يكتب إلى مخرج مركز الأحداث
• يرجع استجابة HTTP

# __init__.py
import azure.functions as func

def main(req: func.HttpRequest,
         documents: func.DocumentList,
         event: func.Out[str]) -> func.HttpResponse:

    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get("body")
    doc_id = documents[0]["id"] if documents else "No documents found"

    event.set(f"HttpRequest content: {http_content} | CosmosDB ID: {doc_id}")

    return func.HttpResponse(
        "Function executed successfully.",
        status_code=200
    )

// function.json
{
  "scriptFile": "__init__.py",
  "entryPoint": "main",
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"],
      "route": "file"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "cosmosDB",
      "direction": "in",
      "name": "documents",
      "databaseName": "test",
      "containerName": "items",
      "id": "cosmosdb-input-test",
      "connection": "COSMOSDB_CONNECTION_SETTING"
    },
    {
      "type": "eventHub",
      "direction": "out",
      "name": "event",
      "eventHubName": "my-test-eventhub",
      "connection": "EVENTHUB_CONNECTION_SETTING"
    }
  ]
}

المفاهيم الرئيسية

• كل وظيفة لها مشغل واحد، لكنها يمكن أن تحتوي على عدة ربطات.
• أضف المدخلات بتحديد ال direction ك "in" في function.json. المخرجات لها قيمة direction .out
• يمكنك الوصول إلى تفاصيل الطلب من خلال الكائن HttpRequest وإنشاء نموذج مخصص HttpResponse يحتوي على الرؤوس، ورمز الحالة، والجسم.

import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="HttpTriggerWithCosmosDB")
@app.route(route="file")
@app.cosmos_db_input(arg_name="documents",
                     database_name="test",
                     container_name="items",
                     connection="COSMOSDB_CONNECTION_SETTING")
@app.event_hub_output(arg_name="event",
                      event_hub_name="my-test-eventhub",
                      connection="EVENTHUB_CONNECTION_SETTING")
def http_trigger_with_cosmosdb(req: func.HttpRequest,
                               documents: func.DocumentList,
                               event: func.Out[str]) -> func.HttpResponse:
    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get('body')
    doc_id = documents[0]['id']

    event.set("HttpRequest content: " + http_content
              + " | CosmosDB ID: " + doc_id)

    return func.HttpResponse(
        f"Function executed successfully.",
        status_code=200
    )

المفاهيم الرئيسية

• استخدم @route() أو الديكور الخاص بالمحفز (@timer_trigger, @queue_trigger, وغيرهم) لتحديد كيفية استدعاء وظيفتك.
• أضف المدخلات باستخدام مزخرفات مثل @blob_input، @queue_input، وغيرها.
• يمكن أن تكون المخرجات:
  • يتم إرجاعه مباشرة (إذا كان هناك مخرج واحد فقط)
  • يتم تعيينها باستخدام Out الروابط وطريقة .set() الإخراج المتعددة.
• يمكنك الوصول إلى تفاصيل الطلب من خلال الكائن HttpRequest وإنشاء نموذج مخصص HttpResponse يحتوي على الرؤوس، ورمز الحالة، والجسم.

روابط نوع SDK

لاختيار المحفزات والربط، يمكنك العمل مع أنواع البيانات التي تنفذها Azure SDKs وأطر العمل الأساسية. باستخدام هذه الروابط من نوع SDK، يمكنك التفاعل مع بيانات الربط كما لو كنت تستخدم SDK الخدمة الأساسية. لمزيد من المعلومات، راجع روابط نوع SDK المدعومة.

Important

دعم ربطات نوع SDK ل Python متوفر فقط في نموذج البرمجة Python v2.

متغيرات البيئة

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

يمكنك تعريف متغيرات البيئة:

• محليا: في ملفlocal.settings.json، أثناء التطوير المحلي.
• في Azure: ك ><إعدادات التطبيق في صفحة إعدادات تطبيق الوظائف الخاص بك في بوابة Azure.

الوصول إلى المتغيرات مباشرة في الكود باستخدام os.environ أو os.getenv.

setting_value = os.getenv("myAppSetting", "default_value")

Note

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

إدارة الحزم

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

على سبيل المثال، توضح العينة التالية كيف تم تضمين الوحدة requests واستخدامها في تطبيق الدوال.

<requirements.txt>
requests==2.31.0

قم بتثبيت الحزمة محليا باستخدام pip install -r requirements.txt.

بمجرد تثبيت الحزمة، يمكنك استيرادها واستخدامها في كود الوظيفة الخاص بك:

import azure.functions as func
import requests

def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

import azure.functions as func
import requests

app = func.FunctionApp()

@app.function_name(name="HttpExample")
@app.route(route="call_api")
def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

الاعتبارات

• التعارضات مع الوحدات المدمجة:
  • تجنب تسمية مجلدات مشروعك باسم Python المكتبات القياسية (على سبيل المثال، email/، json/).
  • لا تدرج Python المكتبات الأصلية (مثل logging، asyncio، أو uuid) في requirements.txt.
• النشر:
  • لمنع ModuleNotFound الأخطاء، تأكد من إدراج جميع التبعيات المطلوبة في requirements.txt.
  • إذا قمت بتحديث نسخة Python الخاصة بتطبيقك، أعد بناء ونشر تطبيقك على النسخة الجديدة من Python لتجنب تعارض الاعتماد مع الحزم التي تم بناؤها سابقا.
• التبعيات غير PyPI:
  • يمكنك تضمين تبعيات غير متوفرة في PyPI في تطبيقك، مثل الحزم المحلية، ملفات العجلات، أو الخلاصات الخاصة. انظر الاعتماديات المخصصة في Python Azure Functions للحصول على تعليمات الإعداد.
• Azure Functions Python تبعيات العمال:
  • إذا كانت الحزمة تحتوي على مكتبات معينة قد تتصادم مع تبعيات العامل (مثلا، أوprotobuf)، grpcio قم بتكوين PYTHON_ISOLATE_WORKER_DEPENDENCIES إلى 1 في إعدادات التطبيق لمنع تطبيقك من الإشارة إلى تبعيات العامل (worker). بالنسبة ل Python 3.13 وما فوق، هذه الميزة مفعلة افتراضيا.

التشغيل والنشر

يوفر هذا القسم معلومات حول تشغيل الدوال محليا، Python إصدار support، build and deployment options، وتكوين وقت التشغيل. استخدم هذه المعلومات لتشغيل تطبيق الوظائف بنجاح في كل من البيئات المحلية وبيئة Azure.

التشغيل محلياً

يمكنك تشغيل واختبار تطبيق وظائف Python على جهازك المحلي قبل نشره على Azure.

باستخدام أدوات Azure Functions الأساسية

قم بتثبيت Azure Functions Core Tools وابدأ وقت التشغيل المحلي بتشغيل أمر func start من جذر مشروعك:

func start

عند تشغيل تطبيق الوظائف محليا، تعرض Core Tools جميع الوظائف التي تجدها لتطبيقك:

Functions:
        http_trigger:  http://localhost:7071/api/http_trigger

يمكنك معرفة المزيد حول كيفية استخدام الأدوات الأساسية بزيارة Develop Azure Functions محليا باستخدام Core Tools.

استدعاء الوظيفة مباشرة

باستخدام azure-functions >= 1.21.0، يمكنك أيضا استدعاء الدوال مباشرة باستخدام مفسر Python دون تشغيل Core Tools. هذه الطريقة مفيدة لاختبارات الوحدة السريعة:

# function_app.py
import azure.functions as func

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@app.route(route="http_trigger")
def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
    return "Hello, World!"

# Test the function directly
print(http_trigger(None))

لرؤية المخرجات، قم بتشغيل الملف مباشرة باستخدام Python:

> python function_app.py

Hello, World!

# __init__.py
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("Hello, World!")

# Test the function directly
print(main(None))

لرؤية المخرجات، قم بتشغيل الملف مباشرة باستخدام Python:

> python __init__.py

Hello, World!

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

نسخ Python المدعومة

يدعم Azure Functions الإصدارات Python المدرجة في اللغات المدعومة في Azure Functions. لمزيد من المعلومات العامة، راجع سياسة دعم وقت التشغيل Azure Functions.

Important

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

البناء والنشر

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

آليات النشر مقارنة سريعة

الأداة / المنصة	القيادة / العمل	أفضل حالة استخدام
Azure Functions أدوات النواة	func azure functionapp publish <APP_NAME>	مثالي لتشغيل CI، والأتمتة المحلية، أو عند العمل عبر المنصات.
AZ CLI	az functionapp deployment source config-zip	مفيد عند برمجة سكريبتات لنشر النشر خارج أدوات النواة. يعمل بشكل جيد في خطوط الأنابيب الآلية أو الطرفيات السحابية (Azure Cloud Shell).
Visual Studio Code (Azure Functions التوسعة)	لوحة الأوامر → "Azure Functions: الانتشار إلى Azure..."	الأفضل للمبتدئين أو للنشر التفاعلي. يتولى التغليف والتصنيع تلقائيا.
GitHub Actions	Azure/functions-action@v1	مثالي لأنظمة CI/CD المبنية على GitHub. يتيح النشر التلقائي عند دمج الدفع أو الروابط العامة.
Azure Pipelines	AzureFunctionApp@2 المهمة	Enterprise CI/CD using Azure DevOps. الأفضل لسير عمل الإصدار المحكم، والبناءات المجهولة، وخطوط الأنابيب متعددة المراحل.
نشر الحاويات المخصص	حاوية دفع → az functionapp create --image <container>	مطلوب عندما تحتاج إلى حزم على مستوى نظام التشغيل، أو بناءات Python مخصصة، أو أوقات تشغيل مثبتة، أو تبعيات غير مدعومة (مثل مكتبات النظام، الملفات الثنائية المحلية).
إنشاء الوظائف المعتمدة على البوابة	إنشاء دالة في محرر البوابة Azure →	تستخدم فقط للوظائف البسيطة والخالية من الاعتمادية. ممتاز للعروض أو التعلم، لكنه غير موصى به للتطبيقات التي تتطلب حزم طرف ثالث.

Note

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

Important

بعد 30 سبتمبر 2028، يتم إيقاف خيار استضافة تطبيق الوظائف الخاص بك على Linux في خطة الاستهلاك. لتجنب الاضطرابات، قم بترحيل تطبيقات خطة الاستهلاك الحالية التي تعمل على Linux إلى خطة Flex Consumption قبل ذلك التاريخ. التطبيقات التي تعمل على Windows في خطة استهلاك لا تتأثر بهذا التغيير.

بعد 30 سبتمبر 2025، لا تضاف أي ميزات جديدة ولا دعم جديد لمكدس اللغات إلى خطة استهلاك لينكس. آخر إصدارات اللغة المدعومة لاستهلاك لينكس هي: .NET 9، Python 3.12، Node.js 22، باورشل 7.4، و Java 21. الإصدارات اللغوية الأحدث غير مدعومة لاستهلاك لينكس.

لمزيد من المعلومات، راجع ترحيل تطبيقات خطة الاستهلاك إلى خطة استهلاك Flex.

تحديثات Python 3.13+

بدءا من Python 3.13، يقدم Azure Functions عدة تحسينات رئيسية في وقت التشغيل والأداء تؤثر على كيفية بناء وتشغيل تطبيقاتك. تشمل التغييرات الرئيسية ما يلي:

• التحكم في الإصدارات أثناء التشغيل: يمكنك الآن الآن تثبيت أو ترقية تطبيقك إلى إصدارات Python المخصصة للموظفين من خلال الرجوع إلى حزمة azure-functions-runtime في requirements.txt الخاص بك.

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

  • تقوم بتمكين التحكم في إصدار وقت التشغيل بإضافة مرجع إلى حزمة وقت التشغيل Python إلى ملف requirements.txt الخاص بك، حيث تحدد القيمة المخصصة للحزمة إصدار وقت التشغيل المستخدم.

  • تجنب تثبيت أي تطبيق إنتاج على إصدارات التشغيل المسبقة (ألفا أو بيتا أو التطوير).

  • للاطلاع على التغييرات، راجع Python ملاحظات الإصدارات أثناء التشغيل بانتظام.

  • الجدول التالي يوضح سلوك الإصدار بناء على قيمة الإصدار لهذا الإعداد في ملف requirements.txt الخاص بك:

    إصدار	Example	سلوك
    لا توجد مجموعة قيم	azure-functions-runtime	تطبيق Python 3.13+ يعمل على أحدث إصدار متاح من وقت تشغيل Functions Python. هذا الخيار هو الأفضل للبقاء على اطلاع بتحسينات وميزات المنصة، حيث يتلقى تطبيقك تلقائيا أحدث تحديثات التشغيل المستقرة.
    مثبت على نسخة محددة	azure-functions-runtime==1.2.0	تطبيق Python 3.13+ يبقى على النسخة المثبتة من وقت التشغيل ولا يتلقى تحديثات تلقائية. بدلا من ذلك، يجب عليك تحديث النسخة المثبتة يدويا للاستفادة من الميزات الجديدة والإصلاحات والتحسينات في وقت التشغيل. يوصى بالتثبيت في الأحمال الإنتاجية الحرجة حيث يكون الاستقرار والتنبؤ ضروريين. يتيح لك تثبيت التطبيق أيضا اختبار تطبيقك على إصدارات وقت التشغيل الجاهزة أثناء التطوير.
    لا يوجد مرجع للحزمة	غير متوفر	بعدم تعيين azure-functions-runtime، يعمل تطبيق Python 3.13+ على نسخة افتراضية من وقت التشغيل Python متأخر عن الإصدار الأخير. يتم إجراء تحديثات دورية من قبل الوظائف. يضمن هذا الخيار الاستقرار والتوافق الواسع. ومع ذلك، يتأخر الوصول إلى أحدث الميزات والإصلاحات حتى يتم تحديث النسخة الافتراضية.

• عزل التبعيات: تبعيات تطبيقك (مثل grpcio أو protobuf) معزولة تماما عن تبعيات العامل، مما يمنع تعارضات الإصدارات. إعداد التطبيق PYTHON_ISOLATE_WORKER_DEPENDENCIES لن يؤثر على التطبيقات التي تعمل على Python 3.13 أو أحدث.

• إعداد تبسيط لبث HTTP —لا حاجة لإعدادات تطبيق خاصة.

• تمت إزالة دعم إضافات العمال وميزات الذاكرة المشتركة.

• التحكم في الإصدارات أثناء التشغيل: يمكنك الآن الآن تثبيت أو ترقية تطبيقك إلى إصدارات Python المخصصة للموظفين من خلال الرجوع إلى حزمة azure-functions-runtime-v1 في requirements.txt الخاص بك.

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

  • تقوم بتمكين التحكم في إصدار وقت التشغيل بإضافة مرجع إلى حزمة وقت التشغيل Python إلى ملف requirements.txt الخاص بك، حيث تحدد القيمة المخصصة للحزمة إصدار وقت التشغيل المستخدم.

  • تجنب تثبيت أي تطبيق إنتاج على إصدارات التشغيل المسبقة (ألفا أو بيتا أو التطوير).

  • للاطلاع على التغييرات، راجع Python ملاحظات الإصدارات أثناء التشغيل بانتظام.

  • الجدول التالي يوضح سلوك الإصدار بناء على قيمة الإصدار لهذا الإعداد في ملف requirements.txt الخاص بك:

    إصدار	Example	سلوك
    لا توجد مجموعة قيم	azure-functions-runtime-v1	تطبيق Python 3.13+ يعمل على أحدث إصدار متاح من وقت تشغيل Functions Python. هذا الخيار هو الأفضل للبقاء على اطلاع بتحسينات وميزات المنصة، حيث يتلقى تطبيقك تلقائيا أحدث تحديثات التشغيل المستقرة.
    مثبت على نسخة محددة	azure-functions-runtime-v1==1.2.0	تطبيق Python 3.13+ يبقى على النسخة المثبتة من وقت التشغيل ولا يتلقى تحديثات تلقائية. بدلا من ذلك، يجب عليك تحديث النسخة المثبتة يدويا للاستفادة من الميزات الجديدة والإصلاحات والتحسينات في وقت التشغيل. يوصى بالتثبيت في الأحمال الإنتاجية الحرجة حيث يكون الاستقرار والتنبؤ ضروريين. يتيح لك تثبيت التطبيق أيضا اختبار تطبيقك على إصدارات وقت التشغيل الجاهزة أثناء التطوير.
    لا يوجد مرجع للحزمة	غير متوفر	بعدم تعيين azure-functions-runtime-v1، يعمل تطبيق Python 3.13+ على نسخة افتراضية من وقت التشغيل Python متأخر عن الإصدار الأخير. يتم إجراء تحديثات دورية من قبل الوظائف. يضمن هذا الخيار الاستقرار والتوافق الواسع. ومع ذلك، يتأخر الوصول إلى أحدث الميزات والإصلاحات حتى يتم تحديث النسخة الافتراضية.

• عزل التبعيات: تبعيات تطبيقك (مثل grpcio أو protobuf) معزولة تماما عن تبعيات العامل، مما يمنع تعارضات الإصدارات. إعداد التطبيق PYTHON_ISOLATE_WORKER_DEPENDENCIES لن يؤثر على التطبيقات التي تعمل على Python 3.13 أو أحدث.

• تمت إزالة دعم إضافات العمال وميزات الذاكرة المشتركة.

الملاحظة والاختبار

يغطي هذا القسم logging، monitoring، و testing capabilities لمساعدتك في تصحيح المشكلات، وتتبع الأداء، وضمان موثوقية تطبيقات الوظائف Python لديك.

التسجيل والمراقبة

Azure Functions يعرض مسجل جذور يمكنك استخدامه مباشرة مع وحدة logging المدمجة في Python. أي رسائل تكتب باستخدام هذا المسجل ترسل تلقائيا إلى Application Insights عندما يكون تطبيقك يعمل في Azure.

يسمح التسجيل بالتقاط معلومات وقت التشغيل وتشخيص المشاكل دون الحاجة إلى المزيد من الإعدادات.

مثال تسجيل السجلات باستخدام مشغل HTTP

import logging
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

يمكنك استخدام مجموعة كاملة من مستويات التسجيل (debug، info، warning، error، critical)، وتظهر في بوابة Azure تحت سجلات أو رؤى التطبيقات.

لمعرفة المزيد عن Azure Functions المراقبة في البوابة، راجع Monitor Azure Functions.

Note

لعرض سجلات التصحيح في Application Insights، يتطلب الأمر المزيد من الإعداد. يمكنك تفعيل هذه الميزة عن طريق تعيين PYTHON_ENABLE_DEBUG_LOGGING إلى 1 وتعيين logLevel إلى trace أو debug في ملفhost.json الخاص بك. افتراضيا، سجلات التصحيح غير مرئية في Application Insights.

تسجيل من المواضيع الخلفية

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

import logging
import threading
import azure.functions as func

def main(req: func.HttpRequest, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

import azure.functions as func
import logging
import threading

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

تكوين مسجلات التسجيل المخصصة

يمكنك تكوين مسجلات السجلات المخصصة في Python عندما تحتاج إلى تحكم أكبر في سلوك التسجيل، مثل التنسيق المخصص، تصفية السجلات، أو التكامل مع طرف ثالث. لتكوين مسجل مخصص، استخدم logging.getLogger() Python مع اسم مخصص وأضف معالجات أو مسجلات حسب الحاجة.

import logging

custom_logger = logging.getLogger('my_custom_logger')

دعم OpenTelemetry

يدعم Azure Functions Python أيضا OpenTelemetry، الذي يتيح لك إرسال الآثار والمقاييس والسجلات بصيغة موحدة. استخدام OpenTelemetry ذو قيمة خاصة للتطبيقات الموزعة أو السيناريوهات التي ترغب فيها في تصدير القياس إلى أدوات خارج Application Insights (مثل Grafana أو Jaeger).

راجع OpenTelemetry Quickstart ل Azure Functions (Python) لتعليمات الإعداد ونموذج الكود.

اختبار الوحدة

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

باستخدام my_function المثال التالي كمثال، هو اختبار تجريبي لدالة مفعلة عبر HTTP:

أولا، أنشئ <ملف project_root>/function_app.py ونفذ الوظيفة my_function كمشغل HTTP.

# <project_root>/function_app.py
import azure.functions as func
import logging

app = func.FunctionApp()

# Define the HTTP trigger that accepts the ?value=<int> query parameter
# Double the value and return the result in HttpResponse
@app.function_name(name="my_function")
@app.route(route="hello")
def my_function(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Executing myfunction.')

    initial_value: int = int(req.params.get('value'))
    doubled_value: int = initial_value * 2

    return func.HttpResponse(
        body=f"{initial_value} * 2 = {doubled_value}",
        status_code=200
    )

يمكنك البدء في كتابة حالات الاختبار لمشغل HTTP الخاص بك.

# <project_root>/test_my_function.py
import unittest
import azure.functions as func

from function_app import my_function

class TestFunction(unittest.TestCase):
  def test_my_function(self):
    # Construct a mock HTTP request.
    req = func.HttpRequest(method='GET',
                           body=None,
                           url='/api/my_function',
                           params={'value': '21'})
    # Call the function.
    func_call = main.build().get_user_function()
    resp = func_call(req)
    # Check the output.
    self.assertEqual(
        resp.get_body(),
        b'21 * 2 = 42',
    )

داخل مجلد البيئة الافتراضية الخاص بك في Python، يمكنك تشغيل الأوامر التالية لاختبار التطبيق:

pip install pytest
pytest test_my_function.py

ترى pytest النتائج في الطرفية، مثل هذه:

============================================================================================================ test session starts ============================================================================================================
collected 1 item                                                                                                                                                                                                                             

test_my_function.py .                                                                                                                                                                                                                  [100%] 
============================================================================================================= 1 passed in 0.24s ============================================================================================================= 

التحسين والمواضيع المتقدمة

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

• القياس والأداء
• استخدام إطار Flask مع Azure Functions
• Durable Functions
• بث HTTP

المقالات ذات الصلة

لمزيد من المعلومات حول الدوال، راجع هذه المقالات:

• Azure Functions توثيق واجهة برمجة التطبيقات للحزم
• أفضل الممارسات ل Azure Functions
• Azure Functions المحفزات والارتباطات
• Blob Storage الروابط
• ارتباطات HTTP وWebhook
• روابط تخزين قائمة الانتظار
• مشغلات المؤقت

هل تواجه مشاكل في استخدام Python؟ أخبرنا وقدم مشكلة.