使用InfluxDB v2 API与InfluxDB集群

使用InfluxDB v2 API /api/v2/write端点进行新的写入工作负载以及将现有v2写入工作负载带到InfluxDB集群。了解如何对请求进行身份验证，调整现有v2工作负载的请求参数，以及找到兼容的工具，用于写入和查询存储在InfluxDB集群数据库中的数据。

如需找到最适合您情况的最佳工作流程，请联系支持。

• 验证API请求
  • 使用令牌进行验证
    • 语法
    • 示例
• 响应
  • 错误示例
• 写入数据
  • /api/v2/write参数
    • 时间戳精度
  • 写入v2 API的工具
    • Telegraf
    • 交互式客户端
    • influx CLI不受支持
    • 客户端库
• 查询数据
  • 执行查询的工具
  • /api/v2/query不受支持

验证API请求

InfluxDB API端点要求每个请求都使用数据库令牌进行身份验证。

使用令牌进行验证

使用Authorization: Bearer方案或Authorization: Token方案传递具有执行操作所需权限的数据库令牌。

Bearer和Token在InfluxDB集群中是等价的。在InfluxDB 2.x API中使用Token方案。Bearer由OAuth 2.0框架定义。不同InfluxDB API客户端可能支持其中之一或另一个。

语法

Authorization: Bearer DATABASE_TOKEN

Authorization: Token DATABASE_TOKEN

示例

使用Bearer对写入请求进行身份验证

curl --request post 'https://cluster-host.com/api/v2/write?bucket=
DATABASE_NAME
&precision=s' \
  --header 'Authorization: Bearer 
DATABASE_TOKEN
' \
  --data-binary 'home,room=kitchen temp=72 1641024000'

curl --request post "https://cluster-host.com/api/v2/write?bucket=
DATABASE_NAME
&precision=s" \
  --header "Authorization: Token 
DATABASE_TOKEN
" \
  --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":"missing bucket value"
  }
  

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

• 反序列化org/bucket/precision失败

  400 Bad Request
  

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

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

写入数据

我们建议使用 InfluxDB v2 API 的 /api/v2/write 端点进行新的写入负载以及现有的 v2 负载。

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

• /api/v2/write 参数
• 写入v2 API的工具

/api/v2/write参数

对于 InfluxDB 集群版 v2 API 的 /api/v2/write 请求，设置参数如下表所示

时间戳精度

在 v2 API 的 /api/v2/write 请求中使用以下任一 精度 值

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

写入v2 API的工具

以下工具与 InfluxDB 集群 /api/v2/write 端点配合使用

• Telegraf
• 交互式客户端
• 客户端库

Telegraf

了解如何配置 Telegraf 以写入 InfluxDB 集群。

交互式客户端

要交互式测试 InfluxDB v2 API 写入，请使用 influx3 数据 CLI 或 cURL 和 Postman 等常见的 HTTP 客户端。

要设置和使用交互式客户端，请参阅 入门 教程。

客户端库

InfluxDB v3 客户端库 和 v2 客户端库 可将数据写入 InfluxDB v2 API 的 /api/v2/write 端点。客户端库是特定于语言的包，它将 InfluxDB API 与您的应用程序集成。

要设置和使用客户端库，请参阅 入门 教程。

查询数据

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

• Flight+gRPC 请求，其中包含 SQL 或 InfluxQL 查询。要了解如何使用 Flight 和 SQL 查询 InfluxDB 集群，请参阅 入门 教程。
• 包含 InfluxQL 查询的 InfluxDB v1 API /query 请求。