HTTP

OneBot 在启动时开启一个 HTTP 服务器,监听配置文件指定的 IP 和端口,接受路径为 /:action 的 API 请求(或 /:action/),如 /send_private_msg,请求可以使用 GET 或 POST 方法,可以通过 query 参数(?arg1=111&arg2=222)、urlencoded 表单(arg1=111&arg2=222)或 JSON({"arg1": "111", "arg2": "222"})传递参数。

参数可能有不同的类型,当用户通过 query 参数或 urlencoded 表单传参,或在 JSON 中使用字符串作为参数值时,OneBot 实现需要从字符串解析出对应类型的数据。

请求

假设配置中指定了 IP 和端口分别为 127.0.0.15700,则在浏览器中访问 http://127.0.0.1:5700/send_private_msg?user_id=1000010000&message=hello 即可给 QQ 号为 1000010000 的好友发送私聊消息 hello

如需使用 JSON 传递参数,则请求如下:

POST /send_private_msg HTTP/1.1
Host: 127.0.0.1:5700
Content-Type: application/json

{
    "user_id": 1000010000,
    "message": "hello"
}

注意

上例中调用的 API(即 action)为 send_private_msg,其它 API 及它们的参数和响应内容,见 API

响应

收到 API 请求并处理后,OneBot 会返回一个 HTTP 响应,根据具体情况不同,HTTP 状态码不同:

状态码为 200 时,响应内容为 JSON 格式,基本结构如下:

{
    "status": "ok",
    "retcode": 0,
    "data": {
        "id": 123456,
        "nickname": "滑稽"
    }
}

status 字段表示请求的状态:

data 字段为 API 返回数据的内容,对于踢人、禁言等不需要返回数据的操作,这里为 null,对于获取群成员信息这类操作,这里为所获取的数据的对象,具体的数据内容将会在相应的 API 描述中给出。注意,异步版本的 API,data 永远是 null,即使其相应的同步接口本身是有数据。

相关配置

提示

配置项名称仅供参考,不同 OneBot 实现可以自行定义名称,只需在样例配置中给出注释即可。

配置项 默认值 说明
http.enable true 是否启用 HTTP
http.host 0.0.0.0 HTTP 服务器监听的 IP
http.port 5700 HTTP 服务器监听的端口

上一节 下一节
通信概述 HTTP POST