使用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请求
- 使用用户名和密码方案进行认证
  - 基本认证
    - 语法
    - 示例
  - 查询字符串认证
    - 语法
    - 示例
- 使用令牌方案进行认证
  - 语法
  - 示例
响应
- 错误示例
写入数据
查询数据

认证API请求

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

使用用户名和密码方案进行认证
使用令牌方案进行认证

使用用户名和密码方案进行认证

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

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

基本认证
查询字符串认证

基本认证

使用 Authorization 标头和 Basic 方案来认证 v1 API 的 /write 和 /query 请求。在验证请求时，InfluxDB 集群检查解码凭证中的 password 部分是否是授权的数据库令牌。InfluxDB 集群忽略解码凭证中的 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 集群中是等效的。在 InfluxDB 2.x API 中使用 Token 方案。在 OAuth 2.0 框架中定义了 Bearer。对其中一个或另一个的支持可能因 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 状态码进行响应。错误响应包含一个包含 code 和 message 属性的 JSON 对象，这些属性描述了错误。响应体中的消息可能因 InfluxDB 集群 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 集群 v1 API 的 /write 请求，参数设置如下表所示

参数	允许在	忽略	值
`一致性`	查询字符串	忽略	不适用
`db` *	查询字符串	受尊重	数据库名称
`精度`	查询字符串	受尊重	时间戳精度
`rp`	查询字符串	受尊重，但不建议使用	保留策略
`u`	查询字符串	忽略	对于查询字符串身份验证，任意字符串
`p`	查询字符串	受尊重	对于查询字符串身份验证，一个数据库令牌，具有写入数据库的权限
`内容编码`	头信息	受尊重	`gzip`（压缩数据）或 `identity`（未压缩）
`授权`	头信息	受尊重	`Bearer DATABASE_TOKEN`、`Token DATABASE_TOKEN` 或 `Basic <base64 [USERNAME]:DATABASE_TOKEN>`

* = 必需

时间戳精度

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

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

写入v1 API的工具

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

Telegraf
交互式客户端
客户端库

Telegraf

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

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

以下表格显示了写入 InfluxDB 集群 v1 API 的 outputs.influxdb 插件参数和值

参数	忽略	值
`数据库`	受尊重	数据库名称
`保留策略`	受尊重，但不建议使用	持续时间
`用户名`	忽略	字符串或空字符串
`密码`	受尊重	数据库令牌，具有写入数据库的权限
`内容编码`	受尊重	`gzip`（压缩数据）或 `identity`（未压缩）
`跳过数据库创建`	忽略	不适用（请参阅如何创建数据库）

要配置 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 v3 中受支持。

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

交互式客户端

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

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

一个 db 查询字符串参数，用于指定要写入的数据库名称。
一个请求正文，包含以行协议语法表示的数据字符串。
在以下认证方案之一中包含数据库令牌：基本认证、查询字符串认证或令牌认证。
可选的参数。

以下示例显示了如何使用 cURL 命令行工具和 InfluxDB 集群 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 CLI（不支持）

不要使用 v1 CLI 与 InfluxDB 集群一起使用。虽然它可能偶然有效，但并未官方支持。

客户端库

使用特定于语言的 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 集群版，请参阅入门教程。
InfluxDB v1 API /query 请求，包含 InfluxQL 查询。当您将已使用 InfluxQL 和 v1 API /query 端点的 InfluxDB 1.x 工作负载引入 InfluxDB 集群版时，请使用此端点。

执行查询的工具

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

v1 API /query参数

对于 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

写入行协议

本页有帮助吗？

感谢您的反馈！

支持和反馈

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

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

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

使用InfluxDB v1 API与InfluxDB集群

认证API请求

使用用户名和密码方案进行认证

基本认证

语法

示例

查询字符串认证

语法

示例

使用令牌方案进行认证

语法

示例

响应

错误示例

写入数据

v1 API /write参数

时间戳精度

写入v1 API的工具

Telegraf

其他Telegraf配置选项

交互式客户端

v1 CLI（不支持）

客户端库

查询数据

执行查询的工具

v1 API /query参数

时间戳精度

InfluxQL 数据库管理（不支持）

支持和反馈

Flux 的未来

InfluxDB v3 增强版和 InfluxDB 集群版现已正式发布

InfluxDB v3 性能和功能

InfluxDB集群版现已正式发布

使用InfluxDB v1 API与InfluxDB集群

认证API请求

使用用户名和密码方案进行认证

基本认证

语法

示例

查询字符串认证

语法

示例

使用令牌方案进行认证

语法

示例

响应

错误示例

写入数据

v1 API /write参数

时间戳精度

写入v1 API的工具

Telegraf

其他Telegraf配置选项

交互式客户端

v1 CLI（不支持）

客户端库

查询数据

执行查询的工具

v1 API /query参数

时间戳精度

InfluxQL 数据库管理（不支持）

相关

支持和反馈

您的 InfluxDB 集群 URL 是什么？

输入集群 URL

感谢您的反馈！

选择新的日期

Flux 的未来

InfluxDB v3 增强版和 InfluxDB 集群版现已正式发布

InfluxDB v3 性能和功能

InfluxDB集群版现已正式发布