文档

HTTP API

更新时间:
一键部署

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路径接受GETHEAD的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路径接受GETPOST的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 mytag1mytag2没有tag value。在第二个数据点中,时间戳是2017-03-01T00:17:18Z,field key myfield的值是12.4,tag key mytag1mytag2的值分别为1214

相同的查询在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 01970-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 mytag1mytag2都没有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®.

  • 本页导读 (1)
文档反馈