InfluxDB API 参考文档

此页面记录了早期版本的 InfluxDB OSS。 InfluxDB OSS v2 是最新的稳定版本。请参阅对应的 InfluxDB v2 文档： InfluxDB HTTP API。

InfluxDB API 提供了一种与数据库交互的简单方式。它使用 HTTP 身份验证和 JWT 令牌。响应使用标准 HTTP 响应代码和 JSON 格式。

要发送 API 请求，您可以使用 InfluxDB v1 客户端库、InfluxDB v2 客户端库、Telegraf 或您选择的客户端。

如果您开始使用 InfluxDB v1，我们建议使用 InfluxDB v1 客户端库和 InfluxQL 以获得 InfluxDB 3 兼容性。

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

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

InfluxDB 3 兼容性

InfluxDB 3 是 InfluxDB 的下一代产品，它允许无限的序列基数，而不会影响整体数据库性能，并带来了原生的 SQL 支持和改进的 InfluxQL 性能。

InfluxDB 3 支持 v1 版本的 /write 和 /query HTTP API 端点。InfluxDB 3 未针对 Flux 进行优化。

如果您开始使用 InfluxDB v1，我们建议使用 InfluxDB v1 客户端库和 InfluxQL。当您准备就绪时，您可以迁移到 InfluxDB 3 并继续使用 v1 客户端库，同时逐步将您的查询工作负载迁移到使用 v3 客户端库（和 v3 Flight API）。

有关更多信息，请参阅 InfluxDB 3 的 API 兼容性和迁移指南。

InfluxDB 2.x API 兼容性端点

InfluxDB 1.8.0 引入了 InfluxDB v2 的向前兼容性 API。InfluxDB v2 客户端库是为 InfluxDB v2 API 构建的，但也适用于 InfluxDB 1.8+。

InfluxDB v1 支持以下 v2 兼容的 API

端点	描述
/api/v2/query	使用 InfluxDB v2 API 和 Flux 在 InfluxDB 1.8.0+ 中查询数据
/api/v2/write	使用 InfluxDB v2 API 写入数据到 InfluxDB 1.8.0+ (兼容 InfluxDB v2 客户端库)
/api/v2/buckets	允许一些使用 bucket 的客户端代码在 1.x 和 2.x 版本上运行而无需修改
/api/v2/delete	支持使用 InfluxDB v2 API 按标签值、时间戳和 measurement 删除数据 (兼容 InfluxDB v2 客户端库)
/health	检查 InfluxDB 实例的健康状况

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

/api/v2/query 端点接受 POST HTTP 请求。使用此端点使用 Flux 和 InfluxDB v2 客户端库查询数据。Flux 是在 InfluxDB v2 中处理数据的主要语言。

包含以下 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 v2 客户端库写入数据到 InfluxDB 1.8.0+ 数据库。

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

包含以下 URL 参数

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

包含以下 HTTP 标头

Authorization: 在 InfluxDB v2 中，使用 API 令牌来访问平台及其所有功能。InfluxDB v1.x 在访问 HTTP API 时使用用户名和密码组合。使用 Token schema 提供您的 InfluxDB 1.x 用户名和密码，用冒号 (:) 分隔。Token schema 是单词 Token，一个空格，以及您的凭据（所有内容都区分大小写）。例如：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"

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

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

包含以下 URL 参数

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

包含以下 HTTP 标头

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

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

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

以下示例展示了如何删除名为 test 的数据库

curl --request DELETE "https://127.0.0.1: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 中删除数据点，包括具有特定标签值、时间戳和 measurement 的数据点。

包含以下 URL 参数

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

包含以下 HTTP 标头

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

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

curl --request POST "https://127.0.0.1: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"
    }'

删除具有特定标签值的特定 measurement 中的数据点

curl --request POST "https://127.0.0.1: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 选项，请查看删除谓词语法并注意其局限性。

`/health` HTTP 端点

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

curl -XGET "localhost:8086/health"

/health 端点响应

响应代码	健康状况	消息	状态
200	健康	`准备好进行查询和写入`	`通过`
503	不健康		`失败`

InfluxDB 1.x HTTP 端点

以下 InfluxDB 1.x API 端点可用

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

`/debug/pprof` HTTP 端点

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

定义

curl https://127.0.0.1:8086/debug/pprof/

/debug/pprof/ 端点生成一个 HTML 页面，其中包含内置 Go profile 列表以及每个 profile 的超链接。

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

要访问上面列出的 /debug/pprof/ profile 之一，请使用以下 cURL 请求，将 <profile> 替换为 profile 的名称。生成的 profile 将输出到 <path/to/output-file> 中指定的文件。

curl -o <path/to/output-file>  https://127.0.0.1:8086/debug/pprof/<profile>

在以下示例中，cURL 命令将生成的 heap profile 输出到文件

curl -o <path/to/output-file> https://127.0.0.1:/8086/debug/pprof/heap

您还可以使用 Go pprof 交互式工具来访问 InfluxDB /debug/pprof/ profile。例如，要使用此工具查看 InfluxDB 实例的 heap profile，您可以使用如下命令

go tool pprof https://127.0.0.1:8086/debug/pprof/heap

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

`/debug/pprof/all` HTTP 端点

/debug/pprof/all 端点是一个自定义的 /debug/pprof profile，主要供 InfluxData 支持部门使用。此端点生成一个 profile.tar.gz 归档文件，其中包含带有标准 Go profile 信息的文本文件以及其他调试数据。当使用 cpu= 选项后跟持续时间（以秒为单位）（例如，cpu=30s）时，将生成可选的 CPU profile。

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

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

如下例所示，cURL 输出包括 “Time Spent”，即经过的时间（以秒为单位）。收集 30 秒的数据后，结果将输出到文件。

➜  ~ curl -o profiles.tar.gz "https://127.0.0.1:8086/debug/pprof/all?cpu=30s"
  % 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

如果使用 InfluxDB 1.8.3 或更早版本，请使用 /debug/pprof/all?cpu=true。

`/debug/requests` HTTP 端点

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

定义

curl https://127.0.0.1:8086/debug/requests

查询字符串参数

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

示例

跟踪十秒间隔内的请求

$ curl https://127.0.0.1:8086/debug/requests

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

响应显示，在过去十秒内，user1 用户从 123.45.678.91 IP 地址向 /write 端点发送了一个请求，并且没有向 /query 端点发送任何请求。

跟踪一分钟间隔内的请求

$ curl https://127.0.0.1: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 https://127.0.0.1:8086/debug/vars

服务器统计信息和信息以 JSON 格式显示。有关 InfluxDB HTTP 服务器指标的信息，请参阅 httpd measurement。

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

`/ping` HTTP 端点

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

定义

GET https://127.0.0.1:8086/ping

HEAD https://127.0.0.1:8086/ping

`verbose` 选项

默认情况下，/ping HTTP 端点返回一个简单的 HTTP 204 状态响应，以告知客户端服务器正在运行。默认值为 false。当 verbose 选项设置为 true (/ping?verbose=true) 时，将返回 HTTP 200 状态。verbose=true 选项是 Google Cloud Load Balancing 健康检查所必需的。

示例

您可以使用 /ping 端点查找 InfluxDB 实例的 build 和版本。X-Influxdb-Build 标头字段显示 InfluxDB build 类型，OSS (开源) 或 ENT (企业版)。X-Influxdb-Version 标头字段显示 InfluxDB 版本。

~ curl -sl -I https://127.0.0.1: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: 1.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 https://127.0.0.1:8086/query

POST https://127.0.0.1:8086/query

动词用法

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

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

示例

使用 `SELECT` 语句查询数据

$ curl -G 'https://127.0.0.1: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 measurement 有两个数据点。第一个数据点的时间戳为 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 'https://127.0.0.1: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 measurement。请注意，系统使用 epoch 0 (1970-01-01T00:00:00Z) 作为空时间戳的等效值。

创建数据库

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

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

成功的 CREATE DATABASE 查询不返回任何其他信息。

查询字符串参数

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

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

** InfluxDB API 也支持基本身份验证。如果您已启用身份验证且未使用查询字符串参数 u 和 p，请使用基本身份验证。请参阅下文中的基本身份验证示例。

示例

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

$ curl -G 'https://127.0.0.1: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` 语句查询数据并返回秒精度 epoch 时间戳

$ curl -G 'https://127.0.0.1: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 身份验证创建数据库

有效凭据

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

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

成功的 CREATE DATABASE 查询不返回任何其他信息。

无效凭据

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

{"error":"authorization failed"}

使用基本身份验证创建数据库

以下示例使用有效凭据。

$ curl -XPOST -u myusername:mypassword 'https://127.0.0.1:8086/query' --data-urlencode 'q=CREATE DATABASE "mydb"'

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

成功的 CREATE DATABASE 查询不返回任何其他信息。

以下示例使用无效凭据。

$ curl -XPOST -u myusername:notmypassword 'https://127.0.0.1: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" https://127.0.0.1:8086/query

以 CSV 格式请求查询结果

语法

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

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

绑定参数

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

查询语法

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

Map 语法

--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 'https://127.0.0.1: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 'https://127.0.0.1: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

第一个数据点没有 mytag1 和 mytag2 标签键的标签值。

从文件提交查询

curl -F "[email protected]" -F "async=true" 'https://127.0.0.1:8086/query'

queries.txt 中的查询示例

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

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

$ curl -G 'https://127.0.0.1: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 将标签值存储为字符串，并且必须在请求中用双引号引起来。

在 `WHERE` 子句中将参数绑定到数值字段值

$ curl -G 'https://127.0.0.1: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 'https://127.0.0.1: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。

状态代码和响应

响应以 JSON 格式返回。包含查询字符串参数 pretty=true 以启用格式化 JSON。

汇总表

HTTP 状态代码	描述
200 OK	成功！返回的 JSON 提供更多信息。
400 Bad Request	不可接受的请求。当查询在语法上不正确时可能会发生。返回的 JSON 提供更多信息。
401 Unauthorized	不可接受的请求。当身份验证凭据无效时可能会发生。

示例

返回数据的成功请求

$ curl -i -G 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 https://127.0.0.1:8086/write

查询字符串参数

查询字符串参数	可选/必需	描述
consistency=[any,one,quorum,all]	可选，仅适用于 InfluxDB Enterprise 集群。	设置数据点的写入一致性。如果您未指定 `consistency`，则 InfluxDB 假定写入一致性为 `one`。有关每个一致性选项的详细描述，请参阅 InfluxDB Enterprise 文档。
db=<database>	必需	设置写入的目标数据库。
p=<password>	如果您尚未启用身份验证，则为可选。如果您已启用身份验证，则为必需。*	如果您已启用身份验证，则设置用于身份验证的密码。与查询字符串参数 `u` 一起使用。
precision=[n,u,ms,s,m,h]	可选	设置提供的 Unix 时间值的精度。如果您未指定精度，则 InfluxDB 假定时间戳以纳秒为单位。**
rp=<retention_policy_name>	可选	设置写入的目标保留策略。如果您未指定保留策略，则 InfluxDB 写入 DEFAULT 保留策略。
u=<username>	如果您尚未启用身份验证，则为可选。如果您已启用身份验证，则为必需。*	如果您已启用身份验证，则设置用于身份验证的用户名。用户必须具有数据库的写入权限。与查询字符串参数 `p` 一起使用。

* InfluxDB API 也支持基本身份验证。如果您已启用身份验证且未使用查询字符串参数 u 和 p，请使用基本身份验证。请参阅下文中的基本身份验证示例。

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

示例

以秒为时间戳，向数据库 `mydb` 写入一个数据点

$ curl -i -XPOST "https://127.0.0.1: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 "https://127.0.0.1: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 "https://127.0.0.1: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 "https://127.0.0.1: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 "https://127.0.0.1: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 "https://127.0.0.1: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 行协议格式。我们的示例展示了 curl 的 --data-binary 参数，我们将在本页的所有示例中使用它。使用除 --data-binary 以外的任何编码方法都可能导致问题；-d、--data-urlencode 和 --data-ascii 可能会删除换行符或引入新的、意外的格式。

选项

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

示例

以纳秒为时间戳，向数据库 `mydb` 写入一个数据点

$ curl -i -XPOST "https://127.0.0.1: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 "https://127.0.0.1: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 "https://127.0.0.1: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 "https://127.0.0.1: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

状态代码和响应

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

汇总表

HTTP 状态代码	描述
204 无内容	成功！
400 Bad Request	不可接受的请求。当 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"}

此页内容对您有帮助吗？

感谢您的反馈！

支持与反馈

感谢您成为我们社区的一份子！我们欢迎并鼓励您提供关于 InfluxDB 和本文档的反馈和错误报告。要获得支持，请使用以下资源

拥有年度或支持合同的客户 可以联系 InfluxData 支持。

编辑此页提交文档问题提交 InfluxDB 问题

InfluxDB API 参考文档

InfluxDB 3 兼容性

InfluxDB 2.x API 兼容性端点

/api/v2/query/ HTTP 端点

/api/v2/write/ HTTP 端点

/api/v2/buckets/ HTTP 端点

/api/v2/delete/ HTTP 端点

/health HTTP 端点

/health 端点响应

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 语句查询数据并返回秒精度 epoch 时间戳

使用 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 端点

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

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

`/health` 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` 语句查询数据并返回秒精度 epoch 时间戳

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

在 `WHERE` 子句中将参数绑定到数值字段值

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

`/write` HTTP 端点

以秒为时间戳，向数据库 `mydb` 写入一个数据点

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

使用 HTTP 身份验证，向数据库 `mydb` 写入一个数据点

使用基本身份验证，向数据库 `mydb` 写入一个数据点

以纳秒为时间戳，向数据库 `mydb` 写入一个数据点

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

通过用换行符分隔数据点，向数据库 `mydb` 写入多个数据点

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