مشاركة عبر

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

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

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

عند عدم الإعلان صراحة، افترض أن الأمثلة تستخدم قيمة إعداد الاتصال الافتراضية ل AzureSignalRConnectionString. للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع الاستعراض العام.

مثال

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

  • نموذج العامل المعزول: دالة C# المترجمة التي يتم تشغيلها في عملية عامل معزولة عن وقت التشغيل. مطلوب عملية عامل معزولة لدعم وظائف C# التي تعمل على إصدارات الدعم طويل المدى (LTS) والإصدارات غير LTS ل .NET و.NET Framework.
  • نموذج قيد المعالجة: دالة C# المحولة برمجيا التي تعمل في نفس العملية مثل وقت تشغيل Azure Functions.
  • البرنامج النصي 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;
}

السمات

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

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

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

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

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

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

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

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

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

التكوين

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

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

تحذير

للتبسيط، نحذف أجزاء المصادقة والتخويل في هذه العينة. ونتيجة لذلك، يمكن الوصول إلى نقطة النهاية هذه بشكل عام دون أي قيود. لضمان أمان نقطة نهاية التفاوض الخاصة بك، يجب عليك تنفيذ آليات المصادقة والتخويل المناسبة بناء على متطلباتك المحددة. للحصول على إرشادات حول حماية نقاط نهاية HTTP، راجع المقالات التالية:

الاستخدام

الاتصالات المدارة المستندة إلى الهوية

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

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

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

يتم من خلال مصادقة خدمة التطبيق تعيين عناوين 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;
}

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

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

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

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

  • Last updated on