Расширение CloudEvents для обработчика событий Azure Web PubSub с протоколом HTTP

Статья
03/30/2023

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

Данные, отправляемые из службы Web PubSub на сервер, всегда в формате CloudEvents binary .

Проверка веб-перехватчика
Расширение атрибутов CloudEvents для Web PubSub
События
- Блокировка событий
  - Системное событие connect
  - Пользовательские события
- Разблокировка событий
  - Системное событие connected
  - Системное событие disconnected

Проверка веб-перехватчика

Проверка веб-перехватчика согласуется с CloudEvents. Заголовок запроса всегда содержит строку WebHook-Request-Origin: xxx.webpubsub.azure.com.

Только в том случае, если в целевом объекте поставки разрешена доставка событий, он ДОЛЖЕН ответить на запрос, включив заголовок WebHook-Allowed-Origin, например:

WebHook-Allowed-Origin: *

Или сделайте так:

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

На данный момент веб-перехватчик-скорость запросов и обратный вызов webhook-request-callback не поддерживаются.

Расширение атрибутов CloudEvents для Web PubSub

Кроме того, стоит отметить, что спецификация HTTP следует тому же шаблону, и в HTTP-заголовки расширений больше не рекомендуется добавлять префикс X-.

Это расширение определяет атрибуты, используемые службой Web PubSub для каждого создаваемого ею события.

Атрибуты

Имя.	Тип	Описание
`userId`	`string`	Пользователь, авторизованный соединением
`hub`	`string`	Концентратор, к которому относится соединение
`connectionId`	`string`	Идентификатор клиентского соединения уникален
`eventName`	`string`	Имя события без префикса
`subprotocol`	`string`	Используемый клиентом подпротокол (если он есть)
`connectionState`	`string`	Определяет состояние подключения. Для сброса значения состояния можно использовать тот же заголовок ответа. Несколько `connectionState` заголовков не допускаются. Кодируйте строковое значение в base64, если оно содержит сложные символы внутри, например для `base64(jsonString)` передачи сложного объекта с помощью этого атрибута.
`signature`	`string`	Подпись вышестоящего веб-перехватчика, подтверждающая, что входящий запрос отправлен из ожидаемого источника. Служба вычисляет значение, используя как первичный ключ доступа, так и вторичный `HMAC` ключ доступа в качестве ключа: `Hex_encoded(HMAC_SHA256(accessKey, connectionId))` Вышестоящая служба должна проверить, является ли запрос допустимым, прежде чем обрабатывать его.

События

Существует два типа событий. Один из них блокирует события, которые служба ожидает продолжения ответа события. и неблокирующие события, при которых служба переходит к обработке следующего сообщения, не дожидаясь отклика.

Блокировка событий
- Системное событие connect
- Пользовательские события
Разблокировка событий
- Системное событие connected
- Системное событие disconnected

Системное событие `connect`

ce-type: azure.webpubsub.sys.connect
Content-Type: application/json

Формат запроса:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

Формат отклика об успешном выполнении:

Заголовок ce-connectionState: если этот заголовок существует, состояние подключения этого подключения будет обновлено до значения заголовка. Только блокирующие события могут обновлять состояние подключения. В приведенном ниже примере для хранения сложного состояния подключения используется строка JSON в кодировке Base64.
Код состояния:
- 204: успех (без содержимого).
- 200: успешное выполнение содержимого ДОЛЖНО быть форматом JSON со следующими свойствами:
  - subprotocols
    
    Событие connect переадресует сведения о подпротоколе и данные проверки подлинности в вышестоящую службу из клиента. Служба Web PubSub использует код состояния, чтобы определить, будет ли запрос обновлен до протокола WebSocket.
    
    Если запрос содержит свойство subprotocols, сервер должен вернуть один подпротокол, который он поддерживает. Если серверу не нужно использовать какие-либо подпротоколы, он не должен отправлять в отклике свойство subprotocol. Отправка пустого заголовка недопустима.
  - userId: {auth-ed user ID}
    
    Так как в службе разрешены анонимные подключения, событие connect обязано сообщить службе идентификатор пользователя клиентского подключения. Служба считывает идентификатор пользователя из полезных данных userId ответа, если он существует. Подключение удаляется, если идентификатор пользователя не может быть прочитан из утверждений запроса или connect полезных данных ответа события.
  - groups: {groups to join}
    
    Это свойство помогает пользователю добавить это подключение к одной или нескольким группам. Таким образом, для добавления подключения к группе не потребуется еще один вызов.
  - roles: {roles the client has}
    
    Свойство предоставляет способ вышестоящий веб-перехватчика для авторизации клиента. Существуют различные роли для предоставления начальных разрешений для клиентов PubSub WebSocket. Подробное описание разрешений представлено в разделе Разрешения клиента.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

Формат сообщения об ошибке:

4xx: ошибка — в ответ на запрос клиента будет возвращен отклик от вышестоящей службы.

HTTP/1.1 401 Unauthorized

Системное событие `connected`

Cлужба вызывает вышестоящий компонент, когда клиент завершит подтверждение WebSocket и успешно подключится.

ce-type: azure.webpubsub.sys.connected
Content-Type: application/json
ce-connectionState: eyJrZXkiOiJhIn0=

Текст запроса представляет собой пустой объект JSON.

Формат запроса:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

Формат отклика:

2xx: отклик при успешном выполнении.

connected — это асинхронное событие, если код состояния ответа не выполнен, служба регистрирует ошибку.

HTTP/1.1 200 OK

Системное событие `disconnected`

disconnectedСобытие всегда активируется при выполнении запроса клиента, если событие connect возвращает код состояния 2xx.

ce-type: azure.webpubsub.sys.disconnected
Content-Type: application/json

Формат запроса:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

reason

Атрибут reason описывает причину отключения клиента.

Формат отклика:

2xx: отклик при успешном выполнении.

disconnected — это асинхронное событие, если код состояния ответа не выполнен, служба регистрирует ошибку.

HTTP/1.1 200 OK

Пользовательское событие `message` для простых клиентов WebSocket

Служба активирует вышестоящий обработчик событий для каждого фрейма сообщения WebSocket.

ce-type: azure.webpubsub.user.message
Content-Type: application/octet-stream для двоичного фрейма; text/plain для текстового фрейма;

UserPayload — это данные, отправляемые клиентом.

Формат запроса:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

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

Код состояния
- 204: успех (без содержимого).
- 200: успех; формат UserResponsePayload зависит от атрибута Content-Type отклика.
Content-Type: application/octet-stream для двоичного фрейма; text/plain для текстового фрейма;
Заголовок Content-Type: application/octet-stream для двоичного кадра; text/plain для текстового кадра;
Заголовок ce-connectionState: если этот заголовок существует, состояние подключения этого подключения будет обновлено до значения заголовка. Только блокирующие события могут обновлять состояние подключения. В приведенном ниже примере используется строка JSON в кодировке Base64 для хранения сложного состояния подключения.

Если для атрибута Content-Type задано значение application/octet-stream, служба отправляет UserResponsePayload клиенту с помощью фрейма WebSocket binary. Если для атрибута Content-Type задано значение text/plain, служба отправляет UserResponsePayload клиенту с помощью фрейма WebSocket text.

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

Формат сообщения об ошибке

Если код состояния не успешно выполнен, он считается ответом на ошибку. Подключение будет удалено , если message код состояния ответа не выполнен.

Настраиваемое пользовательское событие `{custom_event}` для клиентов PubSub WebSocket

Служба вызывает веб-перехватчик обработчика событий для каждого допустимого сообщения о пользовательском событии.

Сценарий 1. Отправка события с текстовыми данными:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "text",
    "data": "text data"
}

Вышестоящий обработчик событий получает приведенные ниже данные; атрибут Content-Type для HTTP-запроса CloudEvents имеет значение text/plain при dataType=text

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

Сценарий 2. Отправка события с данными JSON:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    },
}

Вышестоящий обработчик событий получает приведенные ниже данные; атрибут Content-Type для HTTP-запроса CloudEvents имеет значение application/json при dataType=json

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

Сценарий 3. Отправка события с двоичными данными:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Вышестоящий обработчик событий получает приведенные ниже данные; атрибут Content-Type для HTTP-запроса CloudEvents имеет значение application/octet-stream при dataType=binary

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

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

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload

Код состояния
- 204: успех (без содержимого).
- 200: успех; данные, отправляемые клиенту PubSub WebSocket, зависят от Content-Type.
Заголовок ce-connectionState: если этот заголовок существует, состояние подключения этого подключения будет обновлено до значения заголовка. Только блокирующие события могут обновлять состояние подключения. В приведенном ниже примере для хранения сложного состояния подключения используется строка JSON в кодировке Base64.
Если заголовок Content-Type указан application/octet-stream, служба отправляет UserResponsePayload обратно клиенту, используя dataType binary полезные данные base64, закодированные. Пример ответа:
```
{
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
```
Когда это Content-Type text/plainтак, служба отправляет UserResponsePayload клиенту, используя dataType в качестве text полезных данных строку.
Если для атрибута Content-Type задано значение application/json, служба возвращает клиенту отклик UserResponsePayload, используя dataType=json с маркером значения data в тексте полезных данных.

Формат сообщения об ошибке

Если код состояния не успешно выполнен, он считается ответом на ошибку. Подключение будет удалено , если {custom_event} код состояния ответа не выполнен.

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

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

Руководство. Публикация и подписка на сообщения в Azure Web PubSub

Руководство по созданию чат-комнаты с помощью Azure Web PubSub

Руководство. Использование подпротокола, поддерживаемого службой, для потоковой передачи клиентов

Руководство по созданию бессерверного чата с помощью Функций Azure и Web PubSub

Руководство. Настройка прослушивателя событий

Играть с динамическими демонстрациями

Другие примеры Azure Web PubSub

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

Расширение CloudEvents для обработчика событий Azure Web PubSub с протоколом HTTP

Проверка веб-перехватчика

Расширение атрибутов CloudEvents для Web PubSub

Атрибуты

События

Системное событие `connect`

Формат запроса:

Формат отклика об успешном выполнении:

Формат сообщения об ошибке:

Системное событие `connected`

Формат запроса:

Формат отклика:

Системное событие `disconnected`

Формат запроса:

Формат отклика:

Пользовательское событие `message` для простых клиентов WebSocket

Формат запроса:

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

Формат сообщения об ошибке

Настраиваемое пользовательское событие `{custom_event}` для клиентов PubSub WebSocket

Сценарий 1. Отправка события с текстовыми данными:

Сценарий 2. Отправка события с данными JSON:

Сценарий 3. Отправка события с двоичными данными:

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

Формат сообщения об ошибке

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

Обратная связь

Дополнительные ресурсы

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

Расширение CloudEvents для обработчика событий Azure Web PubSub с протоколом HTTP

Проверка веб-перехватчика

Расширение атрибутов CloudEvents для Web PubSub

Атрибуты

События

Системное событие connect

Формат запроса:

Формат отклика об успешном выполнении:

Формат сообщения об ошибке:

Системное событие connected

Формат запроса:

Формат отклика:

Системное событие disconnected

Формат запроса:

Формат отклика:

Пользовательское событие message для простых клиентов WebSocket

Формат запроса:

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

Формат сообщения об ошибке

Настраиваемое пользовательское событие {custom_event} для клиентов PubSub WebSocket

Сценарий 1. Отправка события с текстовыми данными:

Сценарий 2. Отправка события с данными JSON:

Сценарий 3. Отправка события с двоичными данными:

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

Формат сообщения об ошибке

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

Обратная связь

Дополнительные ресурсы

Системное событие `connect`

Системное событие `connected`

Системное событие `disconnected`

Пользовательское событие `message` для простых клиентов WebSocket

Настраиваемое пользовательское событие `{custom_event}` для клиентов PubSub WebSocket