通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 HTTP 协议的 Azure Web PubSub 事件处理程序的 CloudEvents 扩展

Web PubSub 服务使用 CloudEvents HTTP 协议绑定将客户端事件传送到上游 Webhook。

从 Web PubSub 服务发送到服务器的数据始终采用 CloudEvents binary 格式。

Webhook 验证

Webhook 验证遵循 CloudEvents。 请求始终包含在 WebHook-Request-Origin: xxx.webpubsub.azure.com 标头中。

如果仅当传递目标允许传递事件时，它必须通过包括 WebHook-Allowed-Origin 标头来回复请求，例如：

WebHook-Allowed-Origin: *

或者：

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

目前不支持 WebHook-Request-Rate 和 WebHook-Request-Callback 。

Web PubSub CloudEvents 属性扩展

此外，还指出，HTTP 规范现在遵循类似的模式，不再表明扩展 HTTP 标头以 X 为前缀。

此扩展定义 Web PubSub 为其生成的每个事件使用的属性。

特性

名称 类型 说明 示例
userId string 连接经过身份验证的用户
hub string 连接所属的中心
connectionId string connectionId 对于客户端连接是唯一的
eventName string 不带前缀的事件的名称
subprotocol string 客户端正在使用的子协议（如果有）
connectionState string 定义连接的状态。 可以使用同一响应标头来重置状态的值。 不允许使用多个 connectionState 标头。 如果 base64 包含复杂字符，则对字符串值进行编码，例如， base64(jsonString) 使用此属性传递复杂对象。
signature string 上游 Webhook 的签名，用于验证传入请求是否来自预期源。 服务使用主访问密钥和辅助访问密钥作为HMAC密钥计算值： Hex_encoded(HMAC_SHA256(accessKey, connectionId)) 上游应在处理请求之前检查请求是否有效。

事件

有两种类型的事件。 一个是 阻止 服务等待事件响应继续的事件。 一个是 取消阻止 服务在处理下一条消息之前等待此类事件的响应的事件。

系统 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：如果此标头存在，则此连接的连接状态将更新为标头的值。 只有 阻止 事件才能更新连接状态。 下面的示例使用 base64 编码的 JSON 字符串来存储连接的复杂状态。

  • 状态代码：

    • 204：成功，无内容。
    • 200：成功，内容应为 JSON 格式，允许以下属性：

      • subprotocols

        该 connect 事件将子协议和身份验证信息从客户端转发到上游。 Web PubSub 服务使用状态代码来确定请求是否会升级到 WebSocket 协议。

        如果请求包含该 subprotocols 属性，服务器应返回它支持的一个子协议。 如果服务器不想使用任何子协议，则 它不应 在响应中发送 subprotocol 属性。 发送空白标头无效。

      • userId: {auth-ed user ID}

        由于服务允许匿名连接，事件 connect 负责告知服务客户端连接的用户 ID。 该服务从响应有效负载 userId 读取用户 ID（如果存在）。 如果无法从请求声明读取用户 ID，或者无法读取事件的响应有效负载， connect 则会删除连接。

      • groups: {groups to join}

        该属性为用户提供了一种将此连接添加到一个或多个组的便捷方法。 这样，就无需进行另一个调用来将此连接添加到某些组。

      • roles: {roles the client has}

        该属性为上游 Webhook 提供授权客户端的方法。 可通过不同的角色为 PubSub WebSocket 客户端授予初始权限。 有关权限的详细信息，请参阅 客户端权限。

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

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

错误响应格式：

  • 4xx：错误，来自上游的响应将作为客户端请求的响应返回。
HTTP/1.1 401 Unauthorized

系统 connected 事件

当客户端完成 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当客户端请求完成时，如果连接事件返回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

简单 WebSocket 客户端的用户事件message

该服务为每个 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：如果此标头存在，则此连接的连接状态将更新为标头的值。 只有 阻止 事件才能更新连接状态。 下面的示例使用 base64 编码的 JSON 字符串来存储连接的复杂状态。

当是Content-Typeapplication/octet-stream时，服务将使用 binary WebSocket 帧发送到UserResponsePayload客户端。 当是Content-Typetext/plain时，服务将使用 text WebSocket 帧发送到UserResponsePayload客户端。

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则会删除连接。

PubSub WebSocket 客户端的用户自定义事件{custom_event}

该服务为每个有效的自定义事件消息调用事件处理程序 Webhook。

案例 1：发送包含文本数据的事件：

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

上游事件处理程序接收的内容如下，Content-TypeCloudEvents HTTP 请求适用于text/plaindataType=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-TypeCloudEvents HTTP 请求适用于application/jsondataType=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-TypeCloudEvents HTTP 请求适用于application/octet-streamdataType=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：如果此标头存在，则此连接的连接状态将更新为标头的值。 只有 阻止 事件才能更新连接状态。 下面的示例使用 base64 编码的 JSON 字符串来存储连接的复杂状态。
  • 当标头Content-Type为application/octet-stream时，服务会像使用有效负载 base64 编码一样binary发UserResponsePayload回客户端dataType。 示例响应： 
    {
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
  • 当是Content-Typetext/plain时，服务会像有效负载字符串一样text发送到UserResponsePayload客户端dataType。
  • 当是时，服务将使用datadataTypejson=值令牌作为响应有效负载正文发送到UserResponsePayload客户端。Content-Typeapplication/json

错误响应格式

如果状态代码未成功，则被视为错误响应。 如果响应状态代码未成功，{custom_event}则会删除连接。

后续步骤

使用这些资源开始生成自己的应用程序：

教程：在 Azure Web PubSub 中发布和订阅消息

教程：使用 Azure Web PubSub 创建简单的聊天室

教程：使用服务支持的子协议来进行客户端流传输

教程：使用 Azure Functions 和 Web PubSub 生成无服务器聊天

教程：配置事件侦听器

体验实时演示

探索更多 Azure Web PubSub 示例

  • Last updated on