将 InfluxDB v1 API 与 InfluxDB Clustered 结合使用

将 InfluxDB v1 API /write 和 /query 端点与您带到 InfluxDB Clustered 的 v1 工作负载结合使用。v1 端点适用于用户名/密码身份验证以及现有的 InfluxDB 1.x 工具和代码。InfluxDB v1 API /write 端点适用于 InfluxDB 1.x 客户端库和 Telegraf v1 输出插件。InfluxDB v1 API /query 端点支持 InfluxQL 和第三方集成，如 Grafana。

了解如何验证 API 请求、调整现有 v1 工作负载的请求参数，以及查找用于写入和查询存储在 InfluxDB Clustered 数据库中的数据的兼容工具。

验证 API 请求
- 使用用户名和密码方案进行身份验证
  - 基本身份验证
    - 语法
    - 示例
  - 查询字符串身份验证
    - 语法
    - 示例
- 使用令牌方案进行身份验证
  - 语法
  - 示例
响应
- 错误示例
写入数据
查询数据

验证 API 请求

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

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

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

使用 InfluxDB v1 API，您可以使用 InfluxDB 1.x 的用户名和密码约定，通过将数据库令牌作为 password 凭据传递来验证数据库的读取和写入操作。当验证对 v1 API /write 和 /query 端点的请求时，InfluxDB Clustered 会检查 password (p) 值是否为授权的数据库令牌。InfluxDB Clustered 忽略请求中的 username (u) 参数。

将以下身份验证方案之一与支持基本身份验证或查询参数（不支持令牌身份验证）的客户端一起使用

基本身份验证
查询字符串身份验证

基本身份验证

将带有 Basic 方案的 Authorization 标头用于验证 v1 API /write 和 /query 请求。当验证请求时，InfluxDB Clustered 会检查解码凭据的 password 部分是否为授权的数据库令牌。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 Clustered 数据库
DATABASE_TOKEN：具有对指定数据库的足够权限的数据库令牌

查询字符串身份验证

在 URL 中，传递 p 查询参数以验证 /write 和 /query 请求。当验证请求时，InfluxDB Clustered 会检查 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 Clustered 数据库
DATABASE_TOKEN：具有对指定数据库的足够权限的数据库令牌

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

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

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

包括单词 Bearer 或 Token、一个空格和您的令牌值（所有字符区分大小写）。

语法

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 Clustered 数据库
DATABASE_TOKEN：具有对指定数据库的足够权限的数据库令牌

响应

InfluxDB API 响应使用标准的 HTTP 状态代码。对于成功的写入，InfluxDB 响应 204 No Content 状态代码。错误响应包含一个带有 code 和 message 属性的 JSON 对象，用于描述错误。响应正文消息可能在 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

/api/v2/write 参数
用于写入 v1 API 的工具

v1 API /write 参数

对于 InfluxDB Clustered v1 API /write 请求，请按照下表列出的参数进行设置

参数	允许在	已忽略	值
`consistency`	查询字符串	已忽略	不适用
`db` *	查询字符串	已接受	数据库名称
`precision`	查询字符串	已接受	时间戳精度
`rp`	查询字符串	已接受，但不建议使用	保留策略
`u`	查询字符串	已忽略	对于查询字符串身份验证，任何任意字符串
`p`	查询字符串	已接受	对于查询字符串身份验证，具有写入数据库权限的数据库令牌
`Content-Encoding`	标头	已接受	`gzip`（压缩数据）或 `identity`（未压缩）
`Authorization`	标头	已接受	`Bearer DATABASE_TOKEN`、`Token DATABASE_TOKEN` 或 `Basic <base64 [USERNAME]:DATABASE_TOKEN>`

* = 必需

时间戳精度

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

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

用于写入 v1 API 的工具

以下工具可与 InfluxDB Clustered /write 端点一起使用

Telegraf
交互式客户端
客户端库

Telegraf

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

了解如何使用 Telegraf 和 v2 API 处理尚未使用 v1 API 的新工作负载。

下表显示了用于写入 InfluxDB Clustered v1 API 的 outputs.influxdb 插件参数和值

参数	已忽略	值
`database`	已接受	数据库名称
`retention_policy`	已接受，但不建议使用	Duration
`username`	已忽略	字符串或空
`password`	已接受	具有写入数据库权限的数据库令牌
`content_encoding`	已接受	`gzip`（压缩数据）或 `identity`（未压缩）
`skip_database_creation`	已忽略	不适用（请参阅如何创建数据库）

要配置 v1.x 输出插件以写入 InfluxDB Clustered，请在您的 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 Clustered 数据库
DATABASE_TOKEN：具有对指定数据库的足够权限的数据库令牌

其他 Telegraf 配置选项

influx_uint_support：InfluxDB 3 中支持。

有关更多插件选项，请参阅 GitHub 上的 influxdb。

交互式客户端

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

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

带有要写入的数据库名称的 db 查询字符串参数。
请求正文，其中包含 Line Protocol 语法的数据字符串。
以下身份验证方案之一中的数据库令牌：基本身份验证、查询字符串身份验证或令牌身份验证。
可选的参数。

以下示例演示如何使用 cURL 命令行工具和 InfluxDB Clustered v1 API 将 Line Protocol 数据写入数据库

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 Clustered 数据库
DATABASE_TOKEN：具有对指定数据库的足够权限的数据库令牌

v1 CLI（不支持）

请勿将 v1 CLI 与 InfluxDB Clustered 一起使用。虽然它可能偶尔可以工作，但官方不支持它。

客户端库

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

以下示例演示如何配置 v1 客户端库以写入 InfluxDB Clustered

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 Clustered 数据库
DATABASE_TOKEN：具有对指定数据库的足够权限的数据库令牌

查询数据

InfluxDB Clustered 提供了以下协议来执行查询

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

用于执行查询的工具

InfluxDB Clustered 支持许多不同的工具来查询数据，包括

v1 API /query 参数

对于 InfluxDB Clustered v1 API /query 请求，请按照下表列出的参数进行设置

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

当将 v1 API 工作负载引入 InfluxDB Clustered 时，您需要在客户端配置或代码中调整请求参数。

时间戳精度

将以下值之一用于时间戳精度

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

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

InfluxDB Clustered 不允许使用 InfluxQL 命令来管理或修改数据库。您不能使用以下 InfluxQL 命令

SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL

write line protocol

此页面是否对您有帮助？

感谢您的反馈！

支持和反馈

感谢您成为我们社区的一份子！我们欢迎并鼓励您提供关于 InfluxDB Clustered 和此文档的反馈和错误报告。要查找支持，请使用以下资源

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

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

将 InfluxDB v1 API 与 InfluxDB Clustered 结合使用

验证 API 请求

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

基本身份验证

语法

示例

查询字符串身份验证

语法

示例

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

语法

示例

响应

错误示例

写入数据

v1 API /write 参数

时间戳精度

用于写入 v1 API 的工具

Telegraf

其他 Telegraf 配置选项

交互式客户端

v1 CLI（不支持）

客户端库

查询数据

用于执行查询的工具

v1 API /query 参数

时间戳精度

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

支持和反馈

Flux 的未来

InfluxDB 3 开源版本现已公开发布 Alpha 版

将 InfluxDB v1 API 与 InfluxDB Clustered 结合使用

验证 API 请求

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

基本身份验证

语法

示例

查询字符串身份验证

语法

示例

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

语法

示例

响应

错误示例

写入数据

v1 API /write 参数

时间戳精度

用于写入 v1 API 的工具

Telegraf

其他 Telegraf 配置选项

交互式客户端

v1 CLI（不支持）

客户端库

查询数据

用于执行查询的工具

v1 API /query 参数

时间戳精度

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

相关内容

支持和反馈

您的 InfluxDB 集群 URL 是什么？

输入集群 URL

感谢您的反馈！

选择新日期

Flux 的未来

InfluxDB 3 开源版本现已公开发布 Alpha 版