Documentation

InfluxDB 集群

使用InfluxDB v1 API与InfluxDB集群

使用 InfluxDB v1 API /write 和 /query 端点以及您带入 InfluxDB 集群的 v1 工作负载。
v1 端点支持用户名/密码认证和现有的 InfluxDB 1.x 工具和代码。
InfluxDB v1 API /write 端点与 InfluxDB 1.x 客户端库和 Telegraf v1 输出插件 一起工作。
InfluxDB v1 API /query 端点支持 InfluxQL 和第三方集成，如 Grafana。

了解如何认证请求，调整现有 v1 工作负载的请求参数，并找到适用于编写和查询存储在 InfluxDB 集群数据库中的数据的兼容工具。

验证API请求

InfluxDB 集群要求每个 API 请求都必须通过数据库令牌进行身份验证。 使用 InfluxDB v1 API，您可以在 InfluxDB 1.x 用户名和密码方案中使用数据库令牌，在 InfluxDB v2 Authorization: Token 方案中，或在 OAuth Authorization: Bearer 方案中。

使用用户名和密码方案进行身份验证

通过InfluxDB v1 API，您可以使用InfluxDB 1.x约定的用户名和密码来验证数据库的读取和写入，通过将database token作为password凭证传递。 在对v1 API /write和/query端点进行请求认证时，InfluxDB Clustered检查password（p）值是否是一个授权的database token。InfluxDB Clustered忽略请求中的username（u）参数。

使用以下认证方案之一，适用于支持基本认证或查询参数的客户端（不支持 令牌认证）：

基本认证

使用Authorization头和Basic方案来验证v1 API的/write和/query请求。 当验证请求时，InfluxDB Clustered检查解码凭证的password部分是否是一个授权的database token。 InfluxDB Clustered忽略解码凭证的username部分。

语法
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>

使用 base64 编码对 [USERNAME]:DATABASE_TOKEN 凭据进行编码，然后将编码后的字符串附加到 Authorization: Basic 头。

大多数HTTP客户端提供基本认证选项，该选项接受<username>:<password>语法，并在发送请求之前对凭据进行编码。

示例

以下示例展示了如何使用 cURL 进行 Basic 认证方案和一个 数据库令牌：

curl --get "https://cluster-host.com/query" \
  --user "":"
DATABASE_TOKEN
" \
  --data-urlencode "db=
DATABASE_NAME
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

替换以下内容：

  • DATABASE_NAME: 你的 InfluxDB 集群 数据库
  • DATABASE_TOKEN: 一个数据库令牌，具有足够的权限访问指定的数据库

查询字符串认证

在URL中，传递p查询参数以验证/write和/query请求。 在验证请求时，InfluxDB集群检查p（密码）值是否为授权的数据库令牌，并忽略u（用户名）参数。

语法
https://cluster-host.com/query/?[u=any]&p=DATABASE_TOKEN
https://cluster-host.com/write/?[u=any]&p=DATABASE_TOKEN
示例

以下示例展示了如何使用cURL进行查询字符串身份验证和数据库令牌。

curl --get "https://cluster-host.com/query" \
  --data-urlencode "p=
DATABASE_TOKEN
" \
  --data-urlencode "db=
DATABASE_NAME
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

替换以下内容：

  • DATABASE_NAME: 你的 InfluxDB 集群 数据库
  • DATABASE_TOKEN: 一个数据库令牌，具有对指定数据库的足够权限

使用令牌方案进行身份验证

使用 Authorization: Bearer 或 Authorization: Token 方案传递一个 数据库令牌 来验证 v1 API /write 和 /query 请求。

Bearer 和 Token 在 InfluxDB Clustered 中是等价的。
Token 方案在 InfluxDB 2.x API 中使用。
Bearer 是由 OAuth 2.0 Framework 定义的。
对其中一种的支持可能因 InfluxDB API 客户端而异。

语法

Authorization: Bearer DATABASE_TOKEN

Authorization: Token DATABASE_TOKEN

示例

使用 Bearer 进行写请求的认证：

curl -i "https://cluster-host.com/write?db=
DATABASE_NAME
&precision=s" \
    --header "Authorization: Bearer 
DATABASE_TOKEN
" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

使用 Token 来验证写请求：

curl -i "https://cluster-host.com/write?db=
DATABASE_NAME
&precision=s" \
    --header "Authorization: Token 
DATABASE_TOKEN
" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

替换以下内容：

  • DATABASE_NAME: 你的 InfluxDB 集群 数据库
  • DATABASE_TOKEN: 一个数据库令牌，具有足够权限访问指定的数据库

响应

InfluxDB API 响应使用标准 HTTP 状态码。
对于成功的写入，InfluxDB 以 204 No Content 状态码响应。
错误响应包含一个 JSON 对象，其中包括 code 和 message 属性，用于描述错误。
响应主体消息可能在 InfluxDB Clustered v1 API、v2 API、InfluxDB Cloud 和 InfluxDB OSS 之间有所不同。

错误示例

  • 无效的命名空间名称:

    400 Bad Request

    { "code":"invalid",
  "message":"namespace name length must be between 1 and 64 characters"
}

    请求中缺少?db=参数值。提供数据库名称。

  • 反序列化 db/rp/precision 失败

    400 Bad Request

    { "code":"invalid",
  "message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}

    参数?precision=包含一个未知值。
    提供一个时间戳精度。

写入数据

使用您现有的工作负载向已经使用 InfluxDB v1 或 v1.x 兼容的 /write API 端点写入数据。

POST https://cluster-host.com/write

v1 API /写入参数

对于InfluxDB集群v1 API /write请求，请设置以下表格中列出的参数：

参数允许在被忽略值
consistency查询字符串忽略不适用
db *查询字符串尊敬的数据库名称
precision查询字符串已尊重时间戳精度
rp查询字符串受尊敬但不鼓励保留策略
u查询字符串忽略对于 查询字符串认证，任何任意字符串
p查询字符串已授权对于 查询字符串身份验证，一个 数据库令牌，具有写入数据库的权限
Content-Encoding头部被尊重gzip（压缩数据）或identity（未压缩）
Authorization头部已荣誉Bearer DATABASE_TOKEN, Token DATABASE_TOKEN, or Basic
* = Required

时间戳精度

在 v1 API /write 请求中使用以下 precision 值之一：

  • ns: 纳秒
  • us: 微秒
  • ms: 毫秒
  • s: 秒
  • m: 分钟
  • h: 小时

用于向 v1 API 进行写入的工具

以下工具可与 InfluxDB 集群 /write 端点一起使用：

Telegraf

如果您有使用Telegraf的现有v1工作负载，您可以使用InfluxDB v1.x influxdb Telegraf输出插件来写入数据。

查看如何 使用 Telegraf 和 v2 API 来处理不再使用 v1 API 的新工作负载。

下表显示了 outputs.influxdb 插件参数及其值，用于写入 InfluxDB Clustered v1 API：

参数被忽略值
database尊贵的数据库名称
retention_policy被尊重，但不被鼓励持续时间
username忽略字符串或空
password尊贵的数据库令牌 具有写入数据库的权限
content_encoding尊敬的gzip（压缩数据）或 identity（未压缩）
skip_database_creation被忽略不适用（见如何创建数据库）

要配置 v1.x 输出插件以写入 InfluxDB 集群，请在您的 telegraf.conf 文件中添加以下 outputs.influxdb 配置：

[[outputs.influxdb]]
  urls = ["https://cluster-host.com"]
  database = "
DATABASE_NAME
"
  skip_database_creation = true
  retention_policy = ""
  username = "ignored"
  password = "
DATABASE_TOKEN
"
  content_encoding = "gzip”

替换以下内容：

  • DATABASE_NAME: 你的 InfluxDB 集群 数据库
  • DATABASE_TOKEN: 一个数据库令牌，具有足够权限访问指定的数据库
其他 Telegraf 配置选项

influx_uint_support: 在 InfluxDB 3 中支持。

有关更多插件选项，请参见 influxdb 在 GitHub 上。

交互式客户端

要通过命令行交互式测试 InfluxDB v1 API 写入，可以使用常见的 HTTP 客户端，如 cURL 和 Postman。

在您的请求中包含以下内容：

以下示例显示了如何使用cURL命令行工具和InfluxDB Clustered v1 API将行协议数据写入数据库：

curl -i 'https://cluster-host.com/write?db=
DATABASE_NAME
&precision=s' \
    --header 'Authorization: Bearer 
DATABASE_TOKEN
' \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

替换以下内容：

  • DATABASE_NAME: 你的 InfluxDB 集群 数据库
  • DATABASE_TOKEN: 一个数据库令牌，具有足够权限访问指定的数据库
v1 命令行接口（不支持）

不要在 InfluxDB 集群中使用 v1 CLI。虽然它偶然可能会工作，但并不被官方支持。

客户端库

使用特定语言的 v1 客户端库 和您的自定义代码将数据写入 InfluxDB。 v1 客户端库以 行协议 语法将数据发送到 v1 API /write 端点。

以下示例展示了如何配置 v1 客户端库以写入 InfluxDB 集群：

Node.js Python

使用node-influx JavaScript客户端库创建一个v1 API客户端：

const Influx = require('influx')

// Instantiate a client for writing to InfluxDB Clustered v1 API
const client = new Influx.InfluxDB({
  host: 'cluster-host.com',
  port: 443,
  protocol: 'https'
  database: '
DATABASE_NAME
',
  username: 'ignored',
  password: '
DATABASE_TOKEN
'
})

使用influxdb-python Python客户端库创建v1 API客户端：

from influxdb import InfluxDBClient

# Instantiate a client for writing to InfluxDB Clustered v1 API
client = InfluxDBClient(
  host='cluster-host.com',
  ssl=True,
  database='
DATABASE_NAME
',
  username='',
  password='
DATABASE_TOKEN
'
  headers={'Content-Type': 'text/plain; charset=utf-8'}
  )

替换以下内容：

  • DATABASE_NAME: 你的 InfluxDB 集群 数据库
  • DATABASE_TOKEN: 一个数据库令牌，具有足够权限访问指定的数据库

查询数据

InfluxDB 集群提供以下协议来执行查询：

  • Flight+gRPC 请求，其中包含 SQL 或 InfluxQL 查询。要了解如何使用 Flight 和 SQL 查询 InfluxDB 集群，请参阅 入门 教程。
  • 包含 InfluxQL 查询的 InfluxDB v1 API /query 请求。当您引入已经使用 InfluxQL 和 v1 API /query 端点的 InfluxDB 1.x 工作负载时，请使用此端点与 InfluxDB 集群。

执行查询的工具

InfluxDB 集群支持多种不同的工具来查询数据，包括：

v1 API /查询参数

对于InfluxDB集群v1 API /query 请求，请按照下表中的参数设置：

参数允许在被忽略值
chunked查询字符串已尊重以流式批次而不是单个响应返回点。如果设置为 true，InfluxDB 将按系列或每 10,000 个点分块响应，以先发生者为准。
chunked_size查询字符串已遵守需要将 chunked 设置为 true。如果设置为特定值，InfluxDB 将按系列或按此点数进行分块响应。
db查询字符串受荣誉的数据库名称
epoch查询字符串荣誉时间戳精度
p查询字符串荣誉数据库令牌
pretty查询字符串被忽略不适用
u查询字符串忽略对于 查询字符串认证，任何任意字符串
p查询字符串已授权对于 查询字符串身份验证，一个 数据库令牌，具有写入数据库的权限
rp查询字符串受尊敬但不鼓励保留策略

将 v1 API 工作负载迁移到 InfluxDB 集群时，您需要在客户端配置或代码中调整请求参数。

时间戳精度

使用以下值之一来设置时间戳精度：

  • ns: 纳秒
  • us: 微秒
  • ms: 毫秒
  • s: 秒
  • m: 分钟
  • h: 小时

使用InfluxQL进行数据库管理（不支持）

InfluxDB 集群不允许使用 InfluxQL 命令来管理或修改数据库。 你无法使用以下 InfluxQL 命令：

SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL
write line protocol
© 2025 InfluxData, Inc.

您的 InfluxDB 集群 URL 是什么？

输入你的 InfluxDB 集群 URL，我们将为你更新代码示例。

输入集群 URL

感谢您的反馈!

让我们知道我们可以做得更好的地方：

谢谢！

No thanks

选择一个新日期

在您的存储桶的保留期内选择一个日期。

Update

Flux的未来

Flux 正在进入维护模式。您可以像现在一样继续使用它，而无需对您的代码进行任何更改。

阅读更多

InfluxDB 3 开源版本现已公开Alpha测试

InfluxDB 3 Open Source is now available for alpha testing, licensed under MIT or Apache 2 licensing.

我们将发布两个产品作为测试版的一部分。

InfluxDB 3 核心，是我们新的开源产品。 它是一个用于时间序列和事件数据的实时数据引擎。 InfluxDB 3 企业版是建立在核心基础之上的商业版本，增加了历史查询能力、读取副本、高可用性、可扩展性和细粒度安全性。

有关如何开始的更多信息，请查看：