Протокол гибридных подключений ретранслятора Azure
Ретранслятор Azure является одной из ключевых функций платформы служебной шины Azure. Новая функция ретранслятора, называемая Гибридные подключения, представляет собой безопасный открытый протокол нового поколения, основанный на HTTP и WebSockets. Она заменяет собой прошлый компонент, называемый Службы BizTalk, основанный на старой версии протокола. Интеграция гибридных подключений со службами приложений Azure будет по-прежнему работать.
Гибридные подключения поддерживают двунаправленную связь "запрос — ответ" между двоичными потоками и простой поток датаграмм между двумя сетевыми приложениями. Одна или обе стороны могут находиться за NAT или брандмауэрами.
В этой статье описывается взаимодействие на стороне клиента с ретранслятором гибридных подключений для подключения клиентов в роли прослушивателя и отправителя. В ней также описан процесс приема прослушивателями новых подключений.
Модель взаимодействия
Ретранслятор гибридных подключений подключает две стороны, предоставляя точку рандеву в облаке Azure, которую обе стороны могут обнаружить и с которой они могут установить соединение из своей сети. В этом и других документах, а также в интерфейсах API и на портале Azure точка рандеву называется "Гибридное подключение". Далее в этой статье мы будем называть конечную точку службы "Гибридные подключения" просто "служба".
Служба позволяет ретранслировать подключения через веб-сокет, а также запросы и ответы по протоколу HTTP(S).
Модель взаимодействия полагается на номенклатуру, установленную многими другими сетевыми API. В ней есть прослушиватель, который сначала подтверждает готовность обработать входящие подключения, а затем принимает их по мере поступления. С другой стороны существует клиент, который выполняет подключение к прослушивателю, ожидая, что это подключение будет принято для формирования двустороннего пути обмена данными. "Подключиться", "прослушать" и "принять" — это стандартные термины, которые встречаются в большинстве API-интерфейсах сокетов.
В любой модели взаимодействия с применением ретранслятора одна из сторон устанавливает исходящее подключение к конечной точке службы. Таким образом, "прослушиватель" становится "клиентом" (как принято это называть в разговорной речи), а также возможно нагромождение других терминов. Поэтому ниже приводится точная терминология, которую мы используем для гибридных подключений.
Программы с обеих сторон подключения называются "клиентами", так как для службы они обе являются клиентами. Клиент, который ожидает и принимает подключения, является "прослушивателем", или, как говорят, находится в "роли прослушивателя". Клиент, инициирующий новое подключение к прослушивателю через службу, называется "отправитель" или находится в роли отправителя.
Взаимодействия прослушивателя
Существует пять типов взаимодействий между прослушивателем и службой. Подробнее все они описаны далее в этой статье.
Сообщения прослушивания, приема и запроса поступают от службы. Операции возобновления и проверки связи отправляются прослушивателем.
Сообщение прослушивания
Чтобы сообщить службе о своей готовности принять подключения, прослушиватель создает исходящее подключение через веб-сокет. Подтверждение соединения содержит имя гибридного подключения, настроенное в пространстве имен ретранслятора, и маркер безопасности, который предоставляет этому имени право на прослушивание.
Когда служба принимает веб-сокет, регистрация завершается, а установленный веб-сокет поддерживается в рабочем состоянии как "канал управления" для всех последующих взаимодействий. Служба поддерживает до 25 параллельных прослушивателей на одно гибридное подключение. Квота для AppHooks еще не определена.
В случае гибридного подключения при наличии двух и более активных прослушивателей входящие подключения распределяются между ними в произвольном порядке. Применяется все возможное для обеспечения равномерного распределения.
Сообщение приема
Когда отправитель открывает новое подключение к службе, она выбирает один из активных прослушивателей и уведомляет его о гибридном подключении. Уведомление отправляется в прослушиватель по открытому каналу управления в виде сообщения JSON. Сообщение содержит URL-адрес конечной точки веб-сокета, к которой прослушиватель должен подключиться для приема подключения.
URL-адрес может и должен использоваться прослушивателем напрямую без каких-либо дополнительных действий. Закодированная информация действительна только в течение короткого периода времени; по сути, это время зависит от того, сколько отправитель готов ожидать установления полного подключения. Время ожидания не может превышать 30 секунд. URL-адрес может быть использован только для одного успешного подключения. Сразу же после подключения через веб-сокет к URL-адресу рандеву все дальнейшие действия на этом веб-сокете ретранслируются от отправителя и обратно. Это поведение применяется без дополнительных вмешательств или оценки со стороны службы.
Сообщение запроса
В дополнение к подключениям через веб-сокет прослушиватель также может получать кадры HTTP-запроса от отправителя, если эта возможность явно включена в гибридном подключении.
Прослушиватели, присоединенные к гибридным подключениям с поддержкой HTTP, ДОЛЖНЫ обрабатывать жест request. Если прослушиватель подключен, но не обрабатывает request, что приводит к неоднократным превышениям времени ожидания, в будущем служба МОЖЕТ внести его в список блокировок.
Метаданные заголовка кадра HTTP преобразуются в формат JSON для более простой обработки с помощью структуры прослушивателя, а также потому, что библиотеки анализа HTTP-заголовков используются реже, чем анализаторы JSON. Метаданные HTTP, которые относятся только к связи между отправителем и HTTP-шлюзом ретрансляции, в том числе информация об авторизации, не пересылаются. Текст HTTP-запросов прозрачно передается в виде двоичных кадров WebSocket.
Прослушиватель может отвечать на HTTP-запросы, используя эквивалентный жест.
Поток запросов и ответов по умолчанию использует канал управления, но при необходимости может быть "обновлен" до отдельного веб-сокета рандеву. Отдельные подключения через веб-сокет улучшают пропускную способность для каждого взаимодействия с клиентом, но они обременяют прослушивателя большим количеством подключений, которые нужно обрабатывать, что может быть нежелательным для упрощенных клиентов.
В канале управления текст запроса и ответа ограничен размером 64 КБ. Метаданные заголовка HTTP ограничены до 32 КБ. Если запрос или ответ превышают этот порог, прослушиватель ДОЛЖЕН обновиться до веб-сокета рандеву, используя жест, эквивалентный обработке приема.
Для запросов служба решает, направлять ли запросы по каналу управления. Помимо прочего, это касается ситуаций, когда запрос сразу превышает 64 КБ (заголовки + текст) или отправляется с заголовком Transfer-Encoding: Chunke и у службы есть основания ожидать запрос размером более 64 КБ или задержку чтения запроса. Если служба решает передать запрос через точку рандеву, она передает прослушивателю только адрес рандеву. Затем прослушиватель ДОЛЖЕН установить веб-сокет точки рандеву, и служба незамедлительно отправит полный запрос, включая текст, через веб-сокет рандеву. Ответ ДОЛЖЕН также использовать веб-сокет точки рандеву.
Для запросов, поступающих по каналу управления, прослушиватель решает, как отвечать: по каналу управления или через точку рандеву. Служба ДОЛЖНА включать адрес точки рандеву в каждый запрос, направленный по каналу управления. Этот адрес можно обновить только из текущего запроса.
Если прослушиватель выбирает обновление, он подключается и оперативно передает ответ по установленному сокету точки рандеву.
Когда веб-сокет точки рандеву будет установлен, прослушиватель ДОЛЖЕН поддерживать его для дальнейшей обработки запросов и ответов от одного и того же клиента. Служба будет поддерживать подключение с веб-сокетом до тех пор, пока будет существовать HTTPS-подключение через сокет с отправителем, и будет направлять все последующие запросы от этого отправителя по поддерживаемому веб-сокету. Если прослушиватель решит прервать подключение с веб-сокетом точки рандеву со своей стороны, служба также прервет подключение к отправителю, независимо от того, выполняется ли уже следующий запрос.
Операция возобновления
Срок действия маркера безопасности, который должен использоваться для регистрации прослушивателя и обслуживания канала управления, может истечь, когда прослушиватель еще активен. Срок действия маркера не влияет на текущие подключения, но он приводит к тому, что канал управления будет удален службой в или вскоре после истечения срока действия. Операция возобновления является сообщением JSON, которое прослушиватель может отправить для замены маркера, связанного с каналом управления, чтобы канал управления оставался подключенным в течение длительного времени.
Операция проверки связи
Если канал управления долго простаивает, то посредники на его пути, такие как балансировщики нагрузки или NAT, могут вызывать отключение TCP-соединения. Операция проверки связи позволяет этого избежать, отправляя по каналу небольшой объем данных и напоминая всем на сетевом маршруте, что подключение еще активно. Это также служит тестом активности для прослушивателя. В случае сбоя проверки связи канал управления считается недоступным и прослушивателю требуется подключиться снова.
Взаимодействия отправителя
Отправитель имеет два типа взаимодействия со службой: он подключается по веб-сокету или отправляет запросы через HTTPS. Запросы не могут отправляться через веб-сокет из роли отправителя.
Операция подключения
Операция подключения открывает веб-сокет на стороне службы, указывая имя гибридного подключения и (необязательный, но требуемый по умолчанию) маркер безопасности, предоставляющий разрешение на отправку в строке запроса. Затем служба взаимодействует с прослушивателем, как описано ранее. При этом прослушиватель создает встречное подключение, которое объединяется с этим веб-сокетом. После приема веб-сокета все дальнейшие взаимодействия на нем выполняются с помощью подключенного прослушивателя.
Операция запроса
В случае гибридного подключения, для которого функция включена, отправитель может отправлять в значительной степени неограниченные HTTP-запросы прослушивателям.
За исключением маркера доступа к ретранслятору, который встроен либо в строку запроса, либо в HTTP-заголовок запроса, ретранслятор полностью прозрачен для всех HTTP-операций по адресу ретранслятора и всех суффиксах его пути. При этом прослушиватель полностью управляет сквозной авторизацией и даже функциями расширения HTTP, такими как CORS.
Авторизация отправителя в конечной точке релетрансляции включена по умолчанию, но является необязательной. Владелец гибридного подключения может разрешить анонимных отправителей. Служба будет перехватывать, проверять и удалять данные авторизации следующим образом:
- Если строка запроса содержит выражение
sb-hc-token, выражение ВСЕГДА будет удаляться из строки запроса. Оно будет вычисляться, если авторизация ретрансляции включена. - Если заголовки запроса содержат заголовок
ServiceBusAuthorization, выражение заголовка ВСЕГДА будет удаляться из коллекции заголовков. Оно будет вычисляться, если авторизация ретрансляции включена. - Заголовок оценивается и удаляется, только если авторизация ретрансляции включена, заголовки запроса содержат заголовок
Authorizationи ни одно из предыдущих выражений не присутствует. В противном случаеAuthorizationвсегда передается как есть.
Если активного прослушивателя нет, служба вернет код ошибки 502 "Недопустимый шлюз". Если служба не обрабатывает запрос, служба возвращает 504 "Время ожидания шлюза" через 60 секунд.
Сводка взаимодействий
В результате такой модели взаимодействия после подтверждения соединения клиент отправителя имеет "чистый" веб-сокет, который подключен к прослушивателю и не требует дальнейшей подготовки. Эта модель позволяет практически любой существующей реализации клиента веб-сокета с легкостью воспользоваться преимуществами службы гибридных подключений, указав правильно построенный URL-адрес на уровне клиента веб-сокета.
Веб-сокет встречного подключения, который прослушиватель получает при приеме, также является чистым и может передаваться любой существующей реализации сервера веб-сокета с минимальной дополнительной абстракцией, которая различает операции accept ("принять") на прослушивателях локальной сети своей платформы и удаленные операции accept гибридных подключений.
Модель запросов и ответов HTTP дает отправителю в значительной степени неограниченную контактную зону HTTP-протокола с ДОПОЛНИТЕЛЬНЫМ уровнем авторизации. Прослушиватель получает предварительно обработанный раздел заголовка HTTP-запроса, который может быть возвращен обратно в HTTP-запрос нисходящего потока или обрабатываться как есть вместе с двоичными кадрами с основным текстом HTTP. Ответы используют тот же формат. Взаимодействие с текстом запроса и ответа размером менее 64 КБ можно обрабатывать через один общий веб-сокет, который используется для всех отправителей. Более крупные запросы и ответы могут быть обработаны с использованием модели рандеву.
Справочник по протоколу
В этом разделе подробно описываются взаимодействия протокола, упомянутые выше.
Все подключения через веб-сокет выполняются через порт 443 как обновление с HTTPS 1.1, которое часто абстрагируется некоторыми платформами веб-сокета или API. Описание здесь сохраняется нейтрализовать реализацию, не предлагая определенную платформу.
Протокол прослушивателя
Протокол прослушивателя состоит из двух жестов подключения и трех операций с сообщениями.
Подключение канала управления прослушивателя
Канал управления открывается посредством создания подключения через веб-сокет по адресу:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
namespace-address — это полное доменное имя пространства имен ретранслятора Azure, в котором размещается гибридное подключение (как правило, в формате {myname}.servicebus.windows.net).
Ниже приведены варианты параметров строки запроса.
| Параметр | Обязательное поле | Описание: |
|---|---|---|
sb-hc-action |
Да | Для роли прослушивателя значение параметра должно быть sb-hc-action=listen. |
{path} |
Да | Закодированный в URL-адресе путь к пространству имен предварительно настроенного гибридного подключения для регистрации данного прослушивателя. Это выражение добавляется к фиксированному сегменту пути $hc/. |
sb-hc-token |
Да* | Прослушиватель должен указать допустимый закодированный в URL-адресе общий маркер служебной шины для пространства имен или гибридного подключения, который предоставляет право на прослушивание. |
sb-hc-id |
Нет | Этот необязательный идентификатор, предоставляемый клиентом, обеспечивает комплексную диагностическую трассировку. |
В случае сбоя подключения через веб-сокет из-за того, что путь гибридного подключения не зарегистрирован, маркер является недопустимым либо отсутствует или из-за какой-то другой ошибки, указываются сведения об ошибке. Для этого используется обычная модель предоставления сведений о состоянии HTTP 1.1. Описание состояния содержит идентификатор отслеживания ошибки, который можно сообщить в службу поддержки Azure.
| Код | Ошибка | Описание |
|---|---|---|
| 404 | Не найдено | Путь гибридного подключения является недопустимым, или базовый URL-адрес имеет неправильный формат. |
| 401 | Не авторизовано | Маркер безопасности отсутствует, имеет неправильный формат или является недопустимым. |
| 403 | Запрещено | Маркер безопасности является недопустимым для этого пути с этим действием. |
| 500 | Внутренняя ошибка | Произошла неизвестная ошибка в службе. |
Если служба намеренно завершает подключение через веб-сокет после того, как оно установлено, то причина такого действия сообщается с помощью соответствующего кода ошибки протокола веб-сокета и сообщения с описанием ошибки, которое также содержит идентификатор отслеживания. Служба не завершит работу канала управления без возникновения ошибки. Любое завершение работы без ошибок контролируется клиентом.
| Состояние веб-сокета | Description |
|---|---|
| 1001 | Путь гибридного подключения был удален или отключен. |
| 1008 | Истек срок действия маркера безопасности, поэтому нарушена политика авторизации. |
| 1011 | Произошла неизвестная ошибка в службе. |
Подтверждение приема
Служба отправляет прослушивателю уведомление о приеме по ранее установленному каналу управления в виде сообщения JSON в текстовом окне веб-сокета. Нет ответа на это сообщение.
Сообщение содержит объект JSON с именем accept, который определяет следующие свойства:
- address — строка URL-адреса, используемая при установлении соединения между веб-сокетом и службой. Указывает, чтобы служба приняла входящее подключение.
- id — уникальный идентификатор для этого подключения. Если идентификатор был предоставлен клиентом отправителя, он является предоставленным отправителем значением, в противном случае это системное значение.
- connectHeaders — все заголовки HTTP, предоставленные отправителем для конечной точки ретранслятора. Сюда также включаются заголовки Sec-WebSocket-Protocol и Sec-WebSocket-Extensions.
{
"accept" : {
"address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?...",
"id" : "4cb542c3-047a-4d40-a19f-bdc66441e736",
"connectHeaders" : {
"Host" : "...",
"Sec-WebSocket-Protocol" : "...",
"Sec-WebSocket-Extensions" : "..."
}
}
}
URL-адрес в сообщении JSON используется прослушивателем для того, чтобы указать веб-сокету принять или отклонить сокет отправителя.
Прием сокета
Чтобы принять, прослушиватель устанавливает подключение к указанному адресу по протоколу WebSocket.
Если сообщение "принять" содержит Sec-WebSocket-Protocol заголовок, ожидается, что прослушиватель принимает только WebSocket, если он поддерживает этот протокол. При установке подключения веб-сокета он также установит заголовок.
Это же относится и к заголовку Sec-WebSocket-Extensions. Если платформа поддерживает расширение, она должна задать заголовок для ответа на стороне сервера необходимого подтверждения Sec-WebSocket-Extensions для расширения.
URL-адрес должен использоваться "как есть" для приема сокета, но при этом содержит следующие параметры:
| Параметр | Обязательное поле | Описание: |
|---|---|---|
sb-hc-action |
Да | Для приема сокета этот параметр должен иметь значение sb-hc-action=accept. |
{path} |
Да | (см. следующий абзац). |
sb-hc-id |
Нет | См. описание параметра id, приведенное выше. |
{path} — это закодированный в URL-адресе путь к пространству имен предварительно настроенного гибридного подключения для регистрации прослушивателя. Это выражение добавляется к фиксированному сегменту пути $hc/.
Выражение path можно расширить с помощью суффикса и строкового выражения запроса, следующего за зарегистрированным именем после разделительной косой черты.
Этот параметр позволяет клиенту отправителя передать аргументы перенаправления принимающему прослушивателю, когда невозможно включить заголовки HTTP. Ожидается, что платформа прослушивателя анализирует и выделяет часть фиксированного пути и зарегистрированное имя и сделает оставшуюся часть пути (возможно, без аргументов строки запроса с префиксом sb-) доступной для приложения, которое должно принять решение о принятии подключения.
Дополнительные сведения см. в разделе "Протокол отправителя" ниже.
Если возникла ошибка, служба может ответить следующим образом:
| Код | Ошибка | Описание |
|---|---|---|
| 403 | Запрещено | URL-адрес является недопустимым. |
| 500 | Внутренняя ошибка | Произошла неизвестная ошибка в службе. |
После установления подключения сервер завершит работу веб-сокета, когда завершит работу веб-сокет отправителя. Кроме того, может отобразиться следующее состояние:
| Состояние веб-сокета | Description |
|---|---|
| 1001 | Клиент отправителя прервал подключение. |
| 1001 | Путь гибридного подключения был удален или отключен. |
| 1008 | Истек срок действия маркера безопасности, поэтому нарушена политика авторизации. |
| 1011 | Произошла неизвестная ошибка в службе. |
Отклонение сокета
Для отклонения сокета после проверки сообщения accept требуется похожее подтверждение, чтобы код состояния и описание состояния, сообщающие причину отклонения, были переданы обратно отправителю.
Вариант проектирования протокола используется для использования подтверждения WebSocket (который предназначен для завершения определенного состояния ошибки), чтобы реализации клиентов прослушивателя могли продолжать полагаться на клиент WebSocket и не требуется использовать дополнительный, голый HTTP-клиент.
Для отклонения сокета клиент использует URI адреса из сообщения accept и добавляет к нему два параметра строки запроса:
| Param | Обязательное поле | Description |
|---|---|---|
| sb-hc-statusCode | Да | Числовой код состояния HTTP. |
| sb-hc-statusDescription | Да | Понятная для пользователя причина отклонения. |
Затем полученный универсальный код ресурса (URI) используется для установления подключения WebSocket.
При правильном выполнении это подтверждение намеренно завершится ошибкой с кодом HTTP 410, так как подключение по протоколу WebSocket не было установлено. Если возникает ошибка, то возможны такие варианты:
| Код | Ошибка | Описание |
|---|---|---|
| 403 | Запрещено | URL-адрес является недопустимым. |
| 500 | Внутренняя ошибка | Произошла неизвестная ошибка в службе. |
Сообщение запроса
Служба отправляет сообщение request прослушивателю по каналу управления. Одно и то же сообщение также отправляется по веб-сокету точки рандеву после его установки.
request состоит из двух частей — заголовка и двоичных кадров основного текста.
Если нет текста, кадры тела опущены. Логическое свойство body — индикатор наличия текста в сообщении запроса.
Структура запроса с текстом может выглядеть так:
----- Web Socket text frame ----
{
"request" :
{
"body" : true,
...
}
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------
Прослушиватель ДОЛЖЕН обрабатывать прием текста запроса, разбитого на несколько двоичных кадров (см. фрагменты WebSocket). Запрос завершается, когда получен двоичный кадр с установленным флагом FIN.
Для запроса без текста есть только один текстовый кадр.
----- Web Socket text frame ----
{
"request" :
{
"body" : false,
...
}
}
----------------------------------
Содержимое JSON для request выглядит следующим образом:
address — строка URI. Это адрес точки встречи, который будет использоваться для этого запроса. Если размер входящего запроса превышает 64 КБ, оставшаяся часть этого сообщения остается пустой, и клиент ДОЛЖЕН инициировать подтверждение приема в точке рандеву, эквивалентное операции
accept, описанной ниже. Затем служба будет помещать полныйrequestв установленный веб-сокет. Если ожидается, что ответ будет превышать 64 КБ, прослушиватель ДОЛЖЕН также инициировать подтверждение приема в точке рандеву, а затем передать ответ через установленный веб-сокет.id — строка. Уникальный идентификатор этого запроса.
requestHeaders — этот объект содержит все HTTP-заголовки, которые были отправлены конечной точке отправителем, за исключением информации об авторизации, как описано выше, и заголовков, которые относятся только к соединению с шлюзом. В частности, все заголовки, определенные или зарезервированные в RFC7230, кроме
Via, удаляются и не пересылаются:Connection(RFC7230, раздел 6.1).Content-Length(RFC7230, раздел 3.3.2).Host(RFC7230, раздел 5.4).TE(RFC7230, раздел 4.3).Trailer(RFC7230, раздел 4.4).Transfer-Encoding(RFC7230, раздел 3.3.1).Upgrade(RFC7230, раздел 6.7).Close(RFC7230, раздел 8.1).
requestTarget — строка. Это свойство содержит "целевой объект" (RFC7230, раздел 5.3) запроса. Сюда входит часть строки запроса, из которой удалены ВСЕ параметры с префиксами
sb-hc-.method — строка. Это метод запроса, как описано в RFC7231, раздел 4. Метод
CONNECTНЕ ДОЛЖЕН использоваться.body — логическое значение. Указывает, что дальше следует один или несколько двоичных кадров.
{
"request" : {
"address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?...",
"id" : "42c34cb5-7a04-4d40-a19f-bdc66441e736",
"requestTarget" : "/abc/def?myarg=value&otherarg=...",
"method" : "GET",
"requestHeaders" : {
"Host" : "...",
"Content-Type" : "...",
"User-Agent" : "..."
},
"body" : true
}
}
Ответ на запросы
Получатель ДОЛЖЕН отвечать. Повторное отсутствие ответа на запросы при сохранении подключения может привести к внесению прослушивателя в список блокировок.
Ответы могут быть отправлены в любом порядке, но на каждый запрос должен быть отправлен ответ в течение 60 секунд или доставка будет считаться не выполненной. 60-секундный крайний срок отсчитывается до тех пор, пока кадр response не будет получен службой. Текущий ответ с несколькими двоичными кадрами не может стать бездействующим в течение более 60 секунд или завершается.
Если запрос получен по каналу управления, ответ ДОЛЖЕН быть отправлен либо по этому же каналу, либо по каналу рандеву.
Ответ — это объект JSON с именем "response". Правила обработки текста в точности совпадают с обработкой в сообщении request и зависят от свойства body.
- requestId — строка. Обязательный параметр. Значение свойства
idсообщениеrequest, на которое дается ответ. - statusCode — число. Обязательный параметр. Числовой код состояния HTTP, который указывает на результат уведомления. Все коды состояния в RFC7231, раздел 6 разрешены, за исключением 502 "Недопустимый шлюз" и 504 "Истекло время ожидания шлюза".
- statusDescription — строка. OPTIONAL. Причины возникновения кода состояния HTTP см. в RFC7230, раздел 3.1.2.
- responseHeaders — заголовки HTTP, задаваемые во внешних ответах HTTP.
Как и в случае с
request, определенные заголовки RFC7230 НЕ ДОЛЖНЫ использоваться. - body — логическое значение. Указывает, присутствует ли последующий двоичный кадр с основным текстом.
----- Web Socket text frame ----
{
"response" : {
"requestId" : "42c34cb5-7a04-4d40-a19f-bdc66441e736",
"statusCode" : "200",
"responseHeaders" : {
"Content-Type" : "application/json",
"Content-Encoding" : "gzip"
}
"body" : true
}
}
----- Web Socket binary frame -FIN
{ "hey" : "mydata" }
----------------------------------
Ответ через точку рандеву
Ответы, размер которых превышает 64 КБ, ДОЛЖНЫ быть доставлены через сокет точки рандеву. Кроме того, если запрос превышает 64 КБ, а request содержит только поле адреса, для получения request необходимо установить сокет точки рандеву. Как только сокет точки рандеву будет установлен, ответы соответствующему клиенту и последующие запросы от него ДОЛЖНЫ отправлять через сокет, пока он работает.
URL-адрес address в request должен использоваться "как есть" для установки сокета точки рандеву, но при этом он содержит следующие параметры:
| Параметр | Обязательное поле | Описание: |
|---|---|---|
sb-hc-action |
Да | Для приема сокета этот параметр должен иметь значение sb-hc-action=request. |
Если возникла ошибка, служба может ответить следующим образом:
| Код | Ошибка | Описание |
|---|---|---|
| 400 | Недопустимый запрос | Неопознанное действие или недействительный URL-адрес. |
| 403 | Запрещено | Срок действия URL-адреса истек. |
| 500 | Внутренняя ошибка | Произошла неизвестная ошибка в службе. |
После установления подключения сервер завершит работу веб-сокета, когда завершит работу сокет HTTP клиента. Кроме того, может отобразиться следующее состояние:
| Состояние веб-сокета | Description |
|---|---|
| 1001 | Клиент отправителя прервал подключение. |
| 1001 | Путь гибридного подключения был удален или отключен. |
| 1008 | Истек срок действия маркера безопасности, поэтому нарушена политика авторизации. |
| 1011 | Произошла неизвестная ошибка в службе. |
Возобновление действия маркера прослушивателя
Когда истекает срок действия маркера прослушивателя, его можно заменить, отправив текстовое сообщение в службу по подключенному каналу управления. Сообщение содержит объект JSON с именем renewToken, который определяет следующее свойство:
- token — допустимый закодированный в URL-адресе общий маркер служебной шины для пространства имен или гибридного подключения, который предоставляет право на прослушивание.
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
Если при проверке маркера произойдет сбой, в доступе будет отказано и облачная служба завершит работу веб-сокета канала управления с ошибкой. В противном случае нет ответа.
| Состояние веб-сокета | Description |
|---|---|
| 1008 | Истек срок действия маркера безопасности, поэтому нарушена политика авторизации. |
Протокол подключения веб-сокета
Протокол отправителя практически идентичен установке прослушивателя. Целью является максимальная прозрачность для всего веб-сокета. Адрес подключения такой же, как для прослушивателя, но отличается сегмент action и для маркера требуется другое разрешение:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
namespace-address — это полное доменное имя пространства имен ретранслятора Azure, в котором размещается гибридное подключение (как правило, в формате {myname}.servicebus.windows.net).
Запрос может содержать дополнительные заголовки HTTP произвольной формы, включая заголовки, определяемые приложением. Все передаваемые заголовки направляются в прослушиватель. Их можно найти в объекте connectHeader контрольного сообщения accept.
Ниже приведены варианты параметров строки запроса.
| Param | Обязательный? | Description |
|---|---|---|
sb-hc-action |
Да | Для роли отправителя значение параметра должно быть sb-hc-action=connect. |
{path} |
Да | (см. следующий абзац). |
sb-hc-token |
Да* | Прослушиватель должен указать допустимый закодированный в URL-адресе общий маркер служебной шины для пространства имен или гибридного подключения, который предоставляет право на отправку. |
sb-hc-id |
Нет | Необязательный идентификатор, который обеспечивает комплексную диагностическую трассировку и доступен для прослушивателя при подтверждении приема. |
{path} — это закодированный в URL-адресе путь к пространству имен предварительно настроенного гибридного подключения для регистрации прослушивателя. Выражение path можно расширить с помощью суффикса и строкового выражения запроса для дальнейшего взаимодействия. Если гибридное подключение регистрируется с путем hyco, выражение path может иметь вид hyco/suffix?param=value&..., после чего следуют параметры строки запроса, заданные здесь. Тогда полное выражение может иметь такой вид:
wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...
Выражение path передается на прослушиватель в URI адреса, который содержится в контрольном сообщении accept.
В случае сбоя подключения через веб-сокет из-за того, что путь гибридного подключения не зарегистрирован, маркер является недопустимым либо отсутствует или из-за какой-то другой ошибки, указываются сведения об ошибке. Для этого используется обычная модель предоставления сведений о состоянии HTTP 1.1. Описание состояния содержит идентификатор отслеживания ошибки, который можно сообщить в службу поддержки Azure.
| Код | Ошибка | Описание |
|---|---|---|
| 404 | Не найдено | Путь гибридного подключения является недопустимым, или базовый URL-адрес имеет неправильный формат. |
| 401 | Не авторизовано | Маркер безопасности отсутствует, имеет неправильный формат или является недопустимым. |
| 403 | Запрещено | Маркер безопасности является недопустимым для этого пути с этим действием. |
| 500 | Внутренняя ошибка | Произошла неизвестная ошибка в службе. |
Если служба намеренно завершает подключение через веб-сокет после того, как оно установлено, то причина такого действия сообщается с помощью соответствующего кода ошибки протокола веб-сокета и сообщения с описанием ошибки, которое также содержит идентификатор отслеживания.
| Состояние веб-сокета | Description |
|---|---|
| 1000 | Прослушиватель завершил работу сокета. |
| 1001 | Путь гибридного подключения был удален или отключен. |
| 1008 | Истек срок действия маркера безопасности, что нарушает политику авторизации. |
| 1011 | Произошла неизвестная ошибка в службе. |
Протокол HTTP-запроса
Протокол HTTP-запроса позволяет выполнять произвольные HTTP-запросы, за исключением обновлений протокола. HTTP-запросы отправляются на обычный адрес среды выполнения сущности, без инфикса $hc, который используется для клиентов с гибридными подключениями через веб-сокет.
https://{namespace-address}/{path}?sb-hc-token=...
namespace-address — это полное доменное имя пространства имен ретранслятора Azure, в котором размещается гибридное подключение (как правило, в формате {myname}.servicebus.windows.net).
Запрос может содержать дополнительные заголовки HTTP произвольной формы, включая заголовки, определяемые приложением. Все поставляемые заголовки, за исключением тех, которые явно определены в RFC7230 (см. раздел Сообщение запроса), передаются в прослушиватель и размещаются в объекте requestHeader сообщения запроса.
Ниже приведены варианты параметров строки запроса.
| Param | Обязательный? | Description |
|---|---|---|
sb-hc-token |
Да* | Прослушиватель должен указать допустимый закодированный в URL-адресе общий маркер служебной шины для пространства имен или гибридного подключения, который предоставляет право на отправку. |
Маркер также может содержаться в HTTP-заголовке ServiceBusAuthorization или Authorization. Маркер может быть опущен, если гибридное подключение настроено на разрешение анонимных запросов.
Так как служба эффективно действует как прокси-сервер, даже если она не является истинным прокси-сервером HTTP, она либо добавляет заголовок Via, либо аннотирует существующий заголовок Via в соответствии с RFC7230, раздел 5.7.1.
Служба добавляет имя узла пространства имен ретрансляции к Via.
| Код | Message | Description |
|---|---|---|
| 200 | OK | Запрос был обработан по крайней мере одним прослушивателем. |
| 202 | Accepted | Запрос был принят по крайней мере одним прослушивателем. |
Если возникла ошибка, то ответ службы может быть следующим: Происхождение ответа (от службы или от прослушивателя) можно определить по наличию заголовка Via. Если заголовок присутствует, ответ передан от прослушивателя.
| Код | Ошибка | Описание |
|---|---|---|
| 404 | Не найдено | Путь гибридного подключения является недопустимым, или базовый URL-адрес имеет неправильный формат. |
| 401 | Не авторизовано | Маркер безопасности отсутствует, имеет неправильный формат или является недопустимым. |
| 403 | Запрещено | Маркер безопасности является недопустимым для этого пути с этим действием. |
| 500 | Внутренняя ошибка | Произошла неизвестная ошибка в службе. |
| 503 | Недопустимый шлюз | Запрос не может быть перенаправлен ни одному прослушивателю. |
| 504 | Истекло время ожидания шлюза | Запрос был перенаправлен прослушивателю, но прослушиватель не подтвердил получение за требуемое время. |