From 6e1a31cf92c29f5a526e54f3592203c51a9494b3 Mon Sep 17 00:00:00 2001 From: veehou Date: Wed, 22 Dec 2021 23:33:51 +0800 Subject: [PATCH 01/11] =?UTF-8?q?[feat]=E5=A2=9E=E5=8A=A0python-sdk?= =?UTF-8?q?=E7=9A=84=E5=9F=BA=E7=A1=80=E6=A1=86=E6=9E=B6=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=8C=E9=9C=80=E8=A6=81=E7=BB=A7=E7=BB=AD=E5=AE=8C=E5=96=84?= =?UTF-8?q?=EF=BC=8C=E5=8B=BF=E4=BD=BF=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop/pythonsdk/README.md | 124 ++++++ docs/develop/pythonsdk/guild/get_guild.md | 49 +++ .../guild/guild_role/create_guild_role.md | 51 +++ .../guild_role/create_guild_role_member.md | 48 +++ .../guild/guild_role/delete_guild_role.md | 31 ++ .../guild_role/delete_guild_role_member.md | 47 +++ .../guild/guild_role/get_guild_roles.md | 67 ++++ .../guild/guild_role/update_guild_role.md | 70 ++++ .../develop/pythonsdk/member/delete_member.md | 38 ++ docs/develop/pythonsdk/member/get_member.md | 64 +++ docs/develop/pythonsdk/member/get_members.md | 74 ++++ .../pythonsdk/message/get_message_of_id.md | 87 ++++ .../develop/pythonsdk/message/get_messages.md | 120 ++++++ .../pythonsdk/message/message_format.md | 127 ++++++ .../pythonsdk/message/message_template.md | 376 ++++++++++++++++++ .../pythonsdk/message/post_ark_messages.md | 223 +++++++++++ .../pythonsdk/message/post_messages.md | 135 +++++++ 17 files changed, 1731 insertions(+) create mode 100644 docs/develop/pythonsdk/README.md create mode 100644 docs/develop/pythonsdk/guild/get_guild.md create mode 100644 docs/develop/pythonsdk/guild/guild_role/create_guild_role.md create mode 100644 docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md create mode 100644 docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md create mode 100644 docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md create mode 100644 docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md create mode 100644 docs/develop/pythonsdk/guild/guild_role/update_guild_role.md create mode 100644 docs/develop/pythonsdk/member/delete_member.md create mode 100644 docs/develop/pythonsdk/member/get_member.md create mode 100644 docs/develop/pythonsdk/member/get_members.md create mode 100644 docs/develop/pythonsdk/message/get_message_of_id.md create mode 100644 docs/develop/pythonsdk/message/get_messages.md create mode 100644 docs/develop/pythonsdk/message/message_format.md create mode 100644 docs/develop/pythonsdk/message/message_template.md create mode 100644 docs/develop/pythonsdk/message/post_ark_messages.md create mode 100644 docs/develop/pythonsdk/message/post_messages.md diff --git a/docs/develop/pythonsdk/README.md b/docs/develop/pythonsdk/README.md new file mode 100644 index 00000000..09f4e01e --- /dev/null +++ b/docs/develop/pythonsdk/README.md @@ -0,0 +1,124 @@ +# Python SDK 接入指南 + +## 当前版本 +![PyPI](https://img.shields.io/pypi/v/qq-bot) + +## 安装 + +``` bash +pip install qq-bot +``` + +更新包的话需要添加 ``--upgrade`` ``注：需要python3.7+`` + +## 使用示例 + +下面的例子，通过api获取当前机器人的相关信息： + +``` py +import qqbot + +token = qqbot.Token("{appid}","{token}") +api = qqbot.UserAPI(token, IS_SANDBOX) +user = api.me() + +print(user.username) # 打印机器人名字 +``` + +## ws消息监听 + +通过注册需要监听的事件并设置回调函数后，即可完成对事件的监听。 + +比如下面这个例子：需要监听机器人被@后消息并进行相应的回复。 + +``` py +# 先初始化需要用的 `token` 对象 +t_token = qqbot.Token(test_config["token"]["appid"], test_config["token"]["token"]) +# 通过 `qqbot.HandlerType` 定义需要监听的事件（部分事件可能需要权限申请）可以注册多个 +qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) +# 通过 `qqbot.listen_events` 注册需要监听的事件 +qqbot.listen_events(t_token, False, qqbot_handler) + +# 定义注册事件回调执行函数,如 `_message_handler` +def _message_handler(event, message: Message): + msg_api = qqbot.MessageAPI(t_token, False) + # 打印返回信息 + qqbot.logger.info("event %s" % event + ",receive message %s" % message.content) + # 构造消息发送请求数据对象 + send = qqbot.MessageSendRequest("<@%s>谢谢你，加油" % message.author.id, message.id) + # 通过api发送回复消息 + msg_api.post_message(message.channel_id, send) +``` + +注：当前支持事件及回调事件包括： + +``` py +class HandlerType(Enum): + PLAIN_EVENT_HANDLER = 0 #透传事件 + GUILD_EVENT_HANDLER = 1 #频道事件 + GUILD_MEMBER_EVENT_HANDLER = 2 #频道成员事件 + CHANNEL_EVENT_HANDLER = 3 #子频道事件 + MESSAGE_EVENT_HANDLER = 4 #消息事件 + AT_MESSAGE_EVENT_HANDLER = 5 #At消息事件 + # DIRECT_MESSAGE_EVENT_HANDLER = 6 #私信消息事件 + # AUDIO_EVENT_HANDLER = 7 #音频事件 +``` + +事件回调函数的参数 1 为事件名称，参数 2 返回具体的数据对象。 + +``` py +#透传事件（无具体的数据对象，根据后台返回Json对象） +def _plain_handler(event, data): +#频道事件 +def _guild_handler(event, guild:Guild): +#频道成员事件 +def _guild_member_handler(event, guild_member: GuildMember): +#子频道事件 +def _channel_handler(event, channel: Channel): +#消息事件 #At消息事件 +def _message_handler(event, message: Message): +``` + +## 日志打印 + +基于自带的 logging 模块封装的日志模块，提供了日志写入以及美化了打印格式，并支持通过设置 `QQBOT_LOG_LEVEL` 环境变量来调整日志打印级别（默认打印级别为 `INFO`）。 + +### 使用方法 + +``` py +# 引用模块 +from core.util import logging + +# 获取 `logger` 实例 +logger = logging.getLogger(__name__) + +# 打印日志 +logger.info("hello world!") +``` + +### 设置日志级别 + +通过 `export` 命令添加 `QQBOT_LOG_LEVEL` 环境变量可以设置日志级别。例如： + +``` bash +export QQBOT_LOG_LEVEL=10 # 10表示DEBUG级别 +``` + +几个可选取值（参考了[logging模块的取值](https://docs.python.org/3/library/logging.html#levels)）： + +| Level | 取值 | +| ----- | ------------- | +| CRITICAL | 50 | +| ERROR | 40 | +| WARNING | 30 | +| INFO | 20 | +| DEBUG | 10 | +| NOTSET | 0 | + +### 禁用日志文件输出 + +默认情况下 qqbot 会在当前执行目录下生成格式为 `qqbot.log.*` 的日志文件。如果想禁用这些日志文件，可以通过设置 `QQBOT_DISABLE_LOG` 环境变量为 1 来关闭。 + +``` bash +export QQBOT_DISABLE_LOG=1 # 1表示禁用日志 +``` diff --git a/docs/develop/pythonsdk/guild/get_guild.md b/docs/develop/pythonsdk/guild/get_guild.md new file mode 100644 index 00000000..63870695 --- /dev/null +++ b/docs/develop/pythonsdk/guild/get_guild.md @@ -0,0 +1,49 @@ +# 获取频道详情 + +获取频道详情信息。 + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.guildApi.guild(guildId); +} +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guildId | 是 | string | 频道 ID | + +## 返回说明 + +返回 [Guild](#guild) 对象。 + +### Guild + +| 字段名 | 类型 | 描述 | +| ------------ | ------- | ------------------ | +| id | string | 频道 ID | +| name | string | 频道名称 | +| owner_id | string | 创建人用户 ID | +| owner | boolean | 当前人是否是创建人 | +| member_count | number | 成员数 | +| max_members | number | 最大成员数 | +| description | string | 描述 | + +## 返回示例 + +`data`： + +```python +{ + "id":"guildId", + "name":"频道名称", + "owner_id":"owner_id", + "owner":false, + "member_count":8, + "max_members":300, + "description":"" +} +``` diff --git a/docs/develop/pythonsdk/guild/guild_role/create_guild_role.md b/docs/develop/pythonsdk/guild/guild_role/create_guild_role.md new file mode 100644 index 00000000..73d9ec47 --- /dev/null +++ b/docs/develop/pythonsdk/guild/guild_role/create_guild_role.md @@ -0,0 +1,51 @@ +# 创建频道身份组 + +创建一个频道身份组。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.create_guild_role(guildId, roleInfo) +``` + +::: warning 注意 +需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员。 +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| -------- | ---- | --------------------- | -------------- | +| guildId | 是 | string | 频道 ID | +| roleInfo | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | + +### RoleInfo + +| 字段名 | 必填 | 类型 | 描述 | +| ------ | ---- | ------ | -------------------------------------------------------------- | +| name | 是 | string | 名称 | +| color | 否 | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | 否 | number | 在成员列表中单独展示: 0-否, 1-是 | + +## 返回说明 + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------- | -------------- | +| role_id | string | 频道身份组 ID | +| role | [GuildRole](#guildrole) | 频道身份组对象 | + +### GuildRole + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | diff --git a/docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md b/docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md new file mode 100644 index 00000000..2543748b --- /dev/null +++ b/docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md @@ -0,0 +1,48 @@ +# 创建频道身份组成员 + +创建频道身份组成员。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.create_guild_role_member(guildId, roleId, userId, channel) +``` + +::: warning 注意 + +- 需要使用的 `token` 对应的用户具备增加身份组成员权限，如果是机器人，要求被添加为管理员。 +- 如果要增加的身份组 `ID` 是子频道管理员，需要增加 `Channel` 对象来指定具体是哪个子频道。 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------------------- | ------------------------------------ | +| guildId | 是 | string | 频道 ID | +| roleId | 是 | string | 身份组 ID | +| userId | 是 | string | 用户 ID | +| channel | 是 | [Channel](#channel) | 接收一个只填充了子频道 ID 字段的对象 | + +### Channel + +| 字段名 | 类型 | 描述 | +| ------ | ------ | --------- | +| id | string | 子频道 ID | + +## 返回说明 + +添加是否成功 + +## 返回示例 + +`data`: + +```python +True +``` diff --git a/docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md b/docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md new file mode 100644 index 00000000..c9c9c028 --- /dev/null +++ b/docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md @@ -0,0 +1,31 @@ +# 删除频道身份组 + +删除频道身份组。 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.delete_guild_role(guildId, roleId) +``` + +### 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| ------- | ---- | ------ | --------- | +| guildId | 是 | string | 频道 ID | +| roleId | 是 | string | 身份组 ID | + +### 返回说明 + +是否删除成功 + +### 返回示例 + +`data`： + +```python +True +``` diff --git a/docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md b/docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md new file mode 100644 index 00000000..e5ebbb08 --- /dev/null +++ b/docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md @@ -0,0 +1,47 @@ +# 删除频道身份组成员 + +删除频道身份组成员。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.delete_guild_role_member(guildId, roleId, userId, channel) +``` + +::: warning 注意 + +- 需要使用的 token 对应的用户具备删除身份组成员权限。如果是机器人，要求被添加为管理员。 +- 如果要删除的身份组 ID 是`5-子频道管理员`，需要增加 channel 对象来指定具体是哪个子频道 + ::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------------------- | ------------------------------------ | +| guildId | 是 | string | 频道 ID | +| roleId | 是 | string | 身份组 ID | +| userId | 是 | string | 用户 ID | +| channel | 是 | [Channel](#channel) | 接收一个只填充了子频道 ID 字段的对象 | + +### Channel + +| 字段名 | 类型 | 描述 | +| ------ | ------ | --------- | +| id | string | 子频道 ID | + +## 返回说明 + +返回删除是否成功 + +## 返回示例 + +`data`: + +```python +True +``` diff --git a/docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md b/docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md new file mode 100644 index 00000000..8ac495e8 --- /dev/null +++ b/docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md @@ -0,0 +1,67 @@ +# 获取频道身份组列表 + +获取频道身份组列表。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +guild_roles = api.get_guild_roles(guildId) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guildId | 是 | string | 频道 ID | + +## 返回说明 + +| 字段名 | 类型 | 描述 | +| -------- | ----------------------- | ------------------ | +| guild_id | string | 频道 ID | +| roles | [GuildRole[]](#guildrole) | 频道身份组对象数组 | + +### GuildRole + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | + +## 返回示例 + +`data`： + +```python +{ + "guild_id":"guild_id", + "roles":[ + { + "id":"4", + "name":"名称", + "color":4294927682, + "hoist":1, + "number":1, + "member_limit":1 + }, + { + "id":"2", + "name":"名称", + "color":4280276644, + "hoist":1, + "number":4, + "member_limit":50 + } + ], + "role_num_limit":"30" +} +``` diff --git a/docs/develop/pythonsdk/guild/guild_role/update_guild_role.md b/docs/develop/pythonsdk/guild/guild_role/update_guild_role.md new file mode 100644 index 00000000..8cbcfa7f --- /dev/null +++ b/docs/develop/pythonsdk/guild/guild_role/update_guild_role.md @@ -0,0 +1,70 @@ +# 修改频道身份组 + +修改频道身份组信息。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildRoleAPI(token, False) +result = api.update_guild_role(guildId, roleId, roleInfo) +``` + +::: warning 注意 需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员。 +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| -------- | ---- | --------------------- | -------------- | +| guildId | 是 | string | 频道 ID | +| roleId | 是 | string | 身份组 ID | +| roleInfo | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | + +### RoleInfo + +| 字段名 | 必填 | 类型 | 描述 | +| ------ | ---- | ------ | -------------------------------------------------------------- | +| name | 是 | string | 名称 | +| color | 否 | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | 否 | number | 在成员列表中单独展示: 0-否, 1-是 | + +## 返回说明 + +| 字段名 | 类型 | 描述 | +| -------- | ----------------------- | -------------- | +| guild_id | string | 频道 ID | +| role_id | string | 身份组 ID | +| role | [GuildRole](#guildrole) | 频道身份组对象 | + +### GuildRole + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | + +## 返回示例 + +`data`： + +```python +{ + "guild_id": "guild_id", + "role_id": "role_id", + "role": { + "id": "role_id", + "name": "Test Update Role", + "color": 4278245297, + "hoist": 0, + "number": 0, + "member_limit": 2000} +} +``` \ No newline at end of file diff --git a/docs/develop/pythonsdk/member/delete_member.md b/docs/develop/pythonsdk/member/delete_member.md new file mode 100644 index 00000000..40af09ad --- /dev/null +++ b/docs/develop/pythonsdk/member/delete_member.md @@ -0,0 +1,38 @@ +# 删除频道成员 + +移除频道的某个成员。 + + + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.guildApi.deleteGuildMember(guildId, userId); +} +``` + +::: warning 注意 + +- 需要使用的 token 对应的用户具备踢人权限。如果是机器人，要求被添加为管理员。 +- 操作成功后，会触发频道成员删除事件 + ::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guildId | 是 | string | 频道 ID | +| userId | 是 | string | 用户 ID | + +## 返回说明 + +无 + +## 返回示例 + +`data`: + +```js +''; +``` diff --git a/docs/develop/pythonsdk/member/get_member.md b/docs/develop/pythonsdk/member/get_member.md new file mode 100644 index 00000000..058bb134 --- /dev/null +++ b/docs/develop/pythonsdk/member/get_member.md @@ -0,0 +1,64 @@ +# 获取频道成员详情 + +获取频道下某个成员的信息。 + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.guildApi.guildMember(guildId, userId); +} +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guildId | 是 | string | 频道 ID | +| userId | 是 | string | 用户 ID | + +## 返回说明 + +返回 [Member](model.md) 对象。 + +## Member + +| 字段名 | 类型 | 描述 | +| --------- | ------------- | -------------------------------------------------------------------------------------------- | +| user | [User](#user) | 用户基础信息，来自 QQ 资料，只有成员相关接口中会填充此信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](../guild/role_model.md#DefaultRoleIDs) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| bot | boolean | 是否是机器人 | + +## 返回示例 + +`data`： + +```js +{ + user: { + id: 'USERID', + username: '机器人管家-ostwindli', + avatar: 'http://thirdqq.qlogo.cn/g?b=oidb&k=oPicoPIg01ujpSr8oosudkQ&s=0&t=1637218059', + bot: false, + public_flags: 0, + system: false + }, + nick: '阿青', + roles: [ '4' ], + joined_at: '2021-11-23T15:16:48+08:00', + deaf: false, + mute: false, + pending: false + } +} +``` diff --git a/docs/develop/pythonsdk/member/get_members.md b/docs/develop/pythonsdk/member/get_members.md new file mode 100644 index 00000000..cc392cbb --- /dev/null +++ b/docs/develop/pythonsdk/member/get_members.md @@ -0,0 +1,74 @@ +# 获取频道成员列表 + +获取频道下的成员列表。 + + + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.guildApi.guildMembers(guildId, queryParams); +} +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ----------- | ---- | --------------------------- | -------- | +| guildId | 是 | string | 频道 ID | +| queryParams | 否 | [QueryParams](#queryparams) | 查询参数 | + +### QueryParams + +| 字段名 | 必填 | 类型 | 描述 | +| ------ | ---- | ------ | ---------------------------------------------------------- | +| after | 否 | string | 上一次回包中最大的用户 ID， 如果是第一次请求填 0，默认为 0 | +| limit | 否 | number | 分页大小，1-1000，默认是 1 | + +## 返回说明 + +返回 [Member](#member) 对象。 + +## Member + +| 字段名 | 类型 | 描述 | +| --------- | ------------- | -------------------------------------------------------------------------------------------- | +| user | [User](#user) | 用户基础信息，来自 QQ 资料，只有成员相关接口中会填充此信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](../guild/role_model.md#DefaultRoleIDs) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| bot | boolean | 是否是机器人 | + +## 返回示例 + +`data`： + +```js +[ + { + user: { + id: 'USERID', + username: '机器人管家-ostwindli', + avatar: 'http://thirdqq.qlogo.cn/g?b=oidb&k=oPicoPIg01ujpSr8oosudkQ&s=0&t=1637218059', + bot: false, + public_flags: 0, + system: false, + }, + nick: '阿青', + roles: ['4'], + joined_at: '2021-11-23T15:16:48+08:00', + deaf: false, + mute: false, + pending: false, + }, +]; +``` diff --git a/docs/develop/pythonsdk/message/get_message_of_id.md b/docs/develop/pythonsdk/message/get_message_of_id.md new file mode 100644 index 00000000..a610e643 --- /dev/null +++ b/docs/develop/pythonsdk/message/get_message_of_id.md @@ -0,0 +1,87 @@ +# 获取指定消息 + +获取指定消息。 + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.messageApi.message(channelID, messageID); +} +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ------ | --------- | +| channelID | 是 | string | 子频道 ID | +| messageID | 是 | string | 消息 ID | + +## 返回说明 + +| 参数 | 类型 | 说明 | +| ------- | ------------------- | ----------------- | +| message | [Message](#message) | 返回 message 对象 | + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +`data`: + +```json +{ + "message": { + "id": "abcdef01", + "channel_id": "100001", + "guild_id": "100000000001", + "content": "hello", + "timestamp": "2021-05-25T15:20:34+08:00", + "author": { + "id": "1000000001", + "username": "az", + "bot": false + }, + "member": { + "roles": ["1"], + "joined_at": "2021-04-12T16:34:42+08:00" + } + } +} +``` diff --git a/docs/develop/pythonsdk/message/get_messages.md b/docs/develop/pythonsdk/message/get_messages.md new file mode 100644 index 00000000..11b28c1a --- /dev/null +++ b/docs/develop/pythonsdk/message/get_messages.md @@ -0,0 +1,120 @@ +# 拉取消息列表 + +获取消息列表。 + + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.messageApi.messages(channelID, pager); +} +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ------------------------------- | --------- | +| channelID | 是 | string | 子频道 ID | +| pager | 否 | [MessagesPager](#messagespager) | 分页信息 | + +### MessagesPager + +| 参数 | 必填 | 类型 | 说明 | +| ----- | ---- | ----------------------- | ----------------------------- | +| type | 否 | [TypesEnum](#typesenum) | 拉取类型 | +| id | 否 | string | 消息 ID | +| limit | 否 | string | 每次拉取多少条消息，最大 `20` | + +### TypesEnum + +| 字段名 | 类型 | 描述 | +| -------- | ------ | ------------------ | +| `around` | string | 读此 id 前后的消息 | +| `before` | string | 读此 id 之前的消息 | +| `after` | string | 读此 id 之后的消息 | + +如果 `around/before/after` 均为`空`，则拉取最新的 `limit` 条消息。 + +## 返回说明 + +返回 [Message](#message) 对象数组。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +`data`： + +```json +[ + { + "id": "xxx", + "channel_id": "100001", + "guild_id": "100000000001", + "content": "hello", + "timestamp": "2021-05-25T15:20:34+08:00", + "author": { + "id": "1000000001", + "username": "az", + "bot": false + }, + "member": { + "roles": ["1"], + "joined_at": "2021-04-12T16:34:42+08:00" + } + }, + { + "id": "yyy", + "channel_id": "100001", + "guild_id": "1000000000001", + "content": "world", + "timestamp": "2021-05-25T15:20:32+08:00", + "author": { + "id": "10000001", + "username": "az", + "bot": false + }, + "member": { + "roles": ["1"], + "joined_at": "2021-04-12T16:34:42+08:00" + } + } +] +``` diff --git a/docs/develop/pythonsdk/message/message_format.md b/docs/develop/pythonsdk/message/message_format.md new file mode 100644 index 00000000..81b9201d --- /dev/null +++ b/docs/develop/pythonsdk/message/message_format.md @@ -0,0 +1,127 @@ +# 消息内嵌格式 + +::: warning 注意 + +- 消息不支持 markdown 格式，会自动移除 markdown 格式 +- 内嵌格式仅在 content 中会生效，在 Ark 和 Embed 中不生效 + +::: + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.messageApi.postMessage(channelID, message); +} +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ----------------------------------- | ---------- | +| channelID | 是 | string | 子频道 ID | +| messsage | 是 | [MessageToCreate](#messagetocreate) | 消息体结构 | + +## MessageToCreate + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ----------------------------------------------------------------------- | +| content | string | 消息内容，参考[支持的格式](#支持的格式) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为被动回复消息，否则视为主动推送消息** | + +## MessageEmbed + +| 字段名 | 类型 | 描述 | +| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | +| title | string | 标题 | +| description | string | 描述 | +| prompt | string | 消息弹窗内容 | +| timestamp | string | 消息创建时间 | +| fields | [MessageEmbedField[]](#messageembedfield) | 消息创建时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## MessageEmbedField + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ------ | +| name | string | 字段名 | +| value | string | 字段值 | + +### 支持的格式 + +| 类型 | 结构 | 描述 | 示例 | +| :------ | :------------ | :------------------------------------------------------------------ | :--------------- | +| @用户 | <@user_id> | 解析为 @用户 标签 | <@1234000000001> | +| #子频道 | <#channel_id> | 解析为 #子频道 标签，点击可以跳转至子频道，仅支持当前频道内的子频道 | <#12345> | + +## 返回说明 + +返回[Message](#message) 对象。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +以发送文本内容`<@!1234>hello world`为例，下面是返回示例： + +`data`: + +```json +{ + "id": "xxxxxx", + "channel_id": "xxxxxx", + "guild_id": "xxxxxx", + "content": "<@!1234>hello world", + "timestamp": "2021-05-13T14:45:45+08:00", + "tts": false, + "mention_everyone": false, + "author": { + "id": "xxxxxx", + "username": "abc", + "avatar": "", + "bot": true + }, + "embeds": [{}], + "pinned": false, + "type": 0, + "flags": 0 +} +``` diff --git a/docs/develop/pythonsdk/message/message_template.md b/docs/develop/pythonsdk/message/message_template.md new file mode 100644 index 00000000..537187b3 --- /dev/null +++ b/docs/develop/pythonsdk/message/message_template.md @@ -0,0 +1,376 @@ +# 消息模板 + +为了丰富消息内容，SDK 提供了几种消息模板。 + +::: warning 注意 + +- 发送消息时所有字段均使用`字符串类型`。 +- 如果发送的消息中包含链接（网页、图片、视频链接等），**需要提前在[机器人管理端](https://bot.q.qq.com/#/developer/developer-setting)报备**，操作流程：操作路径为：”开发设置“ -> ”消息 URL 配置“。 + +::: + +## 可用模板 + +- [链接+文本列表模板](#链接、文本列表模板) +- [文本+缩略图模板](#文本、缩略图模板) +- [大图模板](#大图模板34) + +## 链接、文本列表模板 + +### 样式(id=23) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.channel.robot", + "view": "albumAddPic", + "ver": "0.0.0.1", + "desc": "#DESC#", + "prompt": "[QQ小程序]#PROMPT#", + "meta": { + "detail": { + "list": "#LIST#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :------- | :----- | :--------- | +| #DESC# | string | 描述 | +| #PROMPT# | string | 提示消息 | +| #LIST# | array | #LIST#数组 | + +### LIST 结构 + +| 字段名 | 类型 | 描述 | +| :----- | :----- | :------------------------------------------------------------- | +| desc | string | 文本内容 | +| link | string | 链接，需要提前报备，如果不填就显示为文本，如果填了就显示为链接 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 23, + "kv": [ + { + "key": "#DESC#", + "value": "descaaaaaa" + }, + { + "key": "#PROMPT#", + "value": "promptaaaa" + }, + { + "key": "#LIST#", + "obj": [ + { + "obj_kv": [ + { + "key": "desc", + "value": "需求标题：UI问题解决" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "当前状态\"体验中\"点击下列动作直接扭转状态到：" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "已评审" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "已排期" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "开发中" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "增量测试中" + }, + { + "key": "link", + "value": "https://qun.qq.com" + } + ] + }, + { + "obj_kv": [ + { + "key": "desc", + "value": "请关注" + } + ] + } + ] + } + ] + } +} +``` + +## 文本、缩略图模板 + +### 样式(id=24) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.channelrobot.smallpic", + "view": "albumAddPic", + "ver": "0.0.0.1", + "desc": "#DESC#", + "prompt": "[QQ小程序]#PROMPT#", + "meta": { + "detail": { + "title": "#TITLE#", + "desc": "#METADESC#", + "img": "#IMG#", + "link": "#LINK#", + "subTitle": "#SUBTITLE#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :--------- | :----- | :------- | +| #DESC# | string | 描述 | +| #PROMPT# | string | 提示文本 | +| #TITLE# | string | 标题 | +| #METADESC# | string | 详情描述 | +| #IMG# | string | 图片链接 | +| #LINK# | string | 跳转链接 | +| #SUBTITLE# | string | 来源 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 24, + "kv": [ + { + "key": "#DESC#", + "value": "描述描述描放假大方了大家反垄断撒娇两款发动机临时卡封疆大吏撒酒疯；里导数据阿弗莱克的撒娇；廊坊述" + }, + { + "key": "#PROMPT#", + "value": "通知信息xxxxx" + }, + { + "key": "#TITLE#", + "value": "标题fjd;lsajfldjsalkfjdkw封疆大吏撒娇锋利的撒娇；付了定金撒标题标题标题标题fjkdlajfldjal;fd放大了发动机上来空" + }, + { + "key": "#METADESC#", + "value": "Meta描述描述描述风好大换热器继往开来积分考虑到；安静了；了；防静电；来撒会今日而我却哦iopqwfjldsa" + }, + { + "key": "#IMG#", + "value": "https://pub.idqqimg.com/pc/misc/files/20190820/2f4e70ae3355ece23d161cf5334d4fc1jzjfmtep.png" + }, + { + "key": "#LINK#", + "value": "https://qq.com" + }, + { + "key": "#SUBTITLE#", + "value": "子标题" + } + ] + } +} +``` + +## 大图模板 34 + +### 样式(id=34) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.miniapp_01", + "view": "view_8C8E89B49BE609866298ADDFF2DBABA4", + "ver": "1.0.1.12", + "desc": "#DESC#", + "prompt": "#PROMPT#", + "meta": { + "detail_1": { + "title": "#METATITLE#", + "desc": "#METADESC#", + "icon": "#METAICON#", + "preview": "#METAPREVIEW#", + "url": "#METAURL#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :------------ | :----- | :------- | +| #DESC# | string | 描述 | +| #PROMPT# | string | 提示消息 | +| #METATITLE# | string | 标题 | +| #METADESC# | string | 描述 | +| #METAICON# | string | 小图标 | +| #METAPREVIEW# | string | 大图 | +| #METAURL# | string | 跳转链接 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 34, + "kv": [ + { + "key": "#DESC#", + "value": "descaaaaaa" + }, + { + "key": "#PROMPT#", + "value": "promptaaaa" + }, + { + "key": "#METATITLE#", + "value": "metatitle" + }, + { + "key": "#METADESC#", + "value": "metadesc" + }, + { + "key": "#METAICON#", + "value": "https://tangram-1251316161.file.myqcloud.com/files/20211014/bfd7d02235e52d60b05a630ac9ef8bcc.png" + }, + { + "key": "#METAPREVIEW#", + "value": "https://tangram-1251316161.file.myqcloud.com/files/20211014/bfd7d02235e52d60b05a630ac9ef8bcc.png" + }, + { + "key": "#METAURL#", + "value": "https://qq.com" + } + ] + } +} +``` + +## 大图模板 37 + +### 样式(id=37) + +接入流程 + +### 模板格式 + +```json +{ + "app": "com.tencent.imagetextbot", + "view": "index", + "ver": "1.0.0.11", + "prompt": "#PROMPT#", + "meta": { + "robot": { + "title": "#METATITLE#", + "subtitle": "#METASUBTITLE#", + "cover": "#METACOVER#", + "jump_url": "#METAURL#" + } + } +} +``` + +### 字段描述 + +| 字段名 | 类型 | 描述 | +| :------------- | :----- | :-------------------- | +| #PROMPT# | string | 提示消息 | +| #METATITLE# | string | 标题 | +| #METASUBTITLE# | string | 子标题 | +| #METACOVER# | string | 大图，尺寸为 975\*540 | +| #METAURL# | string | 跳转链接 | + +#### 请求示例 + +```json +{ + "ark": { + "template_id": 37, + "kv": [ + { + "key": "#PROMPT#", + "value": "通知提醒" + }, + { + "key": "#METATITLE#", + "value": "标题" + }, + { + "key": "#METASUBTITLE#", + "value": "子标题" + }, + { + "key": "#METACOVER#", + "value": "https://vfiles.gtimg.cn/vupload/20211029/bf0ed01635493790634.jpg" + }, + { + "key": "#METAURL#", + "value": "https://qq.com" + } + ] + } +} +``` diff --git a/docs/develop/pythonsdk/message/post_ark_messages.md b/docs/develop/pythonsdk/message/post_ark_messages.md new file mode 100644 index 00000000..06b0db4a --- /dev/null +++ b/docs/develop/pythonsdk/message/post_ark_messages.md @@ -0,0 +1,223 @@ +# 发送模板消息 + +::: warning 注意 + +- 要求操作人在该子频道具有`发送消息`和 `模板消息` 的权限。 +- 调用前需要先申请消息模板，这一步会得到一个模板 id，在请求时填在 ark.template_id 上 +- 发送成功之后，会触发一个创建消息的事件。 +- 可用模板参考[可用模板](message_template.md) +- 如果发送的消息中包含链接（网页、图片、视频链接等），**需要提前在[机器人管理端](https://bot.q.qq.com/#/developer/developer-setting)报备**，操作流程：操作路径为：”开发设置“ -> ”消息 URL 配置“ + +::: + +## 使用示例 + +需要关注`ark`字段的使用。 + +```javascript +async function demo() { + let { data } = await client.messageApi.postMessage(channelID, message); +} +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ----------------------------------- | ---------- | +| channelID | 是 | string | 子频道 ID | +| messsage | 是 | [MessageToCreate](#messagetocreate) | 消息体结构 | + +## MessageToCreate + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ----------------------------------------------------------------------- | +| content | string | 消息内容，文本内容，支持[内嵌格式](message_format.md) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为被动回复消息，否则视为主动推送消息** | + +## MessageEmbed + +| 字段名 | 类型 | 描述 | +| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | +| title | string | 标题 | +| description | string | 描述 | +| prompt | string | 消息弹窗内容 | +| timestamp | string | 消息创建时间 | +| fields | [MessageEmbedField[]](#messageembedfield) | 消息创建时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +## MessageEmbedField + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ------ | +| name | string | 字段名 | +| value | string | 字段值 | + +### 参数示例 + +假设模板如下，其中`#META_LIST#`类型为数组、`#META_URL#`类型为 `URL`、其他为文本。 + +```json +{ + "app": "com.tencent.miniapp", + "view": "detail", + "ver": "0.0.0.1", + "desc": "#DESC#", + "prompt": "[QQ小程序]#PROMPT#", + "meta": { + "detail": { + "title": "#TITLE#", + "desc": "#META_DESC#", + "url": "#META_URL#", + "list": "#META_LIST#" + } + } +} +``` + +请求体中的 ark 内容为 + +```json +{ + "ark": { + "template_id": 1, + "kv": [ + { + "key": "#DESC#", + "value": "机器人订阅消息" + }, + { + "key": "#PROMPT#", + "value": "XX机器人" + }, + { + "key": "#TITLE#", + "value": "XX机器人消息" + }, + { + "key": "#META_URL#", + "value": "http://domain.com/" + }, + { + "key": "#META_LIST#", + "obj": [ + { + "obj_kv": [ + { + "key": "name", + "value": "aaa" + }, + { + "key": "age", + "value": "3" + } + ] + }, + { + "obj_kv": [ + { + "key": "name", + "value": "bbb" + }, + { + "key": "age", + "value": "4" + } + ] + } + ] + } + ] + } +} +``` + +则实际下发的 json 为 + +```json +{ + "app": "com.tencent.miniapp", + "view": "detail", + "ver": "0.0.0.1", + "desc": "机器人订阅消息", + "prompt": "[QQ小程序]XX机器人", + "meta": { + "detail": { + "title": "XX机器人消息", + "url": "http://domain.com/", + "list": [ + { "name": "aaa", "age": "3" }, + { "name": "bbb", "age": "4" } + ] + } + } +} +``` + +## 返回说明 + +返回[Message](#message) 对象。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 id | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| edited_timestamp | string | 消息编辑时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| mention_everyone | boolean | 是否是@全员消息 | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +```json +{ + "id": "101234567890abcdef", + "channel_id": "10001", + "guild_id": "6400000001", + "content": "<@!1234>hello world", + "timestamp": "2021-05-13T14:45:45+08:00", + "tts": false, + "mention_everyone": false, + "author": { + "id": "12345", + "username": "abc", + "avatar": "", + "bot": true + }, + "pinned": false, + "type": 0, + "flags": 0 +} +``` diff --git a/docs/develop/pythonsdk/message/post_messages.md b/docs/develop/pythonsdk/message/post_messages.md new file mode 100644 index 00000000..d6298fc0 --- /dev/null +++ b/docs/develop/pythonsdk/message/post_messages.md @@ -0,0 +1,135 @@ +# 发送消息 + +向指定子频道推送消息。 + +::: warning 注意 + +- 要求操作人在该子频道具有`发送消息`的权限。 +- 发送成功之后，会触发一个创建消息的事件。 +- 被动回复消息有效期为 `5` 分钟。 +- 主动推送消息每日每个子频道限 `2` 条。 +- **发送消息接口要求机器人接口需要链接到 `websocket gateway` 上保持在线状态** + +::: + +## 使用示例 + +```javascript +async function demo() { + let { data } = await client.messageApi.postMessage(channelID, message); +} +``` + +## 参数说明 + +| 参数 | 必填 | 类型 | 说明 | +| --------- | ---- | ----------------------------------- | ---------- | +| channelID | 是 | string | 子频道 ID | +| messsage | 是 | [MessageToCreate](#messagetocreate) | 消息体结构 | + +## MessageToCreate + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ---------------------------------------------------------------------------------------- | +| content | string | 消息内容，文本内容，支持[内嵌格式](message_format.md) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为[被动回复消息](#被动回复消息)，否则视为主动推送消息** | + +`content`、`embed`、`ark`、`image`**至少需要有一个字段**，否则无法下发消息。 + +### 被动回复消息 + +::: warning 注意 + +被动消息需是用户`@机器人`的消息，否则将会报错。 + +::: + +## MessageEmbed + +详见[消息内嵌格式](./message_format.md)。 + +## MessageArk + +详见[发送模板消息](./post_ark_messages.md)。 + +## 返回说明 + +主动消息都需要审核，返回结果如下： + +```json +{ + "code": 304023, + "message": "push message is waiting for audit now" +} +``` + +若为私域机器人可正常返回[Message](#message) 对象。 + +### Message + +| 字段名 | 类型 | 描述 | +| ---------- | ----------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 ID | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| author | [User](#user) | 消息创建者 | +| member | [Member](#member) | 消息创建者的 member 信息 | + +### User + +| 字段名 | 类型 | 描述 | +| -------- | ------- | ------------ | +| id | string | 用户 ID | +| username | string | 用户名 | +| bot | boolean | 是否是机器人 | + +### Member + +| 字段名 | 类型 | 描述 | +| --------- | -------- | ------------------------------------------------------------------------------------ | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](#defaultroleids) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### DefaultRoleIDs + +系统默认生成下列身份组 ID。 + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | + +## 返回示例 + +以发送文本内容`hello world`为例，下面是返回示例： + +`data`: + +```json +{ + "id": "101234567890abcdef", + "channel_id": "10001", + "guild_id": "6400000001", + "content": "hello world", + "timestamp": "2021-05-13T14:45:45+08:00", + "tts": false, + "mention_everyone": false, + "author": { + "id": "12345", + "username": "abc", + "avatar": "", + "bot": true + }, + "embeds": [{}], + "pinned": false, + "type": 0, + "flags": 0 +} +``` From c933aab28661f24694ed8c1dd7d7fcdcd44348e9 Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 15:19:13 +0800 Subject: [PATCH 02/11] =?UTF-8?q?[feat]=E5=A2=9E=E5=8A=A0python-sdk?= =?UTF-8?q?=E7=9A=84=E5=AE=8C=E6=95=B4=E7=9A=84=E6=8E=A5=E5=8F=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../pythonsdk/api/channel/create_channel.md | 98 ++++++++++++++ .../pythonsdk/api/channel/delete_channel.md | 71 +++++++++++ .../pythonsdk/api/channel/get_channels.md | 90 +++++++++++++ .../pythonsdk/api/channel/update_channel.md | 110 ++++++++++++++++ .../get_channel_permissions.md | 63 +++++++++ .../update_channel_permissions.md | 67 ++++++++++ .../pythonsdk/{ => api}/guild/get_guild.md | 13 +- .../guild/guild_role/create_guild_role.md | 6 +- .../guild_role/create_guild_role_member.md | 8 +- .../guild/guild_role/delete_guild_role.md | 6 +- .../guild_role/delete_guild_role_member.md | 8 +- .../guild/guild_role/get_guild_roles.md | 4 +- .../guild/guild_role/update_guild_role.md | 8 +- .../member/delete_guild_member.md} | 10 +- .../member/get_guild_member.md} | 45 ++++--- .../member/get_guild_members.md} | 14 +- .../message/get_message.md} | 15 ++- .../{ => api}/message/get_messages.md | 22 +++- .../{ => api}/message/message_format.md | 19 ++- .../{ => api}/message/message_template.md | 0 .../{ => api}/message/post_ark_messages.md | 15 ++- .../message/post_message.md} | 19 +-- docs/develop/pythonsdk/config.js | 120 ++++++++++++++++++ docs/develop/pythonsdk/model/audio.md | 27 ++++ docs/develop/pythonsdk/model/channel.md | 42 ++++++ .../pythonsdk/model/channel_permission.md | 27 ++++ docs/develop/pythonsdk/model/dms.md | 9 ++ docs/develop/pythonsdk/model/guild.md | 17 +++ docs/develop/pythonsdk/model/member.md | 20 +++ docs/develop/pythonsdk/model/message.md | 80 ++++++++++++ docs/develop/pythonsdk/model/role.md | 21 +++ docs/develop/pythonsdk/model/user.md | 14 ++ 32 files changed, 996 insertions(+), 92 deletions(-) create mode 100644 docs/develop/pythonsdk/api/channel/create_channel.md create mode 100644 docs/develop/pythonsdk/api/channel/delete_channel.md create mode 100644 docs/develop/pythonsdk/api/channel/get_channels.md create mode 100644 docs/develop/pythonsdk/api/channel/update_channel.md create mode 100644 docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md create mode 100644 docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md rename docs/develop/pythonsdk/{ => api}/guild/get_guild.md (84%) rename docs/develop/pythonsdk/{ => api}/guild/guild_role/create_guild_role.md (91%) rename docs/develop/pythonsdk/{ => api}/guild/guild_role/create_guild_role_member.md (75%) rename docs/develop/pythonsdk/{ => api}/guild/guild_role/delete_guild_role.md (71%) rename docs/develop/pythonsdk/{ => api}/guild/guild_role/delete_guild_role_member.md (75%) rename docs/develop/pythonsdk/{ => api}/guild/guild_role/get_guild_roles.md (95%) rename docs/develop/pythonsdk/{ => api}/guild/guild_role/update_guild_role.md (90%) rename docs/develop/pythonsdk/{member/delete_member.md => api/member/delete_guild_member.md} (69%) rename docs/develop/pythonsdk/{member/get_member.md => api/member/get_guild_member.md} (70%) rename docs/develop/pythonsdk/{member/get_members.md => api/member/get_guild_members.md} (88%) rename docs/develop/pythonsdk/{message/get_message_of_id.md => api/message/get_message.md} (92%) rename docs/develop/pythonsdk/{ => api}/message/get_messages.md (92%) rename docs/develop/pythonsdk/{ => api}/message/message_format.md (94%) rename docs/develop/pythonsdk/{ => api}/message/message_template.md (100%) rename docs/develop/pythonsdk/{ => api}/message/post_ark_messages.md (96%) rename docs/develop/pythonsdk/{message/post_messages.md => api/message/post_message.md} (92%) create mode 100644 docs/develop/pythonsdk/config.js create mode 100644 docs/develop/pythonsdk/model/audio.md create mode 100644 docs/develop/pythonsdk/model/channel.md create mode 100644 docs/develop/pythonsdk/model/channel_permission.md create mode 100644 docs/develop/pythonsdk/model/dms.md create mode 100644 docs/develop/pythonsdk/model/guild.md create mode 100644 docs/develop/pythonsdk/model/member.md create mode 100644 docs/develop/pythonsdk/model/message.md create mode 100644 docs/develop/pythonsdk/model/role.md create mode 100644 docs/develop/pythonsdk/model/user.md diff --git a/docs/develop/pythonsdk/api/channel/create_channel.md b/docs/develop/pythonsdk/api/channel/create_channel.md new file mode 100644 index 00000000..10a2641f --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/create_channel.md @@ -0,0 +1,98 @@ +# 创建子频道 + +创建一个子频道。 + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.create_channel(channel_id, channel) +``` + +::: warning 注意 + +- 要求操作人具有管理频道的权限，如果是机器人，则需要将机器人设置为管理员。 +- 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。 +- 目前不支持创建的子频道类型 + - 子频道分组 + - 私密子频道 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------------------- | ---------- | +| guildId | 是 | string | 频道 ID | +| channel | 是 | [Channel](#channel) | 子频道对象 | + +### Channel + +| 字段名 | 类型 | 必填 | 描述 | +| --------- | ------ | ---- | ---------------------------------------------- | +| name | string | 是 | 子频道名 | +| type | number | 是 | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 是 | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 否 | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 否 | 分组 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回说明 + +返回 [ChannelRes](#channelres) 对象。 + +### ChannelRes + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| owner_id | string | 创建者 ID | + +## 返回示例 + +`data`： + +```python +{ + "id": "channel_id", + "guild_id": "guild_id", + "name": "channel_test", + "type": 1, + "position": 1640240055, + "owner_id": "2854198244", + "sub_type": 0 +} +``` diff --git a/docs/develop/pythonsdk/api/channel/delete_channel.md b/docs/develop/pythonsdk/api/channel/delete_channel.md new file mode 100644 index 00000000..9c90eb30 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/delete_channel.md @@ -0,0 +1,71 @@ +# 删除子频道 + +移除一个子频道。 + + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.delete_channel(channel_id) +``` + +::: warning 注意 + +- 要求操作人具有`管理频道`的权限，如果是机器人，则需要将机器人设置为管理员。 +- 创建成功后，返回创建成功的子频道对象，同时会触发一个频道创建的事件通知。 +- 子频道的删除是无法撤回的，一旦删除，将无法恢复。 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| --------- | ---- | ------ | --------- | +| channel_id | 是 | string | 子频道 ID | + +## 返回说明 + +字段参见 [ChannelRes](#channelres) + +### ChannelRes + +| 字段名 | 类型 | 描述 | +| -------- | ------ | -------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +## 返回示例 + +`data`： + +```python +{ + "id":"channel_id", + "type":0, + "name":"update_channel", + "guild_id":"2020131797974366736" +} +``` diff --git a/docs/develop/pythonsdk/api/channel/get_channels.md b/docs/develop/pythonsdk/api/channel/get_channels.md new file mode 100644 index 00000000..fffed2e9 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/get_channels.md @@ -0,0 +1,90 @@ +# 获取子频道列表 + +``get_channels`` 获取子频道列表 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.get_channels(guild_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------- | ---- | ------ | ------- | +| guild_id | 是 | string | 频道 ID | + +## 返回说明 + +返回 [Channel](#channel) 数组。 + +### Channel + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | +| owner_id | string | 创建人 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回示例 + +`data`： + +```python +[ + { + "id":"channel_id", + "guild_id":"guild_id", + "name":"子频道名", + "type":4, + "position":2, + "parent_id":"0", + "owner_id":"0", + "sub_type":0 + }, + { + "id":"channel_id", + "guild_id":"guild_id", + "name":"子频道名", + "type":4, + "position":3, + "parent_id":"0", + "owner_id":"0", + "sub_type":0 + } +] +``` diff --git a/docs/develop/pythonsdk/api/channel/update_channel.md b/docs/develop/pythonsdk/api/channel/update_channel.md new file mode 100644 index 00000000..c2731fab --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/update_channel.md @@ -0,0 +1,110 @@ +# 修改子频道 + +修改某个子频道的信息。 + + + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.update_channel(channel_id, channel) +``` + +::: warning 注意 + +- 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。 +- 修改成功后，会触发子频道更新事件 + +::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| --------- | ---- | ------------------- | ---------- | +| channelId | 是 | string | 子频道 ID | +| channel | 是 | [Channel](#channel) | 子频道对象 | + +### Channel + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ------------------------------------------ | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +## 返回说明 + +字段参见 [ChannelRes](#channelres)。 + +### ChannelRes + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | +| owner_id | string | 创建人 ID | + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回示例 + +`data`： + +```python +{ + "id":"2186875", + "guild_id":"2020131797974366736", + "name":"update_channel", + "topic":null, + "type":0, + "last_message_id":null, + "last_pin_timestamp":null, + "nsfw":null, + "icon":null, + "position":22, + "bitrate":null, + "recipients":[ + + ], + "user_limit":null, + "parent_id":"1128421", + "rate_limit_per_user":null, + "owner_id":null, + "application_id":null, + "op_user_id":null, + "sub_type":0 +} +``` diff --git a/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md b/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md new file mode 100644 index 00000000..1da58573 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md @@ -0,0 +1,63 @@ +# 获取子频道权限 + +获取指定子频道的权限。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelPermissionsAPI(token, False) +channel = api.get_channel_permissions(channel_id, user_id) +``` + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| --------- | ---- | ------ | --------- | +| channel_id | 是 | string | 子频道 ID | +| user_id | 是 | string | 用户 ID | + +## 返回说明 + +返回 [ChannelPermissions](#channelpermissions) 对象。 + +### ChannelPermissions + +| 字段名 | 类型 | 描述 | +| ----------- | --------------------------- | --------------------------------- | +| channel_id | string | 子频道 ID | +| user_id | string | 用户 ID | +| permissions | [permissions](#permissions) | 用户拥有的子频道权限，是个 string | + +### Permissions + +权限是 QQ 频道管理频道成员的一种方式，管理员可以对不同的人、不同的子频道设置特定的权限。用户的权限包括**个人权限**和**身份组权限**两部分，最终生效是取两种权限的并集。 + +权限使用位图表示，传递时序列化为十进制数值字符串。如权限值为`0x6FFF`，会被序列化为十进制`"28671"`。 + +| 权限 | 值 | 描述 | +| ------------ | --------------------- | ---------------------------------------------------- | +| 可查看子频道 | 0x0000000001 (1 << 0) | 目前仅支持`指定成员`可见类型，不支持`身份组`可见类型 | +| 可管理子频道 | 0x0000000002 (1 << 1) | 创建者、管理员、子频道管理员都具有此权限 | + +##### 参数参考 + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ---------------------------------- | +| add | string | 字符串形式的位图表示赋予用户的权限 | +| remove | string | 字符串形式的位图表示删除用户的权限 | + +## 返回示例 + +`data`： + +```python +{ + "channel_id": "1128412", + "user_id": "9962144428931019739", + "permissions": "6" +} +``` diff --git a/docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md b/docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md new file mode 100644 index 00000000..7e07917e --- /dev/null +++ b/docs/develop/pythonsdk/api/channel_permissions/update_channel_permissions.md @@ -0,0 +1,67 @@ +# 修改子频道权限 + +修改子频道权限。 + +## 使用示例 + +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelPermissionsAPI(token, False) +channel = api.update_channel_permissions(channel_id, user_id, channel_permissions) +``` + +::: warning 注意 + +- 要求操作人具有管理子频道的权限，如果是机器人，则需要将机器人设置为管理员。 +- 参数包括 add 和 remove 两个字段，分别表示授予的权限以及删除的权限。要授予用户权限即把 add 对应位置 1，删除用户权限即把 remove 对应位置 1。当两个字段同一位都为 1，表现为删除权限。 +- 本接口不支持修改可管理子频道权限。 + ::: + +## 参数说明 + +| 字段名 | 必填 | 类型 | 描述 | +| ------------------ | ---- | ----------------------------------------- | --------- | +| channel_id | 是 | string | 子频道 ID | +| user_id | 是 | string | 用户 ID | +| channel_permissions | 是 | [ChannelPermissions](#channelpermissions) | 权限参数 | + +### ChannelPermissions + +| 字段名 | 类型 | 描述 | +| ----------- | --------------------------- | --------------------------------- | +| channel_id | string | 子频道 ID | +| user_id | string | 用户 ID | +| permissions | [permissions](#permissions) | 用户拥有的子频道权限，是个 string | + +### Permissions + +权限是 QQ 频道管理频道成员的一种方式，管理员可以对不同的人、不同的子频道设置特定的权限。用户的权限包括**个人权限**和**身份组权限**两部分，最终生效是取两种权限的并集。 + +权限使用位图表示，传递时序列化为十进制数值字符串。如权限值为`0x6FFF`，会被序列化为十进制`"28671"`。 + +| 权限 | 值 | 描述 | +| ------------ | --------------------- | ---------------------------------------------------- | +| 可查看子频道 | 0x0000000001 (1 << 0) | 目前仅支持`指定成员`可见类型，不支持`身份组`可见类型 | +| 可管理子频道 | 0x0000000002 (1 << 1) | 创建者、管理员、子频道管理员都具有此权限 | + +##### 参数参考 + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ---------------------------------- | +| add | string | 字符串形式的位图表示赋予用户的权限 | +| remove | string | 字符串形式的位图表示删除用户的权限 | + +## 返回说明 + +返回是否更新成功 + +## 返回示例 + +`data`： + +```Python +True +``` diff --git a/docs/develop/pythonsdk/guild/get_guild.md b/docs/develop/pythonsdk/api/guild/get_guild.md similarity index 84% rename from docs/develop/pythonsdk/guild/get_guild.md rename to docs/develop/pythonsdk/api/guild/get_guild.md index 63870695..cf0bcec2 100644 --- a/docs/develop/pythonsdk/guild/get_guild.md +++ b/docs/develop/pythonsdk/api/guild/get_guild.md @@ -4,17 +4,20 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.guildApi.guild(guildId); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.GuildAPI(token, False) +guild = api.get_guild(guild_id) ``` ## 参数说明 | 字段名 | 必填 | 类型 | 描述 | | ------- | ---- | ------ | ------- | -| guildId | 是 | string | 频道 ID | +| guild_id | 是 | string | 频道 ID | ## 返回说明 diff --git a/docs/develop/pythonsdk/guild/guild_role/create_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role.md similarity index 91% rename from docs/develop/pythonsdk/guild/guild_role/create_guild_role.md rename to docs/develop/pythonsdk/api/guild/guild_role/create_guild_role.md index 73d9ec47..00b01790 100644 --- a/docs/develop/pythonsdk/guild/guild_role/create_guild_role.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role.md @@ -10,7 +10,7 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.GuildRoleAPI(token, False) -result = api.create_guild_role(guildId, roleInfo) +result = api.create_guild_role(guild_id,role_info) ``` ::: warning 注意 @@ -21,8 +21,8 @@ result = api.create_guild_role(guildId, roleInfo) | 字段名 | 必填 | 类型 | 描述 | | -------- | ---- | --------------------- | -------------- | -| guildId | 是 | string | 频道 ID | -| roleInfo | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | +| guild_id | 是 | string | 频道 ID | +| role_info | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | ### RoleInfo diff --git a/docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role_member.md similarity index 75% rename from docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md rename to docs/develop/pythonsdk/api/guild/guild_role/create_guild_role_member.md index 2543748b..d461c9cd 100644 --- a/docs/develop/pythonsdk/guild/guild_role/create_guild_role_member.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/create_guild_role_member.md @@ -10,7 +10,7 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.GuildRoleAPI(token, False) -result = api.create_guild_role_member(guildId, roleId, userId, channel) +result = api.create_guild_role_member(guild_id, role_id, user_id, channel) ``` ::: warning 注意 @@ -24,9 +24,9 @@ result = api.create_guild_role_member(guildId, roleId, userId, channel) | 字段名 | 必填 | 类型 | 描述 | | ------- | ---- | ------------------- | ------------------------------------ | -| guildId | 是 | string | 频道 ID | -| roleId | 是 | string | 身份组 ID | -| userId | 是 | string | 用户 ID | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | +| user_id | 是 | string | 用户 ID | | channel | 是 | [Channel](#channel) | 接收一个只填充了子频道 ID 字段的对象 | ### Channel diff --git a/docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role.md similarity index 71% rename from docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md rename to docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role.md index c9c9c028..2082e96f 100644 --- a/docs/develop/pythonsdk/guild/guild_role/delete_guild_role.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role.md @@ -8,15 +8,15 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.GuildRoleAPI(token, False) -result = api.delete_guild_role(guildId, roleId) +result = api.delete_guild_role(guild_id, role_id) ``` ### 参数说明 | 参数 | 必填 | 类型 | 说明 | | ------- | ---- | ------ | --------- | -| guildId | 是 | string | 频道 ID | -| roleId | 是 | string | 身份组 ID | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | ### 返回说明 diff --git a/docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role_member.md similarity index 75% rename from docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md rename to docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role_member.md index e5ebbb08..f37689ab 100644 --- a/docs/develop/pythonsdk/guild/guild_role/delete_guild_role_member.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/delete_guild_role_member.md @@ -10,7 +10,7 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.GuildRoleAPI(token, False) -result = api.delete_guild_role_member(guildId, roleId, userId, channel) +result = api.delete_guild_role_member(guild_id, role_id, user_id, channel) ``` ::: warning 注意 @@ -23,9 +23,9 @@ result = api.delete_guild_role_member(guildId, roleId, userId, channel) | 字段名 | 必填 | 类型 | 描述 | | ------- | ---- | ------------------- | ------------------------------------ | -| guildId | 是 | string | 频道 ID | -| roleId | 是 | string | 身份组 ID | -| userId | 是 | string | 用户 ID | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | +| user_id | 是 | string | 用户 ID | | channel | 是 | [Channel](#channel) | 接收一个只填充了子频道 ID 字段的对象 | ### Channel diff --git a/docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md b/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md similarity index 95% rename from docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md rename to docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md index 8ac495e8..ecccb253 100644 --- a/docs/develop/pythonsdk/guild/guild_role/get_guild_roles.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md @@ -10,14 +10,14 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.GuildRoleAPI(token, False) -guild_roles = api.get_guild_roles(guildId) +guild_roles = api.get_guild_roles(guild_id) ``` ## 参数说明 | 字段名 | 必填 | 类型 | 描述 | | ------- | ---- | ------ | ------- | -| guildId | 是 | string | 频道 ID | +| guild_id | 是 | string | 频道 ID | ## 返回说明 diff --git a/docs/develop/pythonsdk/guild/guild_role/update_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md similarity index 90% rename from docs/develop/pythonsdk/guild/guild_role/update_guild_role.md rename to docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md index 8cbcfa7f..84ce75ad 100644 --- a/docs/develop/pythonsdk/guild/guild_role/update_guild_role.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md @@ -10,7 +10,7 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.GuildRoleAPI(token, False) -result = api.update_guild_role(guildId, roleId, roleInfo) +result = api.update_guild_role(guild_id, role_id, role_info) ``` ::: warning 注意 需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员。 @@ -20,9 +20,9 @@ result = api.update_guild_role(guildId, roleId, roleInfo) | 字段名 | 必填 | 类型 | 描述 | | -------- | ---- | --------------------- | -------------- | -| guildId | 是 | string | 频道 ID | -| roleId | 是 | string | 身份组 ID | -| roleInfo | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | +| guild_id | 是 | string | 频道 ID | +| role_id | 是 | string | 身份组 ID | +| role_info | 是 | [RoleInfo](#roleinfo) | 频道身份组参数 | ### RoleInfo diff --git a/docs/develop/pythonsdk/member/delete_member.md b/docs/develop/pythonsdk/api/member/delete_guild_member.md similarity index 69% rename from docs/develop/pythonsdk/member/delete_member.md rename to docs/develop/pythonsdk/api/member/delete_guild_member.md index 40af09ad..1486fde5 100644 --- a/docs/develop/pythonsdk/member/delete_member.md +++ b/docs/develop/pythonsdk/api/member/delete_guild_member.md @@ -6,10 +6,8 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.guildApi.deleteGuildMember(guildId, userId); -} +```python +# TODO:施工中 ``` ::: warning 注意 @@ -22,8 +20,8 @@ async function demo() { | 字段名 | 必填 | 类型 | 描述 | | ------- | ---- | ------ | ------- | -| guildId | 是 | string | 频道 ID | -| userId | 是 | string | 用户 ID | +| guild_id | 是 | string | 频道 ID | +| user_id | 是 | string | 用户 ID | ## 返回说明 diff --git a/docs/develop/pythonsdk/member/get_member.md b/docs/develop/pythonsdk/api/member/get_guild_member.md similarity index 70% rename from docs/develop/pythonsdk/member/get_member.md rename to docs/develop/pythonsdk/api/member/get_guild_member.md index 058bb134..c2a93d15 100644 --- a/docs/develop/pythonsdk/member/get_member.md +++ b/docs/develop/pythonsdk/api/member/get_guild_member.md @@ -4,18 +4,20 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.guildApi.guildMember(guildId, userId); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) +api = qqbot.GuildMemberAPI(token, False) +members = api.get_guild_member(guild_id, user_id) ``` ## 参数说明 | 字段名 | 必填 | 类型 | 描述 | | ------- | ---- | ------ | ------- | -| guildId | 是 | string | 频道 ID | -| userId | 是 | string | 用户 ID | +| guild_id | 是 | string | 频道 ID | +| user_id | 是 | string | 用户 ID | ## 返回说明 @@ -43,22 +45,23 @@ async function demo() { `data`： -```js +```python { - user: { - id: 'USERID', - username: '机器人管家-ostwindli', - avatar: 'http://thirdqq.qlogo.cn/g?b=oidb&k=oPicoPIg01ujpSr8oosudkQ&s=0&t=1637218059', - bot: false, - public_flags: 0, - system: false + "user": { + "id": "用户 ID", + "username": "用户名", + "avatar": "用户头像地址", + "bot": false, + "public_flags": 0, + "system": false }, - nick: '阿青', - roles: [ '4' ], - joined_at: '2021-11-23T15:16:48+08:00', - deaf: false, - mute: false, - pending: false - } + "nick": "", + "roles": [ + "4" + ], + "joined_at": "2021-09-27T17:19:51+08:00", + "deaf": false, + "mute": false, + "pending": false } ``` diff --git a/docs/develop/pythonsdk/member/get_members.md b/docs/develop/pythonsdk/api/member/get_guild_members.md similarity index 88% rename from docs/develop/pythonsdk/member/get_members.md rename to docs/develop/pythonsdk/api/member/get_guild_members.md index cc392cbb..af298fd4 100644 --- a/docs/develop/pythonsdk/member/get_members.md +++ b/docs/develop/pythonsdk/api/member/get_guild_members.md @@ -6,18 +6,20 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.guildApi.guildMembers(guildId, queryParams); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) +api = qqbot.GuildMemberAPI(token, False) +members = api.get_guild_members(guild_id, query_params) ``` ## 参数说明 | 字段名 | 必填 | 类型 | 描述 | | ----------- | ---- | --------------------------- | -------- | -| guildId | 是 | string | 频道 ID | -| queryParams | 否 | [QueryParams](#queryparams) | 查询参数 | +| guild_id | 是 | string | 频道 ID | +| query_params | 否 | [QueryParams](#queryparams) | 查询参数 | ### QueryParams diff --git a/docs/develop/pythonsdk/message/get_message_of_id.md b/docs/develop/pythonsdk/api/message/get_message.md similarity index 92% rename from docs/develop/pythonsdk/message/get_message_of_id.md rename to docs/develop/pythonsdk/api/message/get_message.md index a610e643..37880c46 100644 --- a/docs/develop/pythonsdk/message/get_message_of_id.md +++ b/docs/develop/pythonsdk/api/message/get_message.md @@ -4,18 +4,21 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.messageApi.message(channelID, messageID); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.get_message(channel_id,message_id) ``` ## 参数说明 | 参数 | 必填 | 类型 | 说明 | | --------- | ---- | ------ | --------- | -| channelID | 是 | string | 子频道 ID | -| messageID | 是 | string | 消息 ID | +| channel_id | 是 | string | 子频道 ID | +| message_id | 是 | string | 消息 ID | ## 返回说明 diff --git a/docs/develop/pythonsdk/message/get_messages.md b/docs/develop/pythonsdk/api/message/get_messages.md similarity index 92% rename from docs/develop/pythonsdk/message/get_messages.md rename to docs/develop/pythonsdk/api/message/get_messages.md index 11b28c1a..e7c9ef9d 100644 --- a/docs/develop/pythonsdk/message/get_messages.md +++ b/docs/develop/pythonsdk/api/message/get_messages.md @@ -5,17 +5,20 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.messageApi.messages(channelID, pager); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.get_messages(channel_id,pager) ``` ## 参数说明 | 参数 | 必填 | 类型 | 说明 | | --------- | ---- | ------------------------------- | --------- | -| channelID | 是 | string | 子频道 ID | +| channel_id | 是 | string | 子频道 ID | | pager | 否 | [MessagesPager](#messagespager) | 分页信息 | ### MessagesPager @@ -33,6 +36,7 @@ async function demo() { | `around` | string | 读此 id 前后的消息 | | `before` | string | 读此 id 之前的消息 | | `after` | string | 读此 id 之后的消息 | +| `latest` | string | 最新limit的消息 | 如果 `around/before/after` 均为`空`，则拉取最新的 `limit` 条消息。 @@ -96,7 +100,9 @@ async function demo() { "bot": false }, "member": { - "roles": ["1"], + "roles": [ + "1" + ], "joined_at": "2021-04-12T16:34:42+08:00" } }, @@ -112,7 +118,9 @@ async function demo() { "bot": false }, "member": { - "roles": ["1"], + "roles": [ + "1" + ], "joined_at": "2021-04-12T16:34:42+08:00" } } diff --git a/docs/develop/pythonsdk/message/message_format.md b/docs/develop/pythonsdk/api/message/message_format.md similarity index 94% rename from docs/develop/pythonsdk/message/message_format.md rename to docs/develop/pythonsdk/api/message/message_format.md index 81b9201d..a59e0606 100644 --- a/docs/develop/pythonsdk/message/message_format.md +++ b/docs/develop/pythonsdk/api/message/message_format.md @@ -9,10 +9,13 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.messageApi.postMessage(channelID, message); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.post_message(channel_id, message_send_request) ``` ## 参数说明 @@ -20,9 +23,9 @@ async function demo() { | 参数 | 必填 | 类型 | 说明 | | --------- | ---- | ----------------------------------- | ---------- | | channelID | 是 | string | 子频道 ID | -| messsage | 是 | [MessageToCreate](#messagetocreate) | 消息体结构 | +| message_send_request | 是 | [MessageSendRequest](#MessageSendRequest) | 消息体结构 | -## MessageToCreate +## MessageSendRequest | 字段名 | 类型 | 描述 | | ------- | ----------------------------- | ----------------------------------------------------------------------- | @@ -119,7 +122,9 @@ async function demo() { "avatar": "", "bot": true }, - "embeds": [{}], + "embeds": [ + {} + ], "pinned": false, "type": 0, "flags": 0 diff --git a/docs/develop/pythonsdk/message/message_template.md b/docs/develop/pythonsdk/api/message/message_template.md similarity index 100% rename from docs/develop/pythonsdk/message/message_template.md rename to docs/develop/pythonsdk/api/message/message_template.md diff --git a/docs/develop/pythonsdk/message/post_ark_messages.md b/docs/develop/pythonsdk/api/message/post_ark_messages.md similarity index 96% rename from docs/develop/pythonsdk/message/post_ark_messages.md rename to docs/develop/pythonsdk/api/message/post_ark_messages.md index 06b0db4a..aad780b3 100644 --- a/docs/develop/pythonsdk/message/post_ark_messages.md +++ b/docs/develop/pythonsdk/api/message/post_ark_messages.md @@ -14,10 +14,13 @@ 需要关注`ark`字段的使用。 -```javascript -async function demo() { - let { data } = await client.messageApi.postMessage(channelID, message); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.post_message(channel_id, message_send_request) ``` ## 参数说明 @@ -25,9 +28,9 @@ async function demo() { | 参数 | 必填 | 类型 | 说明 | | --------- | ---- | ----------------------------------- | ---------- | | channelID | 是 | string | 子频道 ID | -| messsage | 是 | [MessageToCreate](#messagetocreate) | 消息体结构 | +| message_send_request | 是 | [MessageSendRequest](#MessageSendRequest) | 消息体结构 | -## MessageToCreate +## MessageSendRequest | 字段名 | 类型 | 描述 | | ------- | ----------------------------- | ----------------------------------------------------------------------- | diff --git a/docs/develop/pythonsdk/message/post_messages.md b/docs/develop/pythonsdk/api/message/post_message.md similarity index 92% rename from docs/develop/pythonsdk/message/post_messages.md rename to docs/develop/pythonsdk/api/message/post_message.md index d6298fc0..ee0e209e 100644 --- a/docs/develop/pythonsdk/message/post_messages.md +++ b/docs/develop/pythonsdk/api/message/post_message.md @@ -14,10 +14,13 @@ ## 使用示例 -```javascript -async function demo() { - let { data } = await client.messageApi.postMessage(channelID, message); -} +```python +import qqbot + +token = qqbot.Token({appid}, {token}) + +msg_api = qqbot.MessageAPI(token, False) +msg_api.post_message(channel_id, message_send_request) ``` ## 参数说明 @@ -25,9 +28,9 @@ async function demo() { | 参数 | 必填 | 类型 | 说明 | | --------- | ---- | ----------------------------------- | ---------- | | channelID | 是 | string | 子频道 ID | -| messsage | 是 | [MessageToCreate](#messagetocreate) | 消息体结构 | +| message_send_request | 是 | [MessageSendRequest](#MessageSendRequest) | 消息体结构 | -## MessageToCreate +## MessageSendRequest | 字段名 | 类型 | 描述 | | ------- | ----------------------------- | ---------------------------------------------------------------------------------------- | @@ -49,11 +52,11 @@ async function demo() { ## MessageEmbed -详见[消息内嵌格式](./message_format.md)。 +详见[消息内嵌格式](message_format.md)。 ## MessageArk -详见[发送模板消息](./post_ark_messages.md)。 +详见[发送模板消息](post_ark_messages.md)。 ## 返回说明 diff --git a/docs/develop/pythonsdk/config.js b/docs/develop/pythonsdk/config.js new file mode 100644 index 00000000..f59bcc54 --- /dev/null +++ b/docs/develop/pythonsdk/config.js @@ -0,0 +1,120 @@ +module.exports = { + nav: { + text: 'NodeSDK', + link: '/develop/nodesdk/', + }, + sidebar: { + '/develop/nodesdk/': [ + '', + { + title: '术语', + collapsable: false, + sidebarDepth: 0, + children: [ + { title: '用户对象(User)', path: 'model/user' }, + { title: '频道对象(Guild)', path: 'model/guild' }, + { title: '子频道对象(Channel)', path: 'model/channel' }, + { title: '子频道权限对象(ChannelPermissions)', path: 'model/channel_permission' }, + { title: '成员对象(Member)', path: 'model/member' }, + { title: '频道身份组对象(Role)', path: 'model/role' }, + { title: '消息对象(Message)', path: 'model/message' }, + { title: '语音对象(Audio)', path: 'model/audio' }, + ], + }, + { + title: 'Client API', + collapsable: false, + children: [ + { + title: '用户 API', + collapsable: false, + sidebarDepth: 0, + children: ['user/me'], + }, + { + title: '频道 API', + collapsable: false, + sidebarDepth: 0, + children: ['guild/guilds', 'guild/get_guild'], + }, + { + title: '子频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'channel/get_channels', + 'channel/get_channel', + 'channel/post_channels', + 'channel/patch_channel', + 'channel/delete_channel', + ], + }, + { + title: '子频道权限 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'channel_permissions/get_channel_permissions', + 'channel_permissions/put_channel_permissions', + ], + }, + { + title: '成员 API', + collapsable: false, + sidebarDepth: 0, + children: ['member/get_members', 'member/get_member', 'member/delete_member'], + }, + + { + title: '频道身份组 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'guild/get_guild_roles', + 'guild/post_guild_role', + 'guild/patch_guild_role', + 'guild/delete_guild_role', + 'guild/put_guild_member_role', + 'guild/delete_guild_member_role', + ], + }, + { + title: '消息 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'message/get_messages', + 'message/get_message_of_id', + 'message/post_messages', + 'message/message_template', + 'message/post_ark_messages', + 'message/message_format', + ], + }, + // { + // title: '私信 API', + // collapsable: false, + // sidebarDepth: 0, + // children: [ + // 'dms/model.md', + // 'dms/post_dms.md', + // 'dms/post_dms_messages.md', + // ], + // }, + { + title: '音频 API', + collapsable: false, + sidebarDepth: 0, + children: ['audio/audio_control'], + }, + ], + }, + { + title: 'WebSocket API', + collapsable: false, + sidebarDepth: 0, + children: [{ title: 'wss 消息体', path: 'wss/model.md' }], + }, + ], + }, +}; diff --git a/docs/develop/pythonsdk/model/audio.md b/docs/develop/pythonsdk/model/audio.md new file mode 100644 index 00000000..b28185de --- /dev/null +++ b/docs/develop/pythonsdk/model/audio.md @@ -0,0 +1,27 @@ +# 语音对象(AudioControl) + +## AudioControl + +| 字段名 | 类型 | 描述 | +| --------- | ----------------- | --------------------------------------------------------------------- | +| audio_url | string | 音频数据的 url status 为 0 时传 | +| text | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 | +| status | [STATUS](#status) | 播放状态，参考 STATUS | + +## STATUS + +| 字段名 | 值 | 描述 | +| ------ | --- | ------------ | +| START | 0 | 开始播放操作 | +| PAUSE | 1 | 暂停播放操作 | +| RESUME | 2 | 继续播放操作 | +| STOP | 3 | 停止播放操作 | + +## AudioAction + +| 字段名 | 类型 | 描述 | +| ---------- | ------ | --------------------------------------------------------------------- | +| guild_id | string | 频道 ID | +| channel_id | string | 子频道 ID | +| audio_url | string | 音频数据的 url status 为 0 时传 | +| text | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 | diff --git a/docs/develop/pythonsdk/model/channel.md b/docs/develop/pythonsdk/model/channel.md new file mode 100644 index 00000000..c8af3cff --- /dev/null +++ b/docs/develop/pythonsdk/model/channel.md @@ -0,0 +1,42 @@ +# 子频道对象(Channel) + +子频道对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关，请不要理解为真实的 ID。 + +### Channel + +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| name | string | 子频道名 | +| type | number | 子频道类型 [ChannelType](#channeltype) | +| sub_type | number | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | number | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | string | 分组 ID | +| owner_id | string | 创建人 ID | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +注：目前只有`文字子频道`具有 `ChannelSubType` 二级分类，同时二级分类也可能会不断增加，开发者也需要注意对未知 ID 的处理。 diff --git a/docs/develop/pythonsdk/model/channel_permission.md b/docs/develop/pythonsdk/model/channel_permission.md new file mode 100644 index 00000000..dd0d9a4a --- /dev/null +++ b/docs/develop/pythonsdk/model/channel_permission.md @@ -0,0 +1,27 @@ +# 子频道权限对象(ChannelPermissions) + +### ChannelPermissions + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | ----------------------------------------------------------- | +| channel_id | string | 子频道 ID | +| user_id | string | 用户 ID | +| permissions | string | 用户拥有的子频道权限，具体值参考[permissions](#permissions) | + +### Permissions + +权限是 QQ 频道管理频道成员的一种方式，管理员可以对不同的人、不同的子频道设置特定的权限。用户的权限包括**个人权限**和**身份组权限**两部分，最终生效是取两种权限的并集。 + +权限使用位图表示，传递时序列化为十进制数值字符串。如权限值为`0x6FFF`，会被序列化为十进制`"28671"`。 + +| 权限 | 值 | 描述 | +| ------------ | --------------------- | ---------------------------------------------------- | +| 可查看子频道 | 0x0000000001 (1 << 0) | 目前仅支持`指定成员`可见类型，不支持`身份组`可见类型 | +| 可管理子频道 | 0x0000000002 (1 << 1) | 创建者、管理员、子频道管理员都具有此权限 | + +##### 参数参考 + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ---------------------------------- | +| add | string | 字符串形式的位图表示赋予用户的权限 | +| remove | string | 字符串形式的位图表示删除用户的权限 | diff --git a/docs/develop/pythonsdk/model/dms.md b/docs/develop/pythonsdk/model/dms.md new file mode 100644 index 00000000..f0206ed6 --- /dev/null +++ b/docs/develop/pythonsdk/model/dms.md @@ -0,0 +1,9 @@ +# 私信会话对象（DMS） + +## DMS + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | ----------------------- | +| guild_id | string | 私信会话关联的频道 ID | +| channel_id | string | 私信会话关联的子频道 ID | +| create_time | string | 创建私信会话时间戳 | diff --git a/docs/develop/pythonsdk/model/guild.md b/docs/develop/pythonsdk/model/guild.md new file mode 100644 index 00000000..4a97334a --- /dev/null +++ b/docs/develop/pythonsdk/model/guild.md @@ -0,0 +1,17 @@ +# 频道对象(Guild) + +频道对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关，请不要理解为真实的 ID。 + +### Guild + +| 字段名 | 类型 | 描述 | +| --- | --- | --- | +| id | string | 频道ID | +| name | string | 频道名称 | +| icon | string | 频道头像地址 | +| owner_id | string | 创建人用户ID | +| owner | boolean | 当前人是否是创建人 | +| member_count | number | 成员数 | +| max_members | number | 最大成员数 | +| description | string | 描述 | +| joined_at | string | 加入时间 | diff --git a/docs/develop/pythonsdk/model/member.md b/docs/develop/pythonsdk/model/member.md new file mode 100644 index 00000000..e82dada4 --- /dev/null +++ b/docs/develop/pythonsdk/model/member.md @@ -0,0 +1,20 @@ +# 成员对象(Member) + +## Member + +| 字段名 | 类型 | 描述 | +| --------- | -------------------------- | -------------------------------------------------------------------------------------- | +| user | [User](/user#user) | 用户基础信息，来自 QQ 资料，只有成员相关接口中会填充此信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份组 ID，默认值可参考[DefaultRoleIDs](role.md#DefaultRoleIDs) | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | + +### MemberWithGuildID + +| 字段名 | 类型 | 描述 | +| --------- | ----------------------------- | ------------------------------------------------------------------------------------ | +| guild_id | string | 频道 ID | +| user | [User](user) | 用户基础信息 | +| nick | string | 用户在频道内的昵称 | +| roles | string[] | 用户在频道内的身份 | +| joined_at | string | 用户加入频道的时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | diff --git a/docs/develop/pythonsdk/model/message.md b/docs/develop/pythonsdk/model/message.md new file mode 100644 index 00000000..edafa38b --- /dev/null +++ b/docs/develop/pythonsdk/model/message.md @@ -0,0 +1,80 @@ +# 消息对象(Message) + +## Message + +| 字段名 | 类型 | 描述 | +| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------- | +| id | string | 消息 id | +| channel_id | string | 子频道 ID | +| guild_id | string | 频道 ID | +| content | string | 消息内容 | +| timestamp | string | 消息创建时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| edited_timestamp | string | 消息编辑时间，是个 `iISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| mention_everyone | boolean | 是否是@全员消息 | +| author | [User](/user#user) | 消息创建者 | +| attachments | [MessageAttachment[]](#messageattachment) | 附件 | +| embeds | [MessageEmbed[]](#messageembed) | embed | +| mentions | [User](/user#user) | 消息中@的人 | +| member | [Member](d#member) | 消息创建者的 member 信息 | +| ark | [MessageArk](#messageark) | ark 消息 | + +## MessageToCreate + +| 字段名 | 类型 | 描述 | +| ------- | ----------------------------- | ----------------------------------------------------------------------- | +| content | string | 消息内容，文本内容，支持[内嵌格式](message_format.md) | +| embed | [MessageEmbed](#messageembed) | embed 消息，一种特殊的 ark | +| ark | [MessageArk](#messageark) | ark 消息 | +| image | string | 图片 url 地址 | +| msg_id | string | 要回复的消息 id。**带了 msg_id 视为被动回复消息，否则视为主动推送消息** | + +## MessageEmbed + +| 字段名 | 类型 | 描述 | +| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------ | +| title | string | 标题 | +| description | string | 描述 | +| prompt | string | 消息弹窗内容 | +| timestamp | string | 消息创建时间，是个 `ISO8601 timestamp` 字符串，例："2021-11-23T15:16:48+08:00" | +| fields | [MessageEmbedField[]](#messageembedfield) | 消息体 | + +## MessageEmbedField + +| 字段名 | 类型 | 描述 | +| ------ | ------ | ------ | +| name | string | 字段名 | +| value | string | 字段值 | + +## MessageAttachment + +| 字段名 | 类型 | 描述 | +| ------ | ------ | -------- | +| url | string | 下载地址 | + +## MessageArk + +| 字段名 | 类型 | 描述 | +| :---------- | :------------------------------ | :------------------------ | +| template_id | number | ark 模板 id（需要先申请） | +| kv | [MessageAkrKv[]](#messagearkkv) | kv 值列表 | + +## MessageArkKv + +| 字段名 | 类型 | 描述 | +| :----- | :-------------------------------- | :----------------- | +| key | string | key | +| value | string | value | +| obj | [MessageArkObj[]](#messagearkobj) | ark obj 类型的列表 | + +## MessageArkObj + +| 字段名 | 类型 | 描述 | +| :----- | :--------------------------------- | :------------- | +| obj_kv | [MessageArkObjKv[]](#messageobjkv) | ark objkv 列表 | + +## MessageArkObjKv + +| 字段名 | 类型 | 描述 | +| :----- | :----- | :---- | +| key | string | key | +| value | string | value | diff --git a/docs/develop/pythonsdk/model/role.md b/docs/develop/pythonsdk/model/role.md new file mode 100644 index 00000000..fa5efa2e --- /dev/null +++ b/docs/develop/pythonsdk/model/role.md @@ -0,0 +1,21 @@ +# 频道身份组对象(Role) + +### Role + +| 字段名 | 类型 | 描述 | +| ------------ | ------ | -------------------------------------------------------------- | +| id | string | 身份组 ID | +| name | string | 名称 | +| color | number | ARGB 的 HEX 十六进制颜色值转换后的十进制数值（例：4294927682） | +| hoist | number | 是否在成员列表中单独展示: 0-否, 1-是 | +| number | number | 人数 | +| member_limit | number | 成员上限 | + +### DefaultRoleIDs(系统默认生成下列身份组 ID) + +| 身份组 ID 默认值 | 描述 | +| ---------------- | ------------ | +| 1 | 全体成员 | +| 2 | 管理员 | +| 4 | 群主/创建者 | +| 5 | 子频道管理员 | diff --git a/docs/develop/pythonsdk/model/user.md b/docs/develop/pythonsdk/model/user.md new file mode 100644 index 00000000..576c2930 --- /dev/null +++ b/docs/develop/pythonsdk/model/user.md @@ -0,0 +1,14 @@ +# 用户对象(User) + +用户对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关，请不要理解为真实的 ID。 + +## User + +| 字段名 | 类型 | 描述 | +| ------------------ | ------ | -------------------------------------------------------------------------------------------------- | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| bot | boolean | 是否是机器人 | +| union_openid | string | 特殊关联应用的 openid，需要特殊申请并配置后才会返回。如需申请，请联系平台运营人员。 | +| union_user_account | string | 机器人关联的互联应用的用户信息，与 union_openid 关联的应用是同一个。如需申请，请联系平台运营人员。 | From 3c702ccb6ae8aa333d2d56e121df01d57b20fe6f Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 15:19:38 +0800 Subject: [PATCH 03/11] =?UTF-8?q?[feat]=E5=A2=9E=E5=8A=A0python-sdk?= =?UTF-8?q?=E7=9A=84=E5=AE=8C=E6=95=B4=E7=9A=84=E6=8E=A5=E5=8F=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../develop/pythonsdk/api/audio/post_audio.md | 43 ++++++++++ .../pythonsdk/api/channel/get_channel.md | 85 +++++++++++++++++++ .../api/direct_msg/create_direct_message.md | 55 ++++++++++++ .../api/direct_msg/post_direct_message.md | 32 +++++++ docs/develop/pythonsdk/api/user/me.md | 40 +++++++++ docs/develop/pythonsdk/api/user/me_guilds.md | 26 ++++++ .../pythonsdk/websocket/listen_events.md | 53 ++++++++++++ 7 files changed, 334 insertions(+) create mode 100644 docs/develop/pythonsdk/api/audio/post_audio.md create mode 100644 docs/develop/pythonsdk/api/channel/get_channel.md create mode 100644 docs/develop/pythonsdk/api/direct_msg/create_direct_message.md create mode 100644 docs/develop/pythonsdk/api/direct_msg/post_direct_message.md create mode 100644 docs/develop/pythonsdk/api/user/me.md create mode 100644 docs/develop/pythonsdk/api/user/me_guilds.md create mode 100644 docs/develop/pythonsdk/websocket/listen_events.md diff --git a/docs/develop/pythonsdk/api/audio/post_audio.md b/docs/develop/pythonsdk/api/audio/post_audio.md new file mode 100644 index 00000000..6eae0ca8 --- /dev/null +++ b/docs/develop/pythonsdk/api/audio/post_audio.md @@ -0,0 +1,43 @@ +# 音频控制 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +audioApi = qqbot.AudioAPI(token, False) +result = audioApi.post_audio(channel_id, audio_control) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ------------ | ------------------------------------- | -------------- | +| channel_id | String | 子频道 id | +| audio_control | [AudioControl](#audiocontrol) | audio 控制参数 | + +## 返回说明 + +字段参见 [AudioControl](#audiocontrol) + + +# 语音对象 + +## AudioControl + +| 字段名 | 类型 | 描述 | +| --------- | ------ | --------------------------------------------------------------------- | +| audio_url | string | 音频数据的 url status 为 0 时传 | +| text | string | 状态文本（比如：简单爱-周杰伦），可选，status 为 0 时传，其他操作不传 | +| status | STATUS | 播放状态，参考 [STATUS](#STATUS) | + +### STATUS + +| 字段名 | 值 | 描述 | +| ------ | --- | ------------ | +| START | 0 | 开始播放操作 | +| PAUSE | 1 | 暂停播放操作 | +| RESUME | 2 | 继续播放操作 | +| STOP | 3 | 停止播放操作 | \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/channel/get_channel.md b/docs/develop/pythonsdk/api/channel/get_channel.md new file mode 100644 index 00000000..b1b320c0 --- /dev/null +++ b/docs/develop/pythonsdk/api/channel/get_channel.md @@ -0,0 +1,85 @@ +# 获取子频道信息 + +获取子频道 channel 详情 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.ChannelAPI(token, False) +channel = api.get_channel(channel_id) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ---------- | ------ | --------- | +| channel_id | String | 子频道 ID | + +## 返回说明 + +字段参见 [Channel](#Channel) + + +# 子频道对象(Channel) + +子频道对象中所涉及的 ID 类数据，都仅在机器人场景流通，与真实的 ID 无关。请不要理解为真实的 ID + +### Channel +| 字段名 | 类型 | 描述 | +| --------- | ------ | ---------------------------------------------- | +| id | String | 子频道id | +| guild_id | String | 频道id | +| name | String | 子频道名 | +| type | int | 子频道类型 [ChannelType](#channeltype) | +| sub_type | int | 子频道子类型 [ChannelSubType](#channelsubtype) | +| position | int | 排序，必填，而且不能够和其他子频道的值重复 | +| parent_id | String | 分组 id | +| owner_id | String | 创建人 id | + +### ChannelType + +| 值 | 描述 | +| ----- | ------------ | +| 0 | 文字子频道 | +| 1 | 保留，不可用 | +| 2 | 语音子频道 | +| 3 | 保留，不可用 | +| 4 | 子频道分组 | +| 10005 | 直播子频道 | +| 10006 | 应用子频道 | +| 10007 | 论坛子频道 | + +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 + +### ChannelSubType + +| 值 | 描述 | +| --- | ---- | +| 0 | 闲聊 | +| 1 | 公告 | +| 2 | 攻略 | +| 3 | 开黑 | + +## 返回示例 + +`data`： + +```python +{ + "id":"channel_id", + "guild_id":"guild_id", + "name":"子频道名", + "type":0, + "last_message_id":"21", + "nsfw":false, + "position":2, + "parent_id":"分组 id ", + "rate_limit_per_user":0, + "owner_id":"0", + "sub_type":0 +} +``` \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/direct_msg/create_direct_message.md b/docs/develop/pythonsdk/api/direct_msg/create_direct_message.md new file mode 100644 index 00000000..ced9e625 --- /dev/null +++ b/docs/develop/pythonsdk/api/direct_msg/create_direct_message.md @@ -0,0 +1,55 @@ +# 创建私信会话 + +## 功能描述 + +- 机器人和同在一个频道内的成员创建私信会话。 +- 创建成功后，返回创建成功的频道 id ，子频道 id 和创建时间。 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.MessageAPI(token, False) +request = CreateDirectMessageRequest("guild_id", "user_id") +direct_message_guild = api.create_direct_message_guild(request) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | --------- | +| request | [CreateDirectMessageRequest](#CreateDirectMessageRequest) | 私信频道创建请求 | + +## CreateDirectMessageRequest + +| 字段名 | 类型 | 描述 | +| --------------- | ------ | --------- | +| source_guild_id | string | 源频道 ID | +| user_id | string | 接收者 ID | + +## 返回说明 + +成功创建后，返回[DirectMessageGuild](#DirectMessageGuild)对象返回创建成功的频道 ID，子频道 ID 和创建时间。 + +## DirectMessageGuild + +| 字段名 | 类型 | 描述 | +| ----------- | ------ | --------- | +| guild_id | string | 频道 ID | +| channel_id | string | 子频道 ID | +| create_time | string | 创建时间 | + +## 返回示例 + +`data`： + +```json +{ + "guild_id": "xxxxxx", + "channel_id": "xxxxxx", + "create_time": "1638323931" +} +``` \ No newline at end of file diff --git a/docs/develop/pythonsdk/api/direct_msg/post_direct_message.md b/docs/develop/pythonsdk/api/direct_msg/post_direct_message.md new file mode 100644 index 00000000..29eb4e10 --- /dev/null +++ b/docs/develop/pythonsdk/api/direct_msg/post_direct_message.md @@ -0,0 +1,32 @@ +# 发送私信消息 + +## 功能描述 + +- 发送私信消息 +- 私信的 guild_id 在[创建私信会话](create_direct_message.md)时以及[私信消息事件](../../websocket/listen_events.md)中获取 + +## 使用示例 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.MessageAPI(token, False) +message = api.post_direct_message(guild_id, send_msg) +``` + +## 参数说明 + +| 字段名 | 类型 | 描述 | +| ------ | ------------------------------------------------------ | ------ | +| guild_id | string | 创建的私信会话频道[guild_id](create_direct_message.md#返回说明) | +| send_msg | [MessageSendRequest](../message/post_message#MessageSendRequest) | 消息体 | + +## 返回说明 + +返回[Message](../message/post_message.md#message) 对象 + +## 返回示例 + +同[发送消息返回示例](../message/post_message.md#返回示例) diff --git a/docs/develop/pythonsdk/api/user/me.md b/docs/develop/pythonsdk/api/user/me.md new file mode 100644 index 00000000..abd4d030 --- /dev/null +++ b/docs/develop/pythonsdk/api/user/me.md @@ -0,0 +1,40 @@ +# 获取当前用户信息 + +## 使用示例 + +``` python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.UserAPI(token, False) +user = api.me() +``` + +## 返回说明 + +使用当前用户信息填充的 [User](#user) 对象 + +### User + +| 字段名 | 类型 | 描述 | +| ------------------ | ------- | -------------------------------------------------------------------------------------------------- | +| id | string | 用户 ID | +| username | string | 用户名 | +| avatar | string | 用户头像地址 | +| union_openid | string | 特殊关联应用的 openid，需要特殊申请并配置后才会返回。如需申请，请联系平台运营人员。 | +| union_user_account | string | 机器人关联的互联应用的用户信息，与 union_openid 关联的应用是同一个。如需申请，请联系平台运营人员。 | + +## 返回示例 + +`data`： + +```json +{ + "id": "xxxxxx", + "username": "zsh-测试中", + "avatar": "xxxxxx", + "union_openid": "xxxxxx", + "union_user_account": "" +} +``` diff --git a/docs/develop/pythonsdk/api/user/me_guilds.md b/docs/develop/pythonsdk/api/user/me_guilds.md new file mode 100644 index 00000000..5211c976 --- /dev/null +++ b/docs/develop/pythonsdk/api/user/me_guilds.md @@ -0,0 +1,26 @@ +# 获取当前用户频道列表 + +### 使用示例 +``` python +import qqbot + +token = qqbot.Token({appid}, {token}) + +api = qqbot.UserAPI(token, False) +user = api.me_guilds() +``` + +### 返回说明 +当前用户所加入的所有 [Guild](#Guild) 对象列表 + +### Guild + +| 字段名 | 类型 | 描述 | +| ------------ | ------- | ------------------ | +| id | string | 频道 ID | +| name | string | 频道名称 | +| owner_id | string | 创建人用户 ID | +| owner | boolean | 当前人是否是创建人 | +| member_count | number | 成员数 | +| max_members | number | 最大成员数 | +| description | string | 描述 | diff --git a/docs/develop/pythonsdk/websocket/listen_events.md b/docs/develop/pythonsdk/websocket/listen_events.md new file mode 100644 index 00000000..ceb162b2 --- /dev/null +++ b/docs/develop/pythonsdk/websocket/listen_events.md @@ -0,0 +1,53 @@ +# WSS 消息体 + +## 当前支持的事件类型 + +```python +class HandlerType(Enum): + PLAIN_EVENT_HANDLER = 0 # 透传事件 + GUILD_EVENT_HANDLER = 1 # 频道事件 + GUILD_MEMBER_EVENT_HANDLER = 2 # 频道成员事件 + CHANNEL_EVENT_HANDLER = 3 # 子频道事件 + MESSAGE_EVENT_HANDLER = 4 # 消息事件 + AT_MESSAGE_EVENT_HANDLER = 5 # At消息事件 + # DIRECT_MESSAGE_EVENT_HANDLER = 6 #私信消息事件 + # AUDIO_EVENT_HANDLER = 7 #音频事件 +``` + +## 当前事件的返回类型 + +``` py +#透传事件（无具体的数据对象，根据后台返回Json对象） +def _plain_handler(event, data): +#频道事件 +def _guild_handler(event, guild:Guild): +#频道成员事件 +def _guild_member_handler(event, guild_member: GuildMember): +#子频道事件 +def _channel_handler(event, channel: Channel): +#消息事件 #At消息事件 +def _message_handler(event, message: Message): +``` + +## 使用示例 + +### 创建 WSS 实例并监听消息 + +```py +import qqbot + +token = qqbot.Token({appid}, {token}) + +def _message_handler(event, message: Message): + msg_api = qqbot.MessageAPI(t_token, False) + # 打印返回信息 + qqbot.logger.info("event %s" % event + ",receive message %s" % message.content) + # 构造消息发送请求数据对象 + send = qqbot.MessageSendRequest("<@%s>谢谢你，加油" % message.author.id, message.id) + # 通过api发送回复消息 + msg_api.post_message(message.channel_id, send) + +qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) +qqbot.listen_events(token, False, qqbot_handler) +``` + From 63255631403ef80aafd7b7e1d1ffabb61a678ee5 Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 15:36:59 +0800 Subject: [PATCH 04/11] =?UTF-8?q?[feat]=E4=BF=AE=E6=94=B9=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=A0=91=E5=BD=A2=E8=8F=9C=E5=8D=95=E7=9A=84=E6=8E=92?= =?UTF-8?q?=E5=88=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...st_ark_messages.md => post_ark_message.md} | 0 .../pythonsdk/api/message/post_message.md | 2 +- docs/develop/pythonsdk/config.js | 233 +++++++++--------- 3 files changed, 118 insertions(+), 117 deletions(-) rename docs/develop/pythonsdk/api/message/{post_ark_messages.md => post_ark_message.md} (100%) diff --git a/docs/develop/pythonsdk/api/message/post_ark_messages.md b/docs/develop/pythonsdk/api/message/post_ark_message.md similarity index 100% rename from docs/develop/pythonsdk/api/message/post_ark_messages.md rename to docs/develop/pythonsdk/api/message/post_ark_message.md diff --git a/docs/develop/pythonsdk/api/message/post_message.md b/docs/develop/pythonsdk/api/message/post_message.md index ee0e209e..283f84aa 100644 --- a/docs/develop/pythonsdk/api/message/post_message.md +++ b/docs/develop/pythonsdk/api/message/post_message.md @@ -56,7 +56,7 @@ msg_api.post_message(channel_id, message_send_request) ## MessageArk -详见[发送模板消息](post_ark_messages.md)。 +详见[发送模板消息](post_ark_message.md)。 ## 返回说明 diff --git a/docs/develop/pythonsdk/config.js b/docs/develop/pythonsdk/config.js index f59bcc54..741e300a 100644 --- a/docs/develop/pythonsdk/config.js +++ b/docs/develop/pythonsdk/config.js @@ -1,120 +1,121 @@ module.exports = { - nav: { - text: 'NodeSDK', - link: '/develop/nodesdk/', - }, - sidebar: { - '/develop/nodesdk/': [ - '', - { - title: '术语', - collapsable: false, - sidebarDepth: 0, - children: [ - { title: '用户对象(User)', path: 'model/user' }, - { title: '频道对象(Guild)', path: 'model/guild' }, - { title: '子频道对象(Channel)', path: 'model/channel' }, - { title: '子频道权限对象(ChannelPermissions)', path: 'model/channel_permission' }, - { title: '成员对象(Member)', path: 'model/member' }, - { title: '频道身份组对象(Role)', path: 'model/role' }, - { title: '消息对象(Message)', path: 'model/message' }, - { title: '语音对象(Audio)', path: 'model/audio' }, - ], - }, - { - title: 'Client API', - collapsable: false, - children: [ - { - title: '用户 API', - collapsable: false, - sidebarDepth: 0, - children: ['user/me'], - }, - { - title: '频道 API', - collapsable: false, - sidebarDepth: 0, - children: ['guild/guilds', 'guild/get_guild'], - }, - { - title: '子频道 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'channel/get_channels', - 'channel/get_channel', - 'channel/post_channels', - 'channel/patch_channel', - 'channel/delete_channel', - ], - }, - { - title: '子频道权限 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'channel_permissions/get_channel_permissions', - 'channel_permissions/put_channel_permissions', - ], - }, - { - title: '成员 API', - collapsable: false, - sidebarDepth: 0, - children: ['member/get_members', 'member/get_member', 'member/delete_member'], - }, + nav: { + text: 'PythonSDK', + link: '/develop/pythonsdk/', + }, + sidebar: { + '/develop/pythonsdk/': [ + '', + { + title: '术语', + collapsable: false, + sidebarDepth: 0, + children: [ + {title: '用户对象(User)', path: 'model/user'}, + {title: '频道对象(Guild)', path: 'model/guild'}, + {title: '子频道对象(Channel)', path: 'model/channel'}, + {title: '子频道权限对象(ChannelPermissions)', path: 'model/channel_permission'}, + {title: '成员对象(Member)', path: 'model/member'}, + {title: '频道身份组对象(Role)', path: 'model/role'}, + {title: '消息对象(Message)', path: 'model/message'}, + {title: '语音对象(Audio)', path: 'model/audio'}, + ], + }, + { + title: 'Client API', + collapsable: false, + children: [ + { + title: '用户 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/user/me', + 'api/user/me_guilds' + ], + }, + { + title: '频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/guild/get_guild' + ], + }, + { + title: '子频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/channel/get_channel', + 'api/channel/get_channels', + 'api/channel/create_channel', + 'api/channel/update_channel', + 'api/channel/delete_channel', + ], + }, + { + title: '子频道权限 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/channel_permissions/get_channel_permissions', + 'api/channel_permissions/update_channel_permissions', + ], + }, + { + title: '成员 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/member/get_guild_member', + 'api/member/get_guild_members', + 'api/member/delete_guild_member' + ], + }, - { - title: '频道身份组 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'guild/get_guild_roles', - 'guild/post_guild_role', - 'guild/patch_guild_role', - 'guild/delete_guild_role', - 'guild/put_guild_member_role', - 'guild/delete_guild_member_role', - ], - }, - { - title: '消息 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'message/get_messages', - 'message/get_message_of_id', - 'message/post_messages', - 'message/message_template', - 'message/post_ark_messages', - 'message/message_format', - ], - }, - // { - // title: '私信 API', - // collapsable: false, - // sidebarDepth: 0, - // children: [ - // 'dms/model.md', - // 'dms/post_dms.md', - // 'dms/post_dms_messages.md', - // ], - // }, - { - title: '音频 API', - collapsable: false, - sidebarDepth: 0, - children: ['audio/audio_control'], - }, + { + title: '频道身份组 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/guild/get_guild_roles', + 'api/guild/create_guild_role', + 'api/guild/update_guild_role', + 'api/guild/delete_guild_role', + 'api/guild/create_guild_member_role', + 'api/guild/delete_guild_member_role', + ], + }, + { + title: '消息 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/message/get_message', + 'api/message/get_messages', + 'api/message/post_message', + 'api/message/post_ark_message', + 'api/message/message_template', + 'api/message/message_format', + ], + }, + { + title: '音频 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/audio/post_audio' + ], + }, + ], + }, + { + title: 'WebSocket API', + collapsable: false, + sidebarDepth: 0, + children: [{title: '事件监听', path: 'websocket/listen_events.md'}], + }, ], - }, - { - title: 'WebSocket API', - collapsable: false, - sidebarDepth: 0, - children: [{ title: 'wss 消息体', path: 'wss/model.md' }], - }, - ], - }, + }, }; From 45c09542fb470672b8a646eae06c0f6faac6b4e5 Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 17:44:56 +0800 Subject: [PATCH 05/11] =?UTF-8?q?[feat]=E4=BF=AE=E6=94=B9=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=A0=91=E5=BD=A2=E8=8F=9C=E5=8D=95=E7=9A=84=E6=8E=92?= =?UTF-8?q?=E5=88=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vuepress/config.js | 2 + docs/develop/pythonsdk/config.js | 234 +++++++++++++++---------------- 2 files changed, 119 insertions(+), 117 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5159b54a..6104d936 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -1,5 +1,6 @@ const { convertSummary } = require('./summary-sidebar'); const nodesdkConfig = require('../develop/nodesdk/config'); +const pythonsdkConfig = require('../develop/pythonsdk/config'); const commonConfig = require('./common'); // openapi 外部文档隐藏的接口,注意不要携带.md后缀 // 废弃，请使用 summary-public 来约束可以展示的内容 @@ -115,6 +116,7 @@ module.exports = ctx => ({ text: 'SDK文档', items: [ nodesdkConfig.nav, + pythonsdkConfig.nav, { text: 'GoSDK', link: 'https://pkg.go.dev/github.com/tencent-connect/botgo', diff --git a/docs/develop/pythonsdk/config.js b/docs/develop/pythonsdk/config.js index 741e300a..0660c507 100644 --- a/docs/develop/pythonsdk/config.js +++ b/docs/develop/pythonsdk/config.js @@ -1,121 +1,121 @@ module.exports = { - nav: { - text: 'PythonSDK', - link: '/develop/pythonsdk/', - }, - sidebar: { - '/develop/pythonsdk/': [ - '', - { - title: '术语', - collapsable: false, - sidebarDepth: 0, - children: [ - {title: '用户对象(User)', path: 'model/user'}, - {title: '频道对象(Guild)', path: 'model/guild'}, - {title: '子频道对象(Channel)', path: 'model/channel'}, - {title: '子频道权限对象(ChannelPermissions)', path: 'model/channel_permission'}, - {title: '成员对象(Member)', path: 'model/member'}, - {title: '频道身份组对象(Role)', path: 'model/role'}, - {title: '消息对象(Message)', path: 'model/message'}, - {title: '语音对象(Audio)', path: 'model/audio'}, - ], - }, - { - title: 'Client API', - collapsable: false, - children: [ - { - title: '用户 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/user/me', - 'api/user/me_guilds' - ], - }, - { - title: '频道 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/guild/get_guild' - ], - }, - { - title: '子频道 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/channel/get_channel', - 'api/channel/get_channels', - 'api/channel/create_channel', - 'api/channel/update_channel', - 'api/channel/delete_channel', - ], - }, - { - title: '子频道权限 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/channel_permissions/get_channel_permissions', - 'api/channel_permissions/update_channel_permissions', - ], - }, - { - title: '成员 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/member/get_guild_member', - 'api/member/get_guild_members', - 'api/member/delete_guild_member' - ], - }, + nav: { + text: 'PythonSDK', + link: '/develop/pythonsdk/', + }, + sidebar: { + '/develop/pythonsdk/': [ + '', + { + title: '术语', + collapsable: false, + sidebarDepth: 0, + children: [ + {title: '用户对象(User)', path: 'model/user'}, + {title: '频道对象(Guild)', path: 'model/guild'}, + {title: '子频道对象(Channel)', path: 'model/channel'}, + {title: '子频道权限对象(ChannelPermissions)', path: 'model/channel_permission'}, + {title: '成员对象(Member)', path: 'model/member'}, + {title: '频道身份组对象(Role)', path: 'model/role'}, + {title: '消息对象(Message)', path: 'model/message'}, + {title: '语音对象(Audio)', path: 'model/audio'}, + ], + }, + { + title: 'Client API', + collapsable: false, + children: [ + { + title: '用户 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/user/me', + 'api/user/me_guilds' + ], + }, + { + title: '频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/guild/get_guild' + ], + }, + { + title: '子频道 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/channel/get_channel', + 'api/channel/get_channels', + 'api/channel/create_channel', + 'api/channel/update_channel', + 'api/channel/delete_channel', + ], + }, + { + title: '子频道权限 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/channel_permissions/get_channel_permissions', + 'api/channel_permissions/update_channel_permissions', + ], + }, + { + title: '成员 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/member/get_guild_member', + 'api/member/get_guild_members', + 'api/member/delete_guild_member' + ], + }, - { - title: '频道身份组 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/guild/get_guild_roles', - 'api/guild/create_guild_role', - 'api/guild/update_guild_role', - 'api/guild/delete_guild_role', - 'api/guild/create_guild_member_role', - 'api/guild/delete_guild_member_role', - ], - }, - { - title: '消息 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/message/get_message', - 'api/message/get_messages', - 'api/message/post_message', - 'api/message/post_ark_message', - 'api/message/message_template', - 'api/message/message_format', - ], - }, - { - title: '音频 API', - collapsable: false, - sidebarDepth: 0, - children: [ - 'api/audio/post_audio' - ], - }, - ], - }, - { - title: 'WebSocket API', - collapsable: false, - sidebarDepth: 0, - children: [{title: '事件监听', path: 'websocket/listen_events.md'}], - }, + { + title: '频道身份组 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/guild/get_guild_roles', + 'api/guild/create_guild_role', + 'api/guild/update_guild_role', + 'api/guild/delete_guild_role', + 'api/guild/create_guild_member_role', + 'api/guild/delete_guild_member_role', + ], + }, + { + title: '消息 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/message/get_message', + 'api/message/get_messages', + 'api/message/post_message', + 'api/message/post_ark_message', + 'api/message/message_template', + 'api/message/message_format', + ], + }, + { + title: '音频 API', + collapsable: false, + sidebarDepth: 0, + children: [ + 'api/audio/post_audio' + ], + }, ], - }, + }, + { + title: 'WebSocket API', + collapsable: false, + sidebarDepth: 0, + children: [{title: '事件监听', path: 'websocket/listen_events.md'}], + }, + ], + }, }; From c8118f50fca5eb4d09bf01acc5e37ba5e96567ad Mon Sep 17 00:00:00 2001 From: zoswing <1141421776@qq.com> Date: Thu, 23 Dec 2021 17:54:40 +0800 Subject: [PATCH 06/11] =?UTF-8?q?doc=20:=20=E5=A1=AB=E5=8A=A0pythonesdk?= =?UTF-8?q?=E8=8F=9C=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vuepress/config.js | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 6104d936..1132620f 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -140,6 +140,7 @@ module.exports = ctx => ({ sidebar: { '/develop/api/': convertSummary('./docs/develop/api/SUMMARY-PUBLIC.md', hiddenApi, 1, true), ...nodesdkConfig.sidebar, + ...pythonsdkConfig.sidebar, '/': [''], }, From 4c23d293139f2e299f6ccc273efbcd55f11d7545 Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 20:29:28 +0800 Subject: [PATCH 07/11] =?UTF-8?q?[fix]=E4=BF=AE=E5=A4=8D=E7=9B=AE=E5=BD=95?= =?UTF-8?q?=E4=B8=8D=E6=98=BE=E7=A4=BA=E7=9A=84=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop/pythonsdk/README.md | 4 ++-- docs/develop/pythonsdk/config.js | 13 ++++++------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/develop/pythonsdk/README.md b/docs/develop/pythonsdk/README.md index 09f4e01e..977ca1b9 100644 --- a/docs/develop/pythonsdk/README.md +++ b/docs/develop/pythonsdk/README.md @@ -11,7 +11,7 @@ pip install qq-bot 更新包的话需要添加 ``--upgrade`` ``注：需要python3.7+`` -## 使用示例 +## 使用示例-API访问 下面的例子，通过api获取当前机器人的相关信息： @@ -25,7 +25,7 @@ user = api.me() print(user.username) # 打印机器人名字 ``` -## ws消息监听 +## 使用示例-异步消息 通过注册需要监听的事件并设置回调函数后，即可完成对事件的监听。 diff --git a/docs/develop/pythonsdk/config.js b/docs/develop/pythonsdk/config.js index 0660c507..2514cf41 100644 --- a/docs/develop/pythonsdk/config.js +++ b/docs/develop/pythonsdk/config.js @@ -73,18 +73,17 @@ module.exports = { 'api/member/delete_guild_member' ], }, - { title: '频道身份组 API', collapsable: false, sidebarDepth: 0, children: [ - 'api/guild/get_guild_roles', - 'api/guild/create_guild_role', - 'api/guild/update_guild_role', - 'api/guild/delete_guild_role', - 'api/guild/create_guild_member_role', - 'api/guild/delete_guild_member_role', + 'api/guild/guild_role/get_guild_roles', + 'api/guild/guild_role/create_guild_role', + 'api/guild/guild_role/update_guild_role', + 'api/guild/guild_role/delete_guild_role', + 'api/guild/guild_role/create_guild_role_member', + 'api/guild/guild_role/delete_guild_role_member' ], }, { From 35d5e61d8023a4c3c261bd5546211a87943a07dd Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 22:43:27 +0800 Subject: [PATCH 08/11] =?UTF-8?q?[fix]=E4=BF=AE=E5=A4=8D=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=9A=84=E4=B8=8D=E8=A7=84=E8=8C=83=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../pythonsdk/api/channel/create_channel.md | 4 +-- .../pythonsdk/api/channel/delete_channel.md | 2 +- .../pythonsdk/api/channel/get_channel.md | 4 +-- .../pythonsdk/api/channel/get_channels.md | 2 +- .../pythonsdk/api/channel/update_channel.md | 31 +++++------------ .../get_channel_permissions.md | 2 +- docs/develop/pythonsdk/api/guild/get_guild.md | 2 +- .../api/guild/guild_role/get_guild_roles.md | 2 +- .../api/guild/guild_role/update_guild_role.md | 3 +- .../pythonsdk/api/member/get_guild_member.md | 2 +- .../pythonsdk/api/member/get_guild_members.md | 34 ++++++++++--------- .../pythonsdk/api/message/get_messages.md | 6 ++-- .../pythonsdk/websocket/listen_events.md | 4 +-- 13 files changed, 43 insertions(+), 55 deletions(-) diff --git a/docs/develop/pythonsdk/api/channel/create_channel.md b/docs/develop/pythonsdk/api/channel/create_channel.md index 10a2641f..e89f1974 100644 --- a/docs/develop/pythonsdk/api/channel/create_channel.md +++ b/docs/develop/pythonsdk/api/channel/create_channel.md @@ -11,7 +11,7 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.ChannelAPI(token, False) -channel = api.create_channel(channel_id, channel) +channel_res = api.create_channel(channel_id, channel) ``` ::: warning 注意 @@ -85,7 +85,7 @@ channel = api.create_channel(channel_id, channel) `data`： -```python +```json { "id": "channel_id", "guild_id": "guild_id", diff --git a/docs/develop/pythonsdk/api/channel/delete_channel.md b/docs/develop/pythonsdk/api/channel/delete_channel.md index 9c90eb30..6187fece 100644 --- a/docs/develop/pythonsdk/api/channel/delete_channel.md +++ b/docs/develop/pythonsdk/api/channel/delete_channel.md @@ -61,7 +61,7 @@ channel = api.delete_channel(channel_id) `data`： -```python +```json { "id":"channel_id", "type":0, diff --git a/docs/develop/pythonsdk/api/channel/get_channel.md b/docs/develop/pythonsdk/api/channel/get_channel.md index b1b320c0..21b226ed 100644 --- a/docs/develop/pythonsdk/api/channel/get_channel.md +++ b/docs/develop/pythonsdk/api/channel/get_channel.md @@ -53,7 +53,7 @@ channel = api.get_channel(channel_id) | 10006 | 应用子频道 | | 10007 | 论坛子频道 | -注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知 ID 的处理。 +注：由于 QQ 频道还在持续的迭代中，经常会有新的子频道类型增加，文档更新不一定及时，开发者识别 `ChannelType` 时，请注意相关的未知类型的处理。 ### ChannelSubType @@ -68,7 +68,7 @@ channel = api.get_channel(channel_id) `data`： -```python +```json { "id":"channel_id", "guild_id":"guild_id", diff --git a/docs/develop/pythonsdk/api/channel/get_channels.md b/docs/develop/pythonsdk/api/channel/get_channels.md index fffed2e9..ac1e5705 100644 --- a/docs/develop/pythonsdk/api/channel/get_channels.md +++ b/docs/develop/pythonsdk/api/channel/get_channels.md @@ -64,7 +64,7 @@ channel = api.get_channels(guild_id) `data`： -```python +```json [ { "id":"channel_id", diff --git a/docs/develop/pythonsdk/api/channel/update_channel.md b/docs/develop/pythonsdk/api/channel/update_channel.md index c2731fab..c6fa5b63 100644 --- a/docs/develop/pythonsdk/api/channel/update_channel.md +++ b/docs/develop/pythonsdk/api/channel/update_channel.md @@ -83,28 +83,15 @@ channel = api.update_channel(channel_id, channel) `data`： -```python +```json { - "id":"2186875", - "guild_id":"2020131797974366736", - "name":"update_channel", - "topic":null, - "type":0, - "last_message_id":null, - "last_pin_timestamp":null, - "nsfw":null, - "icon":null, - "position":22, - "bitrate":null, - "recipients":[ - - ], - "user_limit":null, - "parent_id":"1128421", - "rate_limit_per_user":null, - "owner_id":null, - "application_id":null, - "op_user_id":null, - "sub_type":0 + "id": "2186875", + "guild_id": "2020131797974366736", + "name": "update_channel", + "type": 0, + "position": 22, + "parent_id": "1128421", + "owner_id": null, + "sub_type": 0 } ``` diff --git a/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md b/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md index 1da58573..4a6c4213 100644 --- a/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md +++ b/docs/develop/pythonsdk/api/channel_permissions/get_channel_permissions.md @@ -54,7 +54,7 @@ channel = api.get_channel_permissions(channel_id, user_id) `data`： -```python +```json { "channel_id": "1128412", "user_id": "9962144428931019739", diff --git a/docs/develop/pythonsdk/api/guild/get_guild.md b/docs/develop/pythonsdk/api/guild/get_guild.md index cf0bcec2..bafb37cb 100644 --- a/docs/develop/pythonsdk/api/guild/get_guild.md +++ b/docs/develop/pythonsdk/api/guild/get_guild.md @@ -39,7 +39,7 @@ guild = api.get_guild(guild_id) `data`： -```python +```json { "id":"guildId", "name":"频道名称", diff --git a/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md b/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md index ecccb253..ce760189 100644 --- a/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/get_guild_roles.md @@ -41,7 +41,7 @@ guild_roles = api.get_guild_roles(guild_id) `data`： -```python +```json { "guild_id":"guild_id", "roles":[ diff --git a/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md b/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md index 84ce75ad..dcbf66a5 100644 --- a/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md +++ b/docs/develop/pythonsdk/api/guild/guild_role/update_guild_role.md @@ -13,7 +13,8 @@ api = qqbot.GuildRoleAPI(token, False) result = api.update_guild_role(guild_id, role_id, role_info) ``` -::: warning 注意 需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员。 +:::warning 注意 +需要使用的 token 对应的用户具备创建身份组权限。如果是机器人，要求被添加为管理员 ::: ## 参数说明 diff --git a/docs/develop/pythonsdk/api/member/get_guild_member.md b/docs/develop/pythonsdk/api/member/get_guild_member.md index c2a93d15..afa164bc 100644 --- a/docs/develop/pythonsdk/api/member/get_guild_member.md +++ b/docs/develop/pythonsdk/api/member/get_guild_member.md @@ -45,7 +45,7 @@ members = api.get_guild_member(guild_id, user_id) `data`： -```python +```json { "user": { "id": "用户 ID", diff --git a/docs/develop/pythonsdk/api/member/get_guild_members.md b/docs/develop/pythonsdk/api/member/get_guild_members.md index af298fd4..8225e318 100644 --- a/docs/develop/pythonsdk/api/member/get_guild_members.md +++ b/docs/develop/pythonsdk/api/member/get_guild_members.md @@ -54,23 +54,25 @@ members = api.get_guild_members(guild_id, query_params) `data`： -```js +```json [ { - user: { - id: 'USERID', - username: '机器人管家-ostwindli', - avatar: 'http://thirdqq.qlogo.cn/g?b=oidb&k=oPicoPIg01ujpSr8oosudkQ&s=0&t=1637218059', - bot: false, - public_flags: 0, - system: false, + "user": { + "id": "USERID", + "username": "机器人管家-ostwindli", + "avatar": "http://thirdqq.qlogo.cn/g?b=oidb&k=oPicoPIg01ujpSr8oosudkQ&s=0&t=1637218059", + "bot": false, + "public_flags": 0, + "system": false }, - nick: '阿青', - roles: ['4'], - joined_at: '2021-11-23T15:16:48+08:00', - deaf: false, - mute: false, - pending: false, - }, -]; + "nick": "阿青", + "roles": [ + "4" + ], + "joined_at": "2021-11-23T15:16:48+08:00", + "deaf": false, + "mute": false, + "pending": false + } +] ``` diff --git a/docs/develop/pythonsdk/api/message/get_messages.md b/docs/develop/pythonsdk/api/message/get_messages.md index e7c9ef9d..e35154b5 100644 --- a/docs/develop/pythonsdk/api/message/get_messages.md +++ b/docs/develop/pythonsdk/api/message/get_messages.md @@ -25,9 +25,9 @@ msg_api.get_messages(channel_id,pager) | 参数 | 必填 | 类型 | 说明 | | ----- | ---- | ----------------------- | ----------------------------- | -| type | 否 | [TypesEnum](#typesenum) | 拉取类型 | -| id | 否 | string | 消息 ID | -| limit | 否 | string | 每次拉取多少条消息，最大 `20` | +| type | 是 | [TypesEnum](#typesenum) | 拉取类型 | +| id | 是 | string | 消息 ID | +| limit | 是 | string | 每次拉取多少条消息，最大 `20` | ### TypesEnum diff --git a/docs/develop/pythonsdk/websocket/listen_events.md b/docs/develop/pythonsdk/websocket/listen_events.md index ceb162b2..024565cd 100644 --- a/docs/develop/pythonsdk/websocket/listen_events.md +++ b/docs/develop/pythonsdk/websocket/listen_events.md @@ -9,9 +9,7 @@ class HandlerType(Enum): GUILD_MEMBER_EVENT_HANDLER = 2 # 频道成员事件 CHANNEL_EVENT_HANDLER = 3 # 子频道事件 MESSAGE_EVENT_HANDLER = 4 # 消息事件 - AT_MESSAGE_EVENT_HANDLER = 5 # At消息事件 - # DIRECT_MESSAGE_EVENT_HANDLER = 6 #私信消息事件 - # AUDIO_EVENT_HANDLER = 7 #音频事件 + AT_MESSAGE_EVENT_HANDLER = 5 # At消息事件 ``` ## 当前事件的返回类型 From 0cadcbad8468f3b20f68bd1f2b6b18b61dda518a Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 22:43:55 +0800 Subject: [PATCH 09/11] =?UTF-8?q?[fix]=E4=BF=AE=E5=A4=8D=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=9A=84=E4=B8=8D=E8=A7=84=E8=8C=83=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop/pythonsdk/api/channel/update_channel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/pythonsdk/api/channel/update_channel.md b/docs/develop/pythonsdk/api/channel/update_channel.md index c6fa5b63..bc4c3ccc 100644 --- a/docs/develop/pythonsdk/api/channel/update_channel.md +++ b/docs/develop/pythonsdk/api/channel/update_channel.md @@ -12,7 +12,7 @@ import qqbot token = qqbot.Token({appid}, {token}) api = qqbot.ChannelAPI(token, False) -channel = api.update_channel(channel_id, channel) +channel_res = api.update_channel(channel_id, channel) ``` ::: warning 注意 From 4a76793c3c95de55f7474a84f9aa41cae978a160 Mon Sep 17 00:00:00 2001 From: veehou Date: Thu, 23 Dec 2021 22:53:22 +0800 Subject: [PATCH 10/11] =?UTF-8?q?[fix]=E5=A2=9E=E5=8A=A0=E4=BA=8B=E4=BB=B6?= =?UTF-8?q?=E7=9A=84=E8=AF=A6=E7=BB=86=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop/pythonsdk/README.md | 29 +------------------ .../pythonsdk/websocket/listen_events.md | 27 ++++++++++++++++- 2 files changed, 27 insertions(+), 29 deletions(-) diff --git a/docs/develop/pythonsdk/README.md b/docs/develop/pythonsdk/README.md index 977ca1b9..a9261231 100644 --- a/docs/develop/pythonsdk/README.md +++ b/docs/develop/pythonsdk/README.md @@ -50,34 +50,7 @@ def _message_handler(event, message: Message): msg_api.post_message(message.channel_id, send) ``` -注：当前支持事件及回调事件包括： - -``` py -class HandlerType(Enum): - PLAIN_EVENT_HANDLER = 0 #透传事件 - GUILD_EVENT_HANDLER = 1 #频道事件 - GUILD_MEMBER_EVENT_HANDLER = 2 #频道成员事件 - CHANNEL_EVENT_HANDLER = 3 #子频道事件 - MESSAGE_EVENT_HANDLER = 4 #消息事件 - AT_MESSAGE_EVENT_HANDLER = 5 #At消息事件 - # DIRECT_MESSAGE_EVENT_HANDLER = 6 #私信消息事件 - # AUDIO_EVENT_HANDLER = 7 #音频事件 -``` - -事件回调函数的参数 1 为事件名称，参数 2 返回具体的数据对象。 - -``` py -#透传事件（无具体的数据对象，根据后台返回Json对象） -def _plain_handler(event, data): -#频道事件 -def _guild_handler(event, guild:Guild): -#频道成员事件 -def _guild_member_handler(event, guild_member: GuildMember): -#子频道事件 -def _channel_handler(event, channel: Channel): -#消息事件 #At消息事件 -def _message_handler(event, message: Message): -``` +注：当前支持事件及回调事件可参考[事件监听](websocket/listen_events.md#当前支持的事件类型) ## 日志打印 diff --git a/docs/develop/pythonsdk/websocket/listen_events.md b/docs/develop/pythonsdk/websocket/listen_events.md index 024565cd..dfef91e4 100644 --- a/docs/develop/pythonsdk/websocket/listen_events.md +++ b/docs/develop/pythonsdk/websocket/listen_events.md @@ -12,6 +12,27 @@ class HandlerType(Enum): AT_MESSAGE_EVENT_HANDLER = 5 # At消息事件 ``` +## 当前支持的事件 + +```python +class WsEvent: + EventGuildCreate = "GUILD_CREATE" + EventGuildUpdate = "GUILD_UPDATE" + EventGuildDelete = "GUILD_DELETE" + + EventChannelCreate = "CHANNEL_CREATE" + EventChannelUpdate = "CHANNEL_UPDATE" + EventChannelDelete = "CHANNEL_DELETE" + + EventGuildMemberAdd = "GUILD_MEMBER_ADD" + EventGuildMemberUpdate = "GUILD_MEMBER_UPDATE" + EventGuildMemberRemove = "GUILD_MEMBER_REMOVE" + + EventMessageCreate = "MESSAGE_CREATE" + + EventAtMessageCreate = "AT_MESSAGE_CREATE" +``` + ## 当前事件的返回类型 ``` py @@ -23,7 +44,9 @@ def _guild_handler(event, guild:Guild): def _guild_member_handler(event, guild_member: GuildMember): #子频道事件 def _channel_handler(event, channel: Channel): -#消息事件 #At消息事件 +#消息事件 +def _message_handler(event, message: Message): +#At消息事件 def _message_handler(event, message: Message): ``` @@ -36,6 +59,7 @@ import qqbot token = qqbot.Token({appid}, {token}) + def _message_handler(event, message: Message): msg_api = qqbot.MessageAPI(t_token, False) # 打印返回信息 @@ -45,6 +69,7 @@ def _message_handler(event, message: Message): # 通过api发送回复消息 msg_api.post_message(message.channel_id, send) + qqbot_handler = qqbot.Handler(qqbot.HandlerType.AT_MESSAGE_EVENT_HANDLER, _message_handler) qqbot.listen_events(token, False, qqbot_handler) ``` From ae6a533630380a1d637deb4d432515243c8ab8ec Mon Sep 17 00:00:00 2001 From: veehou Date: Fri, 24 Dec 2021 20:05:43 +0800 Subject: [PATCH 11/11] =?UTF-8?q?[fix]=E4=BF=AE=E6=94=B9=E5=8F=82=E6=95=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/develop/pythonsdk/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/pythonsdk/README.md b/docs/develop/pythonsdk/README.md index a9261231..1052e513 100644 --- a/docs/develop/pythonsdk/README.md +++ b/docs/develop/pythonsdk/README.md @@ -19,7 +19,7 @@ pip install qq-bot import qqbot token = qqbot.Token("{appid}","{token}") -api = qqbot.UserAPI(token, IS_SANDBOX) +api = qqbot.UserAPI(token, False) user = api.me() print(user.username) # 打印机器人名字