QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第四期]
第四期介绍:频道模块之频道身份组与权限管理
目录
不懂得的也可以来私聊或评论区问哦~
原力到一千才可以推广,三连啊喂!!!
获取频道身份组列表
接口
GET /guilds/{guild_id}/roles
功能描述
用于获取 guild_id
指定的频道下的身份组列表。
Content-Type
application/json
返回
字段名 | 类型 | 描述 |
---|---|---|
guild_id | string | 频道 ID |
roles | Role 对象数组 | 一组频道身份组对象 |
role_num_limit | string | 默认分组上限 |
错误码
详见错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/roles"
Authorization = f"QQBot {你的鉴权}"
}
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.get(url, headers=herders).json()
print(response)
运行结果如下:
{
"guild_id": "123456",
"roles": [
{
"id": "4",
"name": "创建者",
"color": 4294927682,
"hoist": 1,
"number": 1,
"member_limit": 1
},
{
"id": "2",
"name": "管理员",
"color": 4280276644,
"hoist": 1,
"number": 5,
"member_limit": 50
}
],
"role_num_limit": "30"
}
创建频道身份组
接口
POST /guilds/{guild_id}/roles
功能描述
用于在 guild_id
指定的频道下创建一个身份组。
- 需要使用的
token
对应的用户具备创建身份组权限。如果是机器人,要求被添加为管理员。 - 参数为非必填,但至少需要传其中之一,默认为空或
0
。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
name | string | 名称(非必填) |
color | uint32 | ARGB 的 HEX 十六进制颜色值转换后的十进制数值(非必填) |
hoist | int32 | 在成员列表中单独展示: 0-否, 1-是(非必填) |
返回
字段名 | 类型 | 描述 |
---|---|---|
role_id | string | 身份组 ID |
role | Role 对象 | 所创建的频道身份组对象 |
错误码
详见 错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/roles"
Authorization = f"QQBot {你的鉴权}"
data = {
"name": "test",
"color": 99999,
"hoist": "1"
}
}
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.post(url, headers=herders, json=data).json()
print(response)
运行结果如下:
{
"role_id": "10177739",
"role": {
"id": "10177739",
"name": "test",
"color": 99999,
"hoist": 1,
"number": 0,
"member_limit": 2000
}
}
修改频道身份组
接口
PATCH /guilds/{guild_id}/roles/{role_id}
功能描述
用于修改频道 guild_id
下 role_id
指定的身份组。
- 需要使用的
token
对应的用户具备修改身份组权限。如果是机器人,要求被添加为管理员。 - 接口会修改传入的字段,不传入的默认不会修改,至少要传入一个参数。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
name | string | 名称(非必填) |
color | uint32 | ARGB 的 HEX 十六进制颜色值转换后的十进制数值(非必填) |
hoist | int32 | 在成员列表中单独展示: 0-否, 1-是(非必填) |
返回
字段名 | 类型 | 描述 |
---|---|---|
guild_id | string | 频道 ID |
role_id | string | 身份组 ID |
role | Role 对象 | 修改后的频道身份组对象 |
错误码
详见 错误码。
Python示例
import requests
# 替换为你的guild_id和role_id
guild_id = "你的频道ID"
role_id = "你的身份组ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/roles/{role_id}"
Authorization = f"QQBot 你的鉴权token"
data = {
"name": "test",
"color": 99999,
"hoist": 1
}
headers = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.patch(url, headers=headers, json=data).json()
print(response)
请求数据包
{
"name": "test",
"color": 99999,
"hoist": 1
}
响应数据包
{
"guild_id": "3489223429684602178",
"role_id": "10177739",
"role": {
"id": "10177739",
"name": "test",
"color": 99999,
"hoist": 1,
"number": 1,
"member_limit": 2000
}
}
删除频道身份组
接口
DELETE /guilds/{guild_id}/roles/{role_id}
功能描述
用于删除频道 guild_id
下 role_id
对应的身份组。
- 需要使用的
token
对应的用户具备删除身份组权限。如果是机器人,要求被添加为管理员。
Content-Type
application/json
返回
成功返回 HTTP 状态码 204
。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的guild_id和role_id
guild_id = "你的频道ID"
role_id = "你的身份组ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/roles/{role_id}"
Authorization = f"QQBot 你的鉴权token"
headers = {
"Authorization": Authorization
}
response = requests.delete(url, headers=headers)
if response.status_code == 204:
print("身份组删除成功")
else:
print("删除身份组失败,状态码:", response.status_code)
请求数据包
DELETE /guilds/123456/roles/112233
创建频道身份组成员
接口
PUT /guilds/{guild_id}/members/{user_id}/roles/{role_id}
功能描述
用于将频道 guild_id
下的用户 user_id
添加到身份组 role_id
。
- 需要使用的
token
对应的用户具备增加身份组成员权限。如果是机器人,要求被添加为管理员。 - 如果要增加的身份组
ID
是5-子频道管理员
,需要增加channel
对象来指定具体是哪个子频道。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
channel | Channel 对象 | 接收一个只填充了子频道 id 字段的对象 |
返回
成功返回 HTTP 状态码 204
。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的guild_id, user_id和role_id
guild_id = "你的频道ID"
user_id = "你的用户ID"
role_id = "你的身份组ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/members/{user_id}/roles/{role_id}"
Authorization = f"QQBot 你的鉴权token"
data = {
"channel": {
"id": "子频道ID"
}
}
headers = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.put(url, headers=headers, json=data)
if response.status_code == 204:
print("用户成功添加到身份组")
else:
print("添加用户到身份组失败,状态码:", response.status_code)
请求数据包
{
"channel": {
"id": "1744939"
}
}
删除频道身份组成员
接口
DELETE /guilds/{guild_id}/members/{user_id}/roles/{role_id}
功能描述
用于将用户 user_id
从频道 guild_id
的 role_id
身份组中移除。
- 需要使用的
token
对应的用户具备删除身份组成员权限。如果是机器人,要求被添加为管理员。 - 如果要删除的身份组
ID
是5-子频道管理员
,需要增加channel
对象来指定具体是哪个子频道。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
channel | Channel 对象 | 接收一个只填充了子频道 id 字段的对象 |
返回
成功返回 HTTP 状态码 204
。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的guild_id, user_id和role_id
guild_id = "你的频道ID"
user_id = "你的用户ID"
role_id = "你的身份组ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/members/{user_id}/roles/{role_id}"
Authorization = f"QQBot 你的鉴权token"
headers = {
"Authorization": Authorization
}
response = requests.delete(url, headers=headers)
if response.status_code == 204:
print("用户成功从身份组移除")
else:
print("移除用户从身份组失败,状态码:", response.status_code)
获取子频道用户权限
接口
GET /channels/{channel_id}/members/{user_id}/permissions
功能描述
用于获取子频道 channel_id
下用户 user_id
的权限。
- 获取子频道用户权限。
- 要求操作人具有管理子频道的权限,如果是机器人,则需要将机器人设置为管理员。
Content-Type
application/json
返回
返回 ChannelPermissions 对象。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的channel_id和user_id
channel_id = "你的子频道ID"
user_id = "你的用户ID"
url = f"https://api.sgroup.qq.com/channels/{channel_id}/members/{user_id}/permissions"
Authorization = f"QQBot 你的鉴权token"
headers = {
"Authorization": Authorization
}
response = requests.get(url, headers=headers)
permissions = response.json()
print("用户权限:", permissions)
修改子频道用户权限
接口
PUT /channels/{channel_id}/members/{user_id}/permissions
功能描述
用于修改子频道 channel_id
下用户 user_id
的权限。
- 要求操作人具有
管理子频道
的权限,如果是机器人,则需要将机器人设置为管理员。 - 参数包括
add
和remove
两个字段,分别表示授予的权限以及删除的权限。要授予用户权限即把add
对应位置 1,删除用户权限即把remove
对应位置 1。当两个字段同一位都为 1,表现为删除权限。 - 本接口不支持修改
可管理子频道
权限。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
add | string | 字符串形式的位图表示赋予用户的权限 |
remove | string | 字符串形式的位图表示删除用户的权限 |
返回
成功返回 HTTP 状态码 204
。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的channel_id和user_id
channel_id = "你的子频道ID"
user_id = "你的用户ID"
url = f"https://api.sgroup.qq.com/channels/{channel_id}/members/{user_id}/permissions"
Authorization = f"QQBot 你的鉴权token"
data = {
"add": "1",
"remove": "4"
}
headers = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.put(url, headers=headers, json=data)
if response.status_code == 204:
print("用户权限修改成功")
else:
print("修改用户权限失败,状态码:", response.status_code)
获取子频道身份组权限
接口
GET /channels/{channel_id}/roles/{role_id}/permissions
功能描述
用于获取子频道 channel_id
下身份组 role_id
的权限。
- 要求操作人具有管理子频道的权限,如果是机器人,则需要将机器人设置为管理员。
Content-Type
application/json
返回
返回 ChannelPermissions 对象。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的channel_id和role_id
channel_id = "你的子频道ID"
role_id = "你的身份组ID"
url = f"https://api.sgroup.qq.com/channels/{channel_id}/roles/{role_id}/permissions"
Authorization = f"QQBot 你的鉴权token"
headers = {
"Authorization": Authorization
}
response = requests.get(url, headers=headers)
permissions = response.json()
print("身份组权限:", permissions)
修改子频道身份组权限
接口
PUT /channels/{channel_id}/roles/{role_id}/permissions
功能描述
用于修改子频道 channel_id
下身份组 role_id
的权限。
- 要求操作人具有
管理子频道
的权限,如果是机器人,则需要将机器人设置为管理员。 - 参数包括
add
和remove
两个字段,分别表示授予的权限以及删除的权限。要授予身份组权限即把add
对应位置 1,删除身份组权限即把remove
对应位置 1。当两个字段同一位都为 1,表现为删除权限。 - 本接口不支持修改
可管理子频道
权限。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
add | string | 字符串形式的位图表示赋予用户的权限 |
remove | string | 字符串形式的位图表示删除用户的权限 |
返回
成功返回 HTTP 状态码 204
。
错误码
详见 错误码。
Python示例
import requests
# 替换为你的channel_id和role_id
channel_id = "你的子频道ID"
role_id = "你的身份组ID"
url = f"https://api.sgroup.qq.com/channels/{channel_id}/roles/{role_id}/permissions"
Authorization = f"QQBot 你的鉴权token"
data = {
"add": "1",
"remove": "4"
}
headers = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.put(url, headers=headers, json=data)
if response.status_code == 204:
print("身份组权限修改成功")
else:
print("修改身份组权限失败,状态码:", response.status_code)
致谢和更新
文章持续更新,如果三连支持,速更!!!
请在评论区提出疑惑和建议
上次更新: 9/11/2024, AM
⬅️QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第三期]
➡️第五期:频道模块之接口授权管理和发言管理(更新中…)