HTTP API SQL介面開發手冊 - Lindorm

本文介紹時序引擎提供的基於HTTP協議的通用SQL介面的定義和用法。

使用須知

對於非Java語言的應用開發，可以使用本文的API介面直接向時序引擎發送SQL語句。
對於Java語言的應用開發，建議基於Java JDBC Driver構建時序引擎的應用程式，具體請參見Java JDBC Driver開發手冊。
說明
單機版不支援此功能。

請求路徑與方法

請求路徑	要求方法	描述
/api/v2/sql	POST	發送並執行SQL語句。

請求內容

請求上述API時，直接將SQL語句寫入HTTP請求的請求體，並且建議在要求標頭設定Content-Type為text/plain。以Python代碼為例，在Python代碼中向/api/v2/sql傳送一條SQL語句的樣本如下：

import requests

url = "http://ld-bp1s0vbu8955w****-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql"

payload = """CREATE TABLE sensor (
    device_id VARCHAR NOT NULL,
    region VARCHAR NOT NULL,
    time TIMESTAMP NOT NULL,
    temperature DOUBLE,
    humidity BIGINT,
    PRIMARY KEY(device_id, region, time)
)"""

r = requests.post(url, payload)
if r.status_code == 200:
    print(r.content)
else:
    print(r.content)

payload = """insert into sensor (device_id, region, time, temperature, humidity) values 
('F07A1260','north-cn','2021-04-22 15:33:00',12.1,45), 
('F07A1260','north-cn','2021-04-22 15:33:10',13.2,47), 
('F07A1260','north-cn','2021-04-22 15:33:20',10.6,46), 
('F07A1261','south-cn','2021-04-22 15:33:00',18.1,44), 
('F07A1261','south-cn','2021-04-22 15:33:10',19.7,44)"""

r = requests.post(url, payload)
if r.status_code == 200:
    print(r.content)
else:
    print(r.content)

payload = "select * from sensor"

r = requests.post(url, payload)
if r.status_code == 200:
    print(r.content)
else:
    print(r.content)

說明

時序引擎基於SQL-92標準支援使用半形分號（;）作為SQL語句的終止符，但是在調用/api/v2/sql介面傳遞SQL語句時，不能在結尾使用半形分號（;）否則請求過程中會報錯。

支援的查詢參數

/api/v2/sql支援的URL查詢參數如下所示：

名稱	描述
database	SQL執行時的預設Database。當指定的SQL中寫入或查詢的時序表名未顯式指定所屬資料庫名時，時序引擎預設會在該參數指定的database中搜尋操作對象的表名。未指定該查詢參數時，引擎會預設在名為`default`的Database中搜尋表名。
chunked	是否流式返回結果資料。預設為false。當指定為true時，查詢結果資料會以多個JSON塊的方式返回，每個JSON塊最多包含chunk_size行資料。在解析結果資料時，只需要逐個解析JSON塊即可。每個JSON塊的結構參考響應內容部分描述。
chunk_size	指定流式返回結果時每次返回的最大行數。chunked=true時生效，預設為1000。

使用者認證資訊指定

當Lindorm時序引擎開啟使用者鑒權時，通過/api/v2/sql發送SQL請求時需要向HTTP要求標頭中填入使用者認證資訊。目前/api/v2/sql遵循的是BASIC AUTH認證方式，編碼後的認證資訊需要指定在HTTP要求標頭的Authorization欄位中。

基本認證憑據的格式如下：

BASIC {BASE64編碼的認證資訊}

其中BASE64編碼的認證資訊為${使用者名稱}:${對應的使用者密碼}，以半形冒號（:）分隔。

說明

各程式設計語言編碼並填充BASIC AUTH認證資訊的方法，請查詢所用語言的相關類庫的使用文檔，不在此羅列。

對於初始使用者名稱root和初始密碼root，BASE64編碼後HTTP要求標頭的Authorization欄位應包含的資訊如下所示：

Authorization: Basic cm9vdDpyb290

響應內容

查詢成功的HTTP響應碼為200，響應內容為JSON格式資料。說明如下：

名稱	類型	描述
columns	Array	字串數組表示返回結果集中列名。
metadata	Array	字串數組表示返回結果集中每一列的資料類型名稱。可能返回的資料類型請參見資料類型。
rows	Array	數組的數組表示返回結果集的行的集合。其中的每一個數組代表著一行資料，每行資料中的具體資料與columns中返回的列一一對應。

SQL執行出錯時的響應訊息中的HTTP響應碼為400，響應訊息體是一個JSON格式資料，其包含的欄位說明如下：

名稱	類型	描述
code	int	錯誤碼。
sqlstate	String	SQL狀態代碼。
message	String	錯誤詳情。

說明

關於錯誤碼對應的具體錯誤，具體請參見常見錯誤碼參考。

樣本

以下樣本通過常用的curl命令，展示了如果通過該HTTP介面對Lindorm時序引擎執行SQL。

建立名為DB1的Database。

curl -X POST http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql -d 'CREATE DATABASE DB1'

在DB1下建立名為SENSOR的時序資料表。

curl -X POST http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql?database=DB1 -d 'CREATE TABLE SENSOR (device_id VARCHAR TAG,region VARCHAR TAG,time TIMESTAMP,temperature DOUBLE,humidity DOUBLE)'

或者

curl -X POST http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql -d 'CREATE TABLE DB1.SENSOR (device_id VARCHAR TAG,region VARCHAR TAG,time TIMESTAMP,temperature DOUBLE,humidity DOUBLE)'

當使用者鑒權開關開啟時，以一個名為 tsdbuser的使用者查詢上述SENSOR時序表。

curl -X POST -u tsdbuser:password http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql?database=DB1 -d 'SELECT device_id, region, time, MAX(temperature) as max_t FROM SENSOR WHERE time >= 1619076780000 AND time <= 1619076800000 SAMPLE BY 20s'

說明

樣本中已事先對使用者tsdbuser賦予了時序表SENSOR的相關許可權。