使用兼容 API 和客户端库写入数据

当您需要将现有的 InfluxDB v1 或 v2 写入工作负载迁移到 InfluxDB 3.x 时，请使用兼容性 API。/api/v2/write (v2 兼容) 和 /write (v1 兼容) HTTP API 端点与 InfluxDB 客户端库、Telegraf 和第三方集成配合使用，以行协议数据形式将点写入 InfluxDB 3 Core。

InfluxDB v2 兼容性

/api/v2/write InfluxDB v2 兼容性端点提供与能够写入 InfluxDB OSS v2.x 和 Cloud 2 (TSM) 数据的客户端的向后兼容性。

POST /api/v2/write?bucket=mydb&precision=ns

验证 v2 API 请求

InfluxDB 3 Core 要求每个 API 请求都使用令牌进行身份验证。

使用 Authorization: Bearer 或 Authorization: Token 方案来验证 v2 API 写入请求

语法

Authorization: Bearer DATABASE_TOKEN

Authorization: Token DATABASE_TOKEN

示例

使用 Bearer 验证 v2 写入请求

curl -i "https://:8181/api/v2/write?bucket=
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 验证 v2 写入请求

curl -i "https://:8181/api/v2/write?bucket=
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'

v2 API 写入参数

对于 InfluxDB 3 Core v2 API /api/v2/write 请求，请设置下表中列出的参数

时间戳精度

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

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

InfluxDB v1 兼容性

/write InfluxDB v1 兼容性端点提供与能够写入 InfluxDB v1.x 数据的客户端的向后兼容性。

POST /write?db=mydb&precision=ns

验证 v1 API 请求

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

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

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

对于 InfluxDB v1 兼容端点，您可以通过将令牌作为password凭据来使用 InfluxDB 1.x 的用户名和密码约定来验证数据库写入。在验证发往 v1 API /write 端点的请求时，InfluxDB 3 Core 会检查password (p) 值是否是授权的令牌。InfluxDB 3 Core 会忽略请求中的username (u) 参数。

使用以下身份验证方案之一，适用于支持 Basic 身份验证或查询参数的客户端

• Basic 身份验证
• 查询字符串身份验证

Basic 身份验证

使用带有 Basic 方案的 Authorization 标头来验证 v1 API /write 请求。在验证请求时，InfluxDB 3 Core 会检查解码凭据的password部分是否是授权的令牌。InfluxDB 3 Core 会忽略解码凭据的username部分。

语法

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

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

示例

以下示例显示了如何将 cURL 与 Basic 身份验证方案一起使用

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

查询字符串身份验证

在 URL 中，传递 p 查询参数以验证 /write 请求。在验证请求时，InfluxDB 3 Core 会检查 p (password) 值是否是授权的令牌，并忽略 u (username) 参数。

语法

https://:8181/write/?u=any&p=DATABASE_TOKEN

示例

以下示例显示了如何将 cURL 与查询字符串身份验证一起使用

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

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

使用 Authorization: Bearer 或 Authorization: Token 方案来传递令牌，用于验证 v1 API /write 请求。

在 InfluxDB 3 Core 中，Bearer 和 Token 是等效的。Token 方案用于 InfluxDB 2.x API。Bearer 由OAuth 2.0 Framework定义。InfluxDB API 客户端对其中一种的支持可能有所不同。

语法

Authorization: Bearer DATABASE_TOKEN

Authorization: Token DATABASE_TOKEN

示例

使用 Bearer 验证 v1 写入请求

curl -i "https://:8181/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 验证 v1 写入请求

curl -i "https://:8181/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'

v1 API 写入参数

对于 InfluxDB 3 Core v1 API /write 请求，请设置下表中列出的参数

时间戳精度

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

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

客户端库示例

使用特定于语言的客户端库与您的自定义代码一起将数据写入 InfluxDB 3 Core。

v1 客户端库

v1 客户端库将数据以行协议语法发送到 v1 API /write 端点。

const Influx = require('influx')

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

from influxdb import InfluxDBClient

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

v2 客户端库

v2 客户端库将数据以行协议语法发送到 v2 API /api/v2/write 端点。

有关使用 v2 客户端库的更多信息，请参阅v2 客户端库。

Telegraf 配置

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

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

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

[[outputs.influxdb]]
  urls = ["https://:8181"]
  database = "
DATABASE_NAME
"
  skip_database_creation = true
  retention_policy = ""
  username = "ignored"
  password = "
DATABASE_TOKEN
"
  content_encoding = "gzip"

替换以下配置值

• DATABASE_NAME：要写入的数据库的名称
• DATABASE_TOKEN：您的 InfluxDB 3 Core 令牌