RestAPI
# TARS RestAPI
- 版本: 0.9.2
- 修订:
2020年11月06日
增加【批量插入】batch_insert
2
任何第三方应用或网站都可以通过使用开放API为用户提供实时优质的服务。 所有的API都是基于REST基础的接口规范,可兼容多种编程语言。
# 1. 参数编码
所有的请求和响应数据编码皆为utf-8格式,url里的所有参数值请做URIEncode编码;各个参数请进行URL 编码(UTF-8),编码时请遵守 RFC-1738。
# 2. HTTP MIME类型
Content-type: application/json; charset=utf-8
# 3. 服务地址
服务地址默认为TARS 的HTTP端口地址。
http(s)://127.0.0.1:8809
# 4. API 接口
# 4.1. 【用户登录】/rest/user/login
接口说明: 登录中间件
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
user_name | string | TARS用户名 | 是 |
password | string | TARS用户密码MD5值,如果勾选了验证用户身份,则密码是用户密码字符串+全局MD5盐值合并的字符串的MD5值 | 是 |
version | string | 版本号,可选值:2.0 | 否 |
db_name | string | 数据库别名 | 是 |
- 请求示例:
http:/rest/user/login?db_name=mydb&user_name=admin&password=c4ca4238a0b923820dcc509a6f75849b&version=2.0
- 服务端应答
参数名称 | 参数类型 | 描述 |
---|---|---|
status | number | 返回应答状态码 |
message | string | 返回应答状态 |
token | string | token验证信息 |
expire_time | datetime | token过期时间 |
app_secret | string | 应用验证码 |
{
"status": 0,
"message": "ok",
"token": "DBF0FC1C3DD349329459248245AB02E3",
"expire_time": "2017-04-25T10:30:03.232",
"app_secret": "d122e06e41c7485ba27eb38c6afc5159"
}
2
3
4
5
6
7
# 4.2. 【调用存储过程】/rest/db/storedproc
接口说明: 调用存储过程、函数、可返回输出参数、返回值、数据集
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | String | 令牌,用户登录授权成功后,由服务器返回 | 是 |
data | String | 为JSON格式 ① | 是 |
sign_method | String | 签名的摘要算法,可选值为:hmac,md5,② | 否 |
sign | String | 签名 | 否 |
timestamp | String | 时间戳,格式为yyyy-MM-dd HH:mm:ss,时区为GMT+8,例如:2016-01-01 12:00:00 | 否 |
version | String | 版本号,可选值:2.0 | 否 |
①data参数JSON数据
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
db_name | String | 数据库连接名称 | 是 |
proc_name | String | 存储过程名称 | 是 |
method | String | 执行方法,可选值为:open_proc、exec_proc、exec_func | 是 |
params | String | 参数,JSON 数组[{"name":"参数名称","value":"参数值"}] | 否 |
{
"db_name": "DB_MSSQL",
"proc_name": "sp_Test1",
"method": "open_proc",
"params": [{
"name": "@p1",
"value": 10
}, {
"name": "@p2",
"value": "abcdefg"
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
② 签名算法
https://open.taobao.com/doc2/detail.htm?articleId=101617&docType=1&treeId=1 (opens new window)
- 服务端应答数据格式:
{
"status": 0, //状态码
"message": "OK", //状态描述
"rows_affected": 2, //影响的行
"params": [{ //输出参数
"name": "@p3",
"value": "110"
}],
"meta": [
["字段1", "ftGuid"],
["字段2", "ftString", 50],
["字段3", "ftString", 20],
["字段4", "ftBlob"]
],
"data": [
["字段1数据", "字段2数据", "字段3数据", "字段4数据"],
["字段1数据", "字段2数据", "字段3数据", "字段4数据"]
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 4.3. 【查询数据】/rest/db/opensql
接口说明:
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | String | 令牌,用户登录授权成功后,由服务器返回 | 是 |
data | String | 为JSON格式 ① | 是 |
sign_method | String | 签名的摘要算法,可选值为:hmac,md5,② | 否 |
sign | String | 签名 | 否 |
timestamp | String | 时间戳,格式为yyyy-MM-dd HH:mm:ss,时区为GMT+8,例如:2016-01-01 12:00:00 | 否 |
version | String | 版本号,可选值:2.0 | 否 |
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
db_name | String | 数据库连接名称 | 是 |
sql_command_id | String | sql 编号 | 是 |
page_size | int | 每页数据条数 | 否 |
page_index | int | 第 x 页 | 否 |
{
"db_name": "DB_MSSQL",
"sql": "SELECT * FROM my_table WHERE a=:a AND b=:b",
"sql_command_id": "SQL001",
"page_size": 10,
"page_index":0,
"params": [{
"name": "a",
"value": “abc”
}, {
"name": "b",
"value": "123456"
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
- 服务端应答数据格式:
{
"status": 0,
"message": "ok",
"count": 10, //数据行数
"total": 1000, //数据总数
"meta": [
["字段1", "ftGuid"],
["字段2", "ftString", 50],
["字段3", "ftString", 20],
["字段4", "ftBlob"]
],
"data": [
["字段1数据", "字段2数据", "字段3数据", "字段4数据"],
["字段1数据", "字段2数据", "字段3数据", "字段4数据"]
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 4.4. 【执行SQL】/rest/db/execsql
接口说明: 执行SQL查询,获取数据集以及返回值。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | String | 令牌,用户登录授权成功后,由服务器返回 | 是 |
data | String | 为JSON格式 ① | 是 |
sign_method | String | 签名的摘要算法,可选值为:hmac,md5,② | 否 |
sign | String | 签名 | 否 |
timestamp | String | 时间戳,格式为yyyy-MM-dd HH:mm:ss,时区为GMT+8,例如:2016-01-01 12:00:00 | 否 |
version | String | 版本号,可选值:2.0 | 否 |
① data参数JSON数据
{
"db_name": "DB_MSSQL", //数据库连接名称
"sql": "UPDATE my_table SET a=:a WHERE b=:b", //or "DELETE FROM my_table WHERE a=:a AND b=:b"
"sql_command_id": "SQL002",
"params": [{ //输入参数,输出参数不用填
"name": "a",
"value": “abc”
}, {
"name": "b",
"value": "123456"
}]
}
2
3
4
5
6
7
8
9
10
11
12
13
- 服务端应答数据格式:
{"status":0,"message":"ok","rows_affected":1}
# 4.5. 【批量插入】/rest/db/batch_insert
接口说明: 用于数据库中数据的批量插入。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | string | 令牌,用户登录授权成功后,由服务器返回 | 是 |
data | string | 为JSON格式① | 是 |
sign_method | string | 签名的摘要算法,可选值为:hmac,md5,② | 否 |
sign | string | 签名 | 否 |
timestamp | string | 时间戳,格式为yyyy-MM-dd HH:mm:ss,时区为GMT+8,例如:2016-01-01 12:00:00 | 否 |
version | string | 版本号,可选值:2.0 | 否 |
① data参数JSON数据
{
"db_name": "DB_MSSQL",
"sql_command_id": "SQL002",
"params": [
[value1,vaue2,value3.. . ..],
[value1,vaue2,value3.. . ..]
]
}
2
3
4
5
6
7
8
# 4.6. 【获取SQL列表】/rest/db/sqlcommands
接口说明: 用于获取可用的SQL命令的列表。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
db_name | string | 数据库别名 | 是 |
token | string | 令牌,用户登录授权成功后,由服务器返回 | 是 |
# 4.7. 【数据库连接列表】/rest/db/list
接口说明: 用于获取TARS中设置的可用的数据库连接设置列表。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | string | 令牌,用户登录授权成功后,由服务器返回 | 是 |
# 4.8. 【注销】/rest/user/logout
接口说明: 用户注销
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | string | 令牌,用户登录授权成功后,由服务器返回 | 是 |
version | string | 版本号,可选值:2.0 | 否 |
- 服务端应答:
{"status":0,"message":"ok"}
# 4.9. 【重置Token】/rest/user/token/reset
接口说明: 用于刷新token的有效期。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
token | string | 令牌,用户登录授权成功后,由服务器返回 | 是 |
# 4.10. 【短信验证】/rest/alidayu/sendsms
接口说明: 用于短信验证码的发送。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
num | string | 手机号码 | 是 |
token | string | 令牌,获取验证码后,由服务器返回 | 是 |
code | string | 短信验证码 | 是 |
- 请求验证码示例:
http:/rest/alidayu/sendsms?num=1888888888
- 服务端应答:
{"status":0,"message":"ok","token":"0F2752F4AA2E40AA931DE927756EB5D1"}
- 提交验证码示例:
http:/rest/alidayu/sendsms?code=564732&token=0F2752F4AA2E40AA931DE927756EB5D1
- 服务端应答:
{"status":0,"message":"ok"}
# 4.11. 【读取站点数据】/rest/iot/getiotvalue
接口说明: 获取设备采集数据。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
moduleno | string | 设备(群组)编号+站点名称 | 是 |
topic | string |
请求示例:
Modbus 读取:
http:/rest/iot/getiotvalue?moduleno=001-ledstate
- MQTT 读取:
http:/rest/iot/getiotvalue?moduleno=M001-zl5001
- OPC 读取
http:/rest/iot/getiotvalue?moduleno=001-ledstate
- 服务端应答
{"status":0,"message":35.5}
# 4.12. 【写入Modbus站点数据】/rest/iot/setmodbusvalue
接口说明: 向 Modbus 设备指定地址写入数据。
HTTP请求方式: GET/POST
输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
moduleno | string | 设备号(设备编号+站点名称,中间以- 分隔) | 是 |
value | float | 设置值 | 是 |
startreg | int | 寄存器起始位置 | 否 |
regcount | int | 写入的寄存器位数 | 否 |
- 请求示例:
以物联网站点设置地址写入:
http:/rest/iot/setmodbusvalue?moduleno=001-sitename1&value=1
以物联网站点按自定地址和数据长度写入:
http:/rest/iot/setmodbusvalue?moduleno=001-sitename2&startreg=192®count=1&value=1
- 服务端应答
{"status":0,"message":12}
# 4.13. 【写入MQTT站点数据】/rest/iot/setmqttvalue
- 接口说明 发布 MQTT 订阅信息。
- HTTP请求方式: GET/POST
- 输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
moduleno | string | 设备号(群组编号+站点名称,中间以- 分隔) | 是 |
value | float | 设置值 | 是 |
topic | string | 自定发布订阅的主题名称 | 否 |
以物联网站点设置主题写入:
http:/rest/iot/setmqttvalue?moduleno=M001-zl5001&value=[{"i":1,"c":6,"v":{"wledstate":18}}]
以物联网站点按自定地址和数据长度写入:
http:/rest/iot/setmqttvalue?moduleno=M001-zl5001&topic=zl5001&value=[{"i":1,"c":6,"v":{"wledstate":18}}]
# 4.14. 【写入OPC站点数据】/rest/iot/setopcvalue
- 接口说明 写入 OPC 站点数据信息。
- HTTP请求方式: GET/POST
- 输入参数说明:
参数名称 | 参数类型 | 描述 | 是否必须 |
---|---|---|---|
moduleno | string | 设备号(群组编号+站点名称,中间以- 分隔) | 是 |
value | float | 设置值 | 是 |
以物联网站点设置地址写入:
http:/rest/iot/setopcvalue?moduleno=001-wledstate&value=1
# 4.15. 【帮助信息】/system/help
接口说明: 获取RestAPI说明的相关信息。
HTTP请求方式: GET/POST
# 4.16. 【获得64位唯一Id】/system/newid
接口说明: 用于获取生成的64位唯一ID信息。
HTTP请求方式: GET/POST
# 4.17. 【客户端IP】/system/myip
接口说明: 获取当前连接的客户端的IP地址。
HTTP请求方式: GET/POST
# 4.18. 【系统时间】/system/systime
接口说明: 获取当前系统的时间。
HTTP请求方式: GET/POST
# 4.19. 【系统信息】/system/sysinfo
接口说明: 获取系统的相关信息。
HTTP请求方式: GET/POST