全部产品

HTTP API

更新时间:2019-04-19 15:50:31

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

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

TSDB For InfluxDB® HTTP路径(endpoint)

路径 描述
/debug/pprof 使用/debug/pprof生成故障排除的profile
/debug/requests 使用/debug/requests跟踪HTTP客户端发送到/write/query路径的请求
/debug/vars 使用/debug/vars收集统计信息
/ping 使用/ping检查TSDB For InfluxDB®实例的状态和TSDB For InfluxDB®的版本
/query 使用/query查询数据和管理数据库、保留策略和用户
/write 使用/write将数据写入到一个已经存在的数据库

/debug/pprof HTTP路径

TSDB For InfluxDB®支持Go版本的HTTP路径:net/http/pprof,这在排除故障时非常有用。pprofpprof可视化工具期望的格式提供数据的实时分析。

定义

  1. curl https://<网络地址>:3242/debug/pprof?u=<账号名称>&p=<密码>

/debug/pprof/路径生成一个HTML页面,其中包含内置的Go profile及其对应的超链接。

Profile 描述
block 导致同步阻塞的原语的stack跟踪
goroutine 所有当前goroutine的stack跟踪
heap heap分配的stack跟踪的采样
mutex 竞争互斥锁的持有者的stack跟踪
threadcreate 导致创建新的OS线程的stack跟踪

要访问上面列出的其中一个/debug/pprof/ profile,请使用以下的curl请求,将<profile>替换成profile的名字。最终生成的profile输出到中指定的文件。

  1. curl -o <path/to/output-file> https://<网络地址>:3242/debug/pprof/<profile>?u=<账号名称>&p=<密码>

在以下示例中,curl命令将生成的heap profile输出到一个文件:

  1. curl -o <path/to/output-file> https://<网络地址>:3242/debug/pprof/heap?u=<账号名称>&p=<密码>

您也可以使用Go pprof交互式工具来访问TSDB For InfluxDB® /debug/pprof/ profiles。例如,使用这个工具查看一个TSDB For InfluxDB®实例的heap profile,您可以使用以下命令:

  1. go tool pprof https://<网络地址>:3242/debug/pprof/heap?u=<账号名称>&p=<密码>

关于Go /net/http/pprof、交互式pprof分析和可视化工具的更多信息,请查看:

/debug/pprof/all HTTP路径

/debug/pprof/all路径是一个自定义的/debug/pprof profile,它生成profile.tar.gz,其中包含标准的Go profiling信息和其它调试数据的文本文件。当使用选项cpu=true时(默认cpu=false),会生成一个可选的CPU profile。

如果要创建profile.tar.gz,请使用以下的curl命令:

  1. curl -o profiles.tar.gz "https://<网络地址>:3242/debug/pprof/all?cpu=true&u=<账号名称>&p=<密码>"

注释:当使用选项cpu=true时,生成一个CPU profile需要30秒以上。如果您对运行CPU profile有所顾虑(对性能只有暂时的小影响),那么您可以设置?cpu=false或者干脆省略?cpu=true

如下例所示,curl的输出包含Time Spent,即花费的时间(以秒为单位)。当收集完30秒数据后,结果会输出到文件:

  1. ~ curl -o profiles.tar.gz "https://<网络地址>:3242/debug/pprof/all?cpu=true&u=<账号名称>&p=<密码>"
  2. % Total % Received % Xferd Average Speed Time Time Time Current
  3. Dload Upload Total Spent Left Speed
  4. 100 237k 0 237k 0 0 8025 0 --:--:-- 0:00:30 --:--:-- 79588

/debug/requests HTTP路径

使用/debug/requests来跟踪HTTP客户端发送到/write/query路径的请求。该路径返回每个用户和IP地址发送到TSDB For InfluxDB®的写请求和查询请求的数量。

定义

  1. curl https://<网络地址>:3242/debug/requests?u=<账号名称>&p=<密码>

字符串类型的查询参数

字符串类型的查询参数 可选/必需 定义
seconds=\ 可选 设置客户端收集信息的持续时间(duration,以秒为单位),默认的持续时间是10秒。

示例

跟踪十秒内的请求

  1. $ curl https://<网络地址>:3242/debug/requests?u=<账号名称>&p=<密码>
  2. {
  3. "user1:123.45.678.91": {"writes":1,"queries":0},
  4. }

返回结果显示,在过去的十秒内,用户user1从IP地址123.45.678.91发送了一个请求到/write路径,没有发送任何请求到/query路径。

跟踪一分钟内的请求

  1. $ curl https://<网络地址>:3242/debug/requests?seconds=60&u=<账号名称>&p=<密码>
  2. {
  3. "user1:123.45.678.91": {"writes":3,"queries":0},
  4. "user1:000.0.0.0": {"writes":0,"queries":16},
  5. "user2:xx.xx.xxx.xxx": {"writes":4,"queries":0}
  6. }

返回结果显示,在过去的一分钟内,user1123.45.678.91发送了三个请求到/write路径,user1000.0.0.0发送了16个请求到/query路径,user2xx.xx.xxx.xxx发送了四个请求到/write路径。

/debug/vars HTTP路径

TSDB For InfluxDB®通过/debug/vars路径公开它在运行时的统计信息,可通过以下curl命令访问:

  1. curl https://<网络地址>:3242/debug/vars?u=<账号名称>&p=<密码>

服务器的统计信息以JSON格式显示。

/ping HTTP路径

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

定义

  1. GET https://<网络地址>:3242/ping?u=<账号名称>&p=<密码>
  1. 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®的版本。

  1. ~ curl -sl -I https://<网络地址>:3242/ping?u=<账号名称>&p=<密码>
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
  5. X-Influxdb-Build: OSS
  6. X-Influxdb-Version: v1.7.x
  7. X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
  8. Date: Tue, 05 Nov 2018 16:08:32 GMT

状态码和响应

响应的正文是空的。

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

/query HTTP路径

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

定义

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

动词用法(Verb usage)

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

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

示例

使用SELECT语句查询数据

  1. $ curl -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. {"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®的命令行界面中则返回:

  1. name: mymeas
  2. time myfield mytag1 mytag2
  3. ---- ------- ------ ------
  4. 2017-03-01T00:16:18Z 33.1
  5. 2017-03-01T00:17:18Z 12.4 12 14

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

  1. $ curl -XPOST 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'
  2. {"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命令。另请参阅Request body
u=username 如果没有开启认证,这是可选的。开启认证后,这是必需的。 如果开启了认证,请设置用于认证的用户名。用户必须具有读数据库的权限。需要与参数p同时使用。

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

示例

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

  1. $ curl -G 'https://<网络地址>:3242/query?db=mydb&pretty=true&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. {
  3. "results": [
  4. {
  5. "statement_id": 0,
  6. "series": [
  7. {
  8. "name": "mymeas",
  9. "columns": [
  10. "time",
  11. "myfield",
  12. "mytag1",
  13. "mytag2"
  14. ],
  15. "values": [
  16. [
  17. "2017-03-01T00:16:18Z",
  18. 33.1,
  19. null,
  20. null
  21. ],
  22. [
  23. "2017-03-01T00:17:18Z",
  24. 12.4,
  25. "12",
  26. "14"
  27. ]
  28. ]
  29. }
  30. ]
  31. }
  32. ]
  33. }

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

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

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

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

选项(options)

请求多个查询

用分号(;)将多个查询隔开。

发送文件中的查询

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

语法:

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

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

语法:

  1. 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)进行编码:

查询语法:

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

映射语法:

  1. --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隔开。

示例

请求多个查询

  1. $ curl -G 'https://<网络地址>:3242/query?db=mydb&epoch=s&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas";SELECT mean("myfield") FROM "mymeas"'
  2. {"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格式的查询结果

  1. $ curl -H "Accept: application/csv" -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. name,tags,time,myfield,mytag1,mytag2
  3. mymeas,,1488327378000000000,33.1,mytag1,mytag2
  4. mymeas,,1488327438000000000,12.4,12,14

第一个数据点的两个tag key mytag1mytag2都没有tag value。

发送文件中的查询语句

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

其中,文件queries.txt中的查询如下:

  1. SELECT * FROM "mymeas";
  2. SELECT mean("myfield") FROM "mymeas";

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

  1. $ 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"}'
  2. {"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

  1. $ 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}'
  2. {"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

  1. $ 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}'
  2. {"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 无法处理该请求。可能是认证凭证无效引起的。

示例

成功返回数据的请求

  1. $ curl -i -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. HTTP/1.1 200 OK
  3. Connection: close
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:22:54 GMT
  8. Transfer-Encoding: chunked
  9. {"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"]]}]}]}

成功返回错误的请求

  1. $ curl -i -G 'https://<网络地址>:3242/query?db=mydb1&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. HTTP/1.1 200 OK
  3. Connection: close
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:23:48 GMT
  8. Transfer-Encoding: chunked
  9. {"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

格式错误的查询

  1. $ curl -i -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT *'
  2. HTTP/1.1 400 Bad Request
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 19:24:25 GMT
  7. Content-Length: 76
  8. {"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

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

  1. $ curl -i -XPOST 'https://<网络地址>:3242/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'
  2. HTTP/1.1 401 Unauthorized
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. Www-Authenticate: Basic realm="InfluxDB"
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:11:26 GMT
  8. Content-Length: 33
  9. {"error":"authorization failed"}

/write HTTP路径

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

定义

  1. 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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&precision=s&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:33:23 GMT

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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&rp=myrp&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:34:31 GMT

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

有效的凭证:

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=myusername&p=mypassword" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:34:56 GMT

无效的凭证:

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=myusername&p=notmypassword" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 401 Unauthorized
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. Www-Authenticate: Basic realm="InfluxDB"
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 17:40:30 GMT
  8. Content-Length: 33
  9. {"error":"authorization failed"}

使用基本(basic)认证,将数据点写入数据库mydb

有效的凭证:

  1. $ curl -i -XPOST -u myusername:mypassword "https://<网络地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:36:40 GMT

无效的凭证:

  1. $ curl -i -XPOST -u myusername:notmypassword "https://<网络地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 401 Unauthorized
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. Www-Authenticate: Basic realm="InfluxDB"
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 17:46:40 GMT
  8. Content-Length: 33
  9. {"error":"authorization failed"}

Request body

  1. --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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 18:02:57 GMT

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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 18:03:44 GMT

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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
  2. mymeas,mytag=2 myfield=34 1463689152000000000'
  3. HTTP/1.1 204 No Content
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 18:04:02 GMT

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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary @data.txt
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 18:08:11 GMT

其中,文件data.txt中的示例数据如下:

  1. mymeas,mytag1=1 value=21 1463689680000000000
  2. mymeas,mytag1=1 value=34 1463689690000000000
  3. mymeas,mytag2=8 value=78 1463689700000000000
  4. 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提供更多信息。

示例

写入成功

  1. HTTP/1.1 204 No Content

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

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

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

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

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

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

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

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

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

  1. HTTP/1.1 500 Internal Server Error
  2. [...]
  3. {"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®.