# 插件：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-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

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

## 通用约定

- 所有命令都在服务端执行，分类为 `InfluxDB2 连接器`。
- 命令显示名统一为 `InfluxDB2 xx`，例如 `InfluxDB2 连接`、`InfluxDB2 执行Flux查询`、`InfluxDB2 高级查询`。
- 命令列表中是否追加输出变量名，取决于一个默认为空且必填的主属性：连接命令看 `服务地址`，其他命令看 `连接ID`。主属性为空时只显示命令名，非空时显示 `InfluxDB2 xx：输出变量`。
- 连接配置只在 `InfluxDB2 连接` 命令中填写，包括服务地址、访问令牌、组织、存储桶和超时。
- 后续操作命令只填写 `连接ID` 和本次操作参数，不再重复填写访问令牌、组织、存储桶。
- 每个命令只有一个返回值属性，主结果变量都是对象，并通过 `IServerCommandParamGenerator` 定义 schema。
- 必填项在下方参数表中标记为“必填”，代码中同步使用 `[Required]`。
- 插件目标框架为 `.NET 8`，官方 InfluxDB C# 客户端固定使用 `InfluxDB.Client 4.18.0`。
- `访问令牌` 建议通过服务端变量、环境变量或其他安全配置传入，不建议直接写死在命令属性中。

## 推荐调用流程

1. 调用 `InfluxDB2 连接`，填写必填连接参数。
2. 从连接结果对象读取 `connectionId`，例如 `InfluxDB2连接结果.connectionId`。
3. 调用写入、查询或断开命令，把 `连接ID` 设置为上一步得到的 `connectionId`。
4. 页面或服务端流程结束时，可调用 `InfluxDB2 断开连接` 删除连接登记。

## 结果对象

所有命令的结果对象都包含：

| 字段 | 说明 |
| --- | --- |
| `success` | 命令是否执行成功。 |
| `errCode` | 统一错误码，`0` 表示成功。 |
| `message` | 错误或状态消息，成功时为空字符串。 |
| `elapsedMs` | 命令耗时，单位毫秒。 |

连接命令额外返回：

| 字段 | 说明 |
| --- | --- |
| `connectionId` | 连接唯一标识，后续命令使用该值。 |
| `reused` | 是否复用了已有连接。 |

写入和查询命令额外返回 `value`。断开命令没有业务返回值，因此不返回 `value`。

连接失败示例：

```json
{"success":false,"errCode":1101,"message":"Could not connect to InfluxDB2.","elapsedMs":0,"connectionId":"","reused":false}
```

## 错误码

| 错误码 | 含义 |
| --- | --- |
| `0` | 成功。 |
| `1001` | 参数缺失、格式错误或连接配置无效。 |
| `1100` | 连接不存在或已断开。 |
| `1101` | 连接失败、认证失败或权限不足。 |
| `1200` | 请求超时。 |
| `1300` | InfluxDB2 返回业务错误。 |
| `1400` | JSON 或数据类型转换错误。 |
| `5000` | 未分类异常。 |

## InfluxDB2 连接

默认输出变量：`InfluxDB2连接结果`

传入参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `服务地址` | 是 | InfluxDB2 服务地址，例如 `http://localhost:8086`。 |
| `访问令牌` | 是 | InfluxDB2 API Token。 |
| `组织` | 是 | 组织名称或 ID。 |
| `存储桶` | 是 | 默认 Bucket。写入命令和高级查询命令使用该 Bucket。 |
| `超时时间(秒)` | 否 | 默认 `30`，范围 `1` 到 `300`。 |
| `检查存储桶` | 否 | 默认 `true`。为 `true` 时验证 bucket 是否存在且当前 token 有权访问。 |
| `复用已有连接` | 否 | 默认 `true`。配置相同且已有连接时返回已有 `connectionId`。 |
| `连接结果` | 是 | 保存结构化连接结果的变量名。 |

结果对象字段：`success`、`errCode`、`message`、`elapsedMs`、`connectionId`、`reused`。

## InfluxDB2 写入行协议

默认输出变量：`InfluxDB2行协议写入结果`

传入参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `连接ID` | 是 | 由连接结果对象的 `connectionId` 提供。 |
| `行协议` | 是 | 要写入的 Line Protocol 文本，可包含多行。 |
| `时间精度` | 否 | 默认 `纳秒`，可选 `纳秒`、`微秒`、`毫秒`、`秒`。 |
| `跳过空行` | 否 | 默认 `true`。 |
| `批大小` | 否 | 默认 `5000`，范围 `1` 到 `50000`。 |
| `写入结果` | 是 | 保存结构化写入结果的变量名。 |

Line Protocol 示例：

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

结果对象字段：通用字段和 `value`。`value` 为写入的 Line Protocol 行数。

## InfluxDB2 写入数据点

默认输出变量：`InfluxDB2单点写入结果`

传入参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `连接ID` | 是 | 由连接结果对象的 `connectionId` 提供。 |
| `数据表名` | 是 | measurement 名称，例如 `temperature`。 |
| `标签` | 否 | 点击弹窗设置 tag 列表，每项包含标签名和标签值。 |
| `字段` | 是 | 点击弹窗设置 field 列表，每项包含字段名和字段值，至少需要一项。 |
| `使用服务器时间` | 否 | 默认勾选。勾选时由 InfluxDB2 写入服务器当前时间，并隐藏 `时间戳` 输入框。 |
| `时间戳` | 否 | 取消勾选 `使用服务器时间` 时显示并使用，支持日期时间、Unix 时间戳数字或可解析的日期字符串。 |
| `时间精度` | 否 | 默认 `纳秒`，可选 `纳秒`、`微秒`、`毫秒`、`秒`。 |
| `字段类型` | 否 | 默认 `自动识别`，可选 `自动识别`、`字符串`、`浮点数`、`整数`、`布尔值`。 |
| `写入结果` | 是 | 保存结构化单点写入结果的变量名。 |

结果对象字段：通用字段和 `value`。`value` 为写入的数据点数量，单点写入固定为 `1`。

## InfluxDB2 执行Flux查询

默认输出变量：`InfluxDB2Flux查询结果`

适合需要完整控制 Flux 语句的场景。Bucket 由 Flux 中的 `from(bucket:"...")` 指定。

传入参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `连接ID` | 是 | 由连接结果对象的 `connectionId` 提供。 |
| `Flux查询语句` | 是 | 要执行的 Flux 查询语句。 |
| `最大返回行数` | 否 | 默认 `1000`，范围 `1` 到 `100000`。 |
| `包含元数据列` | 否 | 默认 `false`。 |
| `结果格式` | 否 | 默认 `数组对象`；`查询明细` 会返回包含 `rows`、`rowCount`、`truncated` 的对象。 |
| `查询结果` | 是 | 保存结构化查询结果的变量名。 |

Flux 示例：

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

结果对象字段：通用字段和 `value`。默认 `数组对象` 格式下，`value` 为查询结果行数组；选择 `查询明细` 时，`value` 为包含 `rows`、`rowCount`、`truncated` 的对象。

## InfluxDB2 高级查询

默认输出变量：`InfluxDB2高级查询结果`

适合不想手写完整 Flux 的常见读取和统计场景。命令会使用连接中的默认 Bucket 自动生成 Flux。

传入参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `连接ID` | 是 | 由连接结果对象的 `connectionId` 提供。 |
| `数据表名` | 是 | 要查询的 measurement 名称。 |
| `属性查询条件` | 否 | 属性查询条件列表。每项包含属性名、比较方式和属性值；多项之间固定为 AND 关系，暂不支持 OR。常见属性名包括 `_field`、`_value` 和 tag 名。 |
| `开始时间` | 是 | Flux `range` 的 `start`，默认 `-1h`；支持 `-1h`、`now()`、ISO 日期时间。 |
| `结束时间` | 否 | Flux `range` 的 `stop`；留空使用 InfluxDB2 默认结束时间。 |
| `统计方式` | 否 | 默认 `不统计`；可选 `计数`、`平均值`、`求和`、`最小值`、`最大值`、`第一个值`、`最后一个值`、`中位数`、`众数`、`标准差`、`极差`、`唯一记录`。选择 `唯一记录` 时按 `_time` 升序后执行 `unique(column: "_value")`，同一 `_value` 保留首次出现记录，因此 `_time` 为首次出现时间。 |
| `统计窗口` | 否 | 例如 `1m`、`5m`、`1h`；设置后使用 `aggregateWindow`。`唯一记录` 不支持窗口统计，会忽略该设置。 |
| `最大返回行数` | 否 | 默认 `1000`，范围 `1` 到 `100000`。 |
| `包含元数据列` | 否 | 默认 `false`。 |
| `结果格式` | 否 | 默认 `数组对象`，可选 `数组对象`、`查询明细`。 |
| `查询结果` | 是 | 保存结构化查询结果的变量名。 |

比较方式支持（下拉框按以下顺序成对排列）：

| 类型 | 比较方式 |
| --- | --- |
| 等值 | 等于、不等于 |
| 列表 | 在列表中、不在列表中；属性值可填写 JSON 数组，如 `["ok","warn"]`，也可填写逗号分隔文本，如 `ok,warn` |
| 正则 | 匹配正则、不匹配正则 |
| 字符串包含 | 包含字符串、不包含字符串 |
| 字符串前缀 | 开头是、开头不是 |
| 字符串后缀 | 结尾是、结尾不是 |
| 存在性 | 存在、不存在；这两种不需要填写属性值 |
| 数值比较 | 大于、大于等于、小于、小于等于 |

`属性查询条件` 列表示例：

| 属性名 | 比较方式 | 属性值 |
| --- | --- | --- |
| `_field` | 等于 | `value` |
| `device` | 等于 | `d1` |
| `_value` | 大于等于 | `20` |
| `status` | 在列表中 | `ok,warn` |
| `location` | 存在 | 留空 |

以上条件会按 AND 关系生成类似 Flux：

```flux
from(bucket:"telemetry")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "temperature")
  |> filter(fn: (r) => r["_field"] == "value")
  |> filter(fn: (r) => r["device"] == "d1")
  |> filter(fn: (r) => r["_value"] >= 20)
  |> filter(fn: (r) => contains(value: r["status"], set: ["ok", "warn"]))
  |> filter(fn: (r) => exists r["location"])
```

结果对象字段：通用字段和 `value`。默认 `数组对象` 格式下，`value` 为查询结果行数组；选择 `查询明细` 时，`value` 为包含 `rows`、`rowCount`、`truncated` 的对象。

## InfluxDB2 断开连接

默认输出变量：`InfluxDB2断开结果`

传入参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `连接ID` | 是 | 要断开的连接 ID。 |
| `断开结果` | 是 | 保存结构化断开结果的变量名。 |

结果对象字段：`success`、`errCode`、`message`、`elapsedMs`。断开命令没有业务返回值，不返回 `value`。

## 使用建议

- 写入高频数据时，优先使用 `InfluxDB2 写入行协议`，一次传入多行 Line Protocol 并通过 `批大小` 分批提交。
- `复用已有连接` 默认开启，适合多个流程复用同一 InfluxDB2 配置；如果需要强制拿到新的连接 ID，可关闭复用。
- `批大小` 默认 `5000`，通常不需要修改；如果单点很大或网络不稳定，可以适当调小。
- 时间精度建议选择业务所需的最粗粒度，例如秒级数据使用 `S`，毫秒级数据使用 `Ms`。
- tag 适合放设备、位置、类型等低到中等基数的维度；field 适合放实际数值。
- 查询必须有时间范围；高级查询默认使用 `-1h`，原始 Flux 查询需要在语句中自行写 `range`。

## 参考资料

- [InfluxDB OSS v2 Line Protocol](https://docs.influxdata.com/influxdb/v2/reference/syntax/line-protocol/)
- [InfluxDB 写入最佳实践](https://docs.influxdata.com/influxdb/v2/write-data/best-practices/)
- [Flux Documentation](https://docs.influxdata.com/flux/v0/)
- [Query InfluxDB with Flux](https://docs.influxdata.com/flux/v0/query-data/influxdb/)