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 v3兼容性。

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

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

InfluxDB v3兼容性

InfluxDB v3是InfluxDB的下一代，允许无限序列基数而不影响整体数据库性能，并带来了本机SQL支持和改进的InfluxQL性能。

InfluxDB v3支持v1 /write和/query HTTP API端点。InfluxDB v3对Flux未进行优化。

如果您刚开始使用InfluxDB v1，我们建议使用InfluxDB v1客户端库和InfluxQL。当您准备好时，您可以迁移到InfluxDB v3并继续使用v1客户端库，随着您的查询工作负载逐渐转向使用v3客户端库（以及v3飞行API）。

有关更多信息，请参阅InfluxDB v3的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	允许某些使用桶的客户端代码在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 都支持相同的行协议格式用于原始时间序列数据。在写入数据方面，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：行协议中时间戳的精度。接受 ns（纳秒）、us（微秒）、ms（毫秒）和 s（秒）。

包括以下 HTTP 头

Authorization：InfluxDB v2 使用 API 令牌来访问平台及其所有功能。InfluxDB v1.x 使用用户名和密码组合来访问 HTTP API。使用 Token 模式提供您的 InfluxDB 1.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"

`/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 v1.x 使用用户名和密码凭据对 API 请求进行身份验证。要提供 InfluxDB 1.x 凭据，使用 Token 方案，并包含用冒号（:）分隔的用户名和密码。
- Token 方案与 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 中删除点，包括具有特定标签值、时间戳和度量的点。

包括以下 URL 参数

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

包括以下 HTTP 头

Authorization：InfluxDB 2.x 使用此头与 Token 方案和 API 令牌对每个 API 请求进行身份验证。InfluxDB v1.x 使用用户名和密码凭据对 API 请求进行身份验证。要提供 InfluxDB 1.x 凭据，使用 Token 方案，并包含用冒号（:）分隔的用户名和密码。
- Token 方案与 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"
    }'

删除具有特定标签值的特定度量的点

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	生成用于故障排除的配置文件
/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可视化工具期望的格式提供运行时配置文件数据。

定义

curl https://127.0.0.1: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>  https://127.0.0.1:8086/debug/pprof/<profile>

在以下示例中，cURL命令将生成的堆配置文件输出到文件中

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

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

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配置文件，主要用于InfluxData支持。此端点生成一个包含标准Go配置信息和其他调试数据的文本文件的profile.tar.gz存档。使用带有后跟持续时间的cpu=选项（例如，cpu=30s）时，将生成可选的CPU配置文件。

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

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

使用此端点跟踪对/write和/query端点的HTTP客户端请求。/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从IP地址123.45.678.91向/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指标。

注意：InfluxDB输入插件可用于从指定的Kapacitor实例收集指标（使用/debug/vars端点）。有关指标和字段的列表，请参阅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状态。对于Google Cloud Load Balancing健康检查，需要verbose=true选项。

示例

您可以使用/ping端点找到InfluxDB实例的构建和版本。X-Influxdb-Build头字段显示InfluxDB的构建类型，可以是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.7
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 测量有两个点。第一个点的时间戳是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 度量。请注意，系统使用纪元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将根据系列或每10,000个点进行分块响应，以先发生者为准。如果设置为特定值，InfluxDB将根据系列或该数量的点进行分块响应.*
db=<database_name>	对于数据库相关的查询（大多数`SELECT`查询和`SHOW`查询都需要此参数）是必需的。	为查询设置目标数据库。
epoch=[ns,u,µ,ms,s,m,h]	可选	以指定精度返回纪元时间戳。默认情况下，InfluxDB以RFC3339格式返回具有纳秒精度的日期。`u`和`µ`都表示微秒。
p=<password>	如果没有启用身份验证，则为可选。如果启用了身份验证，则为必需。**	如果启用了身份验证，则设置身份验证密码。与查询字符串参数`u`一起使用。
pretty=true	可选	启用格式化的JSON输出。虽然这对于调试很有用，但不建议在生产中使用，因为它消耗不必要的网络带宽。
q=<query>	必需	要执行的InfluxQL字符串。另请参阅请求正文。
u=<username>	如果没有启用身份验证，则为可选。如果启用了身份验证，则为必需.*	如果启用了身份验证，则设置用于身份验证的用户名。用户必须具有数据库的读取权限。与查询字符串参数`p`一起使用。

* InfluxDB不会截断没有chunked参数的请求返回的行数。此行为是可配置的；有关更多信息，请参阅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`语句查询数据并返回秒精度纪元时间戳

$ 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支持将参数绑定到特定字段值或标签值。在查询中使用$<占位符键>作为占位符，并在请求体中将占位符键到占位符值的映射进行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 '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.7
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.7
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.7
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.7
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时间值的精度。如果不指定`precision`，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.7
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.7
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.7
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.7
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.7
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.7
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.7
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.7
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.7
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.7
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 v3兼容性

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

使用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`语句查询数据并返回秒精度纪元时间戳

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

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

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

`/write` HTTP端点

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

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

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

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

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

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

通过在新行中分隔点，将多个点写入数据库 `mydb`

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