愛招飛幫助手冊
目录

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-2024 愛招飛IsoFace | ALL Rights Reserved