Documentation

InfluxDB 云端无服务器

使用 InfluxDB v1 HTTP API

使用 InfluxDB v1 API /write 和 /query 端点与您带到 InfluxDB Cloud Serverless 的 v1 工作负载。 v1 端点使用用户名/密码身份验证和现有的 InfluxDB 1.x 工具和代码。

学习如何认证请求，将数据库和保留策略映射到存储桶，调整现有 v1 工作负载的请求参数，并找到兼容的工具来编写和查询存储在 InfluxDB Cloud Serverless 数据库中的数据。

认证 API 请求

InfluxDB Cloud Serverless 要求每个 API 请求都使用 API token进行身份验证。 使用 InfluxDB v1 API，您可以在 InfluxDB 1.x 的用户名和密码方案中使用 API 令牌，或在 InfluxDB v2 Authorization: Token 方案中使用。

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

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

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

基本认证

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

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

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

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

示例

以下示例展示了如何使用 cURL 进行 Basic 身份验证方案和一个 token：

#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################

curl "https://cloud2.influxdata.com/query" \
  --user "":"
API_TOKEN
" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "rp=
RETENTION_POLICY
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

替换以下内容：

  • DATABASE_NAME: 您的 InfluxDB Cloud Serverless 桶
  • RETENTION_POLICY: 您的 InfluxDB Cloud Serverless 保留策略
  • API_TOKEN: 一个具有足够权限的令牌，用于映射的存储桶

查询字符串认证

在URL中，传递p查询参数以认证/write和/query请求。 在认证请求时，InfluxDB Cloud Serverless会检查p（密码）值是否为已授权的API令牌，并忽略u（用户名）参数。

语法
https://cloud2.influxdata.com/query/?[u=any]&p=API_TOKEN
https://cloud2.influxdata.com/write/?[u=any]&p=API_TOKEN
示例

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

#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 API
#######################################

curl --get "https://cloud2.influxdata.com/query" \
  --data-urlencode "p=
API_TOKEN
" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "rp=
RETENTION_POLICY
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

替换以下内容：

  • DATABASE_NAME: 数据库
  • RETENTION_POLICY: 保留策略
  • API_TOKEN: 一个具有足够权限的令牌，用于映射的存储桶

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

使用 Authorization: Token 方案传递token以对 v1 API /write 和 /query 请求进行认证。

语法

Authorization: Token API_TOKEN

示例

使用 Token 来验证写请求：

########################################################
# Use the Token authorization scheme with v1 /write
# to write data.
########################################################

curl -i "https://cloud2.influxdata.com/write?db=DATABASE_NAME&rp=
RETENTION_POLICY
&precision=ms" \
    --header "Authorization: Token 
API_TOKEN
" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1682358973500'

替换以下内容：

  • DATABASE_NAME: 数据库
  • RETENTION_POLICY: 保留策略
  • API_TOKEN: 一个具有足够权限的令牌，用于映射的存储桶

响应

InfluxDB HTTP API 响应使用标准 HTTP 状态码。 对 部分写入 和错误的响应体包含一个 JSON 对象，带有 code 和 message 属性，用于描述错误。 响应体消息在 InfluxDB Cloud Serverless 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=参数值。提供DBRP数据库名称。

  • 反序列化 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=包含一个未知值。
    提供一个时间戳精度。

将 v1 数据库和保留策略映射到存储桶

在您使用 InfluxDB v1 /write 端点写入数据或使用 v1 /query 端点查询数据之前，必须将存储桶映射到一个 数据库保留策略 (DBRP) 组合。

使用InfluxQL或SQL进行查询时，您不需要将DBRPs映射到存储桶。

在 InfluxDB 1.x 中，数据存储在 数据库 和 保留策略 中。 在 InfluxDB Cloud Serverless 中，数据库和保留策略的概念已经合并为 桶，桶具有 保留期限，但保留策略不再是数据模型的一部分。

InfluxDB 可以 自动映射桶到 DBRP，或者您可以使用 influx v1 dbrp CLI 命令或 InfluxDB v2 API /api/v2/dbrps 端点来 管理 DBRP 映射。

所需权限

管理 DBRP 映射需要一个 token，并具有必要的权限。

  • 写入 dbrp: 创建（自动或手动）、更新或删除 DBRP 映射。
  • read dbrp: 列出 DBRP 映射
  • 写入桶: 在使用 v1 写入 API 时自动为 DBRP 映射创建一个桶

创建映射桶所需的权限

如果您使用 v1 写入 API 向一个不存在的数据库 (db) 和保留策略 (rp) 组合写入数据，InfluxDB 会尝试使用指定的参数值创建一个新的桶。 如果令牌没有权限创建桶，则写入请求将因授权错误而失败。

默认 DBRP

每个在 DBRP 映射中的独特数据库名称都有一个 默认 映射（default 属性等于 true）。 如果您向 v1 /write 或 v1 /query 端点发送请求，并且不指定保留策略名称（rp=）， 那么 InfluxDB 将使用数据库的默认 DBRP 映射来确定存储桶。

自动DBRP映射

InfluxDB Cloud 无服务器在以下操作中自动为您创建 DBRP 映射：

为了让InfluxDB自动创建DBRP映射和桶，您必须使用一个具有DBRP和桶写入权限的 token。

自动生成的桶使用映射桶的名称语法，并且默认保留期为桶的创建日期减去3天。要设置桶的保留期，请查看如何更新桶。

映射桶的名称语法

InfluxDB使用以下命名约定将数据库和保留策略名称映射到存储桶名称：

DATABASE_NAME/RETENTION_POLICY_NAME

桶命名示例

v1 数据库名称v1 保留策略名称桶名称
数据库重复数据库/重复
telegraf自动生成telegraf/自动生成
网络指标1万降采样网络指标/1万降采样

为了避免在每个CLI命令中添加配置参数， 设置一个活跃的InfluxDB配置。

管理 DBRPs

创建 DBRP 映射

要创建DBRP映射，请使用influx CLI或InfluxDB HTTP API。

一个 DBRP 组合只能映射到一个单一的桶

每个唯一的DBRP组合只能映射到一个单独的桶。如果您映射一个已经映射到另一个桶的DBRP组合，它将覆盖现有的DBRP映射。

influx CLI InfluxDB API

使用 influx v1 dbrp create 命令 将数据库和保留策略映射到一个存储桶。 包括以下内容：

* 必填

influx v1 dbrp create \
  --token 
API_TOKEN
 \
  --org ORG_ID \
  --db 
DATABASE_NAME
 \
  --rp 
RETENTION_POLICY_NAME
 \
  --bucket-id 
BUCKET_ID
 \
  --default

替换以下内容：

  • API_TOKEN: 一个 令牌，具有 必要的权限
  • DATABASE_NAME: 要映射到存储桶的数据库名称
  • RETENTION_POLICY_NAME: 将映射到存储桶的保留策略名称
  • BUCKET_ID: 要映射的 bucket ID

输出是DBRP。

使用/api/v2/dbrps API端点创建新的DBRP映射。

POST https://cloud2.influxdata.com/api/v2/dbrps

包含以下内容：

  • 请求方法: POST

  • 标题：

  • 请求体：包含以下字段的JSON对象：

    • bucketID: the bucket ID to map to
    • database: the database name to map to the bucket
    • org or orgID: your organization name or organization ID
    • retention_policy: the retention policy name to map to the bucket
    • Optional: default: true sets the database name’s default DBRP mapping.
curl --request POST https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --header 'Content-type: application/json' \
  --data '{
        "bucketID": "
BUCKET_ID
",
        "database": "
DATABASE_NAME
",
        "default": true,
        "orgID": "
ORG_ID
",
        "retention_policy": "
RETENTION_POLICY_NAME
"
      }'

如果成功，响应状态码为 201: Created，响应主体包含 DBRP。

列出 DBRP 映射

使用influx CLI或InfluxDB HTTP API列出所有DBRP映射，并验证您要查询的存储桶是否映射到数据库和保留政策。

influx CLI InfluxDB HTTP API

使用influx v1 dbrp list命令 来列出DBRP映射。

查看所有 DBRP 映射
influx v1 dbrp list --token 
API_TOKEN
 --org 
ORG_ID
 \
按数据库过滤DBRP映射
influx v1 dbrp list \
  --token 
API_TOKEN
 \
  --org 
ORG_ID
 \
  --db 
DATABASE_NAME
按桶 ID 过滤 DBRP 映射
influx v1 dbrp list \
  --token 
API_TOKEN
 \
  --org 
ORG_ID
 \
  --bucket-id 
BUCKET_ID

使用/api/v2/dbrps API接口来列出DBRP映射。

GET https://cloud2.influxdata.com/api/v2/dbrps

包含以下内容：

  • 请求方法： GET
  • 头部:
  • 查询参数： * 必需
    • * orgID: 你的 组织 ID
    • bucketID: 一个 桶 ID (用于列出特定桶的 DBRP 映射)
    • database: 一个数据库名称 (用于列出具有特定数据库名称的 DBRP 映射)
    • rp: 一个保留策略名称 (用于列出具有特定保留策略名称的 DBRP 映射)
    • id: 一个 DBRP 映射 ID (用于列出特定的 DBRP 映射)
查看所有 DBRP 映射
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
"
按数据库过滤DBRP映射
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
" \
  --data-urlencode  "db=
DATABASE_NAME
"
按桶 ID 过滤 DBRP 映射
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
" \
  --data-urlencode  "bucketID=
BUCKET_ID
"

更新 DBRP 映射

使用influx CLI或InfluxDB HTTP API来更新DBRP映射——例如，更改保留策略名称或将映射设置为数据库名称的默认。

influx CLI InfluxDB HTTP API

使用influx v1 dbrp update命令来更新DBRP映射。包含以下内容：

  • 一个 token，具有 必要的权限
  • 要更新的DBRP映射ID
  • 可选：保留政策名称以更新
  • 可选：默认标志，用于将保留策略设置为数据库名称的 默认 DBRP 映射。
更新默认保留策略
influx v1 dbrp update \
  --token 
API_TOKEN
 \
  --org 
ORG_ID
 \
  --id 
DBRP_ID
 \
  --rp 
RETENTION_POLICY_NAME
 \
  --default

替换以下内容：

  • API_TOKEN: 一个 令牌，具有 必要的权限
  • DBRP_ID: 要更新的 DBRP ID
  • RETENTION_POLICY_NAME: 一个用于映射到存储桶的保留策略名称

输出是DBRP。

使用/api/v2/dbrps/{dbrpID} API端点来更新DBRP映射。

PATCH https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}

包含以下内容：

* 必填

  • 请求方法： PATCH
  • 请求头:
  • 路径参数：
    • * id: 要更新的DBRP映射ID
  • 查询参数:
  • 请求体 (JSON):
    • rp: 要更新的保留策略名称
    • default: 将保留策略设置为数据库名称的 默认 DBRP 映射
更新默认保留策略
curl --request PATCH \
  https://cloud2.influxdata.com/api/v2/dbrps/
DBRP_ID
 \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
" \
  --data '{
      "rp": "
RETENTION_POLICY_NAME
",
      "default": true
    }'

替换以下内容：

  • API_TOKEN: 一个 令牌，具有 必要的权限
  • DBRP_ID: 要更新的 DBRP ID
  • RETENTION_POLICY_NAME: 一个用于映射到存储桶的保留策略名称

输出是DBRP。

删除一个 DBRP 映射

使用influx CLI 或 InfluxDB API 删除一个 DBRP 映射。

influx CLI InfluxDB API

使用influx v1 dbrp delete命令来删除DBRP映射。包含以下内容：

* 必填

influx v1 dbrp delete \
  --token 
API_TOKEN
 \
  --org ORG_ID \
  --id 
DBRP_ID

输出是DBRP。

使用/api/v2/dbrps/{dbrpID} API端点来删除DBRP映射。

DELETE https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}

包含以下内容：

* 必填

  • 请求方法: DELETE
  • 请求头:
  • 路径参数：
    • * id: 要更新的 DBRP 映射 ID
  • 查询参数:
curl --request DELETE \
  https://cloud2.influxdata.com/api/v2/dbrps/
DBRP_ID
 \
  --header "Authorization: Token 
API_TOKEN
" \
  --data-urlencode "orgID=
ORG_ID
"

替换以下内容：

写入数据

查看如何 使用 InfluxDB Cloud 无服务器 HTTP 写入 API 以适应 InfluxDB v1 或 v1.x 兼容工作负载。

查询数据

查看如何使用 InfluxDB Cloud 无服务器 HTTP 查询 API，以适应 InfluxDB v1 或 v1.x 兼容工作负载。

使用InfluxQL进行桶管理（不支持）

InfluxDB Cloud Serverless 不允许使用 InfluxQL 命令来管理或修改存储桶。
您不能使用以下 InfluxQL 命令：

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

选择您的 InfluxDB 云无服务器区域

选择您的 InfluxDB Cloud Serverless 区域，我们将为您定制代码示例。

AWS

有关更多信息，请参见 InfluxDB Cloud Serverless regions。

感谢您的反馈!

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

谢谢！

No thanks

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 企业版是建立在核心基础之上的商业版本，增加了历史查询能力、读取副本、高可用性、可扩展性和细粒度安全性。

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

InfluxDB 云端无服务器

您目前正在查看特定于 InfluxDB Cloud Serverless 的文档，该文档由 v3 存储引擎 提供，功能与由 TSM 存储引擎提供的 InfluxDB Cloud 有所不同。

您是否在使用 InfluxDB Cloud Serverless？ 如何查找？

访问 您组织的主页，并在右侧栏底部找到以下内容：

InfluxDB Cloud Serverless Storage Engine Version 3
Yes – I'm using InfluxDB Cloud Serverless No – I'm using InfluxDB Cloud (TSM)