مشاركة عبر

ربط إدخال خدمة SignalR لـAzure Functions

  • مقالة

قبل أن يتمكن العميل من الاتصال بخدمة Azure SignalR، يجب استرداد عنوان URL لنقطة نهاية الخدمة ورمز وصول صالح. ربط إدخال SignalRConnectionInfo ينتج URL لنقطة نهاية خدمة SignalR ورمزًا مميزًا صالحًا يتم استخدامهما للاتصال بالخدمة. الرمز المميز محدود زمنيا ويمكن استخدامه لمصادقة مستخدم معين على اتصال. لذلك، لا يجب تخزين الرمز المميز مؤقتا أو مشاركته بين العملاء. عادة ما تستخدم SignalRConnectionInfo مع مشغل HTTP للعملاء لاسترداد معلومات الاتصال.

لمزيد من المعلومات حول كيفية استخدام هذا الربط لإنشاء دالة "التفاوض" المتوافقة مع SDK عميل SignalR، راجع تطوير وتكوين Azure Functions باستخدام Azure SignalR Service. للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع الاستعراض العام.

مثال

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

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

هام

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

يوضح المثال التالي دالة C#‎ التي تكتسب معلومات اتصال SignalR باستخدام ربط الإدخال وإعادته عبر HTTP.

[Function(nameof(Negotiate))]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
    [SignalRConnectionInfoInput(HubName = "serverless")] string connectionInfo)
{
    // The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
    return connectionInfo;
}

يوضح المثال التالي ربط إدخال معلومات اتصال SignalR في ملف function.json ودالة تستخدم الربط لإعادة معلومات الاتصال.

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

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "hubName1",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

ها هي كود JavaScript:

const { app, input } = require('@azure/functions');

const inputSignalR = input.generic({
    type: 'signalRConnectionInfo',
    name: 'connectionInfo',
    hubName: 'hubName1',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

app.post('negotiate', {
    authLevel: 'function',
    handler: (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
    },
    route: 'negotiate',
    extraInputs: [inputSignalR],
});

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

يوضح المثال التالي ربط إدخال معلومات اتصال SignalR في ملف function.json و دالة Python التي تستخدم الربط لإعادة معلومات الاتصال.

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

def main(req: func.HttpRequest, connectionInfoJson: str) -> func.HttpResponse:
    return func.HttpResponse(
        connectionInfoJson,
        status_code=200,
        headers={
            'Content-type': 'application/json'
        }
    )

يوضح المثال التالي دالة Java التي تكتسب معلومات اتصال SignalR باستخدام ربط الإدخال وإعادته عبر HTTP.

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            HubName = "hubName1") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

الاستخدام

رموز مميزة مصادق عليها

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

يتم من خلال مصادقة خدمة التطبيق تعيين عناوين HTTP المسماة x-ms-client-principal-id وx-ms-client-principal-name التي تحتوي على معرف واسم العميل الرئيسي للمستخدم المصادق عليه، على الترتيب.

يمكنك تعيين خاصية UserIdالربط إلى القيمة من العنوان باستخدام تعبير ربط:{headers.x-ms-client-principal-id} أو {headers.x-ms-client-principal-name} .

[Function("Negotiate")]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
    [SignalRConnectionInfoInput(HubName = "hubName1", UserId = "{headers.x-ms-client-principal-id}")] string connectionInfo)
{
    // The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
    return connectionInfo;
}

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST, HttpMethod.GET },
            authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(name = "connectionInfo", hubName = "hubName1", userId = "{headers.x-ms-signalr-userid}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

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

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "hubName1",
    "userId": "{headers.x-ms-client-principal-id}",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

ها هي كود JavaScript:

const { app, input } = require('@azure/functions');

const inputSignalR = input.generic({
    type: 'signalRConnectionInfo',
    name: 'connectionInfo',
    hubName: 'hubName1',
    connectionStringSetting: 'AzureSignalRConnectionString',
    userId: '{headers.x-ms-client-principal-id}',
});

app.post('negotiate', {
    authLevel: 'function',
    handler: (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
    },
    route: 'negotiate',
    extraInputs: [inputSignalR],
});

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

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

def main(req: func.HttpRequest, connectionInfo: str) -> func.HttpResponse:
    # connectionInfo contains an access key token with a name identifier
    # claim set to the authenticated user
    return func.HttpResponse(
        connectionInfo,
        status_code=200,
        headers={
            'Content-type': 'application/json'
        }
    )

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            HubName = "hubName1",
            userId = "{headers.x-ms-client-principal-id}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

السمات

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

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

خاصية السمة ‏‏الوصف
HubName مطلوب. اسم المركز.
ConnectionStringSetting اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.
UserId اختياري. معرف المستخدم لاتصال SignalR. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
رمز IdToken اختياري. رمز JWT المميز الذي ستتم إضافة مطالباته إلى مطالبات المستخدم. يجب استخدامه مع ClaimTypeList. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
ClaimTypeList اختياري. قائمة بأنواع المطالبات، والتي تقوم بتصفية المطالبات في IdToken .

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

يوضح الجدول التالي الإعدادات المدعومة للتعليق التوضيحي SignalRConnectionInfoInput.

الإعدادات الوصف
الاسم اسم المتغير المستخدم في تعليمات الوظيفة البرمجية لعنصر معلومات الاتصال.
hubName مطلوب. اسم المركز.
connectionStringSetting اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.
المعرف الخاص بالمستخدم اختياري. معرف المستخدم لاتصال SignalR. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
idToken اختياري. رمز JWT المميز الذي ستتم إضافة مطالباته إلى مطالبات المستخدم. يجب استخدامه مع claimTypeList. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
claimTypeList اختياري. قائمة بأنواع المطالبات، التي تقوم بتصفية المطالبات في idToken .

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

يوضح الجدول التالي الإعدادات المدعومة للتعليق التوضيحي SignalRConnectionInfoInput.

الإعدادات الوصف
الاسم اسم المتغير المستخدم في تعليمات الوظيفة البرمجية لعنصر معلومات الاتصال.
hubName مطلوب. اسم المركز.
connectionStringSetting اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.
المعرف الخاص بالمستخدم اختياري. معرف المستخدم لاتصال SignalR. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
idToken اختياري. رمز JWT المميز الذي ستتم إضافة مطالباته إلى مطالبات المستخدم. يجب استخدامه مع claimTypeList. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
claimTypeList اختياري. قائمة بأنواع المطالبات، التي تقوم بتصفية المطالبات في idToken .

التكوين

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

خاصية function.json ‏‏الوصف
النوع يجب تعيينه إلى signalRConnectionInfo.
الاتجاه يجب تعيينه إلى in.
hubName مطلوب. اسم المركز.
connectionStringSetting اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضياً على AzureSignalRConnectionString.
المعرف الخاص بالمستخدم اختياري. معرف المستخدم لاتصال SignalR. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
idToken اختياري. رمز JWT المميز الذي ستتم إضافة مطالباته إلى مطالبات المستخدم. يجب استخدامه مع claimTypeList. يمكنك استخدام تعبير ربط لربط القيمة برأس طلب HTTP أو استعلام.
claimTypeList اختياري. قائمة بأنواع المطالبات، التي تقوم بتصفية المطالبات في idToken .

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

إنه سيناريو شائع أن تأتي قيم بعض سمات ربط إدخال SignalR من طلبات HTTP. لذلك، نوضح كيفية ربط القيم من طلبات HTTP إلى سمات ربط إدخال SignalR عبر تعبير الربط.

نوع بيانات تعريف HTTP تنسيق تعبير الربط ‏‏الوصف مثال
استعلام طلب HTTP {query.QUERY_PARAMETER_NAME} ربط قيمة معلمة الاستعلام المقابلة بسمة {query.userName}
رأس طلب HTTP {headers.HEADER_NAME} ربط قيمة رأس بسمة {headers.token}

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