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的相关权限。