InfluxDB 3 Clustered 的 InfluxDB v2 HTTP API 为写入存储在 InfluxDB 3 Clustered 数据库中的数据提供了 v2 兼容的编程接口。
InfluxDB v2 HTTP API 允许您使用 /api/v2 端点来管理保留策略映射和写入存储在 InfluxDB 3 实例中的数据。
本文档从 InfluxDB OpenAPI 规范生成。
请参阅入门指南教程，了解如何启动并运行身份验证令牌、写入数据库和查询数据。
InfluxDB API 客户端库和 Flight 客户端可用于将 InfluxDB API 与您的应用程序集成。
使用以下方案之一对 InfluxDB API 进行身份验证
使用带有 Basic 方案的 Authorization 标头来验证 v1 API /write 和 /query 请求。在验证请求时，InfluxDB 3 Clustered 检查解码凭据的 password 部分是否为授权的数据库令牌。InfluxDB 3 Clustered 忽略解码凭据的 username 部分。
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>替换以下内容
[USERNAME]：一个可选的字符串值（InfluxDB 3 Clustered 忽略）。DATABASE_TOKEN：一个数据库令牌。[USERNAME]:DATABASE_TOKEN 凭据进行编码，然后将编码后的字符串附加到 Authorization: Basic 标头。以下示例展示了如何将 cURL 与 Basic 身份验证方案和数据库令牌一起使用
#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 HTTP API
#######################################
# Use the --user option with `--user username:DATABASE_TOKEN` syntax
#######################################
curl --get "http://cluster-id.a.influxdb.io/query" \
--user "":"DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"替换以下内容
DATABASE_NAME：您的 InfluxDB 3 Clustered 数据库DATABASE_TOKEN：具有足够数据库权限的数据库令牌| 安全方案类型 | HTTP |
|---|---|
| HTTP 授权方案 | basic |
将查询字符串身份验证方案与 InfluxDB 1.x API 参数一起使用，以通过查询字符串提供凭据。
在 URL 中，传递 p 查询参数以验证 /write 和 /query 请求。在验证请求时，InfluxDB 3 Clustered 检查 p（password）是否为授权的数据库令牌，并忽略 u（username）参数。
https://cluster-id.a.influxdb.io/query/?[u=any]&p=DATABASE_TOKEN
https://cluster-id.a.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN以下示例展示了如何将 cURL 与查询字符串身份验证和数据库令牌一起使用。
#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 HTTP API
#######################################
# Use authentication query parameters:
# ?p=DATABASE_TOKEN
#######################################
curl --get "https://cluster-id.a.influxdb.io/query" \
--data-urlencode "p=DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"替换以下内容
DATABASE_NAME：您的 InfluxDB 3 Clustered 数据库DATABASE_TOKEN：具有足够数据库权限的数据库令牌| 安全方案类型 | API 密钥 |
|---|---|
| 查询参数名称 | u=&p= |
使用 OAuth Bearer 身份验证方案对 InfluxDB API 进行身份验证。
在您的 API 请求中，发送 Authorization 标头。对于标头值，提供单词 Bearer，后跟一个空格和一个数据库令牌。
Authorization: Bearer INFLUX_TOKEN########################################################
# Use the Bearer token authentication scheme with /api/v2/write
# to write data.
########################################################
curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'有关示例和更多信息，请参阅以下内容
| 安全方案类型 | HTTP |
|---|---|
| HTTP 授权方案 | bearer |
| Bearer 格式 | "JWT" |
使用 Token 身份验证方案对 InfluxDB API 进行身份验证。
在您的 API 请求中，发送 Authorization 标头。对于标头值，提供单词 Token，后跟一个空格和一个数据库令牌。单词 Token 区分大小写。
Authorization: Token INFLUX_API_TOKEN########################################################
# Use the Token authentication scheme with /api/v2/write
# to write data.
########################################################
curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Token DATABASE_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'| 安全方案类型 | API 密钥 |
|---|---|
| 标头参数名称 | Authorization |
InfluxDB HTTP API 端点使用标准 HTTP 请求和响应标头。下表显示了许多 InfluxDB API 端点使用的常用标头。某些端点可能使用执行更特定于这些端点功能的其他标头——例如，POST /api/v2/write 端点接受 Content-Encoding 标头以指示应用于请求正文中行协议的压缩。
| 标头 | 值类型 | 描述 |
|---|---|---|
Accept | string | 客户端可以理解的内容类型。 |
Authorization | string | 授权方案和凭据。 |
Content-Length | integer | 发送到数据库的实体主体的大小（以字节为单位）。 |
Content-Type | string | 请求正文中的数据格式。 |
InfluxDB HTTP API 端点使用标准 HTTP 状态代码来表示成功和失败响应。响应正文可能包含其他详细信息。有关特定操作响应的详细信息，请参阅该操作的响应和响应示例。
API 操作可能会返回以下 HTTP 状态代码
| 代码 | 状态 | 描述 |
|---|---|---|
200 | 成功 | |
204 | 成功。无内容 | InfluxDB 不返回请求的数据。例如，成功的写入请求返回 204 状态代码，确认数据已写入且可查询。 |
400 | 错误请求 | InfluxDB 无法解析请求，原因是参数不正确或语法错误。如果请求正文中的行协议格式错误。响应正文包含第一个格式错误的行，并指示预期内容。对于部分写入，还包括写入的点数和拒绝的点数。 |
401 | 未授权 | 可能表示以下情况之一
|
404 | 未找到 | 未找到请求的资源。响应正文中的 message 提供有关请求资源的详细信息。 |
405 | 方法不允许 | API 路径不支持请求中使用的 HTTP 方法——例如，您向仅允许 GET 的端点发送 POST 请求。 |
413 | 请求实体过大 | 请求负载超过大小限制。 |
422 | 不可处理的实体 | 请求数据无效。响应正文中的 code 和 message 提供有关问题的详细信息。 |
429 | 请求过多 | API 令牌暂时超过请求配额。Retry-After 标头描述了何时再次尝试请求。 |
500 | 内部服务器错误 | |
503 | 服务不可用 | 服务器暂时无法处理请求。Retry-After 标头描述了何时再次尝试请求。 |
查询存储在数据库中的数据。
/query 端点，并以 CSV 或 JSON 格式检索数据。/api/v2/query 端点无法查询 InfluxDB 3 Clustered。使用 InfluxQL 和 InfluxDB v1 请求和响应格式查询 InfluxDB。
| db 必需 | string 要从中查询数据的数据库。 |
| epoch | string 枚举: "ns" "u" "µ" "ms" "s" "m" "h" Unix 时间戳精度。将时间戳格式化为指定精度的unix（epoch）时间戳，而不是具有纳秒精度的RFC3339 时间戳。 |
| p | string 用于验证请求的 InfluxDB 1.x 密码。 |
| q 必需 | string 要执行的 InfluxQL 查询。要执行多个查询，请用分号 ( |
| rp | string 要从中查询数据的保留策略。有关更多信息，请参阅InfluxQL DBRP 命名约定。 |
| u | string 用于验证请求的 InfluxDB 1.x 用户名。 |
| Accept | string 默认: application/json 枚举: "application/json" "application/csv" "text/csv" "application/x-msgpack" 客户端可以理解的媒体类型。 注意：使用 |
| Accept-Encoding | string 默认: identity 枚举: "gzip" "identity" 客户端可以理解的内容编码（通常是压缩算法）。 |
| Content-Type | string 值: "application/json" |
| Zap-Trace-Span | string 示例: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span 上下文 |
使用 InfluxDB v1 或 v2 端点将时间序列数据写入数据库。
| bucket 必需 | string 数据库名称或 ID。InfluxDB 将批处理中的所有点写入指定的数据库。 |
| org 必需 | string 已忽略。组织名称或 ID。 InfluxDB 忽略此参数；使用指定的数据库令牌授权请求，并将数据写入指定的集群数据库。 |
| orgID | string 已忽略。组织 ID。 InfluxDB 忽略此参数；使用指定的数据库令牌授权请求，并将数据写入指定的集群数据库。 |
| precision | string (WritePrecision) 枚举: "ms" "s" "us" "ns" 行协议批处理中 unix 时间戳的精度。 |
| Accept | string 默认: application/json 值: "application/json" 客户端可以理解的内容类型。写入仅在失败时才返回响应正文——例如，由于格式问题或配额限制。
相关指南 |
| Content-Encoding | string 默认: identity 枚举: "gzip" "identity" 应用于请求负载中行协议的压缩。要发送 gzip 负载，请传递 |
| Content-Length | integer 发送到 InfluxDB 的实体主体的大小（以字节为单位）。如果长度大于 |
| Content-Type | string 默认: text/plain; charset=utf-8 枚举: "text/plain" "text/plain; charset=utf-8" 请求正文中的数据格式。要发送行协议负载，请传递 |
| Zap-Trace-Span | string 示例: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span 上下文 |
airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000
{- "code": "invalid",
- "message": "failed to parse line protocol: error writing line 2: Unable to insert iox::column_type::field::integer type into column temp with type iox::column_type::field::string"
}| db 必需 | string 要写入的数据库。如果不存在，InfluxDB 将创建一个具有默认 3 天保留策略的数据库。 |
| p | string 用于验证请求的 InfluxDB 1.x 密码。 |
| precision | string 写入精度。 |
| rp | string 保留策略名称。 |
| u | string 用于验证请求的 InfluxDB 1.x 用户名。 |
| Content-Encoding | string 默认: identity 枚举: "gzip" "identity" 存在时，其值向数据库指示压缩已应用于行协议主体。 |
| Zap-Trace-Span | string 示例: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span 上下文 |
行协议主体
{- "code": "invalid",
- "line": 2,
- "message": "no data written, errors encountered on line(s): error message for first rejected point</n> error message for second rejected point</n> error message for Nth rejected point (up to 100 rejected points)"
}