# mirai-api-http交互工具 **Repository Path**: linux-rm/mirai-api-http-cpp-client ## Basic Information - **Project Name**: mirai-api-http交互工具 - **Description**: 一个易用的开源mirai-api-http交互工具 介绍编写中 - **Primary Language**: C++ - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2023-01-25 - **Last Updated**: 2024-08-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 一个易用的开源mirai-api-http交互工具 # mirai-api-http 使用方法(新手必看) ## 安装mirai-api-http ```bash ./mcl --update-package net.mamoe:mirai-api-http --channel stable-v2 --type plugin ./mcl -u ``` ## 配置 1. 编辑`config/net.mamoe.mirai-api-http/setting.yml`配置文件 (没有则自行创建) 2. 启动MCL `./mcl` 3. 记录日志中出现的`authKey`(如果有) [查看官方setting.yml模板](https://github.com/project-mirai/mirai-api-http#settingyml%E6%A8%A1%E6%9D%BF) 或使用我的setting.yml模板 ```yml ## 启用的 adapter, 内置有 http, ws, reverse-ws, webhook adapters: - http ## 是否开启认证流程, 若为 true 则建立连接时需要验证 verifyKey ## 建议公网连接时开启 enableVerify: false verifyKey: 00000000 ## 是否开启单 session 模式, 若为 true,则自动创建 session 绑定 console 中登录的 bot ## 开启后,接口中任何 sessionKey 不需要传递参数 ## 若 console 中有多个 bot 登录,则行为未定义 ## 确保 console 中只有一个 bot 登录时启用 singleMode: true ## adapter 的单独配置,键名与 adapters 项配置相同 adapterSettings: ## 详情看 http adapter 使用说明 配置 http: host: 0.0.0.0 port: 8080 cors: ["*"] unreadQueueMaxSize: 100 ``` ## 验证 打开浏览器或网络工具(如 curl),直接访问[localhost:8080/about](localhost:8080/about) 正常情况下会显示 ![chrome-about](image/chrome-about.png) ![curl-about](image/curl-about.png) ```json {"code": 0,"msg": "","data": {"version":"xxx"}} ``` 证明安装并启动成功 ## 使用 --- --- ### GET请求 想一想刚刚验证插件时,我们在浏览器访问了[localhost:8080`/about`](localhost:8080/about) 查阅[官方文档](https://github.com/project-mirai/mirai-api-http/blob/master/docs/adapter/HttpAdapter.md#%E5%85%B3%E4%BA%8E),发现`/about` Get 请求可以获取插件信息 --- ### 关于 使用此方法获取插件的信息,如版本号 ``` [GET] /about ``` 通用接口定义: [关于](https://github.com/project-mirai/mirai-api-http/blob/master/docs/api/API.md#%E5%85%B3%E4%BA%8E) --- 仔细看,是不是我们在主机地址后面加入了和文档一样的`/about` 如果成功,那么你学会了 可能你会觉得难,但跟着我的步伐走绝对没错 #### 举一反三 --- ### 获取登录账号 使用此方法获取所有当前登录账号 ``` [GET] /botList ``` 通用接口定义: [获取登录账号](https://github.com/project-mirai/mirai-api-http/blob/master/docs/api/API.md#%E8%8E%B7%E5%8F%96%E7%99%BB%E5%BD%95%E8%B4%A6%E5%8F%B7) --- ### 获取好友资料 此接口获取好友的详细资料 ``` [GET] /friendProfile ``` **本接口为\[GET\]请求, 参数格式为url参数** 通用接口定义: [获取好友资料](https://github.com/project-mirai/mirai-api-http/blob/master/docs/api/API.md#%E8%8E%B7%E5%8F%96%E5%A5%BD%E5%8F%8B%E5%88%97%E8%A1%A8) --- 提示: 1. 参数: 在原有的链接后面加上`问号`, 再接上`名称1=参数1&名称2=参数2...` 例如:`localhost:8080/friendProfile?target=114514` 2. 你可以在`setting.yml`里设置以下内容来禁用验证,或者不设置稍后学习POST得到sessionKey ```yml enableVerify: false verifyKey: 00000000 singleMode: true ``` --- --- ### POST 请求 POST请求稍微复杂一些 你需要其中一种方式配合网络工具 `curl` 使用: * 安卓手机 Termux * linux系统 * windows10+ * Mac OS 或者电脑 `Chrome / Chromium` __先别着急执行命令,因为命令中全部大写的单词 `URL`,`TYPE`,`BODY`参数还没给!!!__ ### curl 终端命令用法: ```bash curl -X POST -H "Content-Type:TYPE" -d 'BODY' URL ``` __先别着急执行命令,因为命令中全部大写的单词 `URL`,`TYPE`,`BODY`参数还没给!!!__ ### 电脑 Chrome/Chromium js命令用法: ```js fetch(new Request('URL',{ method:'POST', headers: {'Content-Type': 'TYPE'}, body:'BODY' })) ``` __先别着急执行命令,因为命令中全部大写的单词 `URL`,`TYPE`,`BODY`参数还没给!!!__ ### 参数(仅JSON) #### URL 其实,URL和Get请求相似,都是在主机地址后加上请求,这个我不再详细阐述 localhost:8080`/verify` 但参数要放在`BODY`里, 而且是json #### TYPE 几乎都是`application/json` ~~备注:只有多媒体内容上传才都是`multipart/form-data`,这个先忽略,作者还不会~~ #### BDDY 这是请求,你需要参阅文档并按实际情况修改 查阅[官方文档](https://github.com/project-mirai/mirai-api-http/blob/master/docs/adapter/HttpAdapter.md),发现`/verify` Post 请求可以认证 --- ### 认证 #### 接口名称 ``` [POST] /verify ``` 使用此方法验证你的身份,并返回一个会话 #### 请求: ```json5 { "verifyKey": "U9HSaDXl39ksd918273hU" } ``` | 名字 | 类型 | 可选 | 举例 | 说明 | | --------- | ------ | ----- | ----------------------- | ---------------------------------------------------------- | | verifyKey | String | false | "U9HSaDXl39ksd918273hU" | 创建Mirai-Http-Server时生成的key,可在启动时指定或随机生成 | #### 响应: ```json5 { "code": 0, "session": "UnVerifiedSession" } ``` | 名字 | 类型 | 举例 | 说明 | | ------- | ------ | ------------------- | --------------- | | code | Int | 0 | 返回状态码 | | session | String | "UnVerifiedSession" | 你的session key | session key 是使用以下方法必须携带的 session key 使用前必须进行校验和绑定指定的Bot,**每个Session只能绑定一个Bot,但一个Bot可有多个Session** session Key 在未进行校验的情况下,一定时间后将会被自动释放 --- 示例: 实际情况: ```yml ## 是否开启认证流程, 若为 true 则建立连接时需要验证 verifyKey ## 建议公网连接时开启 enableVerify: false verifyKey: 00000000 ``` ```json { "verifyKey": "00000000" } ``` 参数准备完毕,你可以尝试了 curl: 提示: curl的 BODY 参数可以换行 ```bash curl -X POST -H "Content-Type:application/json" -d ' { "verifyKey": "00000000" } ' localhost:8080/verify ``` js: js需要格外注意: 1. URL 参数前一定要有 `http://`, 否则会提示不安全或403拒绝 2. BODY 参数不能换行 ```js fetch(new Request('http://localhost:8080/verify',{ method:'POST', headers: {'Content-Type': 'application/json'}, body:'{"verifyKey": "00000000"}' })) ``` 注:由于我关闭了verifyKey验证,所以提示"SINGLE_SESSION" ![curl](image/curl-verify.png) ![js1](image/js-1.png) ![js2](image/js-2.png) **注意** --- ### 传递(重要) `sessionKey` 作为会话的唯一标识, 它对应着服务器缓存及其上下文. 在 `adapter` 允许的情况下, 复用 `sessionKey` 创建多个连接会共享上下文 > `HttpAdapter` 允许复用 `sessionKey` 创建多个连接 在 `singleMode` 模式下: 所有需要 `sessionKey` 参数的接口可忽略 `sessionKey` 在非 `singleMode` 模式下 `sessionKey` 可通过以下方式传递: 1. 设置请求头 `sessionKey: YourSessionKey`, 大小写敏感 2. 设置请求头 `Authorization: session YourSessionKey`, `Authorization` 大小写敏感, `session` 大小写不敏感 3. 设置请求头 `Authorization: sessionKey YourSessionKey`, `Authorization` 大小写敏感, `sessionKey` 大小写不敏感 4. 通过 url参数(对于GET请求)或 json 参数(对于POST请求)填入 `sessionKey` 字段, 大小写敏感 --- #### 举一反三 --- ### 绑定 ``` [POST] /bind ``` 使用此方法校验并激活你的Session,同时将Session与一个**已登录**的Bot绑定 #### 请求: ```json5 { "sessionKey": "UnVerifiedSession", "qq": 123456789 } ``` | 名字 | 类型 | 可选 | 举例 | 说明 | | ---------- | ------ | ----- | ------------------- | -------------------------- | | sessionKey | String | false | "UnVerifiedSession" | 你的session key | | qq | Long | false | 123456789 | Session将要绑定的Bot的qq号 | #### 响应: ```json5 { "code": 0, "msg": "success" } ``` --- ### 释放 ``` [POST] /release ``` 使用此方式释放session及其相关资源(Bot不会被释放) **不使用的Session应当被释放,长时间(30分钟)未使用的Session将自动释放,否则Session持续保存Bot收到的消息,将会导致内存泄露(开启websocket后将不会自动释放)** #### 请求: ```json5 { "sessionKey": "YourSessionKey", "qq": 123456789 } ``` | 名字 | 类型 | 可选 | 举例 | 说明 | | ---------- | ------ | ----- | ---------------- | -------------------------- | | sessionKey | String | false | "YourSessionKey" | 你的session key | | qq | Long | false | 123456789 | 与该Session绑定Bot的QQ号码 | --- ### 发送好友消息 使用此方法向指定好友发送消息 ``` [POST] /sendFriendMessage ``` **本接口为\[POST\]请求, 参数格式为`application/json`** 通用接口定义: [发送好友消息](https://github.com/project-mirai/mirai-api-http/blob/master/docs/api/API.md#%E5%8F%91%E9%80%81%E5%A5%BD%E5%8F%8B%E6%B6%88%E6%81%AF) --- ### 更多:[参阅官方文档](https://github.com/project-mirai/mirai-api-http/blob/master/docs/adapter/HttpAdapter.md)