本文介紹時序引擎提供的基於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-xxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql"
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中搜尋操作對象的表名。未指定該查詢參數時，引擎會預設在名為 |
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的相關許可權。