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

مقالة
04/21/2022
قراءة خلال 6 دقائق

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

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

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

مثال

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

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

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

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
    [SignalRConnectionInfo(HubName = "chat")]SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

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

[Function("SignalRFunction")]
[SignalROutput(HubName = "chat", ConnectionStringSetting = "SignalRConnectionString")]
public static MyMessage Run([SignalRTrigger("SignalRTest", "messages", "SendMessage", parameterNames: new string[] { "message" },
    ConnectionStringSetting = "SignalRConnectionString")] string item,
    [SignalRConnectionInfoInput(HubName = "chat")] MyConnectionInfo connectionInfo,
    FunctionContext context)
{
    var logger = context.GetLogger("SignalRFunction");

    logger.LogInformation(item);
    logger.LogInformation($"Connection URL = {connectionInfo.Url}");

    var message = $"Output message created at {DateTime.Now}";

    return new MyMessage()
    {
        Target = "newMessage",
        Arguments = new[] { message }
    };
}

MyConnectionInfo يتم تعريف الفئات والفئات MyMessage على النحو التالي:

public class MyConnectionInfo
{
    public string Url { get; set; }

    public string AccessToken { get; set; }
}

public class MyMessage
{
    public string Target { get; set; }

    public object[] Arguments { get; set; }
}

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

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

مثال function.json:

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

هنا رمز برنامج C# النصي:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static SignalRConnectionInfo Run(HttpRequest req, SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

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

فيما يلي بيانات ملزمة للمثال في ملف function.json :

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

هنا تعليمة برمجية JavaScript:

module.exports = async function (context, req, connectionInfo) {
    context.res.body = connectionInfo;
};

أمثلة 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 = "chat") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

الاستخدام

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

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

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

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

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req, 
    [SignalRConnectionInfo
        (HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
        SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier claim set to the authenticated user
    return connectionInfo;
}

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

مثال على function.js:

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

هنا رمز برنامج C# النصي:

#r "Microsoft.Azure.WebJobs.Extensions.SignalRService"
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

public static SignalRConnectionInfo Run(HttpRequest req, SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier
    // claim set to the authenticated user
    return connectionInfo;
}

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

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

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

هنا تعليمة برمجية JavaScript:

module.exports = async function (context, req, connectionInfo) {
    // connectionInfo contains an access key token with a name identifier
    // claim set to the authenticated user
    context.res.body = connectionInfo;
};

أمثلة 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 = "chat",
            userId = "{headers.x-ms-client-principal-id}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

السمات

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

يشرح الجدول التالي خصائص السمة SignalRConnectionInfo :

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

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

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

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

خاصية function.json	الوصف
النوع	يجب تعيينها إلى `signalRConnectionInfo`.
⁧⁩direction⁧⁩	يجب تعيينها إلى `in`.
الاسم	اسم المتغير المستخدم في تعليمات الوظيفة البرمجية لعنصر معلومات الاتصال.
hubName	يجب تعيين هذه القيمة إلى اسم مركز SignalR الذي يتم إنشاء معلومات الاتصال له.
معرّف المستخدم	اختياري: قيمة مطالبة معرف المستخدم المراد تعيينها في الرمز المميز لمفتاح الاختصار.
connectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضيا إلى `AzureSignalRConnectionString`.

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

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

الإعداد	الوصف
الاسم	اسم المتغير المستخدم في تعليمات الوظيفة البرمجية لعنصر معلومات الاتصال.
hubName	يجب تعيين هذه القيمة إلى اسم مركز SignalR الذي يتم إنشاء معلومات الاتصال له.
معرّف المستخدم	اختياري: قيمة مطالبة معرف المستخدم المراد تعيينها في الرمز المميز لمفتاح الاختصار.
connectionStringSetting	اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال خدمة SignalR، والتي يتم تعيينها افتراضيا إلى `AzureSignalRConnectionString`.

التكوين