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

مقالة
10/18/2023

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

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

تثبيت الملحق

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

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

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

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

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

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

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

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

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

تثبيت الحزمة

يعد ربط Service Bus جزءاً منحزمة الملحق، المحددة في ملف مشروع host.json الخاص بك. من الممكن أن تحتاج إلى تعديل هذه الحزمة لتغيير إصدار الربط، أو إذا لم تكن الحزم مثبتة بالفعل. لمعرفة المزيد، راجع حزمة الإضافات.

يمكن إضافة حزمة ملحق مجموعة المعاينة v3 هذا من خلال إضافة أو استبدال التعليمة البرمجية التالية في ملف host.jsonالخاص بك:

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

لمعرفة المزيد، راجع تحديث الإضافات.

أنواع الربط

تعتمد أنواع الربط المعتمدة ل .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.

^{2 عند استخدام ServiceBusMessageActions، قم بتعيين AutoCompleteMessages خاصية سمة المشغل إلى false.} يمنع هذا وقت التشغيل من محاولة إكمال الرسائل بعد استدعاء دالة ناجحة.

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

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

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

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

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

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

إعدادات 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. لا تؤثر على عمليات إعادة محاولة تنفيذ الوظائف. لمزيد من المعلومات، راجع إعادة المحاولة.

الخاصية	Default	‏‏الوصف
الوضع	`Exponential`	الأسلوب المستخدم لحساب تأخيرات إعادة المحاولة. يعيد الوضع الأسي الافتراضي المحاولات مع بعض التأخير استناداً إلى إستراتيجية التراجع حيث تزيد كل محاولة من مدة الانتظار قبل إعادة المحاولة. سيعيد الوضع `Fixed` المحاولة على فترات زمنية ثابتة مع كل تأخير بمدة متسقة.
مهلة المحاولة	`00:01:00`	المدة القصوى لانتظار العملية لكل محاولة.
تأخير	`00:00:00.80`	عامل التأخير أو التراجع المراد تطبيقه بين محاولات إعادة المحاولة.
maxDelay	`00:01:00`	الحد الأقصى للتأخير للسماح بين محاولات إعادة المحاولة
maxRetries	`3`	الحد الأقصى لعدد محاولات إعادة المحاولة قبل اعتبار العملية المقترنة قد فشلت.
عدد الجلب المسبق	`0`	الحصول على أو تحديد عدد الرسائل التي يمكن لمتلقي الرسالة أن يطلبها في نفس الوقت.
transportType	amqpTcp	البروتوكول والنقل المستخدم للتواصل مع Service Bus. الخيارات المتاحة: `amqpTcp`، `amqpWebSockets`
webProxy	غير متوفر	الوكيل الذي يجب استخدامه للاتصال بـ Service Bus عبر مآخذ الويب. لا يمكن استخدام الوكيل مع النقل `amqpTcp`.
رسائل الإكمال التلقائي	`true`	تحديد ما إذا كان يجب إكمال الرسائل تلقائيا بعد التنفيذ الناجح للدالة أم لا.
maxAutoLockRenewalDuration	`00:05:00`	الحد الأقصى للمدة التي سيتم خلالها تجديد قفل الرسالة تلقائيًا. ينطبق هذا الإعداد فقط على الدوال التي تتلقى رسالة واحدة في كل مرة.
maxConcurrentCalls	`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.

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

مشاركة عبر

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

تثبيت الملحق

تثبيت الحزمة

أنواع الربط

إعدادات host.json

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

الملاحظات

الموارد الإضافية