导入 WebSocket API

  • 项目

借助 API 管理的 WebSocket API 解决方案，API 发布者可以通过 Azure 门户、Azure CLI、Azure PowerShell 和其他 Azure 工具在 API 管理中快速添加 WebSocket API。

可以应用现有的访问控制策略（如 JWT 验证）来保护 WebSocket API。 还可以使用 Azure 门户和开发人员门户中的 API 测试控制台来测试 WebSocket API。 API 管理以现有的可观察性功能为基础，提供用于监视 WebSocket API 和排除其故障的指标和日志。

在本文中，你将：

  • 了解 Websocket 传递流。
  • 将 WebSocket API 添加到 API 管理实例。
  • 测试 WebSocket API。
  • 查看 WebSocket API 的指标和日志。
  • 了解 WebSocket API 的限制。

先决条件

WebSocket 传递

API 管理支持 WebSocket 传递。

Visual illustration of WebSocket passthrough flow

在 WebSocket 传递过程中，客户端应用程序与 API 管理网关建立 WebSocket 连接，然后与相应的后端服务建立连接。 API 管理然后代理 WebSocket 客户端-服务器消息。

  1. 客户端应用程序向 APIM 网关发送 WebSocket 握手请求，调用 onHandshake 操作。
  2. APIM 网关向相应的后端服务发送 WebSocket 握手请求。
  3. 后端服务升级与 WebSocket 的连接。
  4. APIM 网关升级与 WebSocket 的相应连接。
  5. 建立连接对后，APIM 将在客户端应用程序和后端服务之间来回传递消息。
  6. 客户端应用程序向 APIM 网关发送消息。
  7. APIM 网关将消息转发到后端服务。
  8. 后端服务向 APIM 网关发送消息。
  9. APIM 网关将消息转发到客户端应用程序。
  10. 当任一方断开连接时，APIM 终止相应的连接。

注意

客户端和后端连接由一对一映射组成。

onHandshake 操作

根据 WebSocket 协议，当客户端应用程序尝试与后端服务建立 WebSocket 连接时，它将首先发送一个“打开握手”请求。 API 管理中的每个 WebSocket API 都有一个 onHandshake 操作。 onHandshake 是一个不可变、不可移动、自动创建的系统操作。 onHandshake 操作使 API 发布者能够拦截这些握手请求并对它们应用 API 管理策略。

onHandshake screen example

添加 WebSocket API

    1. 在 Azure 门户，导航到 API 管理实例。

  2. 在左侧菜单中，选择“API”>“+ 添加 API”。

  3. 在“定义新 API”下，选择“WebSocket”。

  4. 在对话框中，选择“完整”并填写必填的表单字段。

    字段 说明
    显示名称 WebSocket API 的显示名称。
    名称 WebSocket API 的原始名称。 键入显示名称时自动填充。
    WebSocket URL 包含 WebSocket 名称的基 URL。 例如：ws://example.com/your-socket-name
    URL 方案 接受默认值
    API URL 后缀 添加 URL 后缀以在该 API 管理实例中标识此特定 API。 它在此 APIM 实例中必须唯一。
    产品 将 WebSocket API 与产品关联来发布它。
    网关 将 WebSocket API 与现有网关相关联。

  5. 单击 “创建” 。

测试 WebSocket API

  1. 导航到 WebSocket API。

  2. 在 WebSocket API 中，选择 onHandshake 操作。

  3. 选择“测试”选项卡以访问“测试”控制台。

  4. （可选）提供 WebSocket 握手所需的查询字符串参数。

    test API example

  5. 单击“连接” 。

  6. 在“输出”中查看连接状态。

  7. 在“有效负载”中输入值。

  8. 单击“发送”。

  9. 在“输出”中查看收到的消息。

  10. 重复上述步骤以测试不同的有效负载。

  11. 测试完成时，选择“断开连接”。

查看指标和日志

使用标准 API 管理和 Azure Monitor 功能来监视 WebSocket API：

  • 查看 Azure Monitor 中的 API 指标
  • （可选）启用诊断设置以收集和查看 API 管理网关日志，其中包括 WebSocket API 操作

例如，下面的屏幕截图显示了来自 ApiManagementGatewayLogs 表的代码为 101 的最近 WebSocket API 响应。 这些结果表明成功将请求从 TCP 协议切换到 WebSocket 协议。

Query logs for WebSocket API requests

限制

以下是 API 管理中 WebSocket 支持的当前限制：

  • 消耗层不支持 WebSocket API。
  • WebSocket API 支持以下有效消息缓冲区类型：Close、BinaryFragment、BinaryMessage、UTF8Fragment 和 UTF8Message。
  • 目前，set-header 策略不支持在 onHandshake 请求中更改某些已知的标头，包括 Host 标头。
  • 在与 WebSocket 后端进行 TLS 握手期间，API 管理会验证服务器证书是否受信任，并且其使用者名称是否与主机名匹配。 通过 HTTP API，API 管理会验证证书是否受信任，但不验证主机名和使用者是否匹配。

有关 WebSocket 连接限制，请参阅 API 管理限制。

不受支持的策略

以下策略不受支持，无法应用于 onHandshake 操作：

  • 模拟响应
  • 从缓存中获取
  • 存储到缓存
  • 允许跨域调用
  • CORS
  • JSONP
  • 设置请求方法
  • 设置正文
  • 将 XML 转换为 JSON
  • 将 JSON 转换为 XML
  • 使用 XSLT 转换 XML
  • 验证内容
  • 验证参数
  • 验证头
  • 验证状态代码

注意

如果将这些策略应用于更高的范围（例如全局或产品），并且 WebSocket API 通过策略继承它们，则它们将在运行时被跳过。

后续步骤

转换和保护已发布的 API