通过

使用 AMQP 协议的 Azure Web PubSub 事件侦听器的 CloudEvents 扩展

  • 项目

Azure Web PubSub 服务将客户端事件描述为 CloudEvents。 CloudEvents 是一种规范，它以通用格式描述事件数据，以提供跨服务、平台和系统的互操作性。

服务的事件侦听器侦听客户端事件。 事件中心是目前唯一受支持的事件侦听器终结点，其主要协议是 AMQP（高级消息队列协议）。 Web PubSub 服务使用 CloudEvents AMQP 协议绑定将 CloudEvents 映射到 AMQP 消息。

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

Web PubSub CloudEvents 属性扩展

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

下表包含了映射到 AMQP 消息的标准属性部分的属性。

名称 步骤 示例
content-type 消息正文的 RFC-2046 MIME 类型 application/json
message-id 唯一定义 Web PubSub 服务中的消息，采用“{连接 ID}/{服务生成的整数}”格式 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

下表包含了映射到 AMQP 消息的应用程序属性部分的所有 CloudEvents 属性。 每个属性名称以 cloudEvents: 为前缀。

名称 步骤 示例
specversion 云事件规范版本，始终为 1.0 1.0
source 表示事件的来源中心和连接 ID，采用“/hubs/{中心}/client/{连接 ID}”格式 /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id 服务生成的整数，在来自同一客户端连接的事件中是唯一的 1
awpsversion 云事件 Azure Web PubSub 规范版本，始终为 1.0 1.0
hub 事件的来源中心名称 聊天
eventname 事件的名称 已连接
type 事件类型 azure.webpubsub.sys.connect
connectionid 客户端连接的 ID 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time 服务发送事件的时间，采用“yyyy-MM-ddTHH:mm:ssZ”格式 2021-01-01T00:00:00Z
userid* 用户的 ID user1
subprotocol* 子协议名称 json.webpubsub.azure.v1
connectionstate* 定义连接的状态。 可以重置事件处理程序的响应头中的值。 有关连接状态的详细信息，请参阅 Web PubSub CloudEvents 属性。 anystring

属性名称后面的“*”表示仅当值不为 null 或不为空时，该属性才存在。

事件

此部分显示 AMQP 消息正文，其中包含依赖于特定客户端事件类型的属性值。 不依赖于客户端事件类型的属性值将被省略。

系统 connected 事件

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.connected
  • cloudEvents:eventname: connected

消息正文始终为空 JSON。

{}

系统 disconnected 事件

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.disconnected
  • cloudEvents:eventname: disconnected

消息正文包含客户端断开连接的原因。

{"reason":"{Reason}"}

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

  • content-type: application/octet-stream 表示二进制帧；text/plain 表示文本帧；
  • cloudEvents:type: azure.webpubsub.user.message

消息正文是客户端发送的内容。

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

  • content-type：对于二进制帧为 application/octet-stream；对于 JSON 帧为 application/json；对于文本帧为 text/plain；对于 Protobuf 帧为 application/x-protobuf
  • cloudEvents:type: azure.webpubsub.user.<event_name>

以下案例演示如何发送具有不同数据内容类型并包含收到的 AMQP 消息正文的事件。

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

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

收到的 AMQP 消息正文：

text data

案例 2：发送包含 JSON 数据的事件：

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

收到的 AMQP 消息正文：

{
    "hello": "world"
}

案例 3：发送包含二进制数据的事件：

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

收到的 AMQP 消息正文：

<binary data>