› 推特 ›阿里云技术文档›正文

HTTP API_工具_时序数据库 InfluxDB® 版_时序时空数据库TSDB

admin 阿里云技术文档 2020-02-11 220 0
阿里云服务器优惠

HTTP API

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，这在排除故障时非常有用。pprof以pprof可视化工具期望的格式提供数据的实时分析。

定义

  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=<密码>
  3. {
  4. "user1:123.45.678.91": {"writes":1,"queries":0},
  5. }

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

跟踪一分钟内的请求

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

返回结果显示，在过去的一分钟内，user1从123.45.678.91发送了三个请求到/write路径，user1从000.0.0.0发送了16个请求到/query路径，user2从xx.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路径接受GET和HEAD的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=<密码>
  3. HTTP/1.1 204 No Content
  4. Content-Type: application/json
  5. Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
  6. X-Influxdb-Build: OSS
  7. X-Influxdb-Version: v1.7.x
  8. X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
  9. Date: Tue, 05 Nov 2018 16:08:32 GMT

状态码和响应

响应的正文是空的。

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

/query HTTP路径

/query路径接受GET和POST的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"'
  3. {"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®的命令行界面中则返回：

  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"'
  3. {"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命令。另请参阅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"'
  3. {
  4.     "results": [
  5.         {
  6.             "statement_id": 0,
  7.             "series": [
  8.                 {
  9.                     "name": "mymeas",
  10.                     "columns": [
  11.                         "time",
  12.                         "myfield",
  13.                         "mytag1",
  14.                         "mytag2"
  15.                     ],
  16.                     "values": [
  17.                         [
  18.                             "2017-03-01T00:16:18Z",
  19.                             33.1,
  20.                             null,
  21.                             null
  22.                         ],
  23.                         [
  24.                             "2017-03-01T00:17:18Z",
  25.                             12.4,
  26.                             "12",
  27.                             "14"
  28.                         ]
  29.                     ]
  30.                 }
  31.             ]
  32.         }
  33.     ]
  34. }

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

  1. $ curl -G 'https://<网络地址>:3242/query?db=mydb&epoch=s&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  3. {"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"'
  3. {"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"'
  3. name,tags,time,myfield,mytag1,mytag2
  4. mymeas,,1488327378000000000,33.1,mytag1,mytag2
  5. mymeas,,1488327438000000000,12.4,12,14

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

发送文件中的查询语句

  1. $ curl -F "[email protected]" -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"}'
  3. {"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}'
  3. {"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}'
  3. {"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"'
  3. HTTP/1.1 200 OK
  4. Connection: close
  5. Content-Type: application/json
  6. Request-Id: [...]
  7. X-Influxdb-Version: 1.7.x
  8. Date: Wed, 08 Nov 2017 19:22:54 GMT
  9. Transfer-Encoding: chunked
  11. {"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"'
  3. HTTP/1.1 200 OK
  4. Connection: close
  5. Content-Type: application/json
  6. Request-Id: [...]
  7. X-Influxdb-Version: 1.7.x
  8. Date: Wed, 08 Nov 2017 19:23:48 GMT
  9. Transfer-Encoding: chunked
  11. {"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

格式错误的查询

  1. $ curl -i -G 'https://<网络地址>:3242/query?db=mydb&u=<账号名称>&p=<密码>' --data-urlencode 'q=SELECT *'
  3. HTTP/1.1 400 Bad Request
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:24:25 GMT
  8. Content-Length: 76
  10. {"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"'
  3. HTTP/1.1 401 Unauthorized
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. Www-Authenticate: Basic realm="InfluxDB"
  7. X-Influxdb-Version: 1.7.x
  8. Date: Wed, 08 Nov 2017 19:11:26 GMT
  9. Content-Length: 33
  11. {"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'
  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 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'
  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 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'
  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 17:34:56 GMT

无效的凭证：

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

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

有效的凭证：

  1. $ curl -i -XPOST -u myusername:mypassword "https://<网络地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'
  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 17:36:40 GMT

无效的凭证：

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

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

  1. $ curl -i -XPOST "https://<网络地址>:3242/write?db=mydb&u=<账号名称>&p=<密码>" --data-binary 'mymeas,mytag=1 myfield=90'
  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: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'
  4. HTTP/1.1 204 No Content
  5. Content-Type: application/json
  6. Request-Id: [...]
  7. X-Influxdb-Version: 1.7.x
  8. 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
  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: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®.

版权声明

本文仅代表作者观点，不代表本站立场。
本文系作者授权发表，未经许可，不得转载。

评论

-----