InfluxDB API 参考手册

查看等价的 InfluxDB v2 文档： InfluxDB HTTP API.

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

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

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

InfluxDB 2.x API兼容端点

InfluxDB 1.8.0引入了与InfluxDB 2.x的前向兼容API。引入这些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客户端库查询数据。Flux是处理InfluxDB 2.x中数据的主要语言。

包括以下HTTP头

Accept: application/csv
Content-type: application/vnd.flux
如果启用了身份验证，请提供您的InfluxDB用户名和密码
授权：令牌 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客户端库将数据写入InfluxDB 1.8.0+数据库。

InfluxDB 1.x和2.x API支持相同的原始时间序列数据行协议格式。对于写入数据的目的，API之间的区别仅在于URL参数和请求头。InfluxDB 2.x使用组织和桶而不是数据库和保留策略。/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令牌一起对每个API请求进行身份验证。InfluxDB v1.x使用用户名和密码凭据对API请求进行身份验证。要提供InfluxDB 1.x凭据，使用Token方案，并用冒号（：）分隔您的用户名和密码。
- 使用v1.x凭据的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"

`/health` HTTP端点

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

curl -XGET "localhost:8086/health"

/health端点响应

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

`/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方案，并用冒号（：）分隔您的用户名和密码。
- 使用v1.x凭据的Token方案
```
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端点 /api/v2/delete 接受 POST HTTP请求。使用此端点从InfluxDB中删除数据点，包括具有特定标签值、时间戳和测量的数据点。

包括以下URL参数

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

包括以下HTTP头

Authorization：InfluxDB 2.x使用此头与Token方案和API令牌一起对每个API请求进行身份验证。InfluxDB v1.x使用用户名和密码凭据对API请求进行身份验证。要提供InfluxDB 1.x凭据，使用Token方案，并用冒号（：）分隔您的用户名和密码。
- 使用v1.x凭据的Token方案
```
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选项，请查看删除谓词语法并注意其限制。

InfluxDB 1.x HTTP端点

以下为InfluxDB 1.x API端点：

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

`/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”，表示经过的时间（秒）。

  % 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 https://127.0.0.1:8086/debug/requests

查询字符串参数

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

示例

在十秒间隔内跟踪请求

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

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

响应显示，在过去十秒内，user1 用户向 /write 端点发送了一条请求，但没有从 123.45.678.91 IP 地址向 /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` 选项

默认值是 false。默认情况下，/ping HTTP 端点以 HTTP 状态 204 和空响应体响应，以便让客户端知道服务器正在运行。如果设置为 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: v1.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身份验证创建数据库

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

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

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

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

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。

状态码和响应

API响应体包含以JSON格式表示的结果或错误消息。为了以美观的格式打印JSON以供查看，请包括查询字符串参数pretty=true或将响应传递给JSON处理器，如jq。

摘要表

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

查询字符串参数

查询字符串参数	可选/必选	描述
一致性=[任何,一个,多数,全部]	可选，仅适用于InfluxDB Enterprise集群。	设置点的写入一致性。如果您未指定`consistency`，InfluxDB假定写入一致性为`one`。有关每个一致性选项的详细描述，请参阅InfluxDB Enterprise文档。
db=<database>	必需	设置写入的目标数据库。
p=<password>	如果没有启用身份验证，则可选。如果启用了身份验证，则为必需.*	如果启用了身份验证，则设置身份验证密码。与查询字符串参数`u`一起使用。
precision=[ns,u,ms,s,m,h]	可选	设置提供的Unix时间值的精度。如果您未指定`precision`，InfluxDB假定时间戳以纳秒为单位。**
rp=<retention_policy_name>	可选	设置写入的目标保留策略。如果您未指定保留策略，InfluxDB将写入`DEFAULT`保留策略。
u=<username>	如果没有启用身份验证，则可选。如果启用了身份验证，则为必需.*	设置认证的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

状态码和响应

一般来说，HTTP 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"}

`/shard-status` HTTP端点

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

响应

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

id：分片ID
size：分片在磁盘上的大小，以字节为单位
is_hot：分片的时间范围是否包含 now
一个空闲的分片是完全压缩的，并且没有接收新的（可能是历史性的）写入。一个热分片可能空闲，也可能不空闲。
state：分片的反熵状态可以是以下之一：healthy、restore pending、restoring、repairing、error processing

示例

curl -q 'https://127.0.0.1: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和此文档的反馈和错误报告。要找到支持，请使用以下资源

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

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

InfluxDB API 参考手册

InfluxDB 2.x API兼容端点

/api/v2/query/ HTTP端点

/api/v2/write/ HTTP端点

/health HTTP端点

/health端点响应

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