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 v2 客户端库兼容）将数据写入 InfluxDB 1.8.0+
/api/v2/buckets	允许一些使用存储桶的客户端代码在 1.x 和 2.x 上运行而无需修改
/api/v2/delete	使用 InfluxDB v2 API （与 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 都支持原始时间序列数据的相同 Line Protocol 格式。对于写入数据，API 的不同之处仅在于 URL 参数和请求标头。InfluxDB v2 使用组织和存储桶，而不是数据库和保留策略。/api/v2/write 端点将提供的版本 1.x 数据库和保留策略映射到一个存储桶。

包含以下 URL 参数

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

包含以下 HTTP 标头

Authorization：InfluxDB v2 使用 API 令牌访问平台及其所有功能。InfluxDB 1.x 在访问 HTTP API 时使用用户名和密码组合。使用令牌方案提供您的 InfluxDB 1.x 用户名和密码，以冒号 (:) 分隔。Token 方案是单词 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 实例中创建、删除、列出、更新和检索存储桶。请注意，InfluxDB 2.x 使用组织和存储桶而不是数据库和保留策略。

包含以下 URL 参数

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

包含以下 HTTP 标头

Authorization：InfluxDB 2.x 将此标头与 Token 方案和 API 令牌一起使用，以验证每个 API 请求。InfluxDB 1.x 使用用户名和密码凭据来验证 API 请求。要提供 InfluxDB 1.x 凭据，请使用 Token 方案并包含您的用户名和密码，以冒号 (:) 分隔。
- 带有 v1.x 凭据的 Token 方案
```
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：Line Protocol 中时间戳的精度。接受 ns（纳秒）、us（微秒）、ms（毫秒）和 s（秒）。

包含以下 HTTP 标头

Authorization：InfluxDB 2.x 将此标头与 Token 方案和 API 令牌一起使用，以验证每个 API 请求。InfluxDB 1.x 使用用户名和密码凭据来验证 API 请求。要提供 InfluxDB 1.x 凭据，请使用 Token 方案并包含您的用户名和密码，以冒号 (:) 分隔。
- 带有 v1.x 凭据的 Token 方案
```
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 选项，请查看删除谓词语法并注意其限制。

`/health` HTTP 端点

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

curl -XGET "localhost:8086/health"

/health 端点响应

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

InfluxDB 1.x HTTP 端点

以下 InfluxDB 1.x API 端点可用

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

`/debug/pprof` HTTP 端点

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

定义

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

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

配置文件	描述
block	导致同步原语阻塞的堆栈跟踪。
goroutine	所有当前 goroutine 的堆栈跟踪。
heap	堆分配的堆栈跟踪采样。
mutex	争用互斥锁持有者的堆栈跟踪。
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 输出包括“Time Spent”（花费的时间），即经过的时间（以秒为单位）。收集 30 秒的数据后，结果将输出到文件。

➜  ~ curl -o profiles.tar.gz "http://localhost: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 端点

使用此端点跟踪到 /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 用户从 123.45.678.91 IP 地址向 /write 端点发送了一个请求，而没有向 /query 端点发送请求。

跟踪一分钟间隔内的请求

$ 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` 选项

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

示例

您可以使用 /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: 1.12.0
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`

* 唯一的例外是包含 INTO 子句的 SELECT 查询。这些 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 指标。请注意，系统使用 epoch 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` 查询需要此参数）必需。	设置查询的目标数据库。
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 '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` 语句查询数据并返回秒精度 epoch 时间戳

$ 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 身份验证创建数据库

有效凭据

$ 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"}

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

以下示例使用有效凭据。

$ 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 支持使用多部分 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

第一个点对于 mytag1 和 mytag2 标签键没有标签值。

从文件提交查询

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

在 `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。

状态代码和响应

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

摘要表

HTTP 状态代码	描述
200 OK	成功！返回的 JSON 提供更多信息。
400 Bad Request	不可接受的请求。可能发生在语法不正确的查询中。返回的 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.12.0
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.12.0
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.12.0
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.12.0
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=[n,u,ms,s,m,h]	可选	设置提供的 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.12.0
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.12.0
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.12.0
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.12.0
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.12.0
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.12.0
Date: Wed, 08 Nov 2017 17:46:40 GMT
Content-Length: 33

{"error":"authorization failed"}

请求正文

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

所有数据都必须采用二进制编码，并且格式为 InfluxDB Line Protocol 格式。我们的示例显示了 curl 中的 --data-binary 参数，我们将在本页的所有示例中使用该参数。使用 --data-binary 以外的任何编码方法都可能导致问题；-d、--data-urlencode 和 --data-ascii 可能会剥离换行符或引入新的、意外的格式。

选项

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

示例

将一个点写入数据库 `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.12.0
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.12.0
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.12.0
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.12.0
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 No Content	成功！
400 Bad Request	不可接受的请求。可能发生在 InfluxDB Line Protocol 语法错误或用户尝试将值写入先前接受不同值类型的字段时。返回的 JSON 提供更多信息。
401 Unauthorized	不可接受的请求。可能发生在无效的身份验证凭据中。
404 Not Found	不可接受的请求。如果用户尝试写入不存在的数据库，则可能发生这种情况。返回的 JSON 提供更多信息。
413 Request Entity Too Large	不可接受的请求。如果 POST 请求的有效负载大于允许的最大大小，则会发生这种情况。有关更多详细信息，请参阅 `max-body-size` 参数。
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"}

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

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`