快速入门¶

本内容将引导您从安装开始，到实装您的第一个可运行机器人。

安装¶

下载 python： https://www.python.org/downloads/
推荐 python 版本：3.9+
安装 python 可参考：https://www.liaoxuefeng.com/wiki/1016959663602400/1016959856222624
安装 python 后，直接使用 pip 安装即可，系统会自动安装 SDK 和其两个依赖包（更多关于 pip 的资讯可参考https://www.runoob.com/w3cnote/python-pip-install-usage.html）

pip install qg-botsdk

注册机器人¶

官方机器人简介文档：https://bot.q.qq.com/wiki/##简介

官方机器人快速注册指南：https://cloud.tencent.com/lab/courseDetail/1005936350069241

注册后，可在“机器人平台后台管理端-开发-开发设置”找到三个关键票据，当中 BotAppID 是机器人 ID，机器人令牌为机器人 token，机器人密钥为机器人 secret。

票据	对应的名称	描述
bot_app_id	BotAppID	用于识别一个机器人的 id（可理解为登录机器人的账号 ID）
bot_token	机器人令牌	机器人 token，用于以机器人身份调用 api（可理解为登录机器人的密码）
bot_secret	机器人密钥	用于在 oauth 场景进行请求签名的密钥（主要可用于调用腾讯内容安全检测接口）

创建并使用¶

下载 sdk 后，即可创建一个新的.py 档案，并透过 import 载入 SDK 内容：

from qg_botsdk import BOT

import 后实例化 BOT，并载入机器人 bot_id（BotAppID）和 bot_token（机器人令牌）：

bot = BOT(bot_id="xxx", bot_token="xxx")
# 如为公域机器人，需传入is_private参数，如下：
# bot = BOT(bot_id="xxx", bot_token="xxx", is_private=False)

之后，便可以编写一个简单的接收事件函数，当中的 data 是最上层包含所有数据的一个物件，而 data 之下衍生的：treated_msg 是经过处理（包括去除艾特机器人的字段、去除/字段等）的内容、id 代表的是 msg_id 消息 ID、channel_id 代表的是子频道 ID：

def deliver(data):
    if "你好" in data.treated_msg:
        data.reply("你好世界")

而同时，可以从 model 库调用模型数据，验证如 data.channel_id，data.id 等的结构是否存在：

from qg_botsdk import Model   # 导入数据模型

def deliver(data: Model.MESSAGE):   # Model.MESSAGE为导入的一个数据模型
    if "你好" in data.treated_msg:
        data.reply("你好世界")

并注册该回调函数到实例化的 BOT 中：

bot.bind_msg(deliver)

最后，开始运行机器人：

bot.start()

因此，完整的代码流程为：

# 导入SDK核心类（BOT）、所有数据模型（Model）
from qg_botsdk import BOT, Model

def deliver(data: Model.MESSAGE):   # 创建接收消息事件的函数并绑定数据模型
    if "你好" in data.treated_msg:   # data.treated_msg 为消息内容
        data.reply("你好世界")

bot = BOT(bot_id="xxx", bot_token="xxx") # 实例化SDK核心类
bot.bind_msg(deliver)  # 绑定接收消息事件的回调函数
bot.start()  # 开始运行机器人

使用上述代码，并填入 bot_id（BotAppID）和 bot_token（机器人令牌）后，可直接开始运行机器人。当在添加了相应机器人的 QQ 频道中，输入”你好”或“/你好”，机器人随之会回复”你好，世界”

可通过添加 is_sandbox=True 参数到实例化的核心类中，开启沙箱环境进行测试，整体指令如下： BOT(bot_id="xxx", bot_token="xxx", is_sandbox=True)

沙箱环境定义：

沙箱频道路径：机器人平台后台管理端-设置-沙箱频道

额外功能¶

qg_botsdk 提供了检查数据结构的模型，导入方法如下：

from qg_botsdk import Model   # 导入数据模型

导入后，即可透过类型提示（data: MESSAGE）的方法验证数据结构正确性：

def deliver(data: Model.MESSAGE):  # Model.MESSAGE为导入的一个数据模型
    if '你好' in data.treated_msg:
        data.reply("你好世界")

当使用数据子项时，你使用的 IDE 理论上将会有相应的子数据结构提示：

而当输入错误的数据结构（正确的字段名为 treated_msg ，而非 treatedmsg ）时，你使用的 IDE 理论上将会提示错误：

提审¶

在开发完机器人的指令功能后，请注意大家需要切换到正式环境后再在机器人平台后台提交审核，具体方法为在实例化 BOT(bot_id="xxx", bot_token="xxx") 时添加一个参数：

bot = BOT(bot_id="xxx", bot_token="xxx", is_sandbox=False)

这个 is_sandbox 的参数代表是否使用沙箱环境，当其为 False 时则代表使用正式环境，切换后就可以前去提交审核了。

更多实例化 BOT()时可使用的参数请参阅{any} SDK组件-主要组件 <实例化机器人> 。

快速入门¶

安装¶

注册机器人¶

创建并使用¶

额外功能¶

提审¶

更多工作流实例¶