HTTP-API: CoolQ/CleverQQ Extensioin

扩展你的QQ/微信机器人用途，提供跨框架平台的PHP/Java/Python/NodeJS等编程语言SDK。

HTTP-API简介

HTTP-API是一款主要通过HTTP协议（另外也包含使用webSocket、socket等协议）与机器人进行通信的插件，主要提供PHP/Java/Python/NodeJS等编程语言SDK，以便将机器人用于WEB、大数据、机器学习等领域，尽可能地提现数据的价值。
目前插件主要支持CleverQQ机器人框架，并兼容酷Q机器人应用，开发者可以通过使用SDK非常方便地对机器人进行操作，比如控制机器人发送消息、公告，获取机器人群列表、好友列表，通过及监听获取近一个月、或者几年的聊天记录。开发者可通过简单的操作完成一些小程序、小应用对的开发，亦可应用于大型应用中。
此外，通过配合使用WEB管理平台，开发者可将自己开发的应用发布到应用商店中，通过用户安装的方式获得收入、使用数据等。用户可直接通过WEB平台安装、管理应用，以及可以批量管理机器人在线状态、收发消息等，让用户用最少的时间完成尽可能多的事。
注：以下表格描述中CleverQQ简称IR，CoolQ（酷Q）简称CQ
交流群：（QQ群，用户加入）537419179
开发群：（QQ群，开发者加入）598629636
管理平台：http://work.ksust.com

版本分布（来源）

• 注：允许开发者发布自己的SDK（参考标准SDK中HTTP-API协议）,若需要将SDK加入上述版本仓库，请联系admin@ksust.com

功能介绍

本插件主要包含三种工作机制，即提交返回、主动推送、消息转发，第一种为被动接受，后两种为主动操作，其中提交返回包括HTTP方式、webSocket方式，主动推送使用HTTP方式，消息转发目前仅公开使用HTTP方式，几种方式中HTTP提交返回最常用也最通用。
下面将简单介绍插件的几种工作方式，相关配置请结合插件进行（页底使用引导）。

提交返回

提交返回是最常用的一种工作方式，其原理为：机器人插件作为客户端（做网页请求），开发者开发WEB服务端；在工作时，插件将收到的消息（如QQ消息）经过协议封装后发送到开发者的WEB服务，该服务队发送过来的数据进行处理并返回给插件一些操作命令（如发送消息）。至此，一次简单的工作流程结束。
显然，该工作流程是被动的，开发者的WEB服务必须等待插件访问才能执行相关逻辑，在这种机制下某些操作不能完成。于是，本插件引入WEB回调，即WEB服务向插件发送回调指令（当然得插件先访问WEB服务），表达自己想要的数据（如获取群列表），插件再收到回调指令后会立即将相关数据封装（如群列表）后发送到WEB服务。
在具体开发中，常用的协议为HTTP，即在插件中填入http://...的地址，将程序部署到WEB服务器上；另外，为了更便于双向通信，同时提供了webSocket支持，只需在相关位置填入类似ws://...地址即可。

主动推送

主动推送是通过HTTP协议对机器人插件进行相关操作的一种方式。其原理为：插件作为HTTP服务器，开发者的应用（使用SDK）作为客户端，开发者可直接主动地操作插件（如主动发送消息、主动获取群列表等）。
此方式的相关操作均为主动操作，一般结合提交返回进行使用，并一般要求插件所在服务器/电脑有固定的公网IP（该条件限制太大，如果没有公网IP，下述消息转发是一种可用的替代方式）。

消息转发

消息转发解决了无公网IP以及不能主动操作的问题，原则上开发者不需要服务器也能获得提交返回、主动推送的功能，并且更加便捷。其原理为：除插件和开发者外，存在若干的转发服务器（转发服务器集群），这些服务器对开发者的操作以及插件产生的消息进行转发，以达到开发者与插件通信的目的。
目前本方式只开放HTTP方式，即只能完成上述主动推送的任务（但是不要求有公网IP）。开发者只需要直到机器人的QQ、授权码即可对机器人进行主动操作，任意一方均不要求有公网IP。

快速开始

以下将使用提供的PHP/Java/Python/NodeJS编程语言SDK开发Demo，以便开发者快速入门。
以下操作建立在配置好插件基础上，相关步骤参考请到跳转到页面底部了解。Demo中使用的SDK均可在本项目GITHUB上下载到，Demo适配的最低版本为2.2.2。 所示Demo包含本插件三大功能（提交返回[包含webSocket]、HTTP主动推送、消息转发推送），相关demo可在本项目demo中下载。

PHP Demo

提交返回

<?php
//插件的提交返回地址中配为本文件的访问地址
error_reporting(0);
header("Content-Type:text/html;Charset=utf8");//设置编码，必需
include 'HTTPSDK.php';
$sdk = HTTPSDK::httpGet();
$msg = $sdk->getMsg();//插件发送过来的消息
$sdk->sendPrivateMsg($msg['QQ'], '你发送了这样的消息：' . $msg['Msg']);//逻辑代码，向发送者回消息
echo $sdk->toJsonString();//命令返回

webSocket（结合使用workman）

<?php
//websocket（结合使用workman）,插件的提交返回地址中配为相关地址（websocket://0.0.0.0:2346），命令行中启动本文件（php demo-ws.php restart）
//workman下载地址：https://www.workerman.net/download/workermanzip
header("Content-type:text/html;charset=utf-8");
require_once __DIR__ . '/workman/Autoloader.php';
use Workerman\Worker;

require_once 'HTTPSDK.php';
// Create a Websocket server
$ws_worker = new Worker("websocket://0.0.0.0:2346");
// 4 processes
$ws_worker->count = 4;
// Emitted when new connection come
$ws_worker->onConnect = function ($connection) {
    echo "New connection\n";
};
// Emitted when data received
$ws_worker->onMessage = function ($connection, $data) {
    $json = json_decode(urldecode(urldecode($data)), true);
    if (isset($json['type']) && $json['type'] == 'init') {
        $connection->send('{"type":"success"}');
    } else {
        //消息操作
        $sdk = HTTPSDK::webSocket($data);
        $msg = $sdk->getMsg();
        if ($msg['Msg'] == 'demo') {
            $sdk->sendPrivateMsg($msg['QQ'], '你发送了这样的消息：' . $msg['Msg']);//逻辑代码，向发送者回消息
        }
        //echo $sdk->toJsonString();
        $connection->send($sdk->toJsonString());
    }

};
// Emitted when connection closed
$ws_worker->onClose = function ($connection) {
    echo "Connection closed\n";
};
// Run worker
Worker::runAll();

HTTP推送

<?php
header("Content-Type:text/html;Charset=utf8");//设置编码，必需
include 'HTTPSDK.php';
//插件中开启推送，并设置端口为8080
$push = HTTPSDK::httpPush('http://127.0.0.1:8080');
var_dump($push->getLoginQQ());//获取登录的QQ
var_dump($push->sendPrivateMsg('QQ', 'hello~'));//向QQ发送消息
var_dump($push->getFriendList());//获取好友列表

消息转发

<?php
header("Content-Type:text/html;Charset=utf8");//设置编码，必需
include 'HTTPSDK.php';
//保证插件再2.2.2及以上并启动
$forward = HTTPSDK::msgForwardPush('QQ', 'code');//输入QQ和授权码（http://work.ksust.com）
var_dump($forward->getLoginQQ());//获取登录的QQ
var_dump($forward->sendPrivateMsg('QQ', 'hello~'));//向QQ发送消息
var_dump($forward->getFriendList());//获取好友列表

Java Demo

Java Demo项目地址：https://github.com/ksust/HTTP-API-Java-Demo

SDK引入方式

1. Maven引入
   Java SDK已经提交Maven中央仓库，直接在pom文件中配置。在pom中加入如下代码即可：

<dependencies>
    <dependency>
        <groupId>com.ksust.qq</groupId>
        <artifactId>http-api-sdk</artifactId>
        <version>2.2.2</version>
    </dependency>
</dependencies>

2. jar包引入（需要手动解决依赖）
   可直接使用jar包（包名如：http-api-sdk-2.2.2.jar），在项目中下载即可，需要手动解决依赖。所需要的依赖及版本如下：（另外可以直接使用3提供的独立jar包，不用解决依赖问题）

    <properties>
        <okttp.version>3.8.1</okttp.version>
        <validator.version>4.2.0.Final</validator.version>
        <lombok.version>1.16.10</lombok.version>
        <fastjson.version>1.2.31</fastjson.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-validator</artifactId>
            <version>${validator.version}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
        </dependency>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>${fastjson.version}</version>
        </dependency>
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
            <version>${okttp.version}</version>
        </dependency>

    </dependencies>

3. jar包引入（包含所需依赖，独立jar包）
   包含后缀-with-dependencies的jar包中已经包含依赖，如http-api-sdk-2.2.2-jar-with-dependencies.jar

提交返回

//本样例基于SpringBoot，可运行的Demo在项目中可直接下载。主要代码如下：
@RestController
public class HTTPSDKDemo {
    @GetMapping("/test")
    public String test() {
        return "success";
    }


    private void test(MessageGet msg) {
        System.out.println(JSON.toJSONString(msg));
    }

    //提交返回演示：外部地址（插件中填的请求地址）：http://yourIP:9999/ip
    @PostMapping(value = "/qq")
    public String qq(@RequestBody String data) throws Exception {
        //外部消息通过这个方法进入，请求地址即为 POST host:port/qq
        //开始演示：发送消息回复（点赞等），并且演示通过提交返回获取群列表
        HTTPSDK httpsdk = HTTPSDK.httpGet(data);
        //插件发来的消息
        MessageGet msg = httpsdk.getMsg();
        test(msg);
        if (httpsdk.getMsg().getType() == TypeEnum.FRIEND.getCode() && !httpsdk.isCallback()) {
            //私聊消息
            //点赞、抖窗、回复
            httpsdk.sendLike(msg.getQQ(), 2);
            httpsdk.sendShake(msg.getQQ());
            httpsdk.sendPrivateMsg(msg.getQQ(), "Hello，这里是HTTP-API演示程序，你发送的消息为：" + msg.getMsg()
                    + "。我还给你点了两个赞哦~");
            //发起获取群列表的请求（提交请求下不能立即得到），待下一次请求时携带消息
            httpsdk.getGroupList();
        }

        //接收 WEB回调消息。
        if (httpsdk.isCallback()) {
            //打印群列表
            if (msg.getType() == TypeEnum.GET_GROUP_LIST.getCode()) {
                for (Group group : httpsdk.getGroupList()) {
                    System.out.println(group.getGroupName() + "," + group.getGroupId());
                }
            }
        }
        //必须！！！向插件回复消息并清空当前对象待发送消息
        return httpsdk.toJsonString();
    }
}

webSocket

//与PHP版本类似，传入获取的字符串即可。取决于用什么框架，和上述提交返回使用方法基本相同，这里不再赘述。

HTTP推送

//推送测试代码如下，插件中开启推送，并设置端口为8080
public class HTTPSDKPushDemo {
    public static void main(String[] args) {
        //首先擦创建对象，支持加密。详情请查看文档
        HTTPSDK httpsdkPush = HTTPSDK.httpPush("http://127.0.0.1:8080", null, null);
        //引号中为测试QQ号
        String qq = "1402549575";
        //发送消息
        httpsdkPush.sendPrivateMsg(qq, "Hello World[ksust,at_all:qq=all][ksust,music:name=明天]");
        httpsdkPush.sendGroupMsg("244510218", "hello[ksust,at_all:qq=all][ksust,music:name=明天]");
        //点赞
        httpsdkPush.sendLike(qq, 1);
        //查看点赞数量
        System.out.println(httpsdkPush.getLikeCount(qq));
        //查看机器人当前状态
        System.out.println(JSON.toJSONString(httpsdkPush.getQQRobotInfo()));
    }
}

消息转发

//保证插件再2.2.2及以上并启动
public class MsgForwardDemo {
    public static void main(String[] args) throws IOException {
        HTTPSDK forwardPush = HTTPSDK.msgForwardPush("QQ", "code");//输入QQ和授权码
        System.out.println(forwardPush.getLoginQQ());
        System.out.println(forwardPush.sendPrivateMsg("QQ", "hello"));
        List<GroupMember> groupMemberList = forwardPush.getGroupMemberList("群号");
        for (GroupMember groupMember : groupMemberList) {
            System.out.println(groupMember.getName() + "," + groupMember.getQq());
        }
    }
}

Python Demo

安装(Python2/3)：pip install http-api-sdk

提交返回

# 独立demo：https://github.com/ksust/http_api_django_demo

webSocket

#原理同提交返回，取决于使用什么外部框架。

HTTP推送

#!/usr/bin/env python
# -*-coding:utf-8-*-
"""
Demo Push
HTTP-API Python SDK(Python2、python3)
 * Created by PyCharm.
 * User: yugao
 * version 2.2.2
 * Note: HTTPSDK for Python(适用于版本2.2.2插件):用于解析插件消息、构造返回数据，以及HTTP推送（发起HTTP请求）
 * Contact: 开发者邮箱 admin@ksust.com
 * 安装：pip install http-api-sdk
"""

from httpapi.HTTPSDK import *

if sys.version_info.major == 2:
    reload(sys)  # python2请配置相应编码
    sys.setdefaultencoding('utf8')
    sys.setdefaultencoding('gb18030')

push = HTTPSDK.httpPush("http://127.0.0.1:8080")
print(push.getGroupList())
print(push.sendPrivdteMsg('QQ', '你好'))

forward = HTTPSDK.msgForwardPush('QQ', '授权码')
print(forward.getGroupList())
print(forward.getLoginQQ())
print(forward.sendPrivdteMsg('QQ', '你好'))
print(forward.getQQRobotInfo())

消息转发

#上述推送中包含消息转发（forward）

NodeJS Demo

安装依赖：npm install http-api-sdk
引用包：如 const HTTPSDK = require('http-api-sdk');

提交返回

/**
 * Demo
 * User: yugao
 * Date: 2019/2/27
 * version 2.2.2
 * Note: HTTPSDK for NodeJS(适用于版本2.2.2插件):用于解析插件消息、构造返回数据，以及HTTP推送（发起HTTP请求）
 * Contact: 开发者邮箱 admin@ksust.com
 * 安装SDK：npm install http-api-sdk
 */
const http = require('http');
const HTTPSDK = require('http-api-sdk');
const server = http.createServer((req, res) => {
    req.on('data', function (data) {
        let sdk = HTTPSDK.httpGet(data.toString());
        //console.log(sdk.getMsg());//获取到的消息
        sdk.sendPrivateMsg(sdk.getMsg()['QQ'], '你发送了这样的消息：' + sdk.getMsg()['Msg']);
        sdk.getLoginQQ();
        //回调演示，提交返回获取群列表、登录QQ等
        if (sdk.isCallback() && parseInt(sdk.getMsg()['Type']) === HTTPSDK.TYPE_GET_LOGIN_QQ) {
            console.log('Login QQ:' + sdk.getLoginQQ());
        }
        res.end(sdk.toJsonString());
    });
});
server.on('clientError', (err, socket) => {
    socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);

webSocket（）

//与PHP版本类似，传入获取的字符串即可。取决于用什么框架，和上述提交返回使用方法基本相同，这里不再赘述。

HTTP推送

/**
 * Demo
 * User: yugao
 * Date: 2019/2/27
 * version 2.2.2
 * Note: HTTPSDK for NodeJS(适用于版本2.2.2插件):用于解析插件消息、构造返回数据，以及HTTP推送（发起HTTP请求）
 * Contact: 开发者邮箱 admin@ksust.com
 * 安装SDK：npm install http-api-sdk
 */
const HTTPSDK = require('http-api-sdk');
//推送演示，需要配置推送
push = HTTPSDK.httpPush('http://127.0.0.1:8080')
push.getGroupList().data(function (data) {
    console.log('push ' + data)
});
push.getLoginQQ().data(function (data) {
    console.log('push ' + data)
});
push.sendPrivateMsg('QQ', 'Hello').data(function (data) {
    console.log('push ' + data)
});
//消息转发演示，插件在线即可用
let forward = HTTPSDK.msgForwardPush('QQ', '授权码');
forward.getLoginQQ().data(function (data) {
    console.log('forward ' + data);
});
forward.getGroupList().data(function (data) {
    console.log('forward ' + data);
});
forward.sendPrivateMsg('QQ', 'Hello').data(function (data) {
    console.log('forward' + data)
});

消息转发

//上述推送中包含消息转发（forward）

SDK参考手册

事件ID及标签

事件ID

其中值>20000的为操作代码，其余的为事件ID。

消息标签

消息标签用于特殊消息发送，例如卡片、@全体成员、音乐标签等，目前支持的标签如下：

数据结构

简单列出必要的几种数据结构（使用JSON格式描述），其余请开发者在开发中查看SDK或者打印。

提交返回-插件提交-数据结构（接口getMsg()返回值）

{
	Myqq:机器人QQ,
	Type:"消息类型，举例：【详看消息类型】 -1 未定义事件 1 好友信息 2,群信息 3,讨论组信息 4,群临时会话 5,讨论组临时会话 6,财付通转账,
	SubType:接收财付通转账时 1为好友 2为群临时会话 3为讨论组临时会话    有人请求入群时，不良成员这里为1,
	From:此消息的来源，如：群号、讨论组ID、临时会话QQ、好友QQ,
	Group:来源群号，若无则为空,
	Discuss:来源讨论组，若无则为空,
	QQ:主动发送这条消息的QQ，踢人时为踢人管理员QQ,
	ObjectQQ:被动触发的QQ，如某人被踢出群，则此参数为被踢出人QQ,
	Msg:消息文本内容（当消息为JSON、XML时为相应内容）。消息反馈时为消息反馈文本（如取群列表）,
	ID:消息id，用于识别消息【如异步处理时】、撤回等，构成：消息序号-消息ID,
	Data:{
		//携带数据，如当消息为转账消息时，则有相关属性。以下举例转账消息
		"Comments": "接收到转账时留言",
		"Money": "接收到转账时金额（数字）",
		"Number": "接收到转账时订单号"
		}
}

提交返回-返回处理-数据结构（WEB返回）

{
					
	data:[
		{
            ID：唯一标识,UUID，
			Type:发送消息类型【具体查看SDK】， 1 好友信息 2,群信息 3,讨论组信息 4,群临时会话 5,讨论组临时会话 ...,20001 点赞,20002 窗口抖动,20011 群禁言（管理）,20012 退群,20013 踢群成员（管理）,20021 设置群名片（管理）,20022 设置群管理（群主）,20023 入群处理（某人请求入群、我被邀请入群、某人被邀请入群）,20024 加好友处理（是否同意被加好友）,20031 发公告,20032 发作业 等
			SubType:子类型，0普通，1匿名（需要群开启，默认0）,
			StructureType:消息结构类型，0为普通文本消息（默认）、1为XML消息、2为JSON消息,
			Group:操作或发送的群号或者讨论组号,
			QQ:操作或者发送的QQ,
			Msg:文本消息【标签等】，当发送类型为JSON、XML时为相应文本，禁言时为分钟数【分钟】,
			Send:是否开启同步发送（1为开启同步发送【测试】，0为不开启【默认】）,
			Data:附加数据，用于特定操作等（文本型）
		} ,
		{
			...		
		}
	    ]
}

推送（转发）-发送-数据结构

{
	time:验证的时间戳,
	verify:验证字符串,
	data:[ //暂时仅允许一个成员
		{
            ID：唯一标识,UUID，
			Type:发送消息类型， 1 好友信息 2,群信息 3,讨论组信息 4,群临时会话 5,讨论组临时会话 ...,20001 点赞,20002 窗口抖动,20011 群禁言（管理）,20012 退群,20013 踢群成员（管理）,20021 设置群名片（管理）,20022 设置群管理（群主）,20023 入群处理（某人请求入群、我被邀请入群、某人被邀请入群）,20024 加好友处理（是否同意被加好友）,20031 发公告,20032 发作业 
			SubType:子类型，0普通，1匿名（需要群开启，默认0）,
			StructureType:消息结构类型，0为普通文本消息（默认）、1为XML消息、2为JSON消息,
			Group:操作或发送的群号或者讨论组号,
			QQ:操作或者发送的QQ,
			Msg:文本消息【标签等】，当发送类型为JSON、XML时为相应文本，禁言时为分钟数【分钟】,
			Send:是否开启同步发送（1为开启同步发送【测试】，0为不开启【默认】）,
			Data:附加数据，用于特定操作等（文本型）
		}
	]
}

插件界面及使用引导

用户使用流程引导

对于使用本插件的用户来说，除了第一次配置插件外，几乎所有操作均在管理平台上进行（包括安装应用、查看机器人状态等）。
对于新用户，步骤如下：

1.注册平台账户（用于线上管理、安装）

• 至管理平台注册用户（用户名最好为英文）http://work.ksust.com
• 加入用户QQ群（用于应用审核等）：（QQ群，用户加入）537419179

2.安装并启用插件（CleverQQ）

• 首先你需要至少登录成功一个机器人QQ。
• 对于CleverQQ，直接下载 HTTP-API.IR.DLL放入插件目录（plugin），然后启用插件即可。
• 如果你是新用户，你可以再次直接下载已经安装好HTTP-API的CleverQQ。下载地址：CleverQQ-HTTP-API

2.安装并启用插件（酷Q）

• 首先你需要至少登录成功一个机器人QQ。
• 直接下载 com.ksust.qq.http-api.cpk放入插件目录（app），然后启用插件即可。
• 如果你是新用户，你可以再次直接下载已经安装好HTTP-API的CQ。下载地址：CQ-HTTP-API

3.重启机器人框架

• 上一步过后，请记得重启机器人，以获取授权码、载入新配置等。

4.打开插件设置进行配置

• 上一步重启机器人并至少登录成功一个机器人QQ后，打开HTTP-API设置，按下图顺序操作；绑定时输入你在平台注册的用户名和密码。
  
• 插件配置完成后，登录管理平台，进入授权管理，此时可以看到你绑定的机器人QQ。
  

5.主人QQ绑定

• 在平台右上角选择绑定主人，选择主人QQ，输入你加入用户QQ群的QQ号（机器人不用加群），点击提交。
  
• 在用户QQ群中发送 验证主人 即可成功绑定。群内发送帮助可获取帮助信息。

6.安装应用及应用审核

• 进入应用商店，点击一款应用进行在线安装。
  
• 在用户QQ群中发送 应用审核 即可自动审核应用。
  
• 等待1分钟或者进入插件设置，点击更新配置后保存，即可看到安装的应用已经成功运行。
  

以上流程为新用户完整流程，尽量描述详细，具体执行过程1-2分钟即可完成；对于老用户，则直接绑定平台账号即可。

开发者相关配置

对于开发者，主要包含开发、发布两个流程。下面主要介绍开发过程中的相关配置，更多请加入开发群了解，开发群也有免费视频培训。

开启开发者模式

• 开启开发者模式

提交返回配置

• 提交返回一般只需填提交URL即可，URL填HTTP协议地址（如http://127.0.0.1），或者填webSocket地址（如ws://127.0.0.1:2346），点击测试即可查看测试结果（测试发起的GET请求）。

主动推送配置

• 主动提交一般只需开启服务，配置监听端口即可。

定时任务配置

• 定时任务只需开启服务并添加任务URL（只能是http://XXX），填写任务间隔（秒）即可，任务间隔最小为1秒。

发布应用到平台

• 应用发布是针对已经认证开发者的开发者。可以在平台上发布开发的应用，用户可很方便地通过线上安装运行你的应用，另外开发者也可以通过这种方式获得收入（应用安装收费）。详情请加入开发群。

如果你觉得本项目还不错，可以捐助本项目，你的捐赠将会使作者更具开发/更新的信心，同时也能推进本项目的发展（在捐助的时候可以备注您的QQ或微信）：

交流群：（QQ群，用户加入）537419179
开发群：（QQ群，开发者加入）598629636
管理平台：http://work.ksust.com