Chatopera 类接口规范

发送请求

Chatopera实例的核心接口是command，以下也使用Chatopera#command来指这个接口，该接口是对 RestAPI Request 的高级封装，内部完成签名认证，RequestHeaders和RequestBody等处理。

接口规范

result = chatopera.command(method, path [, body])

提示： result 返回在 Node.js 中使用await或Promise，参考快速开始；其它语言直接用 = 便可获取。

参数说明

name	type	required	description
method	string	✔	对于资源的具体操作类型，由 HTTP 动词表示。有效值包括GET，POST，PUT，DELETE和HEAD等
path	string	✔	资源的执行路径，通常包含资源实体名称或唯一标识，也可能在 path中使用queryString传递参数
body	JSON数据结构	❓	body 是请求中的数据，对应 RestAPI 中的 Http Body

method不同动词代表的含义一般如下：

• GET - 从服务器取出一项或多项资源；
• POST - 在服务器创建一个资源；
• PUT - 在服务器更新一个资源；
• DELETE - 在服务器删除一个资源。

还有更多类型的method，没有上述几种常用，在此不进行赘述。

queryString是 URL 的一部分。典型的 URL 看起来像这样: http://server/resource?foo=A&bar=B。其中，foo=A&bar=B就是queryString，通常用来传递参数，这个例子中包含两个参数：foo值为A；bar值为B。在下文中，path参数中可能包含queryString，形式如foo={{var1}}&bar={{var2}}，需要把{{var1}}和{{var2}}替换为实际值。

body数据是 JSON 格式的，不同语言对于 JSON 格式支持方式不同。JSON是一种轻量级的数据交换格式，描述了使用键值对、数组、字符串、数字、日期和布尔类型等值存储对象。JSON在不同语言下，等价数据结构如下。

语言	JSON Object	JSON Array
JavaScript	{...}	[...]
Java	org.json.JSONObject	org.json.JSONArray
PHP	基本类型array	基本类型array
Python	基本类型dict	基本类型list
Go	map[string]interface{}	[]map[string]interface{}

下文表述时，统一使用JSON，JSON Object和JSON Array代表 JSON 数据结构和其不同语言下的等价数据结构。

提示： 相对而言，JSON 等价的数据结构，在获取JSON Object的键值或JSON Array的长度和成员时，语法不同，但都易于掌握。在使用时，参考不同 SDK 的示例程序。

body是否必填以及是JSON Object还是JSON Array，取决于method和path的值，不同method和path的组合对应了不同的接口功能，满足不同需求，下文将介绍满足各种需求的method和path，并各个说明body参数。

返回值

返回值即请求结果，针对接口定义，Chatopera#command的返回值result是 JSON Object，并有以下属性。

key	type	description
rc	int	response code，返回码，大于等于 0 的正整型。0代表服务器端按照请求描述，正常返回结果；rc 不等于 0 是代表异常返回。
data	JSON	数据资源。正常返回时，服务器端执行逻辑成功，比如查询时，data就是查询结果。
msg	string	消息，当服务器端执行请求成功，并且不需要返回数据资源时，通过 msg代表文本信息，比如提示信息。
error	string	异常消息，当服务器端返回异常时，具体出错信息包含在error中。
total	int	分页，所有数据记录条数。
current_page	int	分页，当前页码，（分页从 1 开始）。
total_page	int	分页，所有页数。

每次请求结果中，rc是必含有的属性，其它属性为可能含有。不同rc的正整数形代表不同的异常，data、status以及分页信息，则因method和path而异，以下进行详细介绍。

提示： 不同语言对返回值可能进行了封装，但是不离其宗，都是基于以上定义，比如 Java SDK 中，定义com.chatopera.bot.sdk.Response作为Chatopera#command接口返回值，Response类提供getRc、getData和toJSON等方法，提升代码可读性。在使用时，参考不同 SDK 的示例程序。

下文中使用的method，path，body和result等均代表以上介绍的概念。