Поддержка протокола WebSocket
Примечание
Эта функциональность находится на стадии Preview.
Чтобы подключиться к API-шлюзу по протоколу WebSocket, клиентские приложения должны сделать GET-запрос на URI, для которого настроены интеграции в OpenAPI-спецификации. Интеграции вызываются, когда выполняются следующие операции:
x-yc-apigateway-websocket-connect— открытие соединения.x-yc-apigateway-websocket-message— отправка сообщений через веб-сокет.x-yc-apigateway-websocket-disconnect— закрытие соединения.
Операция x-yc-apigateway-websocket-connect
Операция выполняется, когда устанавливается новое соединение. API Gateway, выполняя ее, вызывает интеграцию. Если интеграция вызвана успешно, клиенту возвращается ответ с HTTP-кодом 101 Switching Protocol, после чего веб-сокет считается открытым согласно протоколу RFC. Иначе возвращается ошибка, полученная от интеграции.
Для каждого нового веб-сокета генерируется уникальный идентификатор соединения, который возвращается клиенту в заголовке X-Yc-Apigateway-Websocket-Connection-Id. Идентификатор соединения передается при вызове интеграции. Чтобы управлять установленным соединением — отправлять данные на клиентскую сторону или закрывать соединение — с помощью API, сохраните полученный идентификатор, например в базе данных Yandex Managed Service for YDB.
Ниже приведен список заголовков, которые дополнительно передаются в HTTP-запросе к интеграции:
X-Yc-Apigateway-Websocket-Connection-Id— идентификатор соединения.X-Yc-Apigateway-Websocket-Event-Type— тип события, в данном случаеCONNECT.X-Yc-Apigateway-Websocket-Connected-At— время установления соединения.
Если в качестве интеграции используется функция Yandex Cloud Functions, перечисленная выше информация про веб-сокет передается в виде отдельных полей внутри requestContext JSON-структуры запроса к функции.
Для данной операции можно настроить авторизацию с помощью функции. Если авторизация будет неуспешной, соединение не установится и клиент получит ответ с HTTP-кодом 401 или 403.
Клиенты могут использовать заголовок Sec-WebSocket-Protocol согласно RFC, чтобы запрашивать у API-шлюза поддержку подпротоколов. API-шлюз передаст этот заголовок в HTTP-запросе к интеграции.
Операция не является обязательной. Если операция не определена в спецификации, при подключении клиенту по умолчанию возвращается HTTP-код 101 Switching Protocol. Подключайте интеграции для этой операции, если нужно:
- Реализовывать специальные подпротоколы для общения между клиентом и API-шлюзом.
- Знать, когда открывается и закрывается соединение.
- Контролировать через авторизацию, кто может подключаться по протоколу WebSocket, а кто — нет.
- Отправлять сообщения на клиентскую сторону через API управления соединениями.
- Сохранять идентификатор соединения и другую информацию в базы данных.
Операция x-yc-apigateway-websocket-message
Операция выполняется, когда отправляется сообщение с клиентской стороны. API Gateway, выполняя ее, вызывает интеграцию. Данные, полученные из веб-сокета, передаются в теле HTTP-запроса к интеграции. Поддерживаются текстовые (кодировка UTF-8) и бинарные сообщения согласно RFC. При текстовых данных в заголовок Content-Type проставляется значение application/json, при бинарных — application/octet-stream. Если в качестве интеграции используется функция Cloud Functions, для бинарного сообщения выполняется base64-кодирование данных и получившееся строковое значение записывается в поле body JSON-структуры запроса, а флаг isBase64Encoded проставляется в true.
Тело ответа от интеграции отправляется отдельным сообщением в веб-сокет на клиентскую сторону. Если заголовок Content-Type, полученный от интеграции, имеет значение application/json или начинается с префикса text/, отправляется текстовое сообщение, иначе — бинарное.
Размер сообщения должен быть не более 128 КБ, а размер фрейма — не более 32 КБ. Если размер сообщения превышает 32 КБ, его нужно разбить на несколько фреймов. Если размер сообщения или фрейма превышает указанный лимит, соединение закрывается с кодом 1009.
Для каждого сообщения генерируется уникальный идентификатор. Идентификатор сообщения передается в специальном заголовке, когда вызывается интеграция. Лексикографический порядок идентификаторов сообщений соответствует их временной последовательности.
Ниже приведен список заголовков, которые дополнительно передаются в HTTP-запросе к интеграции:
X-Yc-Apigateway-Websocket-Connection-Id— идентификатор соединения.X-Yc-Apigateway-Websocket-Event-Type— тип события, в данном случаеMESSAGE.X-Yc-Apigateway-Websocket-Message-Id— идентификатор сообщения.
Если в качестве интеграции используется функция Cloud Functions, перечисленная выше информация про сообщение передается в виде отдельных полей внутри requestContext JSON-структуры запроса к функции.
Операция является обязательной, иначе соответствующий ей путь в OpenAPI-спецификации API-шлюза не будет поддерживать подключение по протоколу WebSocket.
Операция x-yc-apigateway-websocket-disconnect
Операция выполняется после того, как соединение закрывается согласно протоколу RFC или разрывается. Соединение может закрыться по инициативе клиента или сервиса API Gateway. API Gateway, выполняя эту операцию, всегда пытается вызвать интеграцию, но выполнение операции не может быть гарантировано.
Операция не является обязательной. При этом делать что-то при закрытии соединения, например удалять информацию о нем из базы данных, рекомендуется в интеграции, которая вызывается при выполнении этой операции.
Ниже приведен список заголовков, которые дополнительно передаются в HTTP-запросе к интеграции:
X-Yc-Apigateway-Websocket-Connection-Id— идентификатор соединения.X-Yc-Apigateway-Websocket-Event-Type— тип события, в данном случаеDISCONNECT.X-Yc-Apigateway-Websocket-Disconnect-Status-Code— статус-код, список возможных кодов описан в протоколе RFC.X-Yc-Apigateway-Websocket-Disconnect-Reason— текстовое описание причины, по которой закрылось соединение.
Если в качестве интеграции используется функция Cloud Functions, перечисленная выше информация про закрытое соединение передается в виде отдельных полей внутри requestContext JSON-структуры запроса к функции.
Максимальное время жизни соединения — 60 минут. Если в течение 10 минут через веб-сокет не ходят сообщения, считается, что он простаивает. В таком случае соединение закрывается. Можно периодически отправлять из клиентского приложения предусмотренные протоколом RFC ping-фреймы, чтобы API-шлюз не считал соединение простаивающим и не закрывал его.
Так как соединение может быть закрыто по указанным выше или другим причинам, при написании клиентских приложений рекомендуется предусмотреть автоматическое переподключение.
Спецификация расширения
Пример спецификации со статическим ответом:
/ws:
x-yc-apigateway-websocket-message:
x-yc-apigateway-integration:
type: dummy
content:
'*': Got new message!
http_code: 200
http_headers:
Content-Type: text/plain
Пример спецификации с вызовом функции:
/ws:
x-yc-apigateway-websocket-connect:
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95ic**********
tag: "$latest"
service_account_id: ajehfe56h**********
x-yc-apigateway-websocket-message:
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95ic**********
tag: "$latest"
service_account_id: ajehfe56h**********
x-yc-apigateway-websocket-disconnect:
x-yc-apigateway-integration:
type: cloud_functions
function_id: b095c95ic**********
tag: "$latest"
service_account_id: ajehfe56h**********