爱招飞帮助手册
目录

RestAPI

# TARS RestAPI

  • 版本： 0.9.2
  • 修订：
2020年11月06日 
增加【批量插入】batch_insert
1
2

  任何第三方应用或网站都可以通过使用开放API为用户提供实时优质的服务。 所有的API都是基于REST基础的接口规范，可兼容多种编程语言。

# 1. 参数编码

  所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做URIEncode编码；各个参数请进行URL 编码(UTF-8)，编码时请遵守 RFC-1738。

# 2. HTTP MIME类型

Content-type: application/json; charset=utf-8
1

# 3. 服务地址

  服务地址默认为TARS 的HTTP端口地址。

http(s)://127.0.0.1:8809
1

# 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://127.0.0.1:9981/rest/user/login?db_name=mydb&user_name=admin&password=c4ca4238a0b923820dcc509a6f75849b&version=2.0
1
  • 服务端应答
参数名称 参数类型 描述
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"
}
1
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"
    }]

}
1
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数据"]
    ]
}
1
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 否

① data参数JSON数据

参数名称 参数类型 描述 是否必须
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"
    }]
}
1
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数据"]
    ]
}
1
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"
    }]

}
1
2
3
4
5
6
7
8
9
10
11
12
13
  • 服务端应答数据格式：
{"status":0,"message":"ok","rows_affected":1}
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.. . ..]
]
}
1
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"}
1

# 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://127.0.0.1:9981/rest/alidayu/sendsms?num=1888888888
1
  • 服务端应答：
{"status":0,"message":"ok","token":"0F2752F4AA2E40AA931DE927756EB5D1"}
1
  • 提交验证码示例：
http://127.0.0.1:9981/rest/alidayu/sendsms?code=564732&token=0F2752F4AA2E40AA931DE927756EB5D1
1
  • 服务端应答：
{"status":0,"message":"ok"}
1

# 4.11. 【读取站点数据】/rest/iot/getiotvalue

  • 接口说明： 获取设备采集数据。

  • HTTP请求方式： GET/POST

  • 输入参数说明：

参数名称 参数类型 描述 是否必须
moduleno string 设备(群组)编号+站点名称 是
topic string

  • 请求示例：

  • Modbus 读取：

http://127.0.0.1:8809/rest/iot/getiotvalue?moduleno=001-ledstate
1
  • MQTT 读取：
http://127.0.0.1:8809/rest/iot/getiotvalue?moduleno=M001-zl5001
1
  • OPC 读取
http://127.0.0.1:8809/rest/iot/getiotvalue?moduleno=001-ledstate
1
  • 服务端应答
{"status":0,"message":35.5}
1

# 4.12. 【写入Modbus站点数据】/rest/iot/setmodbusvalue

  • 接口说明： 向 Modbus 设备指定地址写入数据。

  • HTTP请求方式： GET/POST

  • 输入参数说明：

参数名称 参数类型 描述 是否必须
moduleno string 设备号（设备编号+站点名称，中间以-分隔） 是
value float 设置值 是
startreg int 寄存器起始位置 否
regcount int 写入的寄存器位数 否
  • 请求示例：

以物联网站点设置地址写入：

http://127.0.0.1:8809/rest/iot/setmodbusvalue?moduleno=001-sitename1&value=1
1

以物联网站点按自定地址和数据长度写入：

http://127.0.0.1:8809/rest/iot/setmodbusvalue?moduleno=001-sitename2&startreg=192&regcount=1&value=1
1
  • 服务端应答
{"status":0,"message":12}
1

# 4.13. 【写入MQTT站点数据】/rest/iot/setmqttvalue

  • 接口说明 发布 MQTT 订阅信息。
  • HTTP请求方式： GET/POST
  • 输入参数说明：
参数名称 参数类型 描述 是否必须
moduleno string 设备号（群组编号+站点名称，中间以-分隔） 是
value float 设置值 是
topic string 自定发布订阅的主题名称 否

以物联网站点设置主题写入：

http://127.0.0.1:8809/rest/iot/setmqttvalue?moduleno=M001-zl5001&value=[{"i":1,"c":6,"v":{"wledstate":18}}]
1

以物联网站点按自定地址和数据长度写入：

http://127.0.0.1:8809/rest/iot/setmqttvalue?moduleno=M001-zl5001&topic=zl5001&value=[{"i":1,"c":6,"v":{"wledstate":18}}]
1

# 4.14. 【写入OPC站点数据】/rest/iot/setopcvalue

  • 接口说明 写入 OPC 站点数据信息。
  • HTTP请求方式： GET/POST
  • 输入参数说明：
参数名称 参数类型 描述 是否必须
moduleno string 设备号（群组编号+站点名称，中间以-分隔） 是
value float 设置值 是

以物联网站点设置地址写入：

http://127.0.0.1:8809/rest/iot/setopcvalue?moduleno=001-wledstate&value=1
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

功能介绍
WebSocket

← WebSocket→

Copyright © 2021-2025 爱招飞IsoFace | ALL Rights Reserved