InfluxDB 3 Core API 服务 (3.7.0)

InfluxData: support@influxdata.com URL: https://influxdb.org.cn 许可证: MIT

InfluxDB 3 Core 的 InfluxDB HTTP API 提供了一个与 InfluxDB 3 Core 数据库和资源交互的编程接口。使用此 API 可以

将数据写入 InfluxDB 3 Core 数据库
使用 SQL 或 InfluxQL 查询数据
使用处理引擎插件处理数据
管理数据库、表和处理引擎触发器
执行管理任务和访问系统信息

API 包含以下路径下的终结点

/api/v3: InfluxDB 3 Core 原生终结点
/: InfluxDB v1 工作负载和客户端的兼容性终结点
/api/v2/write: InfluxDB v2 工作负载和客户端的兼容性终结点

快速入门

curl -X POST "https://:8181/api/v3/configure/token/admin"

检查 InfluxDB 服务器的运行状况。

curl "https://:8181/health" \
   --header "Authorization: Bearer ADMIN_TOKEN"

写入数据到 InfluxDB。

curl "https://:8181/api/v3/write_lp?db=sensors&precision=auto"
  --header "Authorization: Bearer ADMIN_TOKEN" \
  --data-raw "home,room=Kitchen temp=72.0
 home,room=Living\ room temp=71.5"

如果所有数据都已写入，响应为 204 No Content。

查询数据从 InfluxDB。

curl -G "https://:8181/api/v3/query_sql" \
  --header "Authorization: Bearer ADMIN_TOKEN" \
  --data-urlencode "db=sensors" \
  --data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
  --data-urlencode "format=jsonl"

输出

{"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"}

有关使用 InfluxDB 3 Core 的更多信息，请参阅入门指南。

身份验证

根据您的工作流程，使用以下一种方案对 InfluxDB 3 API 进行身份验证

身份验证方案	适用于
Bearer 身份验证	所有终结点
令牌身份验证	v1、v2 终结点
Basic 身份验证	v1 终结点
查询字符串身份验证	v1 终结点

基本身份验证

使用 Authorization 标头和 Basic 方案对 v1 API 请求进行身份验证。

适用于 InfluxDB 3 中的 v1 兼容性 /write 和 /query 终结点。

在验证请求时，InfluxDB 3 会检查解码凭证的 password 部分是否为授权令牌，并忽略解码凭证的 username 部分。

示例

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

替换以下内容：

DATABASE_NAME：您的 InfluxDB 3 Core 数据库
AUTH_TOKEN：管理员令牌

安全方案类型	HTTP
HTTP 授权方案	basic

查询字符串身份验证

使用 InfluxDB 1.x API 参数通过查询字符串为 v1 API 请求提供凭证。

查询字符串身份验证适用于 v1 兼容的 /write 和 /query 终结点。

在验证请求时，InfluxDB 3 会检查 p（password）查询参数是否为授权令牌，并忽略 u（username）查询参数。

语法

http://:8181/query/?[u=any]&p=DATABASE_TOKEN
http://:8181/write/?[u=any]&p=DATABASE_TOKEN

示例

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

替换以下内容：

DATABASE_NAME：您的 InfluxDB 3 Core 数据库
AUTH_TOKEN：管理员令牌

#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 HTTP API
#######################################
# Use authentication query parameters:
#   ?p=DATABASE_TOKEN
#######################################

curl --get "https://:8181/query" \
  --data-urlencode "p=AUTH_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

替换以下内容：

DATABASE_NAME：要查询的数据库
AUTH_TOKEN：管理员令牌

安全方案类型	API 密钥
查询参数名称	u=&p=

Bearer 身份验证

使用 OAuth Bearer 身份验证方案向 InfluxDB 3 提供授权令牌。

Bearer 身份验证适用于所有终结点。

在您的 API 请求中，发送一个 Authorization 标头。对于标头值，提供单词 Bearer，后跟一个空格和一个管理员令牌。

语法

Authorization: Bearer AUTH_TOKEN

示例

curl https://:8181/api/v3/query_influxql \
  --header "Authorization: Bearer AUTH_TOKEN"

安全方案类型	HTTP
HTTP 授权方案	bearer
Bearer 格式	"JWT"

令牌身份验证

使用 InfluxDB v2 令牌身份验证向 InfluxDB 3 提供授权令牌。

v2 令牌方案适用于 InfluxDB 3 中的 v1 和 v2 兼容性终结点。

在您的 API 请求中，发送一个 Authorization 标头。对于标头值，提供单词 Token，后跟一个空格和一个数据库令牌。单词 Token 区分大小写。

语法

Authorization: Token AUTH_TOKEN

示例

########################################################
# Use the Token authentication scheme with /api/v2/write
# to write data.
########################################################

curl --request post "https://:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \
  --header "Authorization: Token AUTH_TOKEN" \
  --data-binary 'home,room=kitchen temp=72 1463683075'

管理令牌

安全方案类型	API 密钥
标头参数名称	Authorization

缓存数据

管理内存缓存。

唯一值缓存

唯一值缓存 (DVC) 允许您缓存表中一个或多个列的唯一值，从而提高返回唯一标签和字段值的查询性能。

DVC 是一个内存缓存，用于存储表中特定列的唯一值。创建 DVC 时，您可以指定要缓存的列的唯一值、要缓存的唯一值组合的最大数量以及缓存值的最大年龄。DVC 与一个表相关联，一个表可以有多个 DVC。

最后值缓存

最后值缓存 (LVC) 允许您缓存表中特定字段的最新值，从而提高返回特定序列字段的最新值或字段最后 N 个值的查询性能。

LVC 是一个内存缓存，用于存储表中序列的特定字段的最后 N 个值。创建 LVC 时，您可以指定要缓存的字段、用于标识每个序列的标签以及每个唯一序列要缓存的值的数量。LVC 与一个表相关联，一个表可以有多个 LVC。

创建唯一值缓存

为表创建唯一值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

columns 必需	字符串数组字符串
db 必需	字符串
max_age	整数可选的最大年龄（秒）。
max_cardinality	整数可选的最大基数。
name	字符串可选的缓存名称。
table 必需	字符串

响应

请求示例

载荷

内容类型

application/json

{"db": "mydb",
"table": "mytable",
"columns": ["tag1",
"tag2"
],
"max_cardinality": 1000,
"max_age": 3600
}

删除唯一值缓存

删除唯一值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
name 必需	字符串要删除的唯一值缓存的名称。
table 必需	字符串包含唯一值缓存的表名称。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

创建最后值缓存

为表创建最后值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

count	整数可选的计数。
db 必需	字符串
key_columns	字符串数组字符串可选的键列列表。
name	字符串可选的缓存名称。
table 必需	字符串
ttl	整数可选的生存时间（秒）。
value_columns	字符串数组字符串可选的值列列表。

响应

请求示例

载荷

内容类型

application/json

{"db": "mydb",
"table": "mytable",
"key_columns": ["tag1"
],
"value_columns": ["field1"
],
"count": 100,
"ttl": 3600
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

删除最后值缓存

删除最后值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
name 必需	字符串要删除的最后值缓存的名称。
table 必需	字符串包含最后值缓存的表名称。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

兼容性终结点

InfluxDB 3 为 InfluxDB 1.x 和 InfluxDB 2.x 工作负载和客户端提供了兼容性终结点。

使用 v1 或 v2 兼容终结点写入数据

InfluxDB v2 客户端的 /api/v2/write 终结点，以及将现有 InfluxDB v2 写入工作负载迁移到 InfluxDB 3 时使用。
InfluxDB v1 客户端的 /write 终结点，以及将现有 InfluxDB v1 写入工作负载迁移到 InfluxDB 3 时使用。

对于新工作负载，请使用 /api/v3/write_lp 终结点。

所有终结点都接受相同的行协议格式。

查询数据

使用 HTTP /query 终结点用于 InfluxDB v1 客户端和使用 InfluxQL 的 v1 查询工作负载。

对于新工作负载，请使用以下任一方式

用于使用 SQL 的新查询工作负载的 HTTP /api/v3/query_sql 终结点。
用于使用 InfluxQL 的新查询工作负载的 HTTP /api/v3/query_influxql 终结点。
用于使用 SQL 或 InfluxQL 进行查询的 Flight SQL 和 InfluxDB 3 Flight+gRPC API。有关使用 Flight API 的更多信息，请参阅 InfluxDB 3 客户端库。

服务器信息

/health 和 metrics 等服务器信息终结点与 InfluxDB 1.x 和 InfluxDB 2.x 客户端兼容。

写入行协议（v1 兼容）

将行协议写入指定的数据库。

此终结点为使用 InfluxDB 1.x 客户端库、Telegraf outputs.influxdb 输出插件或第三方工具等工具的 InfluxDB 1.x 写入工作负载提供向后兼容性。

使用此终结点以行协议格式将数据发送到 InfluxDB。使用查询参数指定写入数据的选项。

使用兼容性 API 写入数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

consistency	字符串写入一致性级别。InfluxDB 3 忽略此参数。为与 InfluxDB 1.x 客户端兼容而提供。
db 必需	字符串数据库名称。如果数据库尚不存在，InfluxDB 会创建它，然后将批处理中的所有点写入该数据库。
p	字符串 v1 兼容身份验证的密码。对于查询字符串身份验证，传递管理员令牌。InfluxDB 3 验证 `p` 值是否为授权令牌。
precision 必需	字符串 (PrecisionWriteCompatibility) 枚举： "ms" "s" "us" "ns" 行协议批处理中 Unix 时间戳的精度。
rp	字符串保留策略名称。已尊重但已弃用。InfluxDB 3 不使用保留策略。
u	字符串 v1 兼容身份验证的用户名。在使用基本身份验证或查询字符串身份验证时，InfluxDB 3 会忽略此参数，但允许任何任意字符串以与 InfluxDB 1.x 客户端兼容。

标头参数

Accept	字符串默认： application/json 值： "application/json" 客户端可以理解的内容类型。写入操作只有在失败时（部分或全部）才会返回响应正文——例如，由于语法问题或类型不匹配。
Authorization	字符串用于令牌身份验证的授权标头。支持的方案 `Bearer AUTH_TOKEN` - OAuth bearer 令牌方案 `Token AUTH_TOKEN` - InfluxDB v2 令牌方案 `Basic <base64-encoded USERNAME:AUTH_TOKEN>` - 基本身份验证（用户名被忽略）
Content-Encoding	字符串 (ContentEncoding) 默认： identity 枚举： "gzip" "identity" 请求正文中的行协议所应用的压缩。要发送 gzip 载荷，请传递 `Content-Encoding: gzip` 标头。
Content-Length	整数 (ContentLength) 发送到 InfluxDB 的 entity-body 的大小（以字节为单位）。
Content-Type	字符串 (LineProtocol) 默认： text/plain; charset=utf-8 枚举： "text/plain" "text/plain; charset=utf-8" 请求正文的内容类型。

请求体架构： text/plain

字符串

响应

请求示例

载荷

内容类型

text/plain

示例

measurement,tag=value field=1 1234567890

响应示例

400
401

内容类型

application/json

示例

"{\n \"error\": \"write of line protocol failed\",\n \"data\": [\n {\n \"original_line\": \"dquote> home,room=Kitchen temp=hi\",\n \"line_number\": 2,\n \"error_message\": \"No fields were provided\"\n }\n ]\n}\n"

写入行协议（v2 兼容）

将行协议写入指定的数据库。

此终结点为使用 InfluxDB 2.x 客户端库、Telegraf outputs.influxdb_v2 输出插件或第三方工具等工具的 InfluxDB 2.x 写入工作负载提供向后兼容性。

使用此终结点以行协议格式将数据发送到 InfluxDB。使用查询参数指定写入数据的选项。

使用兼容性 API 写入数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

accept_partial	布尔值 (AcceptPartial) 默认： true 接受部分写入。
db 必需	字符串数据库名称。如果数据库尚不存在，InfluxDB 会创建它，然后将批处理中的所有点写入该数据库。
precision 必需	字符串 (PrecisionWriteCompatibility) 枚举： "ms" "s" "us" "ns" 行协议批处理中 Unix 时间戳的精度。

标头参数

Accept	字符串默认： application/json 值： "application/json" 客户端可以理解的内容类型。写入操作只有在失败时（部分或全部）才会返回响应正文——例如，由于语法问题或类型不匹配。
Content-Encoding	字符串默认： identity 枚举： "gzip" "identity" 请求正文中的行协议所应用的压缩。要发送 gzip 载荷，请传递 `Content-Encoding: gzip` 标头。
Content-Length	整数发送到 InfluxDB 的 entity-body 的大小（以字节为单位）。
Content-Type	字符串 (LineProtocol) 默认： text/plain; charset=utf-8 枚举： "text/plain" "text/plain; charset=utf-8" 请求正文的内容类型。

请求体架构： text/plain

字符串

响应

请求示例

载荷

内容类型

text/plain

示例

measurement,tag=value field=1 1234567890

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

执行 InfluxQL 查询（v1 兼容）

执行 InfluxQL 查询以从指定数据库检索数据。

此终结点与 InfluxDB 1.x 客户端库和 Grafana 等第三方集成兼容。使用查询参数指定数据库和 InfluxQL 查询。

使用 InfluxDB v1 HTTP 查询 API 和 InfluxQL 查询数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

chunk_size	整数默认： 10000 将进入块的记录数。仅当 `chunked=true` 时才使用此参数。
chunked	布尔值默认： false 如果为 true，则响应将分为 `chunk_size` 大小的块。
db	默认： application/json 要查询的数据库。如果未提供，则 InfluxQL 查询字符串必须指定数据库。
epoch	字符串 (EpochCompatibility) 枚举： "ns" "u" "µ" "ms" "s" "m" "h" 将时间戳格式化为具有指定精度的Unix（epoch）时间戳，而不是具有纳秒精度的RFC3339 时间戳。
p	字符串 v1 兼容身份验证的密码。对于查询字符串身份验证，传递管理员令牌。InfluxDB 3 验证 `p` 值是否为授权令牌。
pretty	布尔值默认： false 如果为 true，则 JSON 响应将以人类可读的格式进行格式化。
q 必需	字符串 InfluxQL 查询字符串。
rp	字符串保留策略名称。已尊重但已弃用。InfluxDB 3 不使用保留策略。
u	字符串 v1 兼容身份验证的用户名。在使用基本身份验证或查询字符串身份验证时，InfluxDB 3 会忽略此参数，但允许任何任意字符串以与 InfluxDB 1.x 客户端兼容。

标头参数

Accept	字符串默认： application/json 枚举： "application/json" "application/csv" "text/csv" 客户端可以理解的内容类型。如果指定了 `text/csv`，则 `Content-type` 响应标头为 `application/csv`，并且响应格式为 CSV。如果格式无效或非 UTF-8，则返回错误。
Authorization	字符串用于令牌身份验证的授权标头。支持的方案 `Bearer AUTH_TOKEN` - OAuth bearer 令牌方案 `Token AUTH_TOKEN` - InfluxDB v2 令牌方案 `Basic <base64-encoded USERNAME:AUTH_TOKEN>` - 基本身份验证（用户名被忽略）

响应

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

执行 InfluxQL 查询 (v1 兼容)

执行 InfluxQL 查询以从指定数据库检索数据。

使用 InfluxDB v1 HTTP 查询 API 和 InfluxQL 查询数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Accept

字符串

默认： application/json

枚举： "application/json" "application/csv" "text/csv"

客户端可以理解的内容类型。

如果指定了 text/csv，则 Content-type 响应标头为 application/csv，并且响应格式为 CSV。

如果格式无效或非 UTF-8，则返回错误。

请求体架构： application/json

chunk_size	整数默认： 10000 将进入块的记录数。仅当 `chunked=true` 时才使用此参数。
chunked	布尔值如果为 true，则响应将分为 `chunk_size` 大小的块。
db	字符串要查询的数据库。如果未提供，则 InfluxQL 查询字符串必须指定数据库。
epoch	字符串枚举： "ns" "u" "µ" "ms" "s" "m" "h" Unix 时间戳精度。 `h` 表示小时 `m` 表示分钟 `s` 表示秒 `ms` 表示毫秒 `u` 或 `µ` 表示微秒 `ns` 表示纳秒将时间戳格式化为具有指定精度的Unix（epoch）时间戳，而不是具有纳秒精度的RFC3339 时间戳。
pretty	布尔值如果为 true，则 JSON 响应将以人类可读的格式进行格式化。
q 必需	字符串 InfluxQL 查询字符串。

响应

请求示例

载荷

内容类型

application/json

{"db": "string",
"q": "string",
"chunked": true,
"chunk_size": 10000,
"epoch": "ns",
"pretty": true
}

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

健康检查 (v1)

检查服务的状态。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

数据库

管理数据库

列出数据库

检索数据库列表。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

format

必需

string (Format)

枚举: "json" "csv" "parquet" "jsonl"

响应体中数据的格式。

响应

响应示例

200
401

内容类型

application/json

{"databases": ["string"
]
}

创建数据库

在系统中创建一个新数据库。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

db 必需	字符串
retention_period	字符串数据库的保留期。指定数据应保留多长时间。使用持续时间格式（例如，“1d”、“1h”、“30m”、“7d”）。

响应

请求示例

载荷

内容类型

application/json

{"db": "string",
"retention_period": "7d"
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

删除数据库

软删除数据库。数据库将被安排删除，并且无法查询。使用 hard_delete_at 参数安排硬删除。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
hard_delete_at	string <date-time> 在指定时间安排数据库进行硬删除。如果未提供，数据库将被软删除。使用 ISO 8601 日期时间格式（例如，“2025-12-31T23:59:59Z”）。删除数据库不可撤销删除数据库是一项破坏性操作。一旦数据库被删除，存储在该数据库中的数据将无法恢复。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

移除数据库保留期

从数据库中移除保留期，将其设置为无限期保留。数据库中的数据不会过期。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db

必需

字符串

数据库名称。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

处理引擎

管理处理引擎触发器、测试插件以及发送请求以触发按需插件。

InfluxDB 3 Core 提供 InfluxDB 3 处理引擎，这是一个嵌入式 Python 虚拟机，可以动态加载和触发 Python 插件以响应数据库中的事件。使用处理引擎插件和触发器来运行代码并为不同的数据库事件执行任务。

要开始使用处理引擎，请参阅处理引擎和 Python 插件指南。

创建处理引擎触发器

使用指定的插件文件和触发器规范创建处理引擎触发器。

处理引擎和 Python 插件

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

db 必需	字符串
disabled	布尔值默认： false 触发器是否被禁用。
plugin_filename 必需	字符串要执行的插件的路径和文件名——例如，`schedule.py` 或 `endpoints/report.py`。路径可以是绝对路径，也可以是相对于启动 InfluxDB 3 时配置的 `--plugins-dir` 目录的相对路径。插件文件必须实现与触发器规范关联的触发器接口。
	object 传递给插件的可选参数。
trigger_name 必需	字符串
必需	object 触发器错误处理和执行行为的配置。
trigger_specification 必需	string^(cron:[0-9 ,/-]+\|every:[0-9]+[smhd]\|all_tab... 指定处理引擎触发器何时以及如何被调用。支持的触发器规范基于 Cron 的调度格式：`cron:CRON_EXPRESSION` 使用扩展（6 字段）cron 格式（秒分时月日月周日） `┌───────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌───────────── hour (0-23) │ │ │ ┌───────────── day of month (1-31) │ │ │ │ ┌───────────── month (1-12) │ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ │ * * * * ` 示例 `cron:0 0 6 * 1-5` - 每周工作日早上 6:00 `cron:0 30 14 * * 5` - 每周五下午 2:30 `cron:0 0 0 1 * ` - 每月的第一天午夜基于间隔的调度格式：`every:DURATION` 支持的持续时间：`s`（秒）、`m`（分钟）、`h`（小时）、`d`（天）、`w`（周）、`M`（月）、`y`（年） `every:30s` - 每 30 秒 `every:5m` - 每 5 分钟 `every:1h` - 每小时 `every:1d` - 每天 `every:1w` - 每周 `every:1M` - 每月 `every:1y` - 每年最大间隔*：1 年基于表的触发器 `all_tables` - 触发写入数据库中任何表的事件 `table:TABLE_NAME` - 触发写入特定表的事件按需触发器格式：`request:REQUEST_PATH` 创建一个 HTTP 端点 `/api/v3/engine/REQUEST_PATH` 用于手动调用 `request:hello-world` - 创建端点 `/api/v3/engine/hello-world` `request:data-export` - 创建端点 `/api/v3/engine/data-export`

响应

请求示例

载荷

内容类型

application/json

示例

在 "cron:CRON_EXPRESSION" 中，CRON_EXPRESSION 使用扩展的 6 字段 cron 格式。cron 表达式 0 0 6 * * 1-5 表示触发器将在每个工作日（周一至周五）早上 6:00 运行。

{"db": "mydb",
"plugin_filename": "schedule.py",
"trigger_name": "schedule_cron_trigger",
"trigger_specification": "cron:0 0 6 * * 1-5",
"trigger_settings": {"run_async": false,
"error_behavior": "Log"
}
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

删除处理引擎触发器

删除处理引擎触发器。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
force	布尔值默认： false
trigger_name 必需	字符串

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

禁用处理引擎触发器

禁用处理引擎触发器。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Content-Type

字符串

值： "application/json"

请求体中数据的格式。

请求体架构： application/json

db 必需	字符串
disabled	布尔值默认： false 触发器是否被禁用。
plugin_filename 必需	字符串要执行的插件的路径和文件名——例如，`schedule.py` 或 `endpoints/report.py`。路径可以是绝对路径，也可以是相对于启动 InfluxDB 3 时配置的 `--plugins-dir` 目录的相对路径。插件文件必须实现与触发器规范关联的触发器接口。
	object 传递给插件的可选参数。
trigger_name 必需	字符串
必需	object 触发器错误处理和执行行为的配置。
trigger_specification 必需	string^(cron:[0-9 ,/-]+\|every:[0-9]+[smhd]\|all_tab... 指定处理引擎触发器何时以及如何被调用。支持的触发器规范基于 Cron 的调度格式：`cron:CRON_EXPRESSION` 使用扩展（6 字段）cron 格式（秒分时月日月周日） `┌───────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌───────────── hour (0-23) │ │ │ ┌───────────── day of month (1-31) │ │ │ │ ┌───────────── month (1-12) │ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ │ * * * * ` 示例 `cron:0 0 6 * 1-5` - 每周工作日早上 6:00 `cron:0 30 14 * * 5` - 每周五下午 2:30 `cron:0 0 0 1 * ` - 每月的第一天午夜基于间隔的调度格式：`every:DURATION` 支持的持续时间：`s`（秒）、`m`（分钟）、`h`（小时）、`d`（天）、`w`（周）、`M`（月）、`y`（年） `every:30s` - 每 30 秒 `every:5m` - 每 5 分钟 `every:1h` - 每小时 `every:1d` - 每天 `every:1w` - 每周 `every:1M` - 每月 `every:1y` - 每年最大间隔*：1 年基于表的触发器 `all_tables` - 触发写入数据库中任何表的事件 `table:TABLE_NAME` - 触发写入特定表的事件按需触发器格式：`request:REQUEST_PATH` 创建一个 HTTP 端点 `/api/v3/engine/REQUEST_PATH` 用于手动调用 `request:hello-world` - 创建端点 `/api/v3/engine/hello-world` `request:data-export` - 创建端点 `/api/v3/engine/data-export`

响应

请求示例

载荷

内容类型

application/json

{"db": "string",
"plugin_filename": "string",
"trigger_name": "string",
"trigger_settings": {"run_async": false,
"error_behavior": "Log"
},
"trigger_specification": "cron:0 0 6 * * 1-5",
"trigger_arguments": { },
"disabled": false
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

启用处理引擎触发器

启用处理引擎触发器。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Content-Type

字符串

值： "application/json"

请求体中数据的格式。

请求体架构： application/json

db 必需	字符串
disabled	布尔值默认： false 触发器是否被禁用。
plugin_filename 必需	字符串要执行的插件的路径和文件名——例如，`schedule.py` 或 `endpoints/report.py`。路径可以是绝对路径，也可以是相对于启动 InfluxDB 3 时配置的 `--plugins-dir` 目录的相对路径。插件文件必须实现与触发器规范关联的触发器接口。
	object 传递给插件的可选参数。
trigger_name 必需	字符串
必需	object 触发器错误处理和执行行为的配置。
trigger_specification 必需	string^(cron:[0-9 ,/-]+\|every:[0-9]+[smhd]\|all_tab... 指定处理引擎触发器何时以及如何被调用。支持的触发器规范基于 Cron 的调度格式：`cron:CRON_EXPRESSION` 使用扩展（6 字段）cron 格式（秒分时月日月周日） `┌───────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌───────────── hour (0-23) │ │ │ ┌───────────── day of month (1-31) │ │ │ │ ┌───────────── month (1-12) │ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ │ * * * * ` 示例 `cron:0 0 6 * 1-5` - 每周工作日早上 6:00 `cron:0 30 14 * * 5` - 每周五下午 2:30 `cron:0 0 0 1 * ` - 每月的第一天午夜基于间隔的调度格式：`every:DURATION` 支持的持续时间：`s`（秒）、`m`（分钟）、`h`（小时）、`d`（天）、`w`（周）、`M`（月）、`y`（年） `every:30s` - 每 30 秒 `every:5m` - 每 5 分钟 `every:1h` - 每小时 `every:1d` - 每天 `every:1w` - 每周 `every:1M` - 每月 `every:1y` - 每年最大间隔*：1 年基于表的触发器 `all_tables` - 触发写入数据库中任何表的事件 `table:TABLE_NAME` - 触发写入特定表的事件按需触发器格式：`request:REQUEST_PATH` 创建一个 HTTP 端点 `/api/v3/engine/REQUEST_PATH` 用于手动调用 `request:hello-world` - 创建端点 `/api/v3/engine/hello-world` `request:data-export` - 创建端点 `/api/v3/engine/data-export`

响应

请求示例

载荷

内容类型

application/json

{"db": "string",
"plugin_filename": "string",
"trigger_name": "string",
"trigger_settings": {"run_async": false,
"error_behavior": "Log"
},
"trigger_specification": "cron:0 0 6 * * 1-5",
"trigger_arguments": { },
"disabled": false
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

安装插件包

将指定的 Python 包安装到处理引擎插件环境中。

此端点是同步的，会阻塞直到包安装完成。

处理引擎和 Python 插件

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Content-Type

字符串

值： "application/json"

请求体中数据的格式。

请求体架构： application/json

packages

必需

字符串数组字符串

要安装的 Python 包名称列表。可以包含版本说明符（例如，“scipy==1.9.0”）。

响应

请求示例

载荷

内容类型

application/json

{"packages": ["influxdb3-python",
"scipy",
"pandas==1.5.0",
"requests"
]
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

安装插件需求

从需求文件（也称为“pip requirements 文件”）中安装需求到处理引擎插件环境中。

此端点是同步的，会阻塞直到需求安装完成。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Content-Type

字符串

值： "application/json"

请求体中数据的格式。

请求体架构： application/json

requirements_location

必需

字符串

包含要安装的 Python 包的需求文件的路径。可以是相对路径（相对于插件目录）或绝对路径。

响应

请求示例

载荷

内容类型

application/json

{"requirements_location": "requirements.txt"
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

测试 WAL 插件

执行写前日志 (WAL) 插件的测试。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

测试调度插件

执行调度插件的测试。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

按需处理引擎插件请求

执行触发器 plugin_filename 中指定的按需处理引擎插件。请求可以包括请求标头、查询字符串参数和请求正文，InfluxDB 会将这些传递给插件。

按需插件实现以下签名

def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)

响应取决于插件实现。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

路径参数

request_path

必需

字符串

在请求触发器规范中为插件配置的路径。

例如，如果您定义了一个如下触发器：

trigger_specification: "request:hello-world"

然后，HTTP API 会公开以下插件端点：

<INFLUXDB3_HOST>/api/v3/engine/hello-world

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

按需处理引擎插件请求

执行触发器 plugin_filename 中指定的按需处理引擎插件。请求可以包括请求标头、查询字符串参数和请求正文，InfluxDB 会将这些传递给插件。

按需插件实现以下签名

def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)

响应取决于插件实现。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

路径参数

request_path

必需

字符串

在请求触发器规范中为插件配置的路径。

例如，如果您定义了一个如下触发器：

trigger_specification: "request:hello-world"

然后，HTTP API 会公开以下插件端点：

<INFLUXDB3_HOST>/api/v3/engine/hello-world

标头参数

Content-Type

字符串

值： "application/json"

请求体中数据的格式。

请求体架构： application/json

property name*

any

响应

请求示例

载荷

内容类型

application/json

{ }

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

更新插件文件

更新插件目录中的插件文件。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

更新插件目录

更新插件目录配置。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

服务器信息

检索服务器指标、状态和版本信息

健康检查

检查服务的状态。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

健康检查 (v1)

检查服务的状态。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

Ping 服务器

返回服务器的版本信息。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

200

内容类型

application/json

{"version": "0.1.0",
"revision": "f3d3d3d"
}

指标

检索 Prometheus 兼容的服务器指标。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

表

管理表模式和数据

创建表

在数据库中创建一个新表。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

db 必需	字符串
	Array of objects
table 必需	字符串
tags 必需	字符串数组字符串

响应

请求示例

载荷

内容类型

application/json

{"db": "string",
"table": "string",
"tags": ["string"
],
"fields": [{"name": "string",
"type": "utf8"
}
]
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

删除表

软删除表。表将被安排删除，并且无法查询。使用 hard_delete_at 参数安排硬删除。

删除表不可撤销

删除表是一项破坏性操作。一旦表被删除，存储在该表中的数据将无法恢复。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
hard_delete_at	string <date-time> 在指定时间安排表进行硬删除。如果未提供，表将被软删除。使用 ISO 8601 格式（例如，“2025-12-31T23:59:59Z”）。
table 必需	字符串

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

创建唯一值缓存

为表创建唯一值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

columns 必需	字符串数组字符串
db 必需	字符串
max_age	整数可选的最大年龄（秒）。
max_cardinality	整数可选的最大基数。
name	字符串可选的缓存名称。
table 必需	字符串

响应

请求示例

载荷

内容类型

application/json

{"db": "mydb",
"table": "mytable",
"columns": ["tag1",
"tag2"
],
"max_cardinality": 1000,
"max_age": 3600
}

删除唯一值缓存

删除唯一值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
name 必需	字符串要删除的唯一值缓存的名称。
table 必需	字符串包含唯一值缓存的表名称。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

创建最后值缓存

为表创建最后值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

请求体架构： application/json

count	整数可选的计数。
db 必需	字符串
key_columns	字符串数组字符串可选的键列列表。
name	字符串可选的缓存名称。
table 必需	字符串
ttl	整数可选的生存时间（秒）。
value_columns	字符串数组字符串可选的值列列表。

响应

请求示例

载荷

内容类型

application/json

{"db": "mydb",
"table": "mytable",
"key_columns": ["tag1"
],
"value_columns": ["field1"
],
"count": 100,
"ttl": 3600
}

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

删除最后值缓存

删除最后值缓存。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
name 必需	字符串要删除的最后值缓存的名称。
table 必需	字符串包含最后值缓存的表名称。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

令牌

管理用于身份验证和授权的令牌

创建管理员令牌

创建一个管理员令牌。管理员令牌是一种特殊类型的令牌，对系统中的所有资源具有完全访问权限。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

201
401

内容类型

application/json

{"id": 0,
"name": "_admin",
"token": "apiv3_00xx0Xx0xx00XX0x0",
"hash": "00xx0Xx0xx00XX0x0",
"created_at": "2025-04-18T14:02:45.331Z",
"expiry": null
}

重新生成管理员令牌

重新生成管理员令牌并撤销具有相同名称的先前令牌。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

响应

响应示例

201
401

内容类型

application/json

{"id": 0,
"name": "_admin",
"token": "apiv3_00xx0Xx0xx00XX0x0",
"hash": "00xx0Xx0xx00XX0x0",
"created_at": "2025-04-18T14:02:45.331Z",
"expiry": null
}

删除令牌

删除令牌。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

id

必需

字符串

要删除的令牌的 ID。

响应

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

创建命名管理员令牌

创建一个命名管理员令牌。命名管理员令牌是具有特定名称标识符的管理员令牌。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

name

必需

字符串

管理员令牌的名称。

响应

响应示例

201
401

内容类型

application/json

{"id": 0,
"name": "_admin",
"token": "apiv3_00xx0Xx0xx00XX0x0",
"hash": "00xx0Xx0xx00XX0x0",
"created_at": "2025-04-18T14:02:45.331Z",
"expiry": null
}

查询数据

使用 SQL 或 InfluxQL 查询数据

执行 SQL 查询

执行 SQL 查询以从指定数据库检索数据。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db 必需	字符串数据库名称。
format	string (Format) 枚举: "json" "csv" "parquet" "jsonl" 响应体中数据的格式。
q 必需	string <SQL> 要执行的查询。

标头参数

Accept	字符串默认： application/json 枚举: "application/json" "application/jsonl" "application/vnd.apache.parquet" "text/csv" 客户端可以理解的内容类型。
Content-Type	字符串值： "application/json" 请求体中数据的格式。

响应

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

执行 SQL 查询

执行 SQL 查询以从指定数据库检索数据。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Accept	字符串默认： application/json 枚举: "application/json" "application/jsonl" "application/vnd.apache.parquet" "text/csv" 客户端可以理解的内容类型。
Content-Type	字符串值： "application/json" 请求体中数据的格式。

请求体架构： application/json

db 必需	字符串要查询的数据库名称。如果查询 (`q`) 未指定数据库，则需要此参数。
format	字符串枚举: "json" "csv" "parquet" "jsonl" "pretty" 查询结果的格式。
	object 查询的附加参数。使用此字段传递查询参数。
q 必需	字符串要执行的查询。

响应

请求示例

载荷

内容类型

application/json

{"db": "mydb",
"q": "SELECT * FROM mytable",
"format": "json",
"params": { }
}

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

执行 InfluxQL 查询

执行 InfluxQL 查询以从指定数据库检索数据。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

db	字符串数据库名称。如果提供了一个指定数据库的查询，则可以从请求中省略 'db' 参数。
format	字符串
q 必需	字符串

标头参数

Accept

字符串

默认： application/json

枚举: "application/json" "application/jsonl" "application/vnd.apache.parquet" "text/csv"

客户端可以理解的内容类型。

响应

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

执行 InfluxQL 查询

执行 InfluxQL 查询以从指定数据库检索数据。

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Accept	字符串默认： application/json 枚举: "application/json" "application/jsonl" "application/vnd.apache.parquet" "text/csv" 客户端可以理解的内容类型。
Content-Type	字符串值： "application/json" 请求体中数据的格式。

请求体架构： application/json

db 必需	字符串要查询的数据库名称。如果查询 (`q`) 未指定数据库，则需要此参数。
format	字符串枚举: "json" "csv" "parquet" "jsonl" "pretty" 查询结果的格式。
	object 查询的附加参数。使用此字段传递查询参数。
q 必需	字符串要执行的查询。

响应

请求示例

载荷

内容类型

application/json

{"db": "mydb",
"q": "SELECT * FROM mytable",
"format": "json",
"params": { }
}

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

执行 InfluxQL 查询（v1 兼容）

执行 InfluxQL 查询以从指定数据库检索数据。

此终结点与 InfluxDB 1.x 客户端库和 Grafana 等第三方集成兼容。使用查询参数指定数据库和 InfluxQL 查询。

使用 InfluxDB v1 HTTP 查询 API 和 InfluxQL 查询数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

chunk_size	整数默认： 10000 将进入块的记录数。仅当 `chunked=true` 时才使用此参数。
chunked	布尔值默认： false 如果为 true，则响应将分为 `chunk_size` 大小的块。
db	默认： application/json 要查询的数据库。如果未提供，则 InfluxQL 查询字符串必须指定数据库。
epoch	字符串 (EpochCompatibility) 枚举： "ns" "u" "µ" "ms" "s" "m" "h" 将时间戳格式化为具有指定精度的Unix（epoch）时间戳，而不是具有纳秒精度的RFC3339 时间戳。
p	字符串 v1 兼容身份验证的密码。对于查询字符串身份验证，传递管理员令牌。InfluxDB 3 验证 `p` 值是否为授权令牌。
pretty	布尔值默认： false 如果为 true，则 JSON 响应将以人类可读的格式进行格式化。
q 必需	字符串 InfluxQL 查询字符串。
rp	字符串保留策略名称。已尊重但已弃用。InfluxDB 3 不使用保留策略。
u	字符串 v1 兼容身份验证的用户名。在使用基本身份验证或查询字符串身份验证时，InfluxDB 3 会忽略此参数，但允许任何任意字符串以与 InfluxDB 1.x 客户端兼容。

标头参数

Accept	字符串默认： application/json 枚举： "application/json" "application/csv" "text/csv" 客户端可以理解的内容类型。如果指定了 `text/csv`，则 `Content-type` 响应标头为 `application/csv`，并且响应格式为 CSV。如果格式无效或非 UTF-8，则返回错误。
Authorization	字符串用于令牌身份验证的授权标头。支持的方案 `Bearer AUTH_TOKEN` - OAuth bearer 令牌方案 `Token AUTH_TOKEN` - InfluxDB v2 令牌方案 `Basic <base64-encoded USERNAME:AUTH_TOKEN>` - 基本身份验证（用户名被忽略）

响应

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

执行 InfluxQL 查询 (v1 兼容)

执行 InfluxQL 查询以从指定数据库检索数据。

使用 InfluxDB v1 HTTP 查询 API 和 InfluxQL 查询数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

标头参数

Accept

字符串

默认： application/json

枚举： "application/json" "application/csv" "text/csv"

客户端可以理解的内容类型。

如果指定了 text/csv，则 Content-type 响应标头为 application/csv，并且响应格式为 CSV。

如果格式无效或非 UTF-8，则返回错误。

请求体架构： application/json

chunk_size	整数默认： 10000 将进入块的记录数。仅当 `chunked=true` 时才使用此参数。
chunked	布尔值如果为 true，则响应将分为 `chunk_size` 大小的块。
db	字符串要查询的数据库。如果未提供，则 InfluxQL 查询字符串必须指定数据库。
epoch	字符串枚举： "ns" "u" "µ" "ms" "s" "m" "h" Unix 时间戳精度。 `h` 表示小时 `m` 表示分钟 `s` 表示秒 `ms` 表示毫秒 `u` 或 `µ` 表示微秒 `ns` 表示纳秒将时间戳格式化为具有指定精度的Unix（epoch）时间戳，而不是具有纳秒精度的RFC3339 时间戳。
pretty	布尔值如果为 true，则 JSON 响应将以人类可读的格式进行格式化。
q 必需	字符串 InfluxQL 查询字符串。

响应

请求示例

载荷

内容类型

application/json

{"db": "string",
"q": "string",
"chunked": true,
"chunk_size": 10000,
"epoch": "ns",
"pretty": true
}

响应示例

200
401

内容类型

{"results": [{"series": [{"name": "mytable",
"columns": ["time",
"value"
],
"values": [["2024-02-02T12:00:00Z",
42
]
]
}
]
}
]
}

写入数据

使用行协议格式将数据写入 InfluxDB 3。

写 API 的时间戳精度

InfluxDB 3 提供多个写端点以兼容不同的 InfluxDB 版本。下表比较了 v1、v2 和 v3 写 API 的时间戳精度支持。

精度	v1 (`/write`)	v2 (`/api/v2/write`)	v3 (`/api/v3/write_lp`)
自动检测	❌ 否	❌ 否	✅ `auto` (默认)
秒	✅ `s`	✅ `s`	✅ `second`
毫秒	✅ `ms`	✅ `ms`	✅ `millisecond`
微秒	✅ `u` 或 `µ`	✅ `us`	✅ `microsecond`
纳秒	✅ `ns`	✅ `ns`	✅ `nanosecond`
分钟	✅ `m`	❌ 否	❌ 否
小时	✅ `h`	❌ 否	❌ 否
默认	纳秒	纳秒	自动（猜测）

所有时间戳都存储为纳秒。

写入行协议（v1 兼容）

将行协议写入指定的数据库。

此终结点为使用 InfluxDB 1.x 客户端库、Telegraf outputs.influxdb 输出插件或第三方工具等工具的 InfluxDB 1.x 写入工作负载提供向后兼容性。

使用此终结点以行协议格式将数据发送到 InfluxDB。使用查询参数指定写入数据的选项。

使用兼容性 API 写入数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

consistency	字符串写入一致性级别。InfluxDB 3 忽略此参数。为与 InfluxDB 1.x 客户端兼容而提供。
db 必需	字符串数据库名称。如果数据库尚不存在，InfluxDB 会创建它，然后将批处理中的所有点写入该数据库。
p	字符串 v1 兼容身份验证的密码。对于查询字符串身份验证，传递管理员令牌。InfluxDB 3 验证 `p` 值是否为授权令牌。
precision 必需	字符串 (PrecisionWriteCompatibility) 枚举： "ms" "s" "us" "ns" 行协议批处理中 Unix 时间戳的精度。
rp	字符串保留策略名称。已尊重但已弃用。InfluxDB 3 不使用保留策略。
u	字符串 v1 兼容身份验证的用户名。在使用基本身份验证或查询字符串身份验证时，InfluxDB 3 会忽略此参数，但允许任何任意字符串以与 InfluxDB 1.x 客户端兼容。

标头参数

Accept	字符串默认： application/json 值： "application/json" 客户端可以理解的内容类型。写入操作只有在失败时（部分或全部）才会返回响应正文——例如，由于语法问题或类型不匹配。
Authorization	字符串用于令牌身份验证的授权标头。支持的方案 `Bearer AUTH_TOKEN` - OAuth bearer 令牌方案 `Token AUTH_TOKEN` - InfluxDB v2 令牌方案 `Basic <base64-encoded USERNAME:AUTH_TOKEN>` - 基本身份验证（用户名被忽略）
Content-Encoding	字符串 (ContentEncoding) 默认： identity 枚举： "gzip" "identity" 请求正文中的行协议所应用的压缩。要发送 gzip 载荷，请传递 `Content-Encoding: gzip` 标头。
Content-Length	整数 (ContentLength) 发送到 InfluxDB 的 entity-body 的大小（以字节为单位）。
Content-Type	字符串 (LineProtocol) 默认： text/plain; charset=utf-8 枚举： "text/plain" "text/plain; charset=utf-8" 请求正文的内容类型。

请求体架构： text/plain

字符串

响应

请求示例

载荷

内容类型

text/plain

示例

measurement,tag=value field=1 1234567890

响应示例

400
401

内容类型

application/json

示例

"{\n \"error\": \"write of line protocol failed\",\n \"data\": [\n {\n \"original_line\": \"dquote> home,room=Kitchen temp=hi\",\n \"line_number\": 2,\n \"error_message\": \"No fields were provided\"\n }\n ]\n}\n"

写入行协议（v2 兼容）

将行协议写入指定的数据库。

此终结点为使用 InfluxDB 2.x 客户端库、Telegraf outputs.influxdb_v2 输出插件或第三方工具等工具的 InfluxDB 2.x 写入工作负载提供向后兼容性。

使用此终结点以行协议格式将数据发送到 InfluxDB。使用查询参数指定写入数据的选项。

使用兼容性 API 写入数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

accept_partial	布尔值 (AcceptPartial) 默认： true 接受部分写入。
db 必需	字符串数据库名称。如果数据库尚不存在，InfluxDB 会创建它，然后将批处理中的所有点写入该数据库。
precision 必需	字符串 (PrecisionWriteCompatibility) 枚举： "ms" "s" "us" "ns" 行协议批处理中 Unix 时间戳的精度。

标头参数

Accept	字符串默认： application/json 值： "application/json" 客户端可以理解的内容类型。写入操作只有在失败时（部分或全部）才会返回响应正文——例如，由于语法问题或类型不匹配。
Content-Encoding	字符串默认： identity 枚举： "gzip" "identity" 请求正文中的行协议所应用的压缩。要发送 gzip 载荷，请传递 `Content-Encoding: gzip` 标头。
Content-Length	整数发送到 InfluxDB 的 entity-body 的大小（以字节为单位）。
Content-Type	字符串 (LineProtocol) 默认： text/plain; charset=utf-8 枚举： "text/plain" "text/plain; charset=utf-8" 请求正文的内容类型。

请求体架构： text/plain

字符串

响应

请求示例

载荷

内容类型

text/plain

示例

measurement,tag=value field=1 1234567890

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

写入行协议

将行协议写入指定的数据库。

这是原生的 InfluxDB 3 Core 写端点，它提供了增强的控制，可以通过高级参数实现高性能和容错操作。

使用此终结点以行协议格式将数据发送到 InfluxDB。使用查询参数指定写入数据的选项。

新功能

部分写入：使用 accept_partial=true 允许在批次中的某些行失败时部分成功
异步写入：使用 no_sync=true 跳过等待 WAL 持久化，可以提高响应时间，但会牺牲持久性保证
灵活精度：使用 precision=auto（默认）自动检测时间戳精度

自动精度检测

当您使用 precision=auto 或省略精度参数时，InfluxDB 3 会根据时间戳值的幅度自动检测时间戳精度

时间戳 < 5e9 → 秒精度（乘以 1,000,000,000 转换为纳秒）
时间戳 < 5e12 → 毫秒精度（乘以 1,000,000）
时间戳 < 5e15 → 微秒精度（乘以 1,000）
更大的时间戳 → 纳秒精度（无需转换）

使用 InfluxDB v3 write_lp API 写入数据

授权

Bearer 身份验证令牌身份验证基本身份验证查询字符串身份验证

查询参数

accept_partial	布尔值 (AcceptPartial) 默认： true 接受部分写入。
db 必需	字符串数据库名称。如果数据库尚不存在，InfluxDB 会创建它，然后将批处理中的所有点写入该数据库。
no_sync	boolean (NoSync) 默认： false 在不等待 WAL 持久化的情况下确认成功写入。 Related 使用 HTTP API 和客户端库写入数据数据持久性
precision 必需	string (PrecisionWrite) 枚举: "auto" "nanosecond" "microsecond" "millisecond" "second" 行协议批处理中 Unix 时间戳的精度。

标头参数

Accept	字符串默认： application/json 值： "application/json" 客户端可以理解的内容类型。写入操作只有在失败时（部分或全部）才会返回响应正文——例如，由于语法问题或类型不匹配。
Content-Encoding	字符串 (ContentEncoding) 默认： identity 枚举： "gzip" "identity" 请求正文中的行协议所应用的压缩。要发送 gzip 载荷，请传递 `Content-Encoding: gzip` 标头。
Content-Length	整数 (ContentLength) 发送到 InfluxDB 的 entity-body 的大小（以字节为单位）。
Content-Type	字符串 (LineProtocol) 默认： text/plain; charset=utf-8 枚举： "text/plain" "text/plain; charset=utf-8" 请求正文的内容类型。

请求体架构： text/plain

字符串

响应

请求示例

载荷
cURL - 基本写入
cURL - 带有毫秒精度的写入
cURL - 异步写入，支持部分接受
cURL - 带有标签的多个度量

内容类型

text/plain

示例

measurement,tag=value field=1 1234567890

响应示例

401

内容类型

application/json

{"error": "string",
"data": { }
}

InfluxDB 3 Core API 服务 (3.7.0)

快速入门

身份验证

基本身份验证

示例

相关指南

查询字符串身份验证

语法

示例

相关指南

Bearer 身份验证

语法

示例

令牌身份验证

语法

示例

相关指南

缓存数据

唯一值缓存

最后值缓存

相关指南

创建唯一值缓存

授权

请求体架构： application/json

响应

请求示例

删除唯一值缓存

授权

查询参数

响应

响应示例

创建最后值缓存

授权

请求体架构： application/json

响应

请求示例

响应示例

删除最后值缓存

授权

查询参数

响应

响应示例

兼容性终结点

使用 v1 或 v2 兼容终结点写入数据

查询数据

服务器信息

写入行协议（v1 兼容）

Related

授权

查询参数

标头参数

请求体架构： text/plain

响应

请求示例

响应示例

写入行协议（v2 兼容）

Related

授权

查询参数

标头参数

请求体架构： text/plain

响应

请求示例

响应示例

执行 InfluxQL 查询（v1 兼容）

Related

授权

查询参数

标头参数

响应

响应示例

执行 InfluxQL 查询 (v1 兼容)

Related

授权

标头参数

请求体架构： application/json

响应

请求示例

响应示例

健康检查 (v1)