لربط مشغل خدمة SignalR لوظائف Azure

استخدم رابط مشغل SignalR للرد على الرسائل المرسلة من خدمة Azure SignalR. عند تشغيل الوظيفة، يتم توزيع الرسائل التي تم تمريرها إلى الوظيفة كعنصر json.

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

للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع الاستعراض العام.

مثال

يمكن إنشاء دالة C# باستخدام أحد أوضاع C# التالية:

• نموذج العامل المعزول: دالة C# المترجمة التي يتم تشغيلها في عملية عامل معزولة عن وقت التشغيل. عملية العامل المعزولة مطلوبة لدعم وظائف C# التي تعمل على إصدارات LTS وغير LTS .NET و.NET Framework.
• نموذج قيد المعالجة: دالة C# المحولة برمجيا التي تعمل في نفس العملية مثل وقت تشغيل الوظائف.
• البرنامج النصي C#: يستخدم بشكل أساسي عند إنشاء وظائف C# في مدخل Microsoft Azure.

هام

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

نموذج عامل معزول

يظهر النموذج التالي دالة C# التي تتلقى حدث رسالة من العملاء وتسجل محتوى الرسالة.

[Function(nameof(OnClientMessage))]
public static void OnClientMessage(
    [SignalRTrigger("Hub", "messages", "sendMessage", "content", ConnectionStringSetting = "SignalRConnection")]
        SignalRInvocationContext invocationContext, string content, FunctionContext functionContext)
{
    var logger = functionContext.GetLogger(nameof(OnClientMessage));
    logger.LogInformation("Connection {connectionId} sent a message. Message content: {content}", invocationContext.ConnectionId, content);
}

هام

لا يعمل النموذج المستند إلى الفئة من روابط SignalR Service في عامل C# المعزول على تحسين كيفية كتابة مشغلات SignalR بسبب تقييد نموذج عامل C#. لمزيد من المعلومات حول النموذج المستند إلى الفئة، راجع النموذج المستند إلى الفئة.

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

يحتوي ربط مشغل SignalR Service لنموذج C# قيد المعالجة على نموذجين للبرمجة. النموذج المستند إلى الفئة والنموذج التقليدي. يوفر النموذج القائم على الفئة تجربة برمجة متسقة من جانب الخادم SignalR. يوفر النموذج التقليدي مرونة أكبر ويتشابه مع روابط الوظائف الأخرى.

لدى النموذج المستند إلى الفئة

راجع النموذج المستند إلى الفئة للحصول على التفاصيل.

public class HubName1 : ServerlessHub
{
    [FunctionName("SignalRTest")]
    public Task SendMessage([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
    }
}

باستخدام النموذج التقليدي

يطيع النموذج التقليدي اتفاقية وظيفة Azure المطورة بواسطة C#. إذا لم تكن على دراية به، يمكنك التعلم من المستندات.

[FunctionName("SignalRTest")]
public static Task Run([SignalRTrigger("SignalRTest", "messages", "SendMessage", parameterNames: new string[] {"message"})]InvocationContext invocationContext, string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

نظرًا لأنه قد يكون من الصعب استخدامه ParameterNames في المشغل، يوضح لك المثال التالي كيفية استخدام السمة SignalRParameter لتعريف السمة message .

[FunctionName("SignalRTest")]
public static Task Run([SignalRTrigger("SignalRTest", "messages", "SendMessage")]InvocationContext invocationContext, [SignalRParameter]string message, ILogger logger)
{
    logger.LogInformation($"Receive {message} from {invocationContext.ConnectionId}.");
}

مشغل SignalR غير مدعوم حاليًا لـ Java.

إليك بيانات الربط في ملف function.json:

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

الطراز v4

app.generic("function1",
    {
        trigger: { "type": "signalRTrigger", "name": "invocation", "direction": "in", "hubName": "hubName1", "event": "SendMessage", "category": "messages" },
        handler: (triggerInput, context) => {
            context.log(`Receive ${context.Arguments[0]} from ${triggerInput.ConnectionId}.`)
        }
    })

الطراز v3

إليك بيانات الربط في ملف function.json:

{
    "type": "signalRTrigger",
    "name": "invocation",
    "hubName": "hubName1",
    "category": "messages",
    "event": "SendMessage",
    "parameterNames": [
        "message"
    ],
    "direction": "in"
}

ها هي كود JavaScript:

module.exports = function (context, invocation) {
    context.log(`Receive ${context.bindingData.message} from ${invocation.ConnectionId}.`)
};

أمثلة PowerShell الكاملة معلقة.

إليك التعليمة البرمجية لـ Python:

import logging
import json
import azure.functions as func

def main(invocation) -> None:
    invocation_json = json.loads(invocation)
    logging.info("Receive {0} from {1}".format(invocation_json['Arguments'][0], invocation_json['ConnectionId']))

السمات

تستخدم كل من مكتبات المعالجة والعامل المعزول C# السمة SignalRTrigger لتعريف الدالة. يستخدم البرنامج النصي C# بدلاً من ذلك ملف تكوين function.json.

نموذج عامل معزول

يوضح الجدول التالي خصائص السمة SignalRTrigger:

خاصية السمة	‏‏الوصف
HubName	يجب تعيين هذه القيمة إلى اسم SignalR hub للوظيفة التي سيتم تشغيلها.
الفئة	يجب تعيين هذه القيمة كفئة رسائل للوظيفة التي سيتم تشغيلها. يمكن أن تكون الفئة إحدى القيم التالية: الاتصالات: بما في ذلك الأحداث المتصلةوالمنفصلة الرسائل: بما في ذلك جميع الأحداث الأخرى باستثناء تلك الموجودة في فئة الاتصالات
الحدث	يجب تعيين هذه القيمة كحدث رسائل للوظيفة التي سيتم تشغيلها. بالنسبة إلى فئة الرسائل، الحدث هو الهدففي رسالة الاستدعاء التي يرسلها العملاء. بالنسبة إلى فئة الاتصالات، يتم استخدام الاتصال وقطع الاتصال فقط.
أسماء المعلمات	(اختياري) قائمة بالأسماء التي ترتبط بالمعلمات.
ConnectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.

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

يوضح الجدول التالي خصائص السمة SignalRTrigger:

خاصية السمة	‏‏الوصف
HubName	يجب تعيين هذه القيمة إلى اسم SignalR hub للوظيفة التي سيتم تشغيلها.
الفئة	يجب تعيين هذه القيمة كفئة رسائل للوظيفة التي سيتم تشغيلها. يمكن أن تكون الفئة إحدى القيم التالية: الاتصالات: بما في ذلك الأحداث المتصلةوالمنفصلة الرسائل: بما في ذلك جميع الأحداث الأخرى باستثناء تلك الموجودة في فئة الاتصالات
الحدث	يجب تعيين هذه القيمة كحدث رسائل للوظيفة التي سيتم تشغيلها. بالنسبة إلى فئة الرسائل، الحدث هو الهدففي رسالة الاستدعاء التي يرسلها العملاء. بالنسبة إلى فئة الاتصالات، يتم استخدام الاتصال وقطع الاتصال فقط.
أسماء المعلمات	(اختياري) قائمة بالأسماء التي ترتبط بالمعلمات.
ConnectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.

تعليقات توضيحية

لا يوجد حاليا تعليق توضيحي مدعوم لـ Java لمشغل SignalR.

التكوين

يشرح الجدول الآتي خصائص تكوين ربط البيانات التي عليك تعيينها في ملف function.json.

خاصية function.json	‏‏الوصف
النوع	يجب تعيينه إلى SignalRTrigger.
الاتجاه	يجب تعيينه إلى in.
الاسم	الاسم المتغير المستخدم في رمز الوظيفة للعنصر في سياق استدعاء المشغل.
hubName	يجب تعيين هذه القيمة إلى اسم SignalR hub للوظيفة التي سيتم تشغيلها.
الفئة	يجب تعيين هذه القيمة كفئة رسائل للوظيفة التي سيتم تشغيلها. يمكن أن تكون الفئة إحدى القيم التالية: الاتصالات: بما في ذلك الأحداث المتصلةوالمنفصلة الرسائل: بما في ذلك جميع الأحداث الأخرى باستثناء تلك الموجودة في فئة الاتصالات
الحدث	يجب تعيين هذه القيمة كحدث رسائل للوظيفة التي سيتم تشغيلها. بالنسبة إلى فئة الرسائل، الحدث هو الهدففي رسالة الاستدعاء التي يرسلها العملاء. بالنسبة إلى فئة الاتصالات، يتم استخدام الاتصال وقطع الاتصال فقط.
أسماء المعلمات	(اختياري) قائمة بالأسماء التي ترتبط بالمعلمات.
connectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.

راجع قسم Example للحصول على أمثلة كاملة.

الاستخدام

الحمولات

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

InvocationContext

InvocationContext يحتوي على جميع المحتويات في الرسالة المرسلة من خدمة SignalR، والتي تتضمن الخصائص التالية:

الخاصية	‏‏الوصف
الوسيطات	متوفر لفئة الرسائل. يحتوي على وسيطاتفي رسالة استدعاء
خطأ	متوفرة لحدث قطع الاتصال. قد يكون فارغًا إذا كان الاتصال مغلقًا بدون خطأ، أو أنه يحتوي على رسائل الخطأ.
مركز	اسم المركز الذي تنتمي إليه الرسالة.
الفئة	فئة الرسالة.
الحدث	حدث الرسالة.
ConnectionId	معرف الاتصال للعميل الذي يرسل الرسالة.
معرف المستخدم	هوية المستخدم للعميل الذي يرسل الرسالة.
الرؤوس	رؤوس الطلب.
الاستعلام	الاستعلام عن الطلب عند اتصال العملاء بالخدمة.
المطالبات	ادعاءات العميل.

استخدام ParameterNames

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

لنفترض أن لديك عميل JavaScript SignalR يحاول الاحتجاج بالأسلوبbroadcast في وظيفة Azure باستخدام الوسيطتين message1،message2.

await connection.invoke("broadcast", message1, message2);

بعد تعيين parameterNames، الاسم الذي قمت بتعريفه سيتطابق مع الحجج المرسلة من جانب العميل.

[SignalRTrigger(parameterNames: new string[] {"arg1, arg2"})]

بعد ذلك، arg1 يحتوي على محتوى message1، ويحتوي arg2 على محتوى message2.

ParameterNames الاعتبارات

بالنسبة إلى ربط المعلمة، فإن الأمر مهم. إذا كنت تستخدم ParameterNamesالترتيبParameterNames في تطابق ترتيب الوسائط التي تستدعيها للعميل. إذا كنت تستخدم [SignalRParameter] السمة في C#، فإن ترتيب الوسيطات في أساليب وظيفة Azure يطابق ترتيب الوسيطات للعملاء.

ParameterNamesولا يمكن استخدام السمة [SignalRParameter] و في نفس الوقت، أو ستحصل على استثناء.

خدمة SignalR المتكاملة

تحتاج خدمة SignalR إلى عنوان URL للوصول إلى تطبيق الوظائف عند استخدام ربط مشغل خدمة SignalR. يجب تكوين URL في إعدادات المصدر على جانب خدمة SignalR.

عند استخدام مشغل SignalR Service، يمكن أن يكون عنوان URL بسيطا ومنسقا كما يلي:

<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>

Function_App_URL يمكن العثور على في صفحة نظرة عامة على تطبيق الوظائف ويتم API_KEY إنشاء بواسطة Azure Function. يمكنك الحصول على API_KEY من signalr_extension في شفرة مفاتيح التطبيق من التطبيق الوظائف.

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

عينة خطوة بخطوة

يمكنك متابعة العينة في GitHub لنشر غرفة دردشة على تطبيق الوظائف مع ربط مشغل خدمة SignalR وميزة المصدر: عينة غرفة محادثة ثنائية الاتجاه

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

• تطوير وتكوين وظائف Azure مع خدمة Azure SignalR
• عينة ربط مشغل خدمة SignalR
• نموذج ربط مشغل خدمة SignalR في عملية عامل معزولة