Share via

Поддерживаемый в Azure Web PubSub подпротокол JSON WebSocket

  • Статья

Подпротокол json.webpubsub.azure.v1JSON WebSocket позволяет обмениваться сообщениями публикации и подписки между клиентами через службу без кругового пути к серверу вышестоящий. Подключение WebSocket с помощью json.webpubsub.azure.v1 подпротокола называется клиентом PubSub WebSocket.

Обзор

Простое подключение WebSocket активирует message событие при отправке сообщений и использует серверную сторону для обработки сообщений и выполнения других операций.

json.webpubsub.azure.v1 С помощью подпротокола можно создать клиенты PubSub WebSocket, которые могут:

Например, можно создать клиент PubSub WebSocket со следующим кодом JavaScript:

// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');

В этом документе описываются запросы и ответы подпротокола json.webpubsub.azure.v1 . Входящие и исходящие кадры данных должны содержать полезные данные JSON.

Разрешения

Клиент PubSub WebSocket может публиковаться только в других клиентах, когда он авторизован. Назначенные roles клиенту разрешения определяются клиентом:

Роль Разрешение
Не указано Клиент может отправлять запросы событий.
webpubsub.joinLeaveGroup Клиент может присоединиться к любой группе или выйти из нее.
webpubsub.sendToGroup Клиент может публиковать сообщения в любой группе.
webpubsub.joinLeaveGroup.<group> Клиент может присоединиться или оставить группу <group>.
webpubsub.sendToGroup.<group> Клиент может публиковать сообщения в группе <group>.

Сервер может динамически предоставлять или отзывать разрешения клиента с помощью REST API или пакетов SDK сервера.

Запросы

Присоединение к группам

Формат:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId — это удостоверение каждого запроса и должно быть уникальным. Служба отправляет ответное сообщение об ошибке, чтобы уведомить результат процесса запроса. Дополнительные сведения см. в разделе "Ответ AckId" и "Ack Response"

Выход из групп

Формат:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId — это удостоверение каждого запроса и должно быть уникальным. Служба отправляет ответное сообщение об ошибке, чтобы уведомить результат процесса запроса. Дополнительные сведения см. в разделе "Ответ AckId" и "Ack Response"

публикация сообщений.

Формат:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId — это удостоверение каждого запроса и должно быть уникальным. Служба отправляет ответное сообщение об ошибке, чтобы уведомить результат процесса запроса. Дополнительные сведения см. в разделе "Ответ AckId" и "Ack Response"
  • noEcho является необязательным. Если задано значение true, это сообщение не повторяется в том же соединении. Если значение не задано, значение по умолчанию равно false.
  • dataType может быть задано значение json, textили binary:
    • json: data может относиться к любому типу, поддерживаемому JSON, и публикуется в том же формате. Если не указать dataType, по умолчанию используется формат json.
    • text: значение data должно быть представлено в строковом формате, и публикуются строковые данные;
    • binary: значение data должно быть представлено в формате base64, и публикуются двоичные данные;

Сценарий 1. Публикация текстовых данных:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Клиенты подпротокола получают <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Простые клиенты WebSocket в <group_name> строке text data.

Сценарий 2. Публикация данных JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Клиенты подпротокола получают <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Простые клиенты WebSocket в <group_name> получении сериализованной строки {"hello": "world"}.

Сценарий 3. Публикация двоичных данных:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Клиенты подпротокола получают <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Простые клиенты WebSocket получают <group_name>двоичные данные в двоичном кадре.

Отправка пользовательских событий

Формат:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId — это удостоверение каждого запроса и должно быть уникальным. Служба отправляет ответное сообщение об ошибке, чтобы уведомить результат процесса запроса. Дополнительные сведения см. в разделе "Ответ AckId" и "Ack Response"

Для атрибута dataType можно задать значение text, binary или json:

  • json: данные могут быть любым типом json, поддерживаемым и будут опубликованы как то, что это; Значение по умолчанию — json.
  • text: данные в строковом формате, а строковые данные будут опубликованы;
  • binary: данные в формате base64, а двоичные данные будут опубликованы;

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

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

Обработчик событий вышестоящий получает данные, аналогичные следующим:

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>

text data

Http-запрос Content-Type CloudEvents находится text/plain в том случае.textdataType

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

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

Обработчик событий вышестоящий получает данные, аналогичные следующим:

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>

{
    "hello": "world"
}

Http-запрос Content-Type CloudEvents — application/json это время dataTypejson

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

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_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>

binary

Http-запрос Content-Type CloudEvents находится application/octet-stream в том случае.binarydataType Кадр WebSocket может быть представлен в формате text для кадров текстовых сообщений или двоичных данных с кодировкой UTF8 для кадров сообщений binary.

Служба Web PubSub отклоняет клиент, если сообщение не соответствует описанному формату.

Отклики

Типы сообщений, полученные клиентом, могут быть:

  • ack — ответ на запрос, содержащий объект ackId.
  • message — сообщения из группы или сервера.
  • system — сообщения из службы Web PubSub.

Отклик ACK

Если запрос клиента содержит ackId, служба вернет ответ ack для запроса. Клиент должен обрабатывать механизм ack, ожидая ответа ack с asyncawait операцией и используя операцию тайм-аута, когда ответ ack не получен в определенный период.

Формат:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

Реализация клиента всегда должна проверка, если success это true или false первое, то только считывает ошибку при success наличииfalse.

Ответ на сообщение

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

  1. Если сообщение отправлено из группы:

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. Когда сообщение находится на сервере.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

Сценарий 1. Отправка данных Hello World подключению при помощи REST API с Content-Type=text/plain

  • Простой клиент WebSocket получает текстовый кадр WebSocket с данными: Hello World

  • Клиент PubSub WebSocket получает:

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

Сценарий 2. Отправка данных { "Hello" : "World"} подключению при помощи REST API с Content-Type=application/json

  • Простой клиент WebSocket получает текстовый кадр WebSocket со строковыми данными: { "Hello" : "World"}

  • Клиент PubSub WebSocket получает:

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

Если REST API отправляет строку Hello World с помощью application/json типа контента, простой клиент WebSocket получает строку JSON, которая упаковывается "Hello World" с двойными кавычками (").

Сценарий 3. Отправка двоичных данных подключению при помощи REST API с Content-Type=application/octet-stream

  • Простой клиент WebSocket получает двоичный кадр WebSocket с двоичными данными.

  • Клиент PubSub WebSocket получает:

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

Отклик системы

Служба Web PubSub отправляет системные сообщения клиентам.

Connected

Сообщение, отправленное клиенту при успешном подключении клиента:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Отключено

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

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

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

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

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

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

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

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

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

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

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