Поделиться через


Триггер и привязки Azure Web PubSub для Функций Azure

В этой статье объясняется, как обрабатывать события Web PubSub в Функциях Azure.

Web PubSub — это управляемая служба Azure, которая помогает разработчикам без труда создавать веб-приложения с функциями, работающими в реальном времени, и схемой "публикация-подписка".

Действие Тип
Запуск функции при поступлении сообщений из службы Привязка триггера
Привязка запроса к целевому объекту в триггере Http для согласования и вышестоящих запросов Входная привязка
Вызов действий, выполняемых службой Выходная привязка

Исходный код | Пакет | Справочная документация по API | Документация по продукту | Примеры

Добавление в приложение Функций

Для работы с триггером и привязками требуется ссылка на соответствующий пакет. Пакет NuGet используется для работы с библиотеками классов .NET, а пакет расширений — для всех других типов приложений.

Язык Способ добавления Замечания
C# Установка пакета NuGet предварительной версии
Скрипт C#, JavaScript, Python, PowerShell Явно установить расширения, использовать пакеты расширений Расширение Azure Tools рекомендуется использовать с Visual Studio Code.
C# Script (только при подключении к порталу Azure) Добавление привязки См. дополнительные сведения об обновлении существующих расширений привязки без необходимости переиздавать приложение-функции в разделе Обновление расширений.

Основные понятия

Схема рабочего процесса службы Azure Web PubSub, работающей с приложениями-функциями.

(1)–(2) Входная привязка WebPubSubConnection с HttpTrigger для создания клиентского соединения.

(3)–(4) Привязка триггера WebPubSubTrigger или входная привязка WebPubSubContext к HttpTrigger для запроса на обслуживание.

(5)–(6) Выходная привязка WebPubSub отправляет службе запрос на какое-то действие.

Привязка триггера

Триггер функции используется для обработки запросов из службы Azure Web PubSub.

WebPubSubTrigger используется для обработки запросов со стороны службы. Шаблон конечной точки триггера должен быть задан на стороне службы Web PubSub (портал: параметры —> обработчик событий —> шаблон URL-адреса). В шаблоне конечной точки часть запроса code=<API_KEY> НЕОБХОДИМА, если вы используете приложение-функцию Azure по соображениям безопасности. Ключ можно найти в портал Azure. Найдите ресурс приложения-функции и перейдите к разделу "Функции ->Ключи приложения ">Системные ключи">, webpubsub_extension после развертывания приложения-функции в Azure. Однако этот ключ не нужен при работе с локальными функциями.

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

Снимок экрана: получение системных ключей функции.

Пример

[FunctionName("WebPubSubTrigger")]
public static void Run(
    [WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

WebPubSubTrigger привязка также поддерживает возвращаемое значение в синхронизированных сценариях, например события системы Connect и пользователя, когда сервер может проверять и отклонять запрос клиента или отправлять сообщения вызывающей программе напрямую. Connectсобытия уважают ConnectEventResponse UserEventResponse и уважают события пользователя, EventErrorResponseа EventErrorResponseтипы rest, не соответствующие текущему сценарию, игнорируются. EventErrorResponse Если возвращается, служба удаляет клиентское подключение.

[FunctionName("WebPubSubTriggerReturnValueFunction")]
public static UserEventResponse Run(
    [WebPubSubTrigger("hub", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return request.CreateResponse(BinaryData.FromString("ack"), WebPubSubDataType.Text);
}

Атрибуты и заметки

В библиотеках классов C# используйте атрибут WebPubSubTrigger.

Вот как выглядит атрибут WebPubSubTrigger в сигнатуре метода:

[FunctionName("WebPubSubTrigger")]
public static void Run([WebPubSubTrigger("<hub>", <WebPubSubEventType>, "<event-name>")] 
    WebPubSubConnectionContext context, ILogger log)
{
    ...
}

Полный пример см. в разделе Пример C#.

Настройка

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

Свойство в function.json Свойство атрибута Описание
type Н/Д Обязательное. Необходимо задать значение webPubSubTrigger.
direction Н/Д Обязательное. Необходимо задать значение in.
name Н/Д Обязательное. Имя переменной, используемой в коде функции, для параметра, получающего данные события.
hub Узел Обязательно: в качестве значения следует указать имя концентратора Web PubSub для активируемой функции. Значение атрибута можно установить с более высоким приоритетом или задать в параметрах приложения как глобальное значение.
eventType WebPubSubEventType Обязательно: в качестве значения следует указать тип события сообщений для активируемой функции. Значение должно быть user или system.
eventName EventName Обязательно: в качестве значения следует указать событие сообщений для активируемой функции.
Для system типа события имя события должно находиться в connect, connecteddisconnected.
Для определяемых пользователем подпротоколов используется messageимя события.
Для поддерживаемого системой подпротокола json.webpubsub.azure.v1.имя события — это имя события, определяемое пользователем.
Подключение Connection Необязательно. Имя параметров или коллекции параметров приложения, указывающее вышестоящую службу Azure Web PubSub. Значение используется для проверки подписи. Значение разрешается автоматически с параметрами приложения WebPubSubConnectionString по умолчанию. И null означает, что проверка не требуется и всегда выполняется успешно.

Применение

В C# WebPubSubEventRequest — распознаваемый по типу параметр привязки; остальные параметры привязываются по имени. Доступные параметры и типы см. в таблице ниже.

В слабо типизированном языке, например JavaScript, name используется function.json для привязки объекта триггера относительно приведенной ниже таблицы сопоставления. И уважение dataType function.json к преобразованию сообщения соответствующим образом, если name задано data значение в качестве объекта привязки для входных данных триггера. Все параметры можно считывать и context.bindingData.<BindingName> JObject преобразовывать.

Имя привязки Тип привязки Description Свойства
запрос WebPubSubEventRequest Описание вышестоящего запроса Свойство отличается различными типами событий, включая производные классыConnectEventRequest, ConnectedEventRequestUserEventRequest иDisconnectedEventRequest
connectionContext WebPubSubConnectionContext Стандартные сведения о запросе EventType, EventName, Hub, ConnectionId, UserId, Headers, Origin, Signature, States
. BinaryData,string,,Streambyte[] Запрос данных сообщения от клиента в событии пользователя message -
dataType WebPubSubDataType Запрос данных dataType, который поддерживает binary, textjson -
claims IDictionary<string, string[]> Утверждения пользователей в системном connect запросе -
query IDictionary<string, string[]> Запрос пользователя в системном connect запросе -
subprotocols IList<string> Доступные подпротоколы в системном connect запросе -
clientCertificates IList<ClientCertificate> Список отпечатков сертификатов от клиентов в системном connect запросе -
reason string Причина в системном disconnected запросе -

Внимание

В C# необходимо поместить в первую очередь несколько типов поддерживаемых параметров, т. е. request data другие, кроме типа по умолчаниюBinaryData, чтобы сделать привязку функции правильной.

Возвращаемый ответ

WebPubSubTrigger учитывает возвращаемый клиентом ответ на синхронные события connect события и события пользователя. Только соответствующий ответ отправляется обратно в службу, в противном случае он игнорируется. Кроме того, WebPubSubTrigger возвращаемый объект поддерживает пользователей SetState() для управления метаданными подключения и ClearStates() управления ими. И расширение объединяет результаты из возвращаемого значения с исходными из запроса WebPubSubConnectionContext.States. Значение в существующем ключе перезаписывается и добавляется значение в новом ключе.

Тип возвращаемых данных Description Свойства
ConnectEventResponse Ответ на событие connect Groups, Roles, UserId, Subprotocol
UserEventResponse Ответ на событие пользователя DataType, Data
EventErrorResponse Ответ с ошибкой для события синхронизации Code, ErrorMessage
*WebPubSubEventResponse Для неопределенных сценариев возврата используется базовый тип ответа поддерживаемых типов. -

Входные привязки

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

  • WebPubSubConnection

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

  • WebPubSubContext

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

Пример- WebPubSubConnection

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

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{query.userid}")] WebPubSubConnection connection)
{
    return connection;
}

Прошедшие проверку подлинности маркеры

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

Проверка подлинности службы приложений задает заголовки HTTP x-ms-client-principal-id и x-ms-client-principal-name, содержащие имя и идентификатор субъекта клиента прошедшего проверку подлинности пользователя соответственно.

В качестве значения свойства UserID привязки можно задать один из заголовков с помощью выражения привязки {headers.x-ms-client-principal-id} или {headers.x-ms-client-principal-name}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection)
{
    return connection;
}

Примечание.

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

[FunctionName("WebPubSubConnectionCustomRoles")]
public static async Task<Uri> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest 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);
    return await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
}

Пример- WebPubSubContext

В следующем примере показана функция C#, которая получает данные вышестоящего запроса Web PubSub с помощью входной привязки в connect типе события и возвращает ее по протоколу HTTP.

[FunctionName("WebPubSubContextInputBinding")]
public static object Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubContext] WebPubSubContext wpsContext)
{
    // in the case request is a preflight or invalid, directly return prebuild response by extension.
    if (wpsContext.IsPreflight || wpsContext.HasError)
    {
        return wpsContext.Response;
    }
    var request = wpsContext.Request as ConnectEventRequest;
    var response = new ConnectEventResponse
    {
        UserId = wpsContext.Request.ConnectionContext.UserId
    };
    return response;
}

Настройка

WebPubSubConnection

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

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

WebPubSubContext

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

Свойство в function.json Свойство атрибута Описание
type Н/Д Должен иметь значениеwebPubSubContext.
direction Н/Д Должен иметь значениеin.
name Н/Д Имя переменной, используемое в коде функции для входного запроса Web PubSub.
Подключение Connection Необязательно. Имя параметров или коллекции параметров приложения, указывающее вышестоящую службу Azure Web PubSub. Это значение используется для проверки защиты от злоупотреблений и подписи. Значение автоматически разрешается с помощью WebPubSubConnectionString по умолчанию. И null означает, что проверка не требуется и всегда выполняется успешно.

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

WebPubSubConnection

WebPubSubConnection предоставляет указанные ниже свойства.

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

WebPubSubContext

WebPubSubContext предоставляет указанные ниже свойства.

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

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

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

Примечание.

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

Выходные привязки

Используйте выходную привязку Web PubSub, чтобы вызвать службу Azure Web PubSub, чтобы сделать что-то. Сообщение можно транслировать следующим получателям:

  • всем подключенным клиентам;
  • подключенным клиентам, которые прошли аутентификацию для определенного пользователя.
  • Подключенные клиенты, присоединенные к определенной группе
  • Определенное подключение клиента

Выходная привязка также позволяет управлять клиентами и группами, а также предоставлять или отзывать разрешения, предназначенные для конкретного подключения с группой.

  • Добавление подключения к группе
  • Добавление пользователя в группу
  • Удаление подключения из группы
  • Удаление пользователя из группы
  • Удаление пользователя из всех групп.
  • Закройте все клиентские подключения
  • Закрытие определенного подключения клиента
  • Закрытие подключений в группе
  • Предоставление разрешения на подключение
  • Отмена разрешения подключения

Сведения об установке и настройке см. в обзорной статье.

Пример

[FunctionName("WebPubSubOutputBinding")]
public static async Task RunAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSub(Hub = "<hub>")] IAsyncCollector<WebPubSubAction> actions)
{
    await actions.AddAsync(WebPubSubAction.CreateSendToAllAction("Hello Web PubSub!", WebPubSubDataType.Text));
}

WebPubSubAction

WebPubSubAction — базовый абстрактный тип выходных привязок. Производные типы представляют сервер действий, который требуется вызвать службой.

На языке C# мы предоставляем несколько статических методов WebPubSubAction для обнаружения доступных действий. Например, пользователь может создать по вызову SendToAllAction WebPubSubAction.CreateSendToAllAction().

Производный класс Свойства
SendToAllAction Данные, DataType, исключенные
SendToGroupAction Группа, данные, DataType, исключенные
SendToUserAction UserId, Data, DataType
SendToConnectionAction ConnectionId, Data, DataType
AddUserToGroupAction UserId, Group
RemoveUserFromGroupAction UserId, Group
RemoveUserFromAllGroupsAction UserId
AddConnectionToGroupAction ConnectionId, Group
RemoveConnectionFromGroupAction ConnectionId, Group
CloseAllConnectionsAction Исключены, причина
CloseClientConnectionAction ConnectionId, Reason
CloseGroupConnectionsAction Группа, исключенная, причина
GrantPermissionAction ConnectionId, Permission, TargetName
RevokePermissionAction ConnectionId, Permission, TargetName

Настройка

WebPubSub

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

Свойство в function.json Свойство атрибута Описание
type Н/Д Нужно задать значение webPubSub
direction Н/Д Нужно задать значение out
name Н/Д Имя переменной, используемой в коде функции для выходной привязки объекта.
hub Узел В качестве значения следует указать имя концентратора Web PubSub для активируемой функции. Значение атрибута можно установить с более высоким приоритетом или задать в параметрах приложения как глобальное значение.
Подключение Connection Имя параметра приложения, содержащего строка подключения службы Web PubSub (по умолчанию — WebPubSubConnectionString).

Устранение неполадок

Настройка ведения журнала консоли

Можно легко включить ведение журнала консоли, если вы хотите получить более подробную информацию о запросах к службе.

Следующие шаги

Используйте эти ресурсы для начала создания собственного приложения: