# 插件：InfluxDB2时序数据库连接器

**Repository Path**: low-code-dev-lab/hzg-plugin-influxdb2

## Basic Information

- **Project Name**: 插件：InfluxDB2时序数据库连接器
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# InfluxDB2连接器服务端命令帮助文档

本文说明活字格 InfluxDB2 连接器的服务端命令用法。当前版本采用连接型调用模型：先创建连接并得到 `connectionId`，后续写入、查询和断开命令都使用该 ID 执行。

## 通用约定

- 所有命令都在服务端执行，分类为 `InfluxDB2`。
- 连接配置只在 `创建InfluxDB2连接` 命令中填写，包括 URL、Token、Org、Bucket 和超时。
- 后续操作命令只填写 `连接ID` 和本次操作参数，不再重复填写 Token、Org、Bucket。
- `Token` 建议通过服务端变量、环境变量或其他安全配置传入，不建议直接写死在命令属性中。
- `ResultTo` 是命令的主结果变量。不同命令写入的主结果类型不同，例如连接 ID、布尔值、写入数量或查询 JSON。
- `ResultJsonTo` 是可选完整结果 JSON 变量。留空时不写入。
- `SuccessTo`、`ErrorCodeTo`、`ElapsedMsTo` 是可选简单结果变量。留空时不写入。
- 完整结果 JSON 中的 `success` 表示命令是否成功，`operation` 表示操作名，`connectionId` 表示本次使用的连接 ID，`elapsedMs` 表示耗时毫秒数，`value` 表示主结果值，`data` 表示结构化数据，`error` 表示错误信息。
- 写入命令默认启用 gzip，并按批大小分批提交，默认批大小为 `5000`。

## 推荐调用流程

1. 调用 `创建InfluxDB2连接`，填写服务地址、Token、组织、Bucket。
2. 将主结果变量保存为例如 `InfluxDB2连接ID`。
3. 调用 `写入InfluxDB2行协议`、`写入InfluxDB2数据点`、`批量写入InfluxDB2数据点` 或 `查询InfluxDB2`，把 `连接ID` 设置为上一步结果变量。
4. 页面或服务端流程结束时，可调用 `断开InfluxDB2连接` 释放连接登记。

## 统一错误码

- `InvalidConfiguration`：连接配置无效，例如 URL、token、org、bucket 缺失或格式错误。
- `InvalidInput`：命令输入无效，例如 connectionId、Flux、Line Protocol、JSON 或 timestamp 无效。
- `AuthenticationFailed`：token 无效或权限不足。
- `ConnectionFailed`：无法连接 InfluxDB2 服务。
- `Timeout`：请求超时。
- `InfluxDB2Error`：InfluxDB2 返回业务错误。
- `SerializationError`：结果转换或 JSON 序列化失败。
- `ConnectionNotFound`：连接 ID 不存在或已断开，需要重新创建连接。
- `UnexpectedError`：未分类异常。

## 创建InfluxDB2连接

实际动作：

- 使用连接参数访问 InfluxDB2。
- 调用健康检查接口确认服务可访问。
- 当 `检查Bucket` 为 `true` 时，验证当前 token 是否可以访问指定 bucket。
- 当 `复用已有连接` 为 `true` 且存在相同 URL、Token、Org、Bucket、超时配置的连接时，直接返回已有 `connectionId`，并在结果中标记 `reused=true`。

传入参数：

- `服务地址`：必填。例如 `http://localhost:8086`。
- `Token`：必填。InfluxDB2 API Token。
- `组织`：必填。组织名称或 ID。
- `Bucket`：默认 Bucket。写入命令使用该 Bucket；查询命令可在 Flux 中自行指定 bucket。
- `超时时间(秒)`：默认 `30`，范围 `1` 到 `300`。
- `检查Bucket`：默认 `true`。为 `true` 时验证 bucket 是否存在且当前 token 有权访问。
- `复用已有连接`：默认 `true`。为 `true` 时允许返回已有连接。
- `连接ID`：主结果变量，默认 `InfluxDB2连接ID`。
- `是否复用`：可选。写入本次是否复用了已有连接。

返回值结构：

- `ResultTo`：连接 ID 字符串。失败时写入空字符串。
- `ReusedTo`：布尔值，表示是否复用已有连接。
- `ResultJsonTo.operation`：固定为 `createConnection`。
- `ResultJsonTo.connectionId`：连接 ID。
- `ResultJsonTo.value.connectionId`：连接 ID。
- `ResultJsonTo.value.reused`：是否复用已有连接。
- `ResultJsonTo.value.url`：InfluxDB2 服务地址。
- `ResultJsonTo.value.org`：组织名称或 ID。
- `ResultJsonTo.value.bucket`：Bucket 名称。
- `ResultJsonTo.value.status`：健康状态。
- `ResultJsonTo.value.version`：服务版本。
- `ResultJsonTo.value.bucketExists`：Bucket 是否存在且可访问，未检查时为空。

## 写入InfluxDB2行协议

实际动作：

- 通过 `连接ID` 找到已创建的连接，并将 Line Protocol 文本写入连接中的 Bucket。
- 支持单行或多行 Line Protocol。
- 可选择跳过空行。
- 按 `批大小` 分批写入，默认每批 `5000` 行。

Line Protocol 示例：

```text
temperature,device=d1,site=A value=25.3,ok=true
temperature,device=d2,site=A value=26.1
```

传入参数：

- `连接ID`：必填。由 `创建InfluxDB2连接` 返回。
- `Line Protocol`：必填。要写入的 Line Protocol 文本，可包含多行。
- `时间精度`：默认 `Ns`。可选 `Ns`、`Us`、`Ms`、`S`。
- `跳过空行`：默认 `true`。
- `批大小`：默认 `5000`，范围 `1` 到 `50000`。
- `写入行数`：主结果变量，默认 `InfluxDB2写入行数`。

返回值结构：

- `ResultTo`：写入的 Line Protocol 行数。
- `ResultJsonTo.operation`：固定为 `writeLineProtocol`。
- `ResultJsonTo.connectionId`：本次使用的连接 ID。
- `ResultJsonTo.value`：写入行数。
- `ResultJsonTo.data.lineCount`：写入行数。
- `ResultJsonTo.data.batchSize`：本次使用的批大小。
- `ResultJsonTo.data.batchCount`：实际拆分出的写入批次数。

## 写入InfluxDB2数据点

实际动作：

- 通过 `连接ID` 找到已创建的连接，使用表单化属性构造一个 point 并写入连接中的 Bucket。
- `Measurement` 指定 measurement。
- `Tags JSON` 指定 tag 集，tag 值会转换为字符串。
- `Fields JSON` 指定 field 集，至少包含一个字段。
- 可使用服务端当前时间、公式时间戳或不写入时间戳。

Tags JSON 示例：

```json
{
  "device": "d1",
  "site": "A"
}
```

Fields JSON 示例：

```json
{
  "value": 25.3,
  "ok": true,
  "count": 2,
  "note": "normal"
}
```

传入参数：

- `连接ID`：必填。由 `创建InfluxDB2连接` 返回。
- `Measurement`：必填。measurement 名称，例如 `temperature`。
- `Tags JSON`：可选。JSON 对象。
- `Fields JSON`：必填。JSON 对象，至少包含一个字段。
- `Timestamp`：可选。当 `时间戳模式` 为 `FormulaValue` 时使用。
- `时间戳模式`：默认 `ServerNow`。可选 `ServerNow`、`FormulaValue`、`None`。
- `时间精度`：默认 `Ns`。可选 `Ns`、`Us`、`Ms`、`S`。
- `字段类型`：默认 `Auto`。可选 `Auto`、`String`、`Float`、`Integer`、`Boolean`。
- `写入点数`：主结果变量，默认 `InfluxDB2写入点数`。

返回值结构：

- `ResultTo`：写入的数据点数量，单点写入固定为 `1`。
- `ResultJsonTo.operation`：固定为 `writePoint`。
- `ResultJsonTo.connectionId`：本次使用的连接 ID。
- `ResultJsonTo.value`：写入点数。
- `ResultJsonTo.data.lineProtocol`：插件根据输入生成的诊断用 Line Protocol 文本。

## 批量写入InfluxDB2数据点

实际动作：

- 通过 `连接ID` 找到已创建的连接，使用 `Points JSON` 数组一次提交多个数据点。
- 数组项可单独指定 `measurement`、`tags`、`fields`、`timestamp`。
- 数组项未指定 `measurement` 时，使用命令级 `默认Measurement`。
- 命令级 `默认Tags JSON` 会合并到每个数据点，数组项中的同名 tag 会覆盖默认 tag。
- 按 `批大小` 分批写入，默认每批 `5000` 个数据点。

Points JSON 示例：

```json
[
  {
    "measurement": "temperature",
    "tags": {
      "device": "d1",
      "site": "A"
    },
    "fields": {
      "value": 25.3
    },
    "timestamp": "2026-06-11T04:00:00Z"
  },
  {
    "tags": {
      "device": "d2"
    },
    "fields": {
      "value": 26.1,
      "ok": true
    }
  }
]
```

传入参数：

- `连接ID`：必填。由 `创建InfluxDB2连接` 返回。
- `默认Measurement`：可选。数组项未提供 `measurement` 时使用。
- `默认Tags JSON`：可选。JSON 对象，作为每个数据点的默认 tag。
- `Points JSON`：必填。JSON 数组，每一项必须包含 `fields` 对象。
- `时间戳模式`：默认 `ServerNow`。可选 `ServerNow`、`FormulaValue`、`None`。
- `时间精度`：默认 `Ns`。可选 `Ns`、`Us`、`Ms`、`S`。
- `字段类型`：默认 `Auto`。可选 `Auto`、`String`、`Float`、`Integer`、`Boolean`。
- `批大小`：默认 `5000`，范围 `1` 到 `50000`。
- `写入点数`：主结果变量，默认 `InfluxDB2批量写入点数`。

返回值结构：

- `ResultTo`：写入的数据点数量。
- `ResultJsonTo.operation`：固定为 `writePoints`。
- `ResultJsonTo.connectionId`：本次使用的连接 ID。
- `ResultJsonTo.value`：写入点数。
- `ResultJsonTo.data.pointCount`：写入点数。
- `ResultJsonTo.data.batchSize`：本次使用的批大小。
- `ResultJsonTo.data.batchCount`：实际拆分出的写入批次数。

## 查询InfluxDB2

实际动作：

- 通过 `连接ID` 找到已创建的连接并执行 Flux 查询语句。
- 查询结果会转换为 JSON 行对象。
- 可限制最大返回行数，避免大结果写入活字格变量。
- 可选择是否保留 Flux 元数据列。
- 主结果变量支持写入 JSON 数组或完整包装结果。

Flux 示例：

```flux
from(bucket: "telemetry")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "temperature")
```

传入参数：

- `连接ID`：必填。由 `创建InfluxDB2连接` 返回。
- `Flux查询`：必填。Flux 查询语句。通常在语句中使用 `from(bucket:"bucketName")` 指定 Bucket。
- `最大返回行数`：默认 `1000`，范围 `1` 到 `100000`。
- `包含元数据列`：默认 `false`。为 `true` 时保留 `result`、`table` 等列。
- `结果格式`：默认 `JsonArray`。可选 `JsonArray`、`WrappedResult`。
- `查询结果`：主结果变量，默认 `InfluxDB2查询结果`。
- `行数`：可选。行数变量名。

返回值结构：

- `ResultTo`：查询结果 JSON 字符串。
- 当 `结果格式` 为 `JsonArray` 时，`ResultTo` 是行对象数组 JSON。
- 当 `结果格式` 为 `WrappedResult` 时，`ResultTo` 是完整结果 JSON。
- 查询失败时，`ResultTo` 写入 `[]`。
- `RowCountTo`：实际返回行数；失败时写入 `0`。
- `ResultJsonTo.operation`：固定为 `queryFlux`。
- `ResultJsonTo.connectionId`：本次使用的连接 ID。
- `ResultJsonTo.value.rows`：查询结果行数组。
- `ResultJsonTo.value.rowCount`：查询结果行数。
- `ResultJsonTo.value.truncated`：是否因 `最大返回行数` 被截断。

`JsonArray` 返回示例：

```json
[
  {
    "_time": "2026-06-11T04:00:00Z",
    "_measurement": "temperature",
    "_field": "value",
    "_value": 25.3,
    "device": "d1"
  }
]
```

## 断开InfluxDB2连接

实际动作：

- 通过 `连接ID` 删除插件服务端内的连接登记。
- 断开后，再使用该 ID 写入或查询会返回 `ConnectionNotFound`。

传入参数：

- `连接ID`：必填。由 `创建InfluxDB2连接` 返回。
- `断开成功`：主结果变量，默认 `InfluxDB2断开成功`。

返回值结构：

- `ResultTo`：布尔值。断开成功为 `true`。
- `ResultJsonTo.operation`：固定为 `disconnect`。
- `ResultJsonTo.connectionId`：断开的连接 ID。
- `ResultJsonTo.value`：布尔值，表示是否断开成功。

## 使用建议

- 写入高频数据时，优先使用 `写入InfluxDB2行协议` 或 `批量写入InfluxDB2数据点`。
- `复用已有连接` 默认开启，适合多个流程复用同一 InfluxDB2 配置；如果需要强制拿到新的连接 ID，可关闭复用。
- `批大小` 默认 `5000`，通常不需要修改；如果单点很大或网络不稳定，可以适当调小。
- 时间精度建议选择业务所需的最粗粒度，例如秒级数据使用 `S`，毫秒级数据使用 `Ms`。
- tag 适合放设备、位置、类型等低到中等基数的维度；field 适合放实际数值。
- Flux 查询必须有时间范围，通常使用 `range(start: -1h)` 之类的范围限制。
- 查询结果较大时，设置合理的 `最大返回行数`，并通过 `truncated` 判断是否被截断。

## 参考资料

- [InfluxDB OSS v2 Line Protocol](https://docs.influxdata.com/influxdb/v2/reference/syntax/line-protocol/)
- [Flux Documentation](https://docs.influxdata.com/flux/v0/)
- [Query InfluxDB with Flux](https://docs.influxdata.com/flux/v0/query-data/influxdb/)
- [InfluxDB OSS v2 Documentation](https://docs.influxdata.com/influxdb/v2/)