From a6de0c0022daf303c1a74c33d49aa06ed9e45485 Mon Sep 17 00:00:00 2001 From: rianli Date: Wed, 30 Oct 2024 12:12:23 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0event=20payload?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../interface-framework/event-emit.md | 107 +++++++----------- 1 file changed, 44 insertions(+), 63 deletions(-) diff --git a/docs/develop/api-v2/dev-prepare/interface-framework/event-emit.md b/docs/develop/api-v2/dev-prepare/interface-framework/event-emit.md index e0dead1..efad1f9 100644 --- a/docs/develop/api-v2/dev-prepare/interface-framework/event-emit.md +++ b/docs/develop/api-v2/dev-prepare/interface-framework/event-emit.md @@ -6,36 +6,62 @@ 当用户在QQ平台内的一些行为操作或某些接口的有异步返回通知确认机制的场景的时候，QQ 会通过"事件"的方式，通知到开发者服务器，开发者可自行根据具体事件通知来进行下一步响应。譬如用户跟机器人发消息，用户添加机器人好友，机器人被拉入群聊等等事件。 ::: -## Webhook方式 - -webhook事件回调链路目前在灰度验证，灰度用户可体验通过页面配置事件监听及回调地址。如未在灰度范围，可联系QQ机器人反馈助手开通。 - -QQ机器人反馈助手 - -QQ机器人开放平台支持通过使用HTTP接口接收事件。开发者可通过[管理端](https://q.qq.com/qqbot/#/developer/webhook-setting)设定回调地址，监听事件等。 - -### 数据结构 - -#### Payload +## 通用数据结构 Payload -网关的上下行消息采用的都是同一个结构，如下： +`payload` 指的是在 `webhook`或`websocket` 连接上传输的数据，网关的上下行消息采用的都是同一个结构，如下： ```json { + "id":"event_id", "op": 0, "d": {}, + "s": 42, "t": "GATEWAY_EVENT_NAME" } ``` -##### OpCode +| 字段 | 描述 | +|-----|------------------------------------------------------| +| id | 事件id | +| op | 指的是 opcode，参考连接维护 | +| s | 下行消息都会有一个序列号，标识消息的唯一性，客户端需要再发送心跳的时候，携带客户端收到的最新的s | +| t | 代表事件类型。主要用在op为 0 Dispatch 的时候 | +| d | 代表事件内容，不同事件类型的事件内容格式都不同，请注意识别。主要用在op为 0 Dispatch 的时候 | + -`opcode` 含义如下： +### OpCode 含义 + +所有 `opcode` 列表如下： + +| **CODE** | **名称** | 接入方式 | **客户端行为** | **描述** | +|----------|-------------------|-------------------|---------------|------------------------------------------| +| 0 | Dispatch | webhook/websocket | Receive | 服务端进行消息推送 | +| 1 | Heartbeat | websocket | Send/Receive | 客户端或服务端发送心跳 | +| 2 | Identify | websocket | Send | 客户端发送鉴权 | +| 6 | Resume | websocket | Send | 客户端恢复连接 | +| 7 | Reconnect | websocket | Receive | 服务端通知客户端重新连接 | +| 9 | Invalid Session | websocket | Receive | 当 identify 或 resume 的时候，如果参数有错，服务端会返回该消息 | +| 10 | Hello | websocket | Receive | 当客户端与网关建立 ws 连接之后，网关下发的第一条消息 | +| 11 | Heartbeat ACK | websocket | Receive/Reply | 当发送心跳成功之后，就会收到该消息 | +| 12 | HTTP Callback ACK | webhook | Reply | 仅用于 http 回调模式的回包，代表机器人收到了平台推送的数据 | +| 13 | 回调地址验证 | webhook | Receive | 开放平台对机器人服务端进行验证 | +客户端行为含义如下： + +`Receive` 客户端接收到服务端 `push` 的消息 + +`Send` 客户端发送消息 + +`Reply` 客户端接收到服务端发送的消息之后的回包（HTTP 回调模式） + + +## Webhook方式 + +webhook事件回调链路目前在灰度验证，灰度用户可体验通过页面配置事件监听及回调地址。如未在灰度范围，可联系QQ机器人反馈助手开通。 + +QQ机器人反馈助手 + +QQ机器人开放平台支持通过使用HTTP接口接收事件。开发者可通过[管理端](https://q.qq.com/qqbot/#/developer/webhook-setting)设定回调地址，监听事件等。 -| **CODE** | **名称** | **客户端行为** | **描述** | -|----------|----------|-----------|-----------------| -| 0 | Dispatch | Receive | 服务端进行消息推送 | -| 13 | 回调地址验证 | Receive | 开放平台对机器人服务端进行验证 | ### 签名校验 @@ -141,51 +167,6 @@ body: {"plain_token": "Arq0D5A61EgUu4OxUvOp","signature": "87befc99c42c651b3aac0 优势：本地服务器即可发起调试，无需依赖公网域名和公网服务器（`WebHook`）接收回调通知。 -### 通用数据结构 Payload - -`payload` 指的是在 `websocket` 连接上传输的数据，网关的上下行消息采用的都是同一个结构，如下： - -```json -{ - "op": 0, - "d": {}, - "s": 42, - "t": "GATEWAY_EVENT_NAME" -} -``` - -| 字段 | 描述 | -|-----|------------------------------------------------------| -| op | 指的是 opcode，参考连接维护 | -| s | 下行消息都会有一个序列号，标识消息的唯一性，客户端需要再发送心跳的时候，携带客户端收到的最新的s | -| t | 代表事件类型。主要用在op为 0 Dispatch 的时候 | -| d | 代表事件内容，不同事件类型的事件内容格式都不同，请注意识别。主要用在op为 0 Dispatch 的时候 | - - -### 长连接维护 OpCode - -所有 `opcode` 列表如下： - -| **CODE** | **名称** | **客户端行为** | **描述** | -|----------|-------------------|---------------|------------------------------------------| -| 0 | Dispatch | Receive | 服务端进行消息推送 | -| 1 | Heartbeat | Send/Receive | 客户端或服务端发送心跳 | -| 2 | Identify | Send | 客户端发送鉴权 | -| 6 | Resume | Send | 客户端恢复连接 | -| 7 | Reconnect | Receive | 服务端通知客户端重新连接 | -| 9 | Invalid Session | Receive | 当 identify 或 resume 的时候，如果参数有错，服务端会返回该消息 | -| 10 | Hello | Receive | 当客户端与网关建立 ws 连接之后，网关下发的第一条消息 | -| 11 | Heartbeat ACK | Receive/Reply | 当发送心跳成功之后，就会收到该消息 | -| 12 | HTTP Callback ACK | Reply | 仅用于 http 回调模式的回包，代表机器人收到了平台推送的数据 | - -客户端行为含义如下： - -`Receive` 客户端接收到服务端 `push` 的消息 - -`Send` 客户端发送消息 - -`Reply` 客户端接收到服务端发送的消息之后的回包（HTTP 回调模式） - ### 发起连接到 Gateway 第一步先调用 [获取通用WSS 接入点 | QQ机器人文档](../../openapi/wss/url_get.md) 或 [获取带分片WSS 接入点 | QQ机器人文档](../../openapi/wss/shard_url_get.md) 接口获取网关地址。