diff --git a/docs/.vuepress/public/images/api-231017/feedback_bot.png b/docs/.vuepress/public/images/api-231017/feedback_bot.png new file mode 100644 index 00000000..6e2099d6 Binary files /dev/null and b/docs/.vuepress/public/images/api-231017/feedback_bot.png differ 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 5c8ca829..e0dead14 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 @@ -1,4 +1,3 @@ - # 事件订阅与通知 @@ -9,9 +8,9 @@ ## Webhook方式 -**Webhook方式灰度中，仅灰度用户可使用** 其它用户请使用 [websocket方式](#websocket方式) 。 +webhook事件回调链路目前在灰度验证，灰度用户可体验通过页面配置事件监听及回调地址。如未在灰度范围，可联系QQ机器人反馈助手开通。 -灰度用户如遇问题可通过 [QQ机器人反馈助手](https://mpqq.gtimg.cn/bot-wiki/online/images/api-231017/qqrobot-feedback.jpg) 反馈 +QQ机器人反馈助手 QQ机器人开放平台支持通过使用HTTP接口接收事件。开发者可通过[管理端](https://q.qq.com/qqbot/#/developer/webhook-setting)设定回调地址，监听事件等。 @@ -33,36 +32,39 @@ QQ机器人开放平台支持通过使用HTTP接口接收事件。开发者可 `opcode` 含义如下： -| **CODE** | **名称** | **客户端行为** | **描述** | -| --- | --- | --- | --- | -| 0 | Dispatch | Receive | 服务端进行消息推送 | -| 13 | 回调地址验证 | Receive | 开放平台对机器人服务端进行验证 | +| **CODE** | **名称** | **客户端行为** | **描述** | +|----------|----------|-----------|-----------------| +| 0 | Dispatch | Receive | 服务端进行消息推送 | +| 13 | 回调地址验证 | Receive | 开放平台对机器人服务端进行验证 | ### 签名校验 + 机器人服务端需要对回调请求进行签名验证以保证数据没有被篡改过。 [签名算法](sign.md) ### 回调地址及事件监听配置 开发者需要提供一个HTTPS回调地址。并选定监听的事件类型。开放平台会将事件通过回调的方式推送给机器人。 + event_subscription 配置回调地址后，开放平台会对回调地址进行验证： * 请求结构(Payload.d) -| **字段** | **描述** | -| --- |------------| +| **字段** | **描述** | +|-------------|------------| | plain_token | 需要计算签名的字符串 | -| event_ts | 计算签名使用时间戳 | +| event_ts | 计算签名使用时间戳 | * 返回结果 -| **字段** | **描述** | -| --- |-------------| +| **字段** | **描述** | +|-------------|------------| | plain_token | 需要计算签名的字符串 | -| signature | 签名 | +| signature | 签名 | 计算过程如下(golang)： + ```go func handleValidation(rw http.ResponseWriter, r *http.Request, botSecret string) { httpBody, err := io.ReadAll(r.Body) @@ -131,6 +133,8 @@ body: {"plain_token": "Arq0D5A61EgUu4OxUvOp","signature": "87befc99c42c651b3aac0 ## WebSocket方式 +* websocket 事件推送链路将在24年年底前逐步下线，后续官方不再维护。 + 通过 `WebSocket` 建立与QQ机器人开放平台的长链接通信管道，当需要事件通知的时候QQ后台通过 `WebSocket` 连接下发事件到开发者服务器上。 开发者需要维护 `WebSocket` 长链接的状态，包括连接状态维护、登录鉴权、心跳维护、断线恢复重连等。 @@ -139,7 +143,7 @@ body: {"plain_token": "Arq0D5A61EgUu4OxUvOp","signature": "87befc99c42c651b3aac0 ### 通用数据结构 Payload - `payload` 指的是在 `websocket` 连接上传输的数据，网关的上下行消息采用的都是同一个结构，如下： +`payload` 指的是在 `websocket` 连接上传输的数据，网关的上下行消息采用的都是同一个结构，如下： ```json { @@ -149,29 +153,30 @@ body: {"plain_token": "Arq0D5A61EgUu4OxUvOp","signature": "87befc99c42c651b3aac0 "t": "GATEWAY_EVENT_NAME" } ``` -| 字段 | 描述| -| ----- | ----- | -| op |指的是 opcode，参考连接维护 | -| s |下行消息都会有一个序列号，标识消息的唯一性，客户端需要再发送心跳的时候，携带客户端收到的最新的s | -| t |代表事件类型。主要用在op为 0 Dispatch 的时候| -| d |代表事件内容，不同事件类型的事件内容格式都不同，请注意识别。主要用在op为 0 Dispatch 的时候| + +| 字段 | 描述 | +|-----|------------------------------------------------------| +| 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 回调模式的回包，代表机器人收到了平台推送的数据 | +| **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 回调模式的回包，代表机器人收到了平台推送的数据 | 客户端行为含义如下： @@ -203,7 +208,7 @@ wss://api.sgroup.qq.com/websocket/ ### 登录鉴权获得 Session - `websocket` 长连接建立之后，需要进行登录鉴权，登录鉴权成功后会获得一个 session 会话 id，只有登录成功后，QQ后台才会下发事件通知， +`websocket` 长连接建立之后，需要进行登录鉴权，登录鉴权成功后会获得一个 session 会话 id，只有登录成功后，QQ后台才会下发事件通知， 发送一个 OpCode 2 Identify 消息， `payload` 如下： ```json @@ -223,12 +228,12 @@ wss://api.sgroup.qq.com/websocket/ ``` -| **字段** | **描述** | -| --- | --- | -| token | 格式为"QQBot {AccessToken}" | -| intents | 是此次连接所需要接收的事件，具体可参考 **Intents** [事件订阅intents\|QQ机器人文档](#事件订阅Intents)| -| shard | 考虑到开发者事件接收时可以实现负载均衡，QQ 提供了分片逻辑，事件通知会落在不同的分片上，该参数是个拥有两个元素的数组。
例如：\[0,4\]，代表分为四个片，当前链接是第 0 个片，业务稍后应该继续建立 `shard` 为\[1,4\],\[2,4\],\[3,4\]的链接，才能完整接收事件，更多详细的内容可以参考 **Shard** [Shard机制\|QQ机器人文档](#%E5%88%86%E7%89%87%E8%BF%9E%E6%8E%A5LoadBalance)
若无需分片，使用\[0, 1\]即可。 | -| properties | 目前无实际作用，可以按照自己的实际情况填写，也可以留空 | +| **字段** | **描述** | +|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| token | 格式为"QQBot {AccessToken}" | +| intents | 是此次连接所需要接收的事件，具体可参考 **Intents** [事件订阅intents\ |QQ机器人文档](#事件订阅Intents)| +| shard | 考虑到开发者事件接收时可以实现负载均衡，QQ 提供了分片逻辑，事件通知会落在不同的分片上，该参数是个拥有两个元素的数组。
例如：\[0,4\]，代表分为四个片，当前链接是第 0 个片，业务稍后应该继续建立 `shard` 为\[1,4\],\[2,4\],\[3,4\]的链接，才能完整接收事件，更多详细的内容可以参考 **Shard** [Shard机制\ |QQ机器人文档](#%E5%88%86%E7%89%87%E8%BF%9E%E6%8E%A5LoadBalance)
若无需分片，使用\[0, 1\]即可。 | +| properties | 目前无实际作用，可以按照自己的实际情况填写，也可以留空 | 鉴权成功之后，QQ 后台会下发一个 Ready Event， `payload` 如下： ```json @@ -259,7 +264,6 @@ wss://api.sgroup.qq.com/websocket/ } ``` - 心跳发送成功之后会收到 [OpCode 11 Heartbeat ACK](opcode.md) 消息， `payload` 如下： ```json @@ -346,8 +350,8 @@ INTERACTION (1 << 26) - INTERACTION_CREATE // 互动事件创建时 MESSAGE_AUDIT (1 << 27) -- MESSAGE_AUDIT_PASS // 消息审核通过 -- MESSAGE_AUDIT_REJECT // 消息审核不通过 + - MESSAGE_AUDIT_PASS // 消息审核通过 + - MESSAGE_AUDIT_REJECT // 消息审核不通过 FORUMS_EVENT (1 << 28) // 论坛事件，仅 *私域* 机器人能够设置此 intents。 - FORUM_THREAD_CREATE // 当用户创建主题时 @@ -382,16 +386,16 @@ PUBLIC_GUILD_MESSAGES (1 << 30) // 消息事件，此为公域的消息事件 如果拥有的某个特殊事件类型的权限被取消，则在当前连接上不会报错，但是将不会收到对应的事件类型，如果重新连接，则报错，所以如果开发者的事件类型权限被取消，请及时调整监听事件代码，避免报错导致的无法连接。 - ### 分片连接LoadBalance 随着`bot`的增长并被添加到越来越多的频道中，事件越来越多，业务有必要对事件进行水平分割，实现负载均衡。机器人网关实现了一种用户可控制的分片方法，该方法允许跨多个网关连接拆分事件。 分片完全由用户控制，并且不需要在单独的连接之间进行状态共享。 要在连接上启用分片，需要在建立连接的时候指定分片参数，具体参考[gateway](reference.md) - #### 获得合适的分片数 + 使用[/gateway/bot](../../openapi/wss/shard_url_get.md)接口获取网关地址的时候，会同时返回一个建议的 `shard`数，及最大并发限制。 + ```json { "url": "wss://sandbox.api.sgroup.qq.com/websocket", @@ -406,7 +410,9 @@ PUBLIC_GUILD_MESSAGES (1 << 30) // 消息事件，此为公域的消息事件 ``` #### 分片规则 + 分片是按照频道id进行哈希的，同一个频道的信息会固定从同一个链接推送。具体哈希计算规则如下： + ```bash shard_id = (guild_id >> 22) % num_shards ```