如何通过HTTP与TSDB数据库进行交互_时间序列数据库 TSDB(TSDB)-阿里云帮助中心

TSDB For InfluxDB®提供了一种与数据库进行交互的简易方法，它使用了HTTP响应码、HTTP认证、JWT令牌和基本（basic）认证，并以JSON格式返回结果。

以下章节假设TSDB For InfluxDB®实例运行在<网络地址>上，端口为3242，并且开启HTTPS。

TSDB For InfluxDB® HTTP路径（endpoint）

路径	描述
/ping	使用`/ping`检查TSDB For InfluxDB®实例的状态和TSDB For InfluxDB®的版本
/query	使用`/query`查询数据和管理数据库、保留策略和用户
/write	使用`/write`将数据写入到一个已经存在的数据库

/ping HTTP路径

/ping路径接受GET和HEAD的HTTP请求。使用这个路径，检查TSDB For InfluxDB®实例的状态和TSDB For InfluxDB®的版本。

定义

GET https://<网络地址>:3242/ping?u=<账号名称>&p=<密码>

HEAD https://<网络地址>:3242/ping?u=<账号名称>&p=<密码>

选项verbose

默认情况下，/ping HTTP路径返回一个简单的HTTP 204状态，让客户端知道服务器正在运行。verbose的默认值是false。当verbose设置为true时（/ping?verbose=true），返回HTTP 200状态。

示例

您可以使用/ping路径查看TSDB For InfluxDB®实例的版本（version）。头部字段X-Influxdb-Version显示了TSDB For InfluxDB®的版本。

~ curl -sl -I https://<网络地址>:3242/ping?u=<账号名称>&p=<密码>

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
X-Influxdb-Build: OSS
X-Influxdb-Version: v1.7.x
X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
Date: Tue, 05 Nov 2018 16:08:32 GMT

状态码和响应

响应的正文是空的。

HTTP状态码	描述
204	成功！TSDB For InfluxDB®实例已经启动并正在运行

/query HTTP路径

/query路径接受GET和POST的HTTP请求。使用这个路径，查询数据和管理数据库、保留策略和用户。

定义

GET https://<网络地址>:3242/query?u=<账号名称>&p=<密码>

POST https://<网络地址>:3242/query?u=<账号名称>&p=<密码>

动词用法（Verb usage）

动词（Verb）	查询类型
GET	用于以如下关键字开头的所有查询： SELECT SHOW
POST	用于以如下关键字开头的所有查询： ALTER CREATE DELETE DROP GRANT KILL REVOKE

* 唯一的例外是包含INTO子句的SELECT查询，这些查询需要使用POST请求。

示例

使用SELECT语句查询数据

$ curl -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

measurement mymeas中有两个数据点。在第一个数据点中，时间戳是2017-03-01T00:16:18Z，field key myfield的值是33.1，tag key mytag1和mytag2没有tag value。在第二个数据点中，时间戳是2017-03-01T00:17:18Z，field key myfield的值是12.4，tag key mytag1和mytag2的值分别为12和14。

相同的查询在TSDB For InfluxDB®的命令行界面中则返回：

name: mymeas
time                  myfield  mytag1  mytag2
----                  -------  ------  ------
2017-03-01T00:16:18Z  33.1
2017-03-01T00:17:18Z  12.4     12      14

使用SELECT语句和INTO子句查询数据

$ curl -XPOST 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"result","columns":["time","written"],"values":[["1970-01-01T00:00:00Z",2]]}]}]}

包含INTO子句的SELECT查询需要使用POST请求。

返回结果显示，TSDB For InfluxDB®写入两个数据点到measurement newmeas。请注意，系统使用epoch 0（1970-01-01T00:00:00Z）作为空时间戳。

字符串类型的查询参数

字符串类型的查询参数	可选/必需	描述
chunked=[true, `number_of_points`]	可选。	批量流式地返回数据点，而不是将所有数据一次性返回。如果设置为true，TSDB For InfluxDB®按序列或按10,000个数据点（哪个条件最先满足就以哪个条件来分块）分批返回结果。如果设置为一个特定的值，TSDB For InfluxDB®按序列或按指定数量的数据点分批返回结果。
db=`database_name`	对依赖数据库的查询是必需的（大多数`SELECT`查询和`SHOW`查询需要此参数）。	设置查询的目标数据库
epoch=[ns,u,µ,ms,s,m,h]	可选。	返回具有特定精度的epoch时间戳。TSDB For InfluxDB®默认返回RFC3339格式的时间戳，精度为纳秒。`u`和`µ`都表示微秒。
p=`password`	如果没有开启认证，这是可选的。开启认证后，这是必需的。	如果开启了认证，请设置用于认证的密码。需要与参数`u`同时使用。
pretty=true	可选。	开启JSON输出的美观打印（pretty-printed）。虽然它在调试的时候非常有用，但是不建议用于生产，因为它会消耗不必要的网络带宽。
q=`query`	必需。	需要执行的InfluxQL命令。
u=`username`	如果没有开启认证，这是可选的。开启认证后，这是必需的。	如果开启了认证，请设置用于认证的用户名。用户必须具有读数据库的权限。需要与参数`p`同时使用。

* 如果没有使用参数chunked，TSDB For InfluxDB®不会截断请求返回的行数。

示例

使用SELECT语句查询数据并返回美观打印的JSON

$ curl -G 'https://<网络地址>:3242/query?db=mydb&pretty=true&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "mymeas",
                    "columns": [
                        "time",
                        "myfield",
                        "mytag1",
                        "mytag2"
                    ],
                    "values": [
                        [
                            "2017-03-01T00:16:18Z",
                            33.1,
                            null,
                            null
                        ],
                        [
                            "2017-03-01T00:17:18Z",
                            12.4,
                            "12",
                            "14"
                        ]
                    ]
                }
            ]
        }
    ]
}

使用SELECT语句查询数据并返回除纳秒外其它精度的epoch时间戳

$ curl -G 'https://<网络地址>:3242/query?db=mydb&epoch=s&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]}]}

Request body

--data-urlencode "q=<InfluxQL query>"

所有查询都必须进行URL编码，并遵循InfluxQL语法。本页面的所有示例都使用了curl，在curl命令中使用参数--data-urlencode。

选项（options）

请求多个查询

用分号（;）将多个查询隔开。

发送文件中的查询

API支持使用multipart POST请求发送文件中的查询。文件中的多个查询必须用分号隔开。

语法：

curl -F "q=@<path_to_file>" -F "async=true" https://<网络地址>:3242/query?u=<账号名称>&p=<密码>

请求返回CSV格式的查询结果

语法：

curl -H "Accept: application/csv" -G 'https://<网络地址>:3242/query?u=<账号名称>&p=<密码>' [...]

请注意，当请求中包含-H Accept: application/csv，系统将返回epoch格式的时间戳，而不是RFC3339格式。

绑定参数

API支持将参数绑定到WHERE子句中特定的field value或tag value。使用语法$<placeholder_key>作为查询中的占位符（placeholder），并且URL会对request body中的placeholder key和placeholder value的映射（Map）进行编码：

查询语法：

--data-urlencode 'q= SELECT [...] WHERE [ <field_key> | <tag_key> ] = $<placeholder_key>'

映射语法：

--data-urlencode 'params={"<placeholder_key>":[ <placeholder_float_field_value> | <placeholder_integer_field_value> | "<placeholder_string_field_value>" | <placeholder_boolean_field_value> | "<placeholder_tag_value>" ]}'

使用逗号（,）将多个placeholder key-value pair隔开。

示例

请求多个查询

$ curl -G 'https://<网络地址>:3242/query?db=mydb&epoch=s&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas";SELECT mean("myfield") FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]},{"statement_id":1,"series":[{"name":"mymeas","columns":["time","mean"],"values":[[0,22.75]]}]}]}

该请求包含两个查询：SELECT * FROM "mymeas"和SELECT mean("myfield") FROM "mymeas"。从结果中我们可以看到，系统为每个返回的查询分配一个statement标识符：statement_id。第一个查询返回的结果对应的statement_id是0，第二个查询返回的结果对应的statement_id是1。

请求返回CSV格式的查询结果

$ curl -H "Accept: application/csv" -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'

name,tags,time,myfield,mytag1,mytag2
mymeas,,1488327378000000000,33.1,mytag1,mytag2
mymeas,,1488327438000000000,12.4,12,14

第一个数据点的两个tag key mytag1和mytag2都没有tag value。

发送文件中的查询语句

$ curl -F "q=@queries.txt" -F "async=true" 'https://<网络地址>:3242/query?u=<账号名称>&p=<密码>'

其中，文件queries.txt中的查询如下：

SELECT * FROM "mymeas";
SELECT mean("myfield") FROM "mymeas";

将WHERE子句中的参数绑定到指定的tag value

$ curl -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value' --data-urlencode 'params={"tag_value":"12"}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

该请求将$tag_value映射到12。TSDB For InfluxDB®将tag value存储为字符串，所以必须使用双引号将请求中的tag value括起来。

将WHERE子句中的参数绑定到数值类型的field value

$ curl -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "myfield" > $field_value' --data-urlencode 'params={"field_value":30}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null]]}]}]}

该请求将$field_value映射到30。不需要使用双引号将30括起来，因为在myfield中存储的是数值类型的field value。

将WHERE子句中的两个参数分别绑定到指定的tag value和数值类型的field value

$ curl -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value AND  "myfield" < $field_value' --data-urlencode 'params={"tag_value":"12","field_value":30}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

该请求将$tag_value映射到12，并且将$field_value映射到30。

状态码和响应

响应以JSON格式返回。通过添加参数pretty=true，可开启JSON的美观打印（pretty-print）。

总结

HTTP状态码	描述
200 OK	成功！返回的JSON提供更多信息。
400 Bad Request	无法处理该请求。可能是查询的语法不正确引起的。返回的JSON提供更多信息。
401 Unauthorized	无法处理该请求。可能是认证凭证无效引起的。

示例

成功返回数据的请求

$ curl -i -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:22:54 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

成功返回错误的请求

$ curl -i -G 'https://<网络地址>:3242/query?db=mydb1&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:23:48 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

格式错误的查询

$ curl -i -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT *'

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:24:25 GMT
Content-Length: 76

{"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

使用无效的认证凭证查询数据

$ curl -i  -XPOST 'https://<网络地址>:3242/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:11:26 GMT
Content-Length: 33

{"error":"authorization failed"}

/write HTTP路径

/write路径接受POST的HTTP请求。使用这个路径，将数据写入已经创建好的数据库。

定义

POST https://<网络地址>:3242/write?u=<账号名称>&p=<密码>

字符串类型的查询参数

字符串类型的查询参数	可选/必需	描述
db=\	必需	设置写入的目标数据库。
p=\	如果没有开启认证，这是可选的。开启认证后，这是必需的。	如果开启了认证，请设置用于认证的密码。需要与参数`u`同时使用。
precision=[ns,u,ms,s,m,h]	可选	设置所提供的Unix时间的精度。如果您不指定精度，TSDB For InfluxDB®假设时间戳的精度为纳秒。
rp=\	可选	设置写入的目标保留策略。如果您不指定保留策略，TSDB For InfluxDB®会将数据写入默认(`DEFAULT`)保留策略。
u=\	如果没有开启认证，这是可选的。开启认证后，这是必需的。	如果开启了认证，请设置用于认证的用户名。用户必须具有写数据库的权限。需要与参数`p`同时使用。

** 我们建议尽量使用最低的精度，因为这可以显著提高压缩效果。

示例

将时间戳精确到秒的数据点写入数据库mydb

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&precision=s&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:33:23 GMT

将数据点写入数据库mydb和保留策略myrp

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&rp=myrp&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:31 GMT

使用HTTP认证，将数据点写入数据库mydb

有效的凭证：

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=myusername&p=mypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:56 GMT

无效的凭证：

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=myusername&p=notmypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:40:30 GMT
Content-Length: 33

{"error":"authorization failed"}

使用基本（basic）认证，将数据点写入数据库mydb

有效的凭证：

$ curl -i -XPOST -u myusername:mypassword "https://<网络地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:36:40 GMT

无效的凭证：

$ curl -i -XPOST -u myusername:notmypassword "https://<网络地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:46:40 GMT
Content-Length: 33

{"error":"authorization failed"}

Request body

--data-binary '<Data in Line Protocol format>'

所有数据必须采用二进制编码并采用行协议格式。本页面的所有示例都使用了curl，在curl命令中使用参数--data-binary。使用除--data-binary外的其它编码方式，可能会导致错误；-d、--data-urlencode和--data-ascii可能会将换行符去掉或者引入新的、非预期的格式。

选项：

通过用换行符分隔多个数据点，可在一个请求中将这些数据点写入数据库。
将文件中的数据点写入数据库，该文件需带标记@。文件中的数据点需要使用行协议格式。每个数据点必须占据一行，多个数据点用换行符（\n）隔开。文件中包含回车键会导致解析错误。

我们建议分批写入数据，每批数据5,000或10,000个数据点。如果每一批数据的数据点变少，会产生更多的HTTP请求，导致性能无法达到最优。

示例

将时间戳精确到纳秒的数据点写入数据库mydb

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:02:57 GMT

将使用本地服务器时间戳（精确到纳秒）的数据点写入数据库mydb

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:03:44 GMT

使用换行符，将多个数据点写入数据库mydb

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
mymeas,mytag=2 myfield=34 1463689152000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:04:02 GMT

从文件data.txt中，将多个数据点写入数据库mydb

$ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary @data.txt

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:08:11 GMT

其中，文件data.txt中的示例数据如下：

mymeas,mytag1=1 value=21 1463689680000000000
mymeas,mytag1=1 value=34 1463689690000000000
mymeas,mytag2=8 value=78 1463689700000000000
mymeas,mytag3=9 value=89 1463689710000000000

状态码和响应

一般来说，2xx形式的状态码表示成功，4xx表示TSDB For InfluxDB®无法理解请求，5xx表示系统过载或严重受损。错误以JSON格式返回。

总结

HTTP状态码	描述
204 No Content	成功！
400 Bad Request	无法处理该请求。可能写协议语法错误引起的，或者是用户尝试将数据写入之前接受不同数据类型的field引起的。返回的JSON提供更多信息。
401 Unauthorized	无法处理该请求。可能是认证凭证无效引起的。
404 Not Found	无法处理该请求。可能是用户尝试将数据写入不存在的数据库引起的。返回的JSON提供更多信息。
500 Internal Server Error	系统过载或严重受损。可能是用户尝试将数据写入不存在的保留策略引起的。返回的JSON提供更多信息。

示例

写入成功

HTTP/1.1 204 No Content

写入时间戳不正确的数据点

HTTP/1.1 400 Bad Request
[...]
{"error":"unable to parse 'mymeas,mytag=1 myfield=91 abc123': bad timestamp"}

将整数写入到之前接受浮点数的field

HTTP/1.1 400 Bad Request
[...]
{"error":"field type conflict: input field \"myfield\" on measurement \"mymeas\" is type int64, already exists as type float"}

使用无效的认证凭证写入数据

HTTP/1.1 401 Unauthorized
[...]
{"error":"authorization failed"}

将数据点写入不存在的数据库

HTTP/1.1 404 Not Found
[...]
{"error":"database not found: \"mydb1\""}

将数据点写入不存在的保留策略

HTTP/1.1 500 Internal Server Error
[...]
{"error":"retention policy not found: myrp"}

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.