Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: 更新event payload说明文档 #244

Merged
merged 1 commit into from
Oct 30, 2024
Merged

feat: 更新event payload说明文档 #244

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 44 additions & 63 deletions docs/develop/api-v2/dev-prepare/interface-framework/event-emit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,36 +6,62 @@
当用户在QQ平台内的一些行为操作或某些接口的有异步返回通知确认机制的场景的时候，QQ 会通过"事件"的方式，通知到开发者服务器，开发者可自行根据具体事件通知来进行下一步响应。譬如用户跟机器人发消息，用户添加机器人好友，机器人被拉入群聊等等事件。
:::

## Webhook方式

webhook事件回调链路目前在灰度验证，灰度用户可体验通过页面配置事件监听及回调地址。如未在灰度范围，可联系QQ机器人反馈助手开通。

<img :src="$withBotBase('/images/api-231017/feedback_bot.png')" alt="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机器人反馈助手开通。

<img :src="$withBotBase('/images/api-231017/feedback_bot.png')" alt="QQ机器人反馈助手">

QQ机器人开放平台支持通过使用HTTP接口接收事件。开发者可通过[管理端](https://q.qq.com/qqbot/#/developer/webhook-setting)设定回调地址，监听事件等。

| **CODE** | **名称** | **客户端行为** | **描述** |
|----------|----------|-----------|-----------------|
| 0 | Dispatch | Receive | 服务端进行消息推送 |
| 13 | 回调地址验证 | Receive | 开放平台对机器人服务端进行验证 |

### 签名校验

Expand Down Expand Up @@ -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) 接口获取网关地址。
Expand Down
Loading