InfluxDB API 参考

InfluxDB API提供了一种简单的方法与数据库交互。它使用HTTP响应代码，使用用户名和密码凭据或API令牌进行身份验证，以及JSON格式的响应数据。

以下部分假设您的 InfluxDB 实例运行在 localhost 端口 8086 且未启用 HTTPS。这些设置是可配置的。

InfluxDB 2.x API 兼容性端点
InfluxDB 1.x HTTP 端点

InfluxDB 2.x API 兼容性端点

InfluxDB 1.8.0 引入了与 InfluxDB 2.x 向前兼容的 API。引入这些的原因有多种：

InfluxDB 2.x 客户端库是为 InfluxDB /api/v2 API 构建的，适用于 InfluxDB 2.x 和 InfluxDB 1.8+。
InfluxDB Cloud 是一个在多个云服务提供商和地区普遍可用的服务，完全兼容 InfluxDB 2.x 客户端库。

如果您今天刚开始使用 InfluxDB 1.x，我们建议采用最新的 InfluxDB 2.x 客户端库。它们使您能够轻松地从 InfluxDB 1.x 迁移到 InfluxDB OSS 2.x 或 InfluxDB Cloud （当您准备好时）。

以下可向前兼容的API可用：

端点	描述
/api/v2/query	使用 InfluxDB 2.x API 和 Flux 在 InfluxDB 1.8.0+ 中查询数据
/api/v2/write	使用 InfluxDB 2.x API 将数据写入 InfluxDB 1.8.0+ (与 InfluxDB 2.x 客户端库兼容)
/health	检查您的InfluxDB实例的健康状况
/api/v2/buckets	允许某些使用桶的客户端代码在1.X和2.X上运行而无需修改
/api/v2/delete	支持通过标签值、时间戳和测量值使用 InfluxDB 2.x API 进行删除

`/api/v2/query/` HTTP 端点

此 /api/v2/query 端点接受 POST HTTP 请求。
使用此端点通过 Flux 和 InfluxDB 2.x client libraries 查询数据。
Flux 是在 InfluxDB 2.x 中处理数据的主要语言。

包含以下HTTP头：

Accept: application/csv
Content-type: application/vnd.flux
如果启用了身份验证，提供您的 InfluxDB 用户名和密码：
Authorization: Token USERNAME:PASSWORD

未授权已启用授权

curl -XPOST localhost:8086/api/v2/query -sS \
  -H 'Accept:application/csv' \
  -H 'Content-type:application/vnd.flux' \
  -d 'from(bucket:"telegraf")
        |> range(start:-5m)
        |> filter(fn:(r) => r._measurement == "cpu")'

curl -XPOST localhost:8086/api/v2/query -sS \
  -H 'Accept:application/csv' \
  -H 'Content-type:application/vnd.flux' \
  -H 'Authorization: Token USERNAME:PASSWORD' \
  -d 'from(bucket:"telegraf")
        |> range(start:-5m)
        |> filter(fn:(r) => r._measurement == "cpu")'

`/api/v2/write/` HTTP 端点

该 /api/v2/write 端点接受 POST HTTP 请求。
使用此端点可以通过 InfluxDB 2.x client libraries 向 InfluxDB 1.8.0+ 数据库写入数据。

InfluxDB 1.x 和 2.x API 支持相同的原始时间序列数据行协议格式。在写入数据方面，API 仅在 URL 参数和请求头上有所不同。 InfluxDB 2.x 使用 organizations 和 buckets 代替数据库和保留策略。 /api/v2/write 端点将提供的 1.8 版本数据库和保留策略映射到一个桶。

包含以下URL参数：

bucket: 提供数据库名称和保留策略，以斜杠 (/) 分隔。例如: database/retention-policy。空的保留策略映射到默认的保留策略。 database/weekly 映射到一个名为“database”的数据库和一个名为“weekly”的保留策略。 database/ 和 database 映射到一个名为“database”的数据库和默认的保留策略。
org: 在 InfluxDB 1.x 中，没有组织的概念。org 参数被忽略，可以留空。
precision: 行协议中时间戳的精度。接受 ns（纳秒）、us（微秒）、ms（毫秒）和 s（秒）。

包含以下HTTP头：

Authorization: InfluxDB 2.x 使用此头部与 Token 方案和 API Tokens 来验证每个 API 请求。 InfluxDB v1.x 使用用户名和密码凭据来验证 API 请求。要提供 InfluxDB 1.x 凭据，使用 Token 方案，并包括您的用户名和密码，以冒号 (:) 分隔。
- Token 方案与 v1.x 凭证：
```
Authorization: Token USERNAME:PASSWORD
```

未授权已启用授权

curl -XPOST "localhost:8086/api/v2/write?bucket=db/rp&precision=s" \
  --data-raw "mem,host=host1 used_percent=23.43234543 1556896326"

curl -XPOST "localhost:8086/api/v2/write?bucket=db/rp&precision=s" \
  -H 'Authorization: Token <username>:<password>' \
  --data-raw "mem,host=host1 used_percent=23.43234543 1556896326"

`/health` HTTP 端点

该 /health 端点接受 Get HTTP 请求。
使用此端点检查您的 InfluxDB 实例的健康状态。

curl -XGET "localhost:8086/health"

/健康端点响应

响应代码	健康状况	消息	状态
200	健康	`ready for queries and writes`	`pass`
503	不健康		`fail`

`/api/v2/buckets/` HTTP 端点

/api/v2/buckets 端点接受 GET、POST 和 DELETE HTTP 请求。使用此端点来创建、删除、列出、更新和检索您的 InfluxDB 实例中的桶。请注意，InfluxDB 2.x 使用组织和桶，而不是数据库和保留策略。

包含以下URL参数：

bucket: 提供数据库名称和保留策略，用斜杠 (/) 分隔。例如：database/retention-policy。空的保留策略映射到默认的保留策略。
org: 在 InfluxDB 1.x 中，没有组织的概念。org 参数被忽略，可以留空。

包含以下HTTP头：

Authorization: InfluxDB 2.x 使用此头部与 Token 方案和 API Tokens 来验证每个 API 请求。 InfluxDB v1.x 使用用户名和密码凭据来验证 API 请求。要提供 InfluxDB 1.x 凭据，使用 Token 方案，并包括您的用户名和密码，以冒号 (:) 分隔。
- Token 方案与 v1.x 凭证：
```
Authorization: Token USERNAME:PASSWORD
```

以下示例展示了如何列出所有数据库：

curl --request GET "http://localhost:8086/api/v2/buckets"   
  -H 'Authorization: Token <username>:<password>'

以下示例演示如何删除名为“test”的数据库：

curl --request DELETE "http://localhost:8086/api/v2/buckets/test/autogen" 
  --header "Content-type: application/json"   
  -H 'Authorization: Token <username>:<password>'

`/api/v2/delete/` HTTP 端点

该 /api/v2/delete 端点接受 POST HTTP 请求。使用此端点从 InfluxDB 删除数据点，包括具有特定标签值、时间戳和测量值的数据点。

包含以下URL参数：

bucket: 提供数据库名称和保留策略，用斜杠 (/) 分隔。例如: database/retention-policy。
precision: 行协议中时间戳的精度。接受 ns（纳秒）、us（微秒）、ms（毫秒）和 s（秒）。

包含以下HTTP头：

Authorization: InfluxDB 2.x 使用此头部与 Token 方案和 API Tokens 来验证每个 API 请求。 InfluxDB v1.x 使用用户名和密码凭据来验证 API 请求。要提供 InfluxDB 1.x 凭据，使用 Token 方案，并包括您的用户名和密码，以冒号 (:) 分隔。
- Token 方案与 v1.x 凭证：
```
Authorization: Token USERNAME:PASSWORD
```

删除指定时间范围内的所有点：

curl --request POST "http://localhost:8086/api/v2/delete?bucket=exampleDB/autogen \
  --header 'Authorization: Token <username>:<password>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2020-03-01T00:00:00Z",
    "stop": "2020-11-14T00:00:00Z"
    }'

删除具有特定标签值的特定测量中的点：

curl --request POST "http://localhost:8086/api/v2/delete?bucket=exampleDB/autogen \
  --header 'Authorization: Token <username>:<password>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2020-03-01T00:00:00Z",
    "stop": "2020-11-14T00:00:00Z",
    "predicate": "_measurement=\"example-measurement\" AND exampleTag=\"exampleTagValue\""
    }'

如果您在请求中使用 predicate 选项，请查看 delete predicate syntax 并注意其 limitations。

InfluxDB 1.x HTTP 端点

以下 InfluxDB 1.x API 端点可用：

端点	描述
/debug/pprof	生成用于故障排除的分析数据
/debug/requests	跟踪HTTP客户端请求到`/write`和`/query`端点
/debug/vars	收集内部的InfluxDB统计信息
/ping	检查您的InfluxDB实例的状态和您的InfluxDB版本
/query	使用 InfluxQL 查询数据，管理数据库、保留策略和用户
/write	将数据写入数据库
/shard-status	获取有关数据节点分片的信息

`/debug/pprof` HTTP 端点

InfluxDB 支持 Go net/http/pprof HTTP 端点，这对于故障排除很有用。 pprof 包提供了以 pprof 可视化工具预期的格式的运行时性能数据。

定义

curl http://localhost:8086/debug/pprof/

此 /debug/pprof/ 端点生成一个包含内置 Go 配置文件列表及每个文件超链接的 HTML 页面。

个人信息	描述
块	导致在同步原语上阻塞的堆栈跟踪。
goroutine	所有当前 goroutine 的堆栈跟踪。
堆	对堆分配的堆栈跟踪进行采样。
互斥锁	竞争互斥锁的持有者的堆栈跟踪。
threadcreate	导致新操作系统线程创建的堆栈跟踪。

要访问上述列出的其中一个 /debug/pprof/ 配置文件，请使用以下 cURL 请求，将 <profile> 替换为配置文件的名称。结果配置文件输出到在 <path/to/output-file> 中指定的文件。

curl -o <path/to/output-file>  http://localhost:8086/debug/pprof/<profile>

在以下示例中，cURL 命令将结果堆配置文件输出到文件中：

curl -o <path/to/output-file> http://localhost:/8086/debug/pprof/heap

您还可以使用Go pprof 交互工具来访问InfluxDB /debug/pprof/ 资料。例如，要使用该工具查看InfluxDB实例的堆资料，您可以使用类似于以下的命令：

go tool pprof http://localhost:8086/debug/pprof/heap

有关 Go /net/http/pprof 包以及交互式 pprof 分析和可视化工具的更多信息，请参见：

`/debug/pprof/all` HTTP 端点

这个 /debug/pprof/all 端点是一个自定义的 /debug/pprof 配置，主要供 InfluxData 支持使用。这个端点生成一个 profile.tar.gz 压缩包，包含带有标准 Go 性能分析信息和额外调试数据的文本文件。当使用 cpu= 选项后跟以秒为单位的持续时间时（例如，cpu=30s），将生成一个可选的 CPU 配置。

要创建一个 profile.tar.gz 归档文件，请使用以下 cURL 命令生成一个 profile.tar.gz 文件，以便与 InfluxData 支持团队共享。

curl -o profiles.tar.gz "http://localhost:8086/debug/pprof/all?cpu=30s"

cURL 输出包括“消耗时间”，经过的时间（以秒为单位）。

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  237k    0  237k    0     0   8025      0 --:--:--  0:00:30 --:--:-- 79588

在收集了30秒的数据后，结果将输出到指定的文件。

`/debug/requests` HTTP 端点

使用此端点来跟踪对 /write 和 /query 端点的HTTP客户端请求。 /debug/requests 端点返回每个用户名和IP地址对InfluxDB的写入和查询次数。

定义

curl http://localhost:8086/debug/requests

查询字符串参数

查询字符串参数	可选/必需	定义
seconds=<integer>	可选	设置客户端收集信息的持续时间（以秒为单位）。默认持续时间为十秒。

示例

在十秒间隔内跟踪请求

$ curl http://localhost:8086/debug/requests

{
"user1:123.45.678.91": {"writes":1,"queries":0},
}

响应显示，在过去的十秒内，user1用户向/write端点发送了一条请求，而没有向/query端点发送请求，IP地址为123.45.678.91。

跟踪一分钟时间间隔内的请求

$ curl http://localhost:8086/debug/requests?seconds=60

{
"user1:123.45.678.91": {"writes":3,"queries":0},
"user1:000.0.0.0": {"writes":0,"queries":16},
"user2:xx.xx.xxx.xxx": {"writes":4,"queries":0}
}

响应显示，在过去的分钟内， user1 从 123.45.678.91 向 /write 端点发送了三次请求， user1 从 000.0.0.0 向 /query 端点发送了16次请求，而 user2 从 xx.xx.xxx.xxx 向 /write 端点发送了四次请求。

`/debug/vars` HTTP 端点

InfluxDB 通过 /debug/vars 端点公开统计信息和运行时信息，可以使用以下 cURL 命令访问：

curl http://localhost:8086/debug/vars

服务器统计信息以JSON格式显示。有关InfluxDB HTTP服务器指标的信息，请参见httpd度量.

注意： InfluxDB 输入插件可用于从指定的 Kapacitor 实例收集度量（使用 /debug/vars 端点）。有关测量和字段的列表，请参见 InfluxDB 输入插件 README。

`/ping` HTTP 端点

ping 端点同时接受 GET 和 HEAD HTTP 请求。使用此端点检查你的 InfluxDB 实例的状态和你的 InfluxDB 版本。

定义

GET http://localhost:8086/ping

HEAD http://localhost:8086/ping

`verbose` 选项

默认值是 false。默认情况下，/ping HTTP 端点以 HTTP 状态 204 响应，并且响应主体为空，以告知客户端服务器正在运行。如果设置为 true (/ping?verbose=true)，服务器将以 HTTP 状态 200 状态和包含详细信息的响应主体进行响应。 verbose=true 选项是 Google Cloud Load Balancing 健康检查所需的。

示例

您可以使用 /ping 端点来查找 InfluxDB 实例的构建和版本。 X-Influxdb-Build 头字段显示 InfluxDB 的构建类型，可以是 OSS（开源）或 ENT（企业版）。 X-Influxdb-Version 头字段显示 InfluxDB 的版本。

~ curl -sl -I http://localhost:8086/ping

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.11.8
X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
Date: Tue, 05 Nov 2018 16:08:32 GMT

状态码和响应

响应主体为空。

HTTP 状态码	描述
204	成功！您的 InfluxDB 实例已启动并正在运行。

`/query` HTTP 端点

这个 /query 端点接受 GET 和 POST HTTP 请求。使用这个端点来查询数据和管理数据库、保留策略，以及用户。

定义

GET http://localhost:8086/query

POST http://localhost:8086/query

动词用法

动词	查询类型
GET	用于所有以以下内容开头的查询： `SELECT`* `SHOW`
POST	用于所有以以下内容开头的查询： `ALTER` `CREATE` `DELETE` `DROP` `GRANT` `KILL` `REVOKE`

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

示例

使用 `SELECT` 语句查询数据

$ curl -G 'http://localhost:8086/query?db=mydb' --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"]]}]}]}

该 mymeas 测量有两个点。第一个点的时间戳是 2017-03-01T00:16:18Z, myfield 的值为 33.1, 并且没有 mytag1 和 mytag2 的标签键值。第二个点的时间戳是 2017-03-01T00:17:18Z, myfield 的值为 12.4, mytag1 的值为 12, 和 mytag2 的值为 14。

在InfluxDB 命令行界面 (CLI) 中执行相同的查询会返回以下表格：

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 'http://localhost:8086/query?db=mydb' --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 请求。

响应显示 InfluxDB 向 newmeas 测量写入了两个点。注意，系统使用纪元 0 (1970-01-01T00:00:00Z) 作为空时间戳等效。

创建数据库

$ curl -XPOST 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE "mydb"'

{"results":[{"statement_id":0}]}

一个成功的 CREATE DATABASE 查询不返回额外的信息。

查询字符串参数

查询字符串参数	可选/必需	定义
chunked=[true \| <number_of_points>]	可选	返回以流式批处理方式的点，而不是单个响应。如果设置为 `true`，InfluxDB 将按系列或每 10,000 个点进行分块响应，以先到者为准。如果设置为特定值，InfluxDB 将按系列或按该点数进行分块响应.*
db=<database_name>	在依赖于数据库的查询中是必需的（大多数 `SELECT` 查询和 `SHOW` 查询需要此参数）。	设置查询的目标 database。
epoch=[ns,u,µ,ms,s,m,h]	可选	返回具有指定精度的时间戳。默认情况下，InfluxDB 以纳秒精度以 RFC3339 格式返回时间戳。`u` 和 `µ` 都表示微秒。
p=<password>	如果您尚未启用身份验证，则为可选项。如果您已启用身份验证，则为必需项。**	如果您已启用身份验证，则设置身份验证的密码。与查询字符串参数 `u` 一起使用。
pretty=true	可选	启用美化的 JSON 输出。虽然这对于调试非常有用，但不推荐用于生产环境，因为它消耗了不必要的网络带宽。
q=<query>	必需	要执行的InfluxQL字符串。另见请求体。
u=<用户名>	如果您没有启用身份验证，则此项为可选。如果您已启用身份验证，则此项为必需。	如果您已启用身份验证，则设置用于身份验证的用户名。该用户必须具有数据库的读取权限。与查询字符串参数`p`一起使用。

* InfluxDB 不会截断没有 chunked 参数的请求返回的行数。该行为是可配置的；有关更多信息，请参阅 max-row-limit 配置选项。

** InfluxDB API 还支持基本身份验证。如果您已启用身份验证并且不使用查询字符串参数 u 和 p，请使用基本身份验证。请参阅下面的示例以了解基本身份验证。

示例

使用 `SELECT` 语句查询数据并返回格式化的 JSON

$ curl -G 'http://localhost:8086/query?db=mydb&pretty=true' --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`语句查询数据并返回秒精度的时间戳

$ curl -G 'http://localhost:8086/query?db=mydb&epoch=s' --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"]]}]}]}

使用HTTP认证创建数据库

以下示例展示了如何使用 v1.x 凭据在查询字符串中进行身份验证并创建数据库：

$ curl -XPOST 'http://localhost:8086/query?u=myusername&p=mypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'

响应体包含以下内容：

{"results":[{"statement_id":0}]}

一个成功的 CREATE DATABASE 查询不返回额外的信息。

以下示例传递无效凭据：

curl -XPOST 'http://localhost:8086/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'

响应体包含以下内容：

{"error":"authorization failed"}

使用基本认证创建数据库

以下示例展示了如何使用 v1.x 凭据进行基本认证并创建数据库。

curl -XPOST -u myusername:mypassword 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE "mydb"'

{"results":[{"statement_id":0}]}

一个成功的 CREATE DATABASE 查询不返回额外的信息。

以下示例使用无效凭证。

curl -XPOST -u myusername:notmypassword 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE "mydb"'

响应体包含以下内容：

{"error":"authorization failed"}

请求体

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

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

选项

请求多个查询

用分号 ; 分隔多个查询。

从文件提交查询

此API支持使用 multipart POST 请求从文件提交查询。文件中的查询必须用分号 (;) 分隔。

语法：

curl -F "q=@<path_to_file>" -F "async=true" http://localhost:8086/query

以CSV格式请求查询结果

语法：

curl -H "Accept: application/csv" -G 'http://localhost:8086/query' [...]

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

绑定参数

该API支持将参数绑定到特定的字段值或标签值。使用语法 $<placeholder_key> 作为查询中的占位符，并在请求体中对占位符键到占位符值的映射进行URL编码。这允许所有可定制值的InfluxQL查询——例如字段值、函数名称或时间间隔——使用绑定参数表示。

查询语法：

--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>" ]}'

用逗号 , 分隔多个占位符键值对。

示例

发送多个查询

$ curl -G 'http://localhost:8086/query?db=mydb&epoch=s' --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_id 为 0，第二个查询的结果具有 statement_id 为 1。

以CSV格式请求查询结果

$ curl -H "Accept: application/csv" -G 'http://localhost:8086/query?db=mydb' --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 values 对于 mytag1 和 mytag2 tag keys。

从文件提交查询

curl -F "q=@queries.txt" -F "async=true" 'http://localhost:8086/query'

在 queries.txt 中的查询示例：

CREATE DATABASE mydb;
CREATE RETENTION POLICY four_weeks ON mydb DURATION 4w REPLICATION 1;

将`WHERE`子句中的参数绑定到特定的标签值

$ curl -G 'http://localhost:8086/query?db=mydb' --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。 InfluxDB 将 tag values 存储为字符串，并且在请求中必须用双引号括起来。

将`WHERE`子句中的一个参数绑定到一个数值字段值

$ curl -G 'http://localhost:8086/query?db=mydb' --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 存储数值字段值。

将两个参数绑定到`WHERE`子句中的特定标签值和数字字段值

$ curl -G 'http://localhost:8086/query?db=mydb' --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。

状态码和响应

API响应体包含以JSON格式的结果或错误消息。要进行漂亮打印以便查看JSON，请包含查询字符串参数 pretty=true 或将响应传递给像 jq 这样的JSON处理器。

摘要表

HTTP 状态码	描述
200 OK	成功。响应体包含JSON格式的数据。
400 错误请求	不可接受的请求。可能由于语法上不正确的查询导致。响应体包含附加信息的错误消息，格式为JSON。
401 Unauthorized	不可接受的请求。可能是由于无效的身份验证凭据。

示例

返回数据的成功请求

$ curl -i -G 'http://localhost:8086/query?db=mydb' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.11.8
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 'http://localhost:8086/query?db=mydb1' --data-urlencode 'q=SELECT * FROM "mymeas"'

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

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

格式不正确的查询

$ curl -i -G 'http://localhost:8086/query?db=mydb' --data-urlencode 'q=SELECT *'

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.11.8
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 'http://localhost:8086/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.11.8
Date: Wed, 08 Nov 2017 19:11:26 GMT
Content-Length: 33

{"error":"authorization failed"}

`/write` HTTP 端点

这个 /write 端点接受 POST HTTP 请求。
使用此端点将数据写入现有数据库。

定义

POST http://localhost:8086/write

查询字符串参数

查询字符串参数	可选/必需	描述
consistency=[any,one,quorum,all]	可选，仅在 InfluxDB Enterprise 集群中可用。	设置该点的写入一致性。如果您不指定 `consistency`，InfluxDB 假定写入一致性为 `one`。有关每个一致性选项的详细说明，请参见 InfluxDB Enterprise 文档。
db=<database>	必填	设置写入的目标数据库。
p=<password>	如果您尚未启用身份验证，则为可选。如果您已经启用身份验证，则为必需。	如果您已启用身份验证，则设置身份验证的密码。与查询字符串参数`u`一起使用。
precision=[纳秒,微秒,毫秒,秒,分钟,小时]	可选	为提供的Unix时间值设置精度。如果您不指定 `precision`，InfluxDB 假定时间戳是以纳秒为单位的。**
rp=<retention_policy_name>	可选	设置写入的目标保留策略。如果不指定保留策略，InfluxDB 会写入 `DEFAULT` 保留策略。
u=<username>	如果您没有启用身份验证，则这是可选的。如果您已启用身份验证，则这是必需的。	如果您已启用身份验证，则设置身份验证的用户名。用户必须具有对数据库的写入访问权限。与查询字符串参数`p`一起使用。

* InfluxDB API 也支持基本认证。如果您已启用认证并且没有使用查询字符串参数 u 和 p，则使用基本认证。请查看以下示例以了解基本认证。

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

示例

将一个带有时间戳（秒）的点写入数据库 `mydb`

$ curl -i -XPOST "http://localhost:8086/write?db=mydb&precision=s" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'

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

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

$ curl -i -XPOST "http://localhost:8086/write?db=mydb&rp=myrp" --data-binary 'mymeas,mytag=1 myfield=90'

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

使用HTTP认证将一个点写入数据库 `mydb`

有效的凭证：

$ curl -i -XPOST "http://localhost:8086/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.11.8
Date: Wed, 08 Nov 2017 17:34:56 GMT

无效的凭据：

$ curl -i -XPOST "http://localhost:8086/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.11.8
Date: Wed, 08 Nov 2017 17:40:30 GMT
Content-Length: 33

{"error":"authorization failed"}

使用基本认证将一个点写入数据库 `mydb`

有效的凭证：

$ curl -i -XPOST -u myusername:mypassword "http://localhost:8086/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.11.8
Date: Wed, 08 Nov 2017 17:36:40 GMT

无效的凭据：

$ curl -i -XPOST -u myusername:notmypassword "http://localhost:8086/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.11.8
Date: Wed, 08 Nov 2017 17:46:40 GMT
Content-Length: 33

{"error":"authorization failed"}

请求体

--data-binary '<Data in InfluxDB line protocol format>'

所有数据必须是二进制编码，并且采用 InfluxDB 行协议格式。我们的例子展示了 --data-binary 参数来自 curl，我们将在本页的所有示例中使用它。使用除 --data-binary 以外的任何编码方法可能会导致问题； -d、--data-urlencode 和 --data-ascii 可能会去掉换行或引入新的、未预期的格式。

选项：

通过换行符将每个点分开，使用一个请求将多个点写入数据库。
使用 @ 标志从文件中写入点。文件应包含以 InfluxDB 行协议格式批量写入的点。每个点必须单独占据一行，并由换行符 (\n) 分隔。包含回车的文件会导致解析错误。
我们建议将数据分批写入，每批5,000到10,000个点。更小的批次和更多的HTTP请求将导致性能不 optimal。

示例

将一个点写入数据库 `mydb`，使用纳秒时间戳

$ curl -i -XPOST "http://localhost:8086/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'

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

将一个点写入数据库 `mydb`，并使用本地服务器的纳秒时间戳

$ curl -i -XPOST "http://localhost:8086/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=90'

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

通过用新行分隔点将几个点写入数据库 `mydb`

$ curl -i -XPOST "http://localhost:8086/write?db=mydb" --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.11.8
Date: Wed, 08 Nov 2017 18:04:02 GMT

从文件 `data.txt` 向数据库 `mydb` 写入多个点

$ curl -i -XPOST "http://localhost:8086/write?db=mydb" --data-binary @data.txt

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.11.8
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

状态码和响应

一般来说，HTTP 2xx 状态码表示成功，4xx 状态码表示 InfluxDB 无法理解请求，而 5xx 状态码表示系统过载或显著受损。响应体包含以 JSON 格式的错误消息。

摘要表

HTTP 状态码	描述
204 没有内容	成功!
400 错误请求	不可接受的请求。这可能发生在 InfluxDB 行协议语法错误时，或当用户尝试向一个以前接受过不同值类型的字段写入值时。返回的 JSON 提供了进一步的信息。
401 Unauthorized	不可接受的请求。可能是由于无效的身份验证凭据。
404 未找到	不可接受的请求。如果用户尝试写入一个不存在的数据库，则可能会发生此情况。返回的 JSON 提供了更多信息。
413 请求实体过大	不可接受的请求。如果POST请求的有效负载超出了允许的最大大小，就会发生此情况。请参阅 `max-body-size` 参数以获取更多详细信息。
500 内部服务器错误	系统过载或严重受损。如果用户尝试写入不存在的保留策略，则可能会发生。返回的 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"}

将整数写入之前接受浮点数的字段

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/2 413 Request Entity Too Large
[...]
{"error":"Request Entity Too Large"}

写入一个不存在的保留策略的点

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

`/shard-status` HTTP 端点

这个 /shard-status 端点接受 HTTP GET 请求。使用此端点获取有关特定数据节点的所有分片的信息。

响应

对 /shard-status 的请求返回以下信息，格式为 JSON：

id: 分片ID
size: 分片在磁盘上的大小，以字节为单位
is_hot: whether the time range from the shard includes now
一个空闲分片是完全压缩的，并且不接收新的（可能是历史的）写入。一个热分片可能是空闲的，也可能不是。
state: 分片的反熵状态可以是以下之一： healthy,restore pending,restoring,repairing,error processing

示例

curl -q 'http://localhost:8086/shard-status' | jq
{
  "databases": [
    {
      "name": "_internal",
      "retention_policies": [
        {
          "name": "monitor",
          "replication_factor": 1,
          "shards": [
            {
              "id": 2,
              "size": 594491,
              "is_hot": true
            }
          ]
        }
      ]
    },
    {
      "name": "stress",
      "retention_policies": [
        {
          "name": "autogen",
          "replication_factor": 1,
          "shards": [
            {
              "id": 3,
              "is_hot": false
            },
            {
              "id": 6,
              "size": 1921,
              "is_hot": false
            },
            {
              "id": 7,
              "is_hot": false
            },
            {
              "id": 10,
              "size": 1920,
              "is_hot": false
            },
            {
              "id": 11,
              "is_hot": true
            }
          ]
        }
      ]
    }
  ]
}

这个例子使用jq来打印JSON对象。

InfluxDB API 参考

InfluxDB 2.x API 兼容性端点

/api/v2/query/ HTTP 端点

/api/v2/write/ HTTP 端点

/health HTTP 端点

/健康端点响应

/api/v2/buckets/ HTTP 端点

/api/v2/delete/ HTTP 端点

InfluxDB 1.x HTTP 端点

/debug/pprof HTTP 端点

定义

/debug/pprof/all HTTP 端点

/debug/requests HTTP 端点

定义

查询字符串参数

示例

在十秒间隔内跟踪请求

跟踪一分钟时间间隔内的请求

/debug/vars HTTP 端点

/ping HTTP 端点

定义

verbose 选项

示例

状态码和响应

/query HTTP 端点

定义

动词用法

示例

使用 SELECT 语句查询数据

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

创建数据库

查询字符串参数

示例

使用 SELECT 语句查询数据并返回格式化的 JSON

使用SELECT语句查询数据并返回秒精度的时间戳

使用HTTP认证创建数据库

使用基本认证创建数据库

请求体

选项

请求多个查询

从文件提交查询

以CSV格式请求查询结果

绑定参数

示例

发送多个查询

以CSV格式请求查询结果

从文件提交查询

将WHERE子句中的参数绑定到特定的标签值

将WHERE子句中的一个参数绑定到一个数值字段值

将两个参数绑定到WHERE子句中的特定标签值和数字字段值

状态码和响应

摘要表

示例

返回数据的成功请求

包含错误的查询

格式不正确的查询

请求的身份验证凭据无效

/write HTTP 端点

定义

查询字符串参数

示例

将一个带有时间戳（秒）的点写入数据库 mydb

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

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

使用基本认证将一个点写入数据库 mydb

请求体

示例

将一个点写入数据库 mydb，使用纳秒时间戳

将一个点写入数据库 mydb，并使用本地服务器的纳秒时间戳

通过用新行分隔点将几个点写入数据库 mydb

从文件 data.txt 向数据库 mydb 写入多个点

状态码和响应

摘要表

示例

成功的写入

写一个带有错误时间戳的点

将整数写入之前接受浮点数的字段

使用无效的身份验证凭据写入一个点

写入一个不存在的数据库中的数据

发送一个过大的请求体

`/api/v2/query/` HTTP 端点

`/api/v2/write/` HTTP 端点

`/health` HTTP 端点

`/api/v2/buckets/` HTTP 端点

`/api/v2/delete/` HTTP 端点

`/debug/pprof` HTTP 端点

`/debug/pprof/all` HTTP 端点

`/debug/requests` HTTP 端点

`/debug/vars` HTTP 端点

`/ping` HTTP 端点

`verbose` 选项

`/query` HTTP 端点

使用 `SELECT` 语句查询数据

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

使用 `SELECT` 语句查询数据并返回格式化的 JSON

使用`SELECT`语句查询数据并返回秒精度的时间戳

将`WHERE`子句中的参数绑定到特定的标签值

将`WHERE`子句中的一个参数绑定到一个数值字段值

将两个参数绑定到`WHERE`子句中的特定标签值和数字字段值

`/write` HTTP 端点

将一个带有时间戳（秒）的点写入数据库 `mydb`

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

使用HTTP认证将一个点写入数据库 `mydb`

使用基本认证将一个点写入数据库 `mydb`

将一个点写入数据库 `mydb`，使用纳秒时间戳

将一个点写入数据库 `mydb`，并使用本地服务器的纳秒时间戳

通过用新行分隔点将几个点写入数据库 `mydb`

从文件 `data.txt` 向数据库 `mydb` 写入多个点

`/shard-status` HTTP 端点