روابط ناقل خدمة Microsoft Azure لـ Azure Functions

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

الإجراء	نوع
قم بتشغيل وظيفة عند قائمة انتظار ناقل الخدمة أو رسالة موضوع	المشغِّل
إرسال رسائل ناقل خدمة Azure	ربط الإخراج

تثبيت الملحق

تعتمد حزمة NuGet الملحق التي تقوم بتثبيتها على وضع C# الذي تستخدمه في تطبيق الوظائف:

نموذج عامل معزول
نموذج قيد المعالجة

يتم تنفيذ الوظائف في عملية عامل C# معزولة. لمعرفة المزيد، راجع دليل تشغيل وظائف C# Azure في عملية عامل معزولة.

أضف الملحق إلى مشروعك عن طريق تثبيت حزمة NuGet.

تختلف وظيفة الملحق باختلاف إصدار الملحق:

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

يسمح هذا الإصدار بالربط بالأنواع من Azure.Messaging.ServiceBus.

يدعم هذا الإصدار تكوين المشغلات والروابط من خلال تكامل .NET Aspire.

أضف الملحق إلى مشروعك عن طريق تثبيت حزمة NuGet، الإصدار 5.x.

تثبيت الحزمة

لكي تتمكن من استخدام ملحق الربط هذا في تطبيقك، تأكد من أن ملف host.json في جذر مشروعك يحتوي على هذا extensionBundle المرجع:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

في هذا المثال، version ترشد قيمة [4.0.0, 5.0.0) مضيف الوظائف إلى استخدام إصدار حزمة على الأقل 4.0.0 ولكن أقل من 5.0.0، والذي يتضمن جميع الإصدارات المحتملة من 4.x. يحافظ هذا النص بشكل فعال على تطبيقك على أحدث إصدار ثانوي متوفر من مجموعة ملحقات v4.x.

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

أنواع الربط

تعتمد أنواع الربط المعتمدة ل .NET على كل من إصدار الملحق ووضع تنفيذ C#، والتي يمكن أن تكون واحدة مما يلي:

نموذج عامل معزول
مكتبة الصف قيد المعالجة

تعمل مكتبة فئة معالجة عامل معزولة تعمل دالة C# المحولة برمجيا في عملية معزولة عن وقت التشغيل.

اختر إصدارا للاطلاع على تفاصيل نوع الربط للوضع والإصدار.

يدعم ملحق ناقل خدمة Microsoft Azure أنواع المعلمات وفقا للجدول أدناه.

سيناريو الربط	أنواع المعلمات
مشغل ناقل خدمة Microsoft Azure (رسالة واحدة)	ServiceBusReceivedMessage `string` `byte[]` أنواع^{JSON القابلة للتسلسل 1}
مشغل ناقل خدمة Microsoft Azure (دفعة الرسائل)	`ServiceBusReceivedMessage[]` `string[]`
سيناريوهات متقدمة^{لمشغل ناقل خدمة Microsoft Azure 2}	ServiceBusClient ServiceBusMessageActions ServiceBusSessionMessageActions ServiceBusReceiveActions
إخراج ناقل خدمة Microsoft Azure (رسالة واحدة)	ServiceBusMessage `string` `byte[]` أنواع^{JSON القابلة للتسلسل 1}
إخراج ناقل خدمة Microsoft Azure (رسائل متعددة)	`ICollector<T>` أو `IAsyncCollector<T>` أين `T` هو أحد أنواع الرسائل الفردية ServiceBusSender

¹ يمكن إلغاء تسلسل الرسائل التي تحتوي على بيانات JSON إلى أنواع كائنات CLR معروفة قديمة عادية (POCO).

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

تعرض الإصدارات السابقة من الملحق الأنواع من مساحة اسم Microsoft.Azure.ServiceBus المهملة الآن. الأنواع الأحدث من Azure.Messaging.ServiceBus حصرية للملحق 5.x+.

في 30 سبتمبر 2026، سنتقاعد مكتبات SDK ناقل خدمة Azure WindowsAzure.ServiceBus وMicrosoft.Azure.ServiceBus و com.microsoft.azure.servicebus، والتي لا تتوافق مع إرشادات Azure SDK. سننهي أيضا دعم بروتوكول SBMP، لذلك لن تتمكن من استخدام هذا البروتوكول بعد 30 سبتمبر 2026. قم بالترحيل إلى أحدث مكتبات Azure SDK، والتي توفر تحديثات أمان هامة وقدرات محسنة، قبل ذلك التاريخ.

على الرغم من أنه لا يزال من الممكن استخدام المكتبات القديمة بعد 30 سبتمبر 2026، إلا أنها لن تتلقى بعد ذلك الدعم والتحديثات الرسمية من Microsoft. لمزيد من المعلومات، راجع إعلان إيقاف الدعم.

يدعم هذا الإصدار من الملحق أنواع المعلمات وفقا للجدول أدناه.

يدعم ملحق ناقل خدمة Microsoft Azure أنواع المعلمات وفقا للجدول أدناه.

سيناريو الربط	أنواع المعلمات
مشغل ناقل خدمة Microsoft Azure (رسالة واحدة)	[Microsoft.Azure.ServiceBus.Message] `string` `byte[]` أنواع^{JSON القابلة للتسلسل 1}
مشغل ناقل خدمة Microsoft Azure (دفعة الرسائل)	`ServiceBusReceivedMessage[]` `string[]`
سيناريوهات متقدمة^{لمشغل ناقل خدمة Microsoft Azure 2}	IMessageReceiver MessageReceiver IMessageSession
إخراج ناقل خدمة Microsoft Azure (رسالة واحدة)	رسالة `string` `byte[]` أنواع^{JSON القابلة للتسلسل 1}
إخراج ناقل خدمة Microsoft Azure (رسائل متعددة)	`ICollector<T>` أو `IAsyncCollector<T>` أين `T` هو أحد أنواع الرسائل الفردية MessageSender

¹ يمكن إلغاء تسلسل الرسائل التي تحتوي على بيانات JSON إلى أنواع كائنات CLR معروفة قديمة عادية (POCO).

تدعم عملية العامل المعزولة أنواع المعلمات وفقا للجداول أدناه.

مشغل ناقل خدمة Azure

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

نوع	‏‏الوصف
`string`	الرسالة كسلسلة. استخدم عندما تكون الرسالة نصاً بسيطاً.
`byte[]`	وحدات البايت للرسالة.
‏‏أنواع قابلة للتسلسل إلى JSON	عندما يحتوي حدث على بيانات JSON، تحاول الدالات إلغاء تسلسل بيانات JSON إلى نوع كائن CLR (POCO) قديم عادي.
ServiceBusReceivedMessage¹	كائن الرسالة. عند الربط ب `ServiceBusReceivedMessage`، يمكنك اختياريا أيضا تضمين معلمة من نوع ServiceBusMessageActions^1,2 لتنفيذ إجراءات تسوية الرسائل.

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

نوع	‏‏الوصف
`T[]` حيث `T` هو أحد أنواع الرسائل الفردية	صفيف من الأحداث من الدفعة. يمثل كل إدخال حدثا واحدا. عند الربط ب `ServiceBusReceivedMessage[]`، يمكنك اختياريا أيضا تضمين معلمة من نوع ServiceBusMessageActions^1,2 لتنفيذ إجراءات تسوية الرسائل.

¹ لاستخدام هذه الأنواع، تحتاج إلى الرجوع إلى Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 أو أحدث والتبعيات الشائعة لروابط نوع SDK.

يمنع هذا وقت التشغيل من محاولة إكمال الرسائل بعد استدعاء دالة ناجحة.

ربط إخراج ناقل خدمة Microsoft Azure

عندما تريد أن تكتب الدالة رسالة واحدة، يمكن ربط إخراج ناقل خدمة Microsoft Azure بالأنواع التالية:

نوع	‏‏الوصف
`string`	الرسالة كسلسلة. استخدم عندما تكون الرسالة نصاً بسيطاً.
`byte[]`	وحدات البايت للرسالة.
‏‏أنواع قابلة للتسلسل إلى JSON	كائن يمثل الرسالة. تحاول الدالات تسلسل نوع كائن CLR (POCO) قديم عادي في بيانات JSON.

عندما تريد أن تكتب الدالة رسائل متعددة، يمكن ربط إخراج ناقل خدمة Microsoft Azure بالأنواع التالية:

نوع	‏‏الوصف
`T[]` حيث `T` هو أحد أنواع الرسائل الفردية	صفيف يحتوي على رسالة متعددة. يمثل كل إدخال رسالة واحدة.

بالنسبة لسيناريوهات الإخراج الأخرى، قم بإنشاء ServiceBusClient واستخدامه مع أنواع أخرى من Azure.Messaging.ServiceBus مباشرة. راجع تسجيل عملاء Azure للحصول على مثال لاستخدام إدخال التبعية لإنشاء نوع عميل من Azure SDK.

أنواع ربط SDK

أنواع SDK لناقل خدمة Microsoft Azure قيد المعاينة. اتبع روابط Python SDK لعينة ناقل خدمة Microsoft Azure لبدء استخدام أنواع SDK لناقل خدمة Microsoft Azure في Python.

هام

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

الربط	أنواع المعلمات	العينات
مشغل ServiceBus	ServiceBusReceivedMessage	`ServiceBusReceivedMessage`

إعدادات host.json

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

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

clientRetryOptions تنطبق الإعدادات فقط على التفاعلات مع خدمة ناقل خدمة Microsoft Azure. لا تؤثر على عمليات إعادة محاولة تنفيذ الوظائف. لمزيد من المعلومات، راجع إعادة المحاولة.

الخاصية	الإعداد الافتراضي	‏‏الوصف
الوضع	`Exponential`	الأسلوب المستخدم لحساب تأخيرات إعادة المحاولة. يعيد الوضع الأسي الافتراضي المحاولات مع بعض التأخير استناداً إلى إستراتيجية التراجع حيث تزيد كل محاولة من مدة الانتظار قبل إعادة المحاولة. سيعيد الوضع `Fixed` المحاولة على فترات زمنية ثابتة مع كل تأخير بمدة متسقة.
مهلة المحاولة	`00:01:00`	المدة القصوى لانتظار العملية لكل محاولة.
تأخير	`00:00:00.80`	عامل التأخير أو التراجع المراد تطبيقه بين محاولات إعادة المحاولة.
maxDelay	`00:01:00`	الحد الأقصى للتأخير للسماح بين محاولات إعادة المحاولة
maxRetries	`3`	الحد الأقصى لعدد محاولات إعادة المحاولة قبل اعتبار العملية المقترنة قد فشلت.
عدد الجلب المسبق	`0`	الحصول على أو تحديد عدد الرسائل التي يمكن لمتلقي الرسالة أن يطلبها في نفس الوقت.
نوع النقل	amqpTcp	البروتوكول والنقل المستخدم للتواصل مع Service Bus. الخيارات المتاحة: `amqpTcp`، `amqpWebSockets`
webProxy	غير متوفر	الوكيل الذي يجب استخدامه للاتصال بـ Service Bus عبر مآخذ الويب. لا يمكن استخدام الوكيل مع النقل `amqpTcp`.
رسائل الإكمال التلقائي	`true`	تحديد ما إذا كان يجب إكمال الرسائل تلقائيا بعد التنفيذ الناجح للدالة أم لا.
maxAutoLockRenewalDuration	`00:05:00`	الحد الأقصى للمدة التي سيتم خلالها تجديد قفل الرسالة تلقائيًا. ينطبق هذا الإعداد فقط على الوظائف التي تتلقى رسالة واحدة في كل مرة ولا ينطبق على الوظائف التي تتلقى دفعة من الرسائل. بالنسبة للدفعات، يتم تعيين الحد الأقصى للمدة في ناقل خدمة Microsoft Azure على مستوى قائمة الانتظار أو الاشتراك.
maxConcurrentCalls	`16`	بشكل افتراضي، يعالج وقت تشغيل الوظائف رسائل متعددة في نفس الوقت. يحد هذا الإعداد من الحد الأقصى لعدد الاستدعاءات المتزامنة إلى رد الاتصال الذي يمكن بدؤه لكل مثيل على نطاق واسع. عندما تحتوي خطة الاستضافة الخاصة بك على أكثر من نواة واحدة لكل مثيل، يتم ضرب الحد الأقصى لعدد الاستدعاءات بشكل فعال في عدد الذاكرات الأساسية. على سبيل المثال، في خطة تعمل على أجهزة ذات نواتين، يعني الإعداد `16` الافتراضي أن الحد الأقصى لعدد الاستدعاءات المتزامنة لكل مثيل هو حقا `32` (أو `2 * 16`). يتم استخدام هذا الإعداد فقط عند تعيين الخاصية `isSessionsEnabled` أو السمة على المشغل إلى `false`. ينطبق هذا الإعداد فقط على الوظائف التي تتلقى رسالة واحدة في كل مرة بدلا من دفعة واحدة.
maxConcurrentSessions	`8`	الحد الأقصى لعدد الجلسات التي يمكن معالجتها بشكل متزامن لكل مثيل تم قياسه. يتم استخدام هذا الإعداد فقط عند تعيين الخاصية `isSessionsEnabled` أو السمة على المشغل إلى `true`. ينطبق هذا الإعداد فقط على الدوال التي تتلقى رسالة واحدة في كل مرة.
maxMessageBatchSize	`1000`	الحد الأقصى لعدد الرسائل التي سيتم تمريرها إلى كل استدعاء وظيفة. ينطبق هذا الإعداد فقط على الدوال التي تتلقى مجموعة من الرسائل.
minMessageBatchSize¹	`1`	الحد الأدنى لعدد الرسائل المطلوبة في دفعة واحدة. ينطبق الحد الأدنى فقط عندما تتلقى الدالة رسائل متعددة ويجب أن تكون أقل من `maxMessageBatchSize`. الحد الأدنى للحجم غير مضمون بشكل صارم. يتم إرسال دفعة جزئية عندما لا يمكن إعداد دفعة كاملة قبل `maxBatchWaitTime` انقضاء .
maxBatchWaitTime¹	`00:00:30`	الحد الأقصى للفاصل الزمني الذي يجب أن ينتظره المشغل لتعبئة دفعة قبل استدعاء الدالة. يتم مراعاة وقت الانتظار فقط عندما `minMessageBatchSize` يكون أكبر من 1 ويتم تجاهله بخلاف ذلك. إذا كان أقل من `minMessageBatchSize` الرسائل متوفرة قبل انقضاء وقت الانتظار، يتم استدعاء الدالة مع دفعة جزئية. أطول وقت انتظار مسموح به هو 50٪ من مدة تأمين رسالة الكيان، ما يعني أن الحد الأقصى المسموح به هو دقيقتان و30 ثانية. وإلا، فقد تحصل على استثناءات التأمين. ملاحظة: هذا الفاصل الزمني ليس ضمانا صارما للتوقيت الدقيق الذي يتم استدعاء الدالة عليه. هناك هامش خطأ صغير بسبب دقة المؤقت.
sessionIdleTimeout	غير متوفر	أقصى مدة انتظار حتى يتم استلام رسالة للجلسة النشطة حاليًا. بعد انقضاء هذا الوقت، سيتم إغلاق الجلسة وستحاول الدالة معالجة جلسة عمل أخرى.
enableCrossEntityTransactions	`false`	ما إذا كان يجب تمكين المعاملات التي تمتد عبر كيانات متعددة على مساحة اسم Service Bus أم لا.

¹ استخدام minMessageBatchSize ويتطلب maxBatchWaitTimeالإصدار 5.10.0 من الحزمة Microsoft.Azure.WebJobs.Extensions.ServiceBus ، أو إصدار أحدث.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "prefetchCount": 100,
            "messageHandlerOptions": {
                "autoComplete": true,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:05:00"
            },
            "sessionHandlerOptions": {
                "autoComplete": false,
                "messageWaitTimeout": "00:00:30",
                "maxAutoRenewDuration": "00:55:00",
                "maxConcurrentSessions": 16
            },
            "batchOptions": {
                "maxMessageCount": 1000,
                "operationTimeout": "00:01:00",
                "autoComplete": true
            }
        }
    }
}

عند تعيين خاصية أو سمة isSessionsEnabled على المشغل إلى true، يتم احترام sessionHandlerOptions. عند تعيين خاصية أو سمة isSessionsEnabled على المشغل إلى false، يتم احترام messageHandlerOptions.

الخاصية	الإعداد الافتراضي	‏‏الوصف
عدد الجلب المسبق	`0`	الحصول على أو تحديد عدد الرسائل التي يمكن لمتلقي الرسالة أن يطلبها في نفس الوقت.
maxAutoRenewDuration	`00:05:00`	الحد الأقصى للمدة التي سيتم خلالها تجديد قفل الرسالة تلقائيًا.
الإكمال التلقائي	`true`	ما إذا كان يجب على المشغل الاتصال تلقائياً بعد المعالجة، أو إذا اكتمل رمز الدالة يدوياً. الإعداد إلى `false` مدعوم فقط في C#‎. عند التعيين على `true`، يكمل المشغل الرسالة أو الجلسة أو الدفعة تلقائياً عندما يكتمل تنفيذ الدالة بنجاح ويتخلى عن الرسالة بخلاف ذلك. عند التعيين إلى `false`، فأنت مسؤول عن استدعاء أساليب ServiceBusReceiver لإكمال الرسالة أو الجلسة أو الدفعة أو التخلي عنها أو إخلالها. إذا تم طرح استثناء (ولم يتم استدعاء أي`ServiceBusReceiver` من الطرق)، فسيظل القفل موجوداً. بمجرد انتهاء صلاحية القفل، يتم إعادة وضع الرسالة`DeliveryCount` في قائمة الانتظار مع الزيادة ويتم تجديد القفل تلقائيًا. في الوظائف غير C #، ينتج عن الاستثناءات في الوظيفة استدعاءات وقت التشغيل`abandonAsync` في الخلفية. إذا لم يحدث استثناء، فسيتم`completeAsync` استدعاء في الخلفية.
maxConcurrentCalls	`16`	الحد الأقصى لعدد المكالمات المتزامنة لرد الاتصال التي يجب أن تبدأها مضخة الرسائل لكل مثيل تم قياسه. بشكل افتراضي، يعالج وقت تشغيل الوظائف رسائل متعددة في نفس الوقت.
maxConcurrentSessions	`2000`	الحد الأقصى لعدد الجلسات التي يمكن معالجتها بشكل متزامن لكل مثيل تم قياسه.
maxMessageCount	`1000`	أقصى عدد من الرسائل المرسلة إلى الوظيفة عند تشغيلها.
مهلة العملية	`00:01:00`	يتم التعبير عن قيمة الفترة الزمنية بـ `hh:mm:ss`.

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2023-10-18