TDengine Restful 接口API

簡介

為支持各種不同類型平臺的開發，TDengine 提供符合 RESTful 設計標準的 API，即 REST API。為最大程度降低學習成本，不同于其他數據庫 REST API 的設計方法，TDengine 直接通過 HTTP POST 請求 BODY 中包含的 SQL 語句來操作數據庫，僅需要一個 URL。REST API 的使用參見視頻教程。

:::note
與原生連接器的一個區別是，RESTful 接口是無狀態的，因此 USE db_name 指令沒有效果，所有對表名、超級表名的引用都需要指定數據庫名前綴。支持在 RESTful URL 中指定 db_name，這時如果 SQL 語句中沒有指定數據庫名前綴的話，會使用 URL 中指定的這個 db_name。
:::

安裝

RESTful 接口不依賴于任何 TDengine 的庫，因此客戶端不需要安裝任何 TDengine 的庫，只要客戶端的開發語言支持 HTTP 協議即可。TDengine 的 RESTful API 由 taosAdapter 提供，在使用 RESTful API 之前需要確保 taosAdapter 正常運行。

驗證

在已經安裝 TDengine 服務器端的情況下，可以按照如下方式進行驗證。

下面以 Ubuntu 環境中使用 curl 工具（請確認已經安裝）來驗證 RESTful 接口是否工作正常，驗證前請確認 taosAdapter 服務已開啟，在 Linux 系統上此服務默認由 systemd 管理，使用命令 systemctl start taosadapter 啟動。

下面示例是列出所有的數據庫，請把 h1.taosdata.com 和 6041（缺省值）替換為實際運行的 TDengine 服務 FQDN 和端口號：

curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \-d "select name, ntables, status from information_schema.ins_databases;" \h1.taosdata.com:6041/rest/sql

返回值結果如下表示驗證通過：

{"code": 0,"column_meta": [["name","VARCHAR",64],["ntables","BIGINT",8],["status","VARCHAR",10]],"data": [["information_schema",16,"ready"],["performance_schema",9,"ready"]],"rows": 2
}

HTTP 請求格式

http://<fqdn>:<port>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

參數說明：

fqdn：集群中的任一臺主機 FQDN 或 IP 地址。
port：配置文件中 httpPort 配置項，缺省為 6041。
db_name：可選參數，指定本次所執行的 SQL 語句的默認數據庫庫名。
tz：可選參數，指定返回時間的時區，遵照 IANA Time Zone 規則，如 America/New_York。
req_id：可選參數，指定請求 id，可以用于 tracing。
row_with_meta：可選參數，指定是否每行數據都攜帶列名，缺省為 false。（3.3.2.0 版本開始支持）

例如：http://h1.taos.com:6041/rest/sql/test 是指向地址為 h1.taos.com:6041 的 URL，并將默認使用的數據庫庫名設置為 test。

HTTP 請求的 Header 里需帶有身份認證信息，TDengine 支持 Basic 認證與自定義認證兩種機制，后續版本將提供標準安全的數字簽名機制來做身份驗證。

自定義身份認證信息如下所示：
```
Authorization: Taosd <TOKEN>
```
Basic 身份認證信息如下所示：
```
Authorization: Basic <TOKEN>
```

HTTP 請求的 BODY 里就是一個完整的 SQL 語句，SQL 語句中的數據表應提供數據庫前綴，例如 db_name.tb_name。如果表名不帶數據庫前綴，又沒有在 URL 中指定數據庫名的話，系統會返回錯誤。因為 HTTP 模塊只是一個簡單的轉發，沒有當前 DB 的概念。

使用 curl 通過自定義身份認證方式來發起一個 HTTP Request，語法如下：

curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

或者，

curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

其中，TOKEN 為 {username}:{password} 經過 Base64 編碼之后的字符串，例如 root:taosdata 編碼后為 cm9vdDp0YW9zZGF0YQ==。

HTTP 返回格式

HTTP 響應碼

默認情況下，taosAdapter 對大多數 C 接口調用出錯時也會返回 200 響應碼，但是 HTTP body 中包含錯誤信息。從 TDengine 3.0.3.0 開始 taosAdapter 提供配置參數 httpCodeServerError 用來設置當 C 接口返回錯誤時是否返回非 200 的 HTTP 響應碼。無論是否設置此參數，響應 body 里都有詳細的錯誤碼和錯誤信息，具體請參考錯誤。

當 httpCodeServerError 為 false 時：

分類說明	HTTP 響應碼
C 接口調用成功	200
C 接口調用出錯，且不是鑒權錯誤	200
HTTP 請求 URL 參數錯誤	400
C 接口調用鑒權錯誤	401
接口不存在	404
系統資源不足	503

當 httpCodeServerError 為 true 時：

分類說明	HTTP 響應碼
C 接口調用成功	200
HTTP 請求 URL 參數錯誤和 C 接口調用參數解析錯誤	400
C 接口調用鑒權錯誤	401
接口不存在	404
C 接口調用網絡不可用錯誤	502
系統資源不足	503
其他 C 接口調用錯誤	500

C 接口參數解析相關錯誤碼：

TSDB_CODE_TSC_SQL_SYNTAX_ERROR (0x0216)
TSDB_CODE_TSC_LINE_SYNTAX_ERROR (0x021B)
TSDB_CODE_PAR_SYNTAX_ERROR (0x2600)
TSDB_CODE_TDB_TIMESTAMP_OUT_OF_RANGE (0x060B)
TSDB_CODE_TSC_VALUE_OUT_OF_RANGE (0x0224)
TSDB_CODE_PAR_INVALID_FILL_TIME_RANGE (0x263B)

C 接口鑒權相關錯誤碼：

TSDB_CODE_MND_USER_ALREADY_EXIST (0x0350)
TSDB_CODE_MND_USER_NOT_EXIST (0x0351)
TSDB_CODE_MND_INVALID_USER_FORMAT (0x0352)
TSDB_CODE_MND_INVALID_PASS_FORMAT (0x0353)
TSDB_CODE_MND_NO_USER_FROM_CONN (0x0354)
TSDB_CODE_MND_TOO_MANY_USERS (0x0355)
TSDB_CODE_MND_INVALID_ALTER_OPER (0x0356)
TSDB_CODE_MND_AUTH_FAILURE (0x0357)

C 接口網絡不可用相關錯誤碼：

TSDB_CODE_RPC_NETWORK_UNAVAIL (0x000B)

錯誤碼和錯誤描述請參考錯誤碼

HTTP body 結構

正確執行插入

樣例：

{"code": 0,"column_meta": [["affected_rows", "INT", 4]],"data": [[0]],"rows": 1
}

說明：

code：（int）0 代表成功。
column_meta：（[1][3]any）只返回 [["affected_rows", "INT", 4]]。
rows：（int）只返回 1。
data：（[][]any）返回受影響行數。

正確執行查詢

樣例：

{"code": 0,"column_meta": [["ts", "TIMESTAMP", 8],["count", "BIGINT", 8],["endpoint", "VARCHAR", 45],["status_code", "INT", 4],["client_ip", "VARCHAR", 40],["request_method", "VARCHAR", 15],["request_uri", "VARCHAR", 128]],"data": [["2022-06-29T05:50:55.401Z",2,"LAPTOP-NNKFTLTG:6041",200,"172.23.208.1","POST","/rest/sql"],["2022-06-29T05:52:16.603Z",1,"LAPTOP-NNKFTLTG:6041",200,"172.23.208.1","POST","/rest/sql"],["2022-06-29T06:28:14.118Z",1,"LAPTOP-NNKFTLTG:6041",200,"172.23.208.1","POST","/rest/sql"],["2022-06-29T05:52:16.603Z",2,"LAPTOP-NNKFTLTG:6041",401,"172.23.208.1","POST","/rest/sql"]],"rows": 4
}

說明：

code：（int）0 代表成功。
column_meta：（[][3]any）列信息，每個列會用三個值來說明，分別為：列名（string）、列類型（string）、類型長度（int）。
rows：（int）數據返回行數。
data：（[][]any）具體數據內容（時間格式僅支持 RFC3339，結果集為 0 時區，指定 tz 時返回對應時區）。

列類型使用如下字符串：

“NULL”
“BOOL”
“TINYINT”
“SMALLINT”
“INT”
“BIGINT”
“FLOAT”
“DOUBLE”
“VARCHAR”
“TIMESTAMP”
“NCHAR”
“TINYINT UNSIGNED”
“SMALLINT UNSIGNED”
“INT UNSIGNED”
“BIGINT UNSIGNED”
“JSON”
“VARBINARY”
“GEOMETRY”

VARBINARY 和 GEOMETRY 類型返回數據為 Hex 字符串，樣例：

準備數據

create database demo
use demo
create table t(ts timestamp,c1 varbinary(20),c2 geometry(100))
insert into t values(now,'\x7f8290','point(100 100)')

執行查詢

curl --location 'http://<fqdn>:<port>/rest/sql' \
--header 'Content-Type: text/plain' \
--header 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' \
--data 'select * from demo.t'

返回結果

{"code": 0,"column_meta": [["ts","TIMESTAMP",8],["c1","VARBINARY",20],["c2","GEOMETRY",100]],"data": [["2023-11-01T06:28:15.210Z","7f8290","010100000000000000000059400000000000005940"]],"rows": 1
}

010100000000000000000059400000000000005940 為 point(100 100) 的 Well-Known Binary (WKB) 格式

錯誤

樣例：

{"code": 9728,"desc": "syntax error near \"1\""
}

說明：

code：（int）錯誤碼。
desc：（string）錯誤描述。

錯誤碼和錯誤描述請參考錯誤碼

返回 key-value 形式數據

當指定 url 參數 row_with_meta=true 時，返回的 data 中的數據會從數組的形式變成對象的形式，對象的 key 為列名，value 為數據，如下所示：

插入數據返回示例

{"code": 0,"column_meta": [["affected_rows","INT",4]],"data": [{"affected_rows": 1}],"rows": 1
}

查詢數據返回示例

{"code": 0,"column_meta": [["ts","TIMESTAMP",8],["current","FLOAT",4],["voltage","INT",4],["phase","FLOAT",4],["groupid","INT",4],["location","VARCHAR",24]],"data": [{"ts": "2017-07-14T02:40:00.000Z","current": -2.498076,"voltage": 0,"phase": -0.846025,"groupid": 8,"location": "California.Sunnyvale"}],"rows": 1
}

自定義授權碼

HTTP 請求中需要帶有授權碼 <TOKEN>，用于身份識別。授權碼通常由管理員提供，可簡單的通過發送 HTTP GET 請求來獲取授權碼，操作如下：

curl http://<fqnd>:<port>/rest/login/<username>/<password>

其中，fqdn 是 TDengine 數據庫的 FQDN 或 IP 地址，port 是 TDengine 服務的端口號，username 為數據庫用戶名，password 為數據庫密碼，返回值為 JSON 格式，各字段含義如下：

code：返回值代碼。
desc：授權碼。

獲取授權碼示例：

curl http://192.168.0.1:6041/rest/login/root/taosdata

返回值：

{"code": 0,"desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}

使用示例

在 demo 庫里查詢表 d1001 的所有記錄：

curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql

返回值：

{"code": 0,"column_meta": [["ts","TIMESTAMP",8],["current","FLOAT",4],["voltage","INT",4],["phase","FLOAT",4]],"data": [["2022-07-30T06:44:40.32Z",10.3,219,0.31],["2022-07-30T06:44:41.32Z",12.6,218,0.33]],"rows": 2
}

創建庫 demo：

curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql
curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "create database demo" 192.168.0.1:6041/rest/sql

返回值：

{"code": 0,"column_meta": [["affected_rows","INT",4]],"data": [[0]],"rows": 1
}

TDengine 2.x 和 3.0 之間 REST API 的差異

URI

URI	TDengine 2.x	TDengine 3.0
/rest/sql	支持	支持（響應代碼和消息體不同）
/rest/sqlt	支持	不再支持
/rest/sqlutc	支持	不再支持

HTTP code

HTTP code	TDengine 2.x	TDengine 3.0	備注
200	支持	支持	正確返回和 taosc 接口錯誤返回
400	不支持	支持	參數錯誤返回
401	不支持	支持	鑒權失敗
404	支持	支持	接口不存在
500	不支持	支持	內部錯誤
503	支持	支持	系統資源不足

響應代碼和消息體

TDengine 2.x 響應代碼和消息體

{"status": "succ","head": ["name","created_time","ntables","vgroups","replica","quorum","days","keep1,keep2,keep(D)","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","precision","status"],"data": [["log","2020-09-02 17:23:00.039",4,1,1,1,10,"30,30,30",1,3,100,4096,1,3000,2,"us","ready"]],"rows": 1
}

  "data": [["information_schema",16,"ready"],["performance_schema",9,"ready"]],

TDengine 3.0 響應代碼和消息體

{"code": 0,"column_meta": [["name","VARCHAR",64],["ntables","BIGINT",8],["status","VARCHAR",10]],"data": [["information_schema",16,"ready"],["performance_schema",9,"ready"]],"rows": 2
}