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

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

يركز هذا الدليل بشكل خاص على بناء وظائف Azure المبنية على بايثون ويساعدك على:

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

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

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

الشروع

اختر البيئة التي تناسب سير عملك وابدأ في Azure Functions لبايثون:

• كود فيجوال ستوديو السريع
• بداية سريعة لأدوات النواة

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

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

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

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

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

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

Important

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

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

Example

إليك دالة بسيطة تستجيب لطلب 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 توفر مكتبة بايثون الأنواع الأساسية المستخدمة للتفاعل مع وقت تشغيل Azure Functions. لرؤية جميع الأنواع والطرق المتاحة، قم بزيارة azure-functions واجهة برمجة التطبيقات (API). يمكن لكود الوظيفة الخاص بك أن يستخدم azure-functions ل:

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

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

Note

تعرف المكتبة azure-functions سطح البرمجة لوظائف Python Azure، لكنها ليست حزمة تطوير تطوير للأغراض العامة. استخدمه خصيصا لتأليف وتشغيل الوظائف ضمن وقت تشغيل 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	اعتماديات بايثون مثبتة أثناء النشر عند استخدام البناء عن بعد.	❌ (موصى به لإدارة الطرود)
local.settings.json	إعدادات وأسرار التطبيق المحلية فقط (لم تنشر أبدا).	❌ (مطلوب للتطوير المحلي)
.funcignore	يحدد الملفات والمجلدات لاستبعادها من النشر (على سبيل المثال، .venv/، tests/، local.settings.json).	❌ (مستحسن)
.venv/	البيئة الافتراضية المحلية لبايثون (مستثناة من النشر).	❌
.vscode/	إعداد المحرر لكود فيجوال ستوديو. غير مطلوب للنشر.	❌
shared/	يحتفظ بكود المساعدة المشترك عبر مشروع تطبيق الوظائف	❌
additional_functions/	يستخدم لتنظيم الشيفرة المعيارية—عادة مع المخططات.	❌
tests/	اختبارات الوحدة لتطبيق الوظائف الخاص بك. لم ينشر على Azure.	❌
Dockerfile	يحدد حاوية مخصصة للنشر.	❌

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

Example

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

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

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

Note

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

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

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

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

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

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

1. تعريف مخطط في ملف بايثون آخر، مثل 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 والمحفزات باستخدام الديكوريتورز.	✅
host.json	تكوين عام لجميع الوظائف في التطبيق.	✅
requirements.txt	اعتماديات بايثون مثبتة أثناء النشر عند استخدام البناء عن بعد.	❌ (موصى به لإدارة الطرود)
local.settings.json	إعدادات وأسرار التطبيق المحلية فقط (لم تنشر أبدا).	❌ (مطلوب للتطوير المحلي)
.funcignore	يحدد الملفات والمجلدات لاستبعادها من النشر (على سبيل المثال، .venv/، tests/، local.settings.json).	❌ (مستحسن)
.venv/	البيئة الافتراضية المحلية لبايثون (مستثناة من النشر).	❌
.vscode/	إعداد المحرر لكود فيجوال ستوديو. غير مطلوب للنشر.	❌
shared/	يحتفظ بكود المساعدة المشترك عبر مشروع تطبيق الوظائف	❌
additional_functions/	يستخدم لتنظيم الشيفرة المعيارية—عادة مع المخططات.	❌
tests/	اختبارات الوحدة لتطبيق الوظائف الخاص بك. لم ينشر على Azure.	❌
Dockerfile	يحدد حاوية مخصصة للنشر.	❌

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

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

---

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

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

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

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

لمزيد من المعلومات حول المشغلات والقيود المتاحة، راجع المشغلات والروابط في 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 للغة بايثون متوفر فقط في نموذج البرمجة الإصدار الثاني من بايثون.

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

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

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

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

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

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

Note

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

إدارة الحزم

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

على سبيل المثال، توضح العينة التالية كيف تم تضمين الوحدة 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}")

الاعتبارات

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

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

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

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

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

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

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

func start

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

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

يمكنك معرفة المزيد عن كيفية استخدام الأدوات الأساسية من خلال زيارة قسم تطوير وظائف Azure محليا باستخدام Core Tools.

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

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

# 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 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 __init__.py

Hello, World!

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

نسخ بايثون المدعومة

يدعم Azure Functions نسخ بايثون المدرجة في اللغات المدعومة في Azure Functions. لمزيد من المعلومات العامة، راجع سياسة دعم وقت التشغيل Azure Functions.

Important

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

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

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

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

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

Note

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

Important

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

تحديثات بايثون 3.13+

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يقدم Azure Functions جهاز تسجيل جذور يمكنك استخدامه مباشرة مع وحدة بايثون المدمجة logging . أي رسائل مكتوبة باستخدام هذا المسجل ترسل تلقائيا إلى 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 في البوابة، راجع مراقبة وظائف Azure.

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")

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

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

import logging

custom_logger = logging.getLogger('my_custom_logger')

دعم OpenTelemetry

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

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

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

اكتب وشغل اختبارات الوحدة لوظائفك باستخدام pytest. يمكنك اختبار وظائف بايثون مثل باقي كودات بايثون باستخدام أطر اختبار قياسية. بالنسبة لمعظم الربطات، يمكنك إنشاء كائن إدخال تجريبي عن طريق إنشاء نسخة من فئة مناسبة من الحزمة 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',
    )

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

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 ============================================================================================================= 

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

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

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

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

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

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

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