HTTP API SQL接口开发手册

本文介绍时序引擎提供的基于HTTP协议的通用SQL接口的定义和用法。

使用须知

  • 对于非Java语言的应用开发,可以使用本文的API接口直接向时序引擎发送SQL语句。

  • 对于Java语言的应用开发,建议基于Java JDBC Driver构建时序引擎的应用程序,具体请参见Java JDBC Driver开发手册

请求路径与方法

请求路径

请求方法

描述

/api/v2/sql

POST

发送并执行SQL语句。

请求内容

请求上述API时,直接将SQL语句写入HTTP请求的请求体,并且建议在请求头设置Content-Typetext/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中搜寻操作对象的表名。未指定该查询参数时,引擎会默认在名为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认证信息的方法,请查询所用语言的相关类库的使用文档,不在此罗列。

响应内容

查询成功的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的相关权限。

阿里云首页 云原生多模数据库 Lindorm 相关技术圈