Входные привязки Azure Web PubSub для Функции Azure

Наше расширение предлагает две привязки входных данных для различных потребностей.

  • WebPubSubConnection

    Прежде чем клиент сможет подключиться к службе Azure Web PubSub, ему необходимо получить URL-адрес конечной точки службы и действительный маркер доступа. Входная привязка WebPubSubConnection создает необходимую информацию, поэтому клиенту не нужно самостоятельно управлять созданием этого маркера. Маркер ограничен временем и может пройти проверку подлинности конкретного пользователя в подключении. Поэтому не кэшируйте маркер или не делитесь им между клиентами. Триггер HTTP, работающий с этой входной привязкой, позволяет клиенту получить сведения о соединении.

  • WebPubSubContext

    При использовании статических веб-приложений HttpTrigger используется единственный поддерживаемый триггер. В сценариях Web PubSub входная WebPubSubContext привязка помогает пользователям десериализировать исходящие HTTP-запросы из службы в протоколах Web PubSub. Таким образом, клиенты могут получить аналогичные результаты по сравнению с WebPubSubTrigger легкой обработкой в функциях. При использовании с HttpTriggerклиентом необходимо настроить предоставленный URL-адрес HttpTrigger в обработчике событий соответствующим образом.

WebPubSubConnection

Пример

В следующем примере показана функция триггера HTTP, которая получает сведения о подключении Web PubSub с помощью входной привязки и возвращает его по протоколу HTTP. В следующем примере передается UserId через часть запроса клиента, например ?userid={User-A}.

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{query.userid}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}
const { app, input } = require('@azure/functions');

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{query.userId}',
    hub: '<hub>'
});

app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [connection],
    handler: async (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get('connection')) };
    },
});

Создайте папку с согласованием и обновлением переговоров/function.json и скопируйте следующие коды JSON.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Определите функцию в согласовании или инициализации.py.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

Примечание.

Полные примеры для этого языка ожидаются

Примечание.

Расширения Web PubSub для Java пока не поддерживаются.

Получение идентификатора пользователя, прошедшего проверку подлинности

Если функцию активирует прошедший проверку подлинности клиент, вы можете добавить утверждение идентификатора пользователя для созданного маркера. Вы можете легко добавить аутентификацию к приложению-функции с помощью аутентификации Службы приложений.

Проверка подлинности службы приложений задает заголовки 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("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{headers.x-ms-client-principal-id}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}
const { app, input } = require('@azure/functions');

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{headers.x-ms-client-principal-id}',
    hub: '<hub>'
});

app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [connection],
    handler: async (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get('connection')) };
    },
});

Создайте папку с согласованием и обновлением переговоров/function.json и скопируйте следующие коды JSON.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{headers.x-ms-client-principal-id}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Определите функцию в согласовании или инициализации.py.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

Примечание.

Полные примеры для этого языка ожидаются

Примечание.

Расширения Web PubSub для Java пока не поддерживаются.

Настройка

В следующей таблице описываются свойства конфигурации привязки, заданные в файле function.json и атрибуте WebPubSubConnection .

Свойство в function.json Свойство атрибута Описание
тип Н/Д Нужно задать значение webPubSubConnection
направление Н/Д Нужно задать значение in
имя Н/Д Имя переменной, используемой в коде функции для объекта входной привязки подключения.
втулка Узел Обязательно. Для активации функции необходимо задать имя концентратора Web PubSub. Значение атрибута можно установить с более высоким приоритетом или задать в параметрах приложения как глобальное значение.
userId UserId Необязательно: значение утверждения идентификатора пользователя, которое следует задать в маркере доступа.
clientProtocol ClientProtocol Необязательный — тип протокола клиента. Допустимые значения включают default и mqtt.
Для клиентов MQTT необходимо задать для него mqttзначение .
Для других клиентов можно опустить свойство или задать для него значение default.
Подключение Подключение Обязательный — имя параметра приложения, содержащего строка подключения службы Web PubSub (по умолчанию — WebPubSubConnectionString).

Использование

WebPubSubConnection предоставляет следующие свойства.

Имя привязки Тип привязки Описание
BaseUri URI-адрес URI подключения клиента Web PubSub.
URI-адрес URI-адрес Абсолютный универсальный код ресурса (URI) подключения Web PubSub содержит AccessToken созданную базу для запроса.
AccessToken строка Создано AccessToken на основе сведений о пользователе и службе запроса.

WebPubSubConnection предоставляет следующие свойства.

Имя привязки Описание
BaseUrl URI подключения клиента Web PubSub.
URL-адрес Абсолютный универсальный код ресурса (URI) подключения Web PubSub содержит AccessToken созданную базу для запроса.
accessToken Создано AccessToken на основе сведений о пользователе и службе запроса.

Примечание.

Расширения Web PubSub для Java пока не поддерживаются.

Дополнительные настройки созданного маркера

Ограниченные типы параметров привязки не поддерживают способ передачи списка или массива, он WebPubSubConnection не полностью поддерживается со всеми пакетами SDK для сервера параметров, особенно roles, а также включает groups и expiresAfter.

Если клиенту необходимо добавить роли или отложить создание маркера доступа в функции, мы рекомендуем вам работать с серверным пакетом SDK для C#.

[Function("WebPubSubConnectionCustomRoles")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req)
{
    var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "<hub>", "<web-pubsub-connection-string>");
    var userId = req.Query["userid"].FirstOrDefault();
    // your method to get custom roles.
    var roles = GetRoles(userId);
    var url = await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteString(url.ToString());
    return response;
}

Если клиенту необходимо добавить роли или отложить сборку маркера доступа в функции, мы рекомендуем работать с серверным пакетом SDK для JavaScript.

const { app } = require('@azure/functions');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
        let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
        return { body: token.url };
    },
});

Примечание.

Полные примеры для этого языка ожидаются

Примечание.

Расширения Web PubSub для Java пока не поддерживаются.

WebPubSubContext

Пример

// validate method when upstream set as http://<func-host>/api/{event}
[Function("validate")]
public static HttpResponseData Validate(
    [HttpTrigger(AuthorizationLevel.Anonymous, "options")] HttpRequestData req,
    [WebPubSubContextInput] WebPubSubContext wpsReq)
{
    return BuildHttpResponseData(req, wpsReq.Response);
}

// Respond AbuseProtection to put header correctly.
private static HttpResponseData BuildHttpResponseData(HttpRequestData request, SimpleResponse wpsResponse)
{
    var response = request.CreateResponse();
    response.StatusCode = (HttpStatusCode)wpsResponse.Status;
    response.Body = response.Body;
    foreach (var header in wpsResponse.Headers)
    {
        response.Headers.Add(header.Key, header.Value);
    }
    return response;
}
const { app, input } = require('@azure/functions');

const wpsContext = input.generic({
    type: 'webPubSubContext',
    name: 'wpsContext'
});

app.http('connect', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [wpsContext],
    handler: async (request, context) => {
        var wpsRequest = context.extraInputs.get('wpsContext');

        return { "userId": wpsRequest.request.connectionContext.userId };
    }
});

Примечание.

Полные примеры для этого языка ожидаются

Примечание.

Расширения Web PubSub для Java пока не поддерживаются.

Настройка

В таблице ниже описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте WebPubSubContext.

Свойство в function.json Свойство атрибута Описание
тип Н/Д Должен иметь значениеwebPubSubContext.
направление Н/Д Должен иметь значениеin.
имя Н/Д Имя переменной, используемое в коде функции для входного запроса Web PubSub.
connections Connections Необязательно. Массив имен параметров приложения или префиксов коллекции, определяющих исходящие подключения службы Azure Web PubSub. Эти значения используются для проверки защиты от злоупотреблений и подписи. Если не указано, вернитесь к глобальному WebPubSubConnectionString параметру приложения. Если проверка не настроена, проверка пропускается, и все запросы принимаются.
Примере: ["CustomWebPubSubConnection1", "CustomWebPubSubConnection2"]

Внимание

Для оптимальной безопасности приложение-функция должна использовать управляемые удостоверения при подключении к службе Web PubSub вместо использования строки подключения, содержащей общий секретный ключ. Дополнительные сведения см. в статье "Авторизация запроса управляемого удостоверения с помощью идентификатора Microsoft Entra".

Использование

WebPubSubContext предоставляет следующие свойства.

Имя привязки Тип привязки Описание Свойства
запрос WebPubSubEventRequest Запрос от клиента см. в следующей таблице. WebPubSubConnectionContext из заголовка запроса и других свойств десериализированы из текста запроса, например Reason , для DisconnectedEventRequestзапроса.
Отклик HttpResponseMessage Расширение создает ответ в основном для AbuseProtection случаев ошибок и ошибок. -
сообщение об ошибке строка Описание сведений об ошибке при обработке вышестоящего запроса. -
ЕстьОшибка булевая переменная (bool) Пометка, чтобы указать, является ли это допустимым запросом вышестоящего веб-pubSub. -
isPreflight булевая переменная (bool) Пометка, чтобы указать, является ли это предварительным запросом AbuseProtection. -

Для WebPubSubEventRequestэтого десериализировано в разные классы, предоставляющие различные сведения о сценарии запроса. Для PreflightRequest или недействителен, пользователь может проверить флаги IsPreflight и HasError узнать. Мы рекомендуем напрямую возвращать ответ WebPubSubContext.Response на сборку системы или клиент может регистрировать ошибки по запросу. В разных сценариях клиент может читать свойства запроса следующим образом.

Производный класс Описание Свойства
PreflightRequest Используется в AbuseProtection том случае, если IsPreflight значение true -
ConnectEventRequest Используется в системном Connect типе событий Утверждения, запрос, подпротоколы, ClientCertificates
ConnectedEventRequest Используется в системном Connected типе событий -
UserEventRequest Используется в типе события пользователя Данные, DataType
DisconnectedEventRequest Используется в системном Disconnected типе событий Причина

Примечание.

WebPubSubContext Хотя входная привязка обеспечивает аналогичный способ HttpTrigger десериализации запросов по сравнению с WebPubSubTrigger, есть ограничения, т. е. состояние подключения после слияния не поддерживается. Ответ возврата по-прежнему учитывается службой, но пользователям требуется создать ответ самостоятельно. Если пользователям нужно задать ответ на событие, необходимо вернуть HttpResponseMessage содержащиеся ConnectEventResponse или сообщения для события пользователя в качестве текста ответа и поместить состояние подключения с ключом ce-connectionstate в заголовке ответа.