551 lines
14 KiB
Markdown
551 lines
14 KiB
Markdown
# IntegrationGateway B 组接口文档
|
||
|
||
> **版本**: 1.0
|
||
> **日期**: 2026-06-04
|
||
> **基址**: `http://{host}:{port}`（默认 `http://localhost:5100`）
|
||
> **内容类型**: `application/json`（除标注外）
|
||
> **认证**: 可选 `X-Gateway-Key` 请求头（与 Gateway 段配置一致时生效）
|
||
> **通用错误码**: 见 §5
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [健康检查](#1-健康检查) — B1
|
||
2. [设备管理](#2-设备管理) — B2, B3, B3-sync
|
||
3. [视频与流媒体](#3-视频与流媒体) — B6a, B6b, 截图, B7
|
||
4. [IoT 实时数据](#4-iot-实时数据) — B4, B4-batch, B5
|
||
5. [告警管理](#5-告警管理) — B8, B9-confirm, B9-end
|
||
6. [录像查询](#6-录像查询)
|
||
7. [设备控制 (通用)](#7-设备控制-通用) — B10
|
||
8. [业务记录查询](#8-业务记录查询) — B11
|
||
9. [数据同步](#9-数据同步) — B12, B13
|
||
10. [错误代码](#10-错误代码)
|
||
|
||
---
|
||
|
||
## 1. 健康检查
|
||
|
||
### B1: 查询所有适配器健康状态
|
||
|
||
```
|
||
GET /api/gateway/health
|
||
```
|
||
|
||
**请求参数**: 无
|
||
|
||
**返回参数**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `[].adapterCode` | string | 适配器编码，如 `Owl:main`、`MC4:31ku`、`KMS:main` |
|
||
| `[].displayName` | string | 人类可读的适配器名称 |
|
||
| `[].healthy` | bool | `true` = 适配器在线，`false` = 离线或不可达 |
|
||
| `[].capabilities` | object | 适配器能力声明 |
|
||
|
||
**capabilities 字段**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `hasFlatDevices` | bool | 是否支持扁平设备列表 |
|
||
| `hasOwnDeviceTree` | bool | 是否支持层级对象树 |
|
||
| `hasStreams` | bool | 是否支持视频取流 |
|
||
| `hasPoints` | bool | 是否支持 IoT 实时点位 |
|
||
| `hasAlarms` | bool | 是否支持告警查询 |
|
||
| `hasRecordings` | bool | 是否支持录像查询 |
|
||
|
||
**返回示例**:
|
||
```json
|
||
[
|
||
{
|
||
"adapterCode": "Owl:main",
|
||
"displayName": "Owl (Owl:main)",
|
||
"healthy": true,
|
||
"capabilities": { "hasFlatDevices": true, "hasStreams": true, "hasAlarms": true, "hasRecordings": true }
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 设备管理
|
||
|
||
### B2: 分页获取扁平设备列表
|
||
|
||
```
|
||
GET /api/gateway/devices?adapter={adapterCode}&page={page}&size={size}&keyword={keyword}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|:--:|------|------|
|
||
| `adapter` | string | ✅ | — | 适配器编码，如 `Owl:main` |
|
||
| `page` | int | ❌ | 1 | 页码（从 1 开始） |
|
||
| `size` | int | ❌ | 20 | 每页条数 |
|
||
| `keyword` | string | ❌ | null | 设备名称模糊搜索 |
|
||
|
||
**返回参数**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `items` | array | 设备列表 |
|
||
| `total` | int | 总设备数 |
|
||
|
||
**items[].StandardDevice**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `sourceId` | string | 子系统设备原始 ID |
|
||
| `name` | string | 设备名称 |
|
||
| `category` | string | 设备种类（如 `硬盘录像机`、`摄像头`、`智能钥匙柜`、`钥匙位`） |
|
||
| `group` | string | 设备分组（`视频设备`/`IoT设备`/`门禁设备`） |
|
||
| `isParent` | bool | 是否父设备（含下级子设备） |
|
||
| `parentSourceId` | string? | 上级设备 SourceId |
|
||
| `isOnline` | bool | 是否在线 |
|
||
| `ipAddress` | string? | IP 地址 |
|
||
| `port` | int? | 端口号 |
|
||
| `extra` | object? | 子系统特有扩展属性 |
|
||
|
||
**返回示例**:
|
||
```json
|
||
{
|
||
"items": [
|
||
{ "sourceId": "locker_25", "name": "10位智能公共钥匙柜", "category": "智能钥匙柜", "group": "门禁设备", "isParent": true, "isOnline": true },
|
||
{ "sourceId": "lockhole_25_1", "name": "仓库大门钥匙", "category": "钥匙位", "group": "门禁设备", "isParent": false, "isOnline": true, "parentSourceId": "locker_25" }
|
||
],
|
||
"total": 11
|
||
}
|
||
```
|
||
|
||
### B3: 获取层级对象树
|
||
|
||
```
|
||
GET /api/gateway/tree?adapter={adapterCode}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码，如 `MC4:31ku` |
|
||
|
||
**返回参数**: `DeviceTreeNode[]`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `sourceId` | string | 节点 ID |
|
||
| `name` | string | 节点名称 |
|
||
| `tag` | string | 节点标签（如 `区域`/`设备组`/`IoT设备`） |
|
||
| `type` | int | 节点类型：1=父节点, 0=叶子节点 |
|
||
| `children` | array | 子节点列表（递归） |
|
||
| `option` | object? | 扩展配置 |
|
||
|
||
### B3-sync: 手动触发设备同步
|
||
|
||
```
|
||
POST /api/gateway/devices/sync?adapter={adapterCode}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
|
||
**返回参数**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `deviceCount` | int | 同步设备数（扁平设备） |
|
||
| `nodeCount` | int | 同步节点数（对象树） |
|
||
| `message` | string | 同步结果描述 |
|
||
|
||
---
|
||
|
||
## 3. 视频与流媒体
|
||
|
||
### B6a: 获取实时流地址
|
||
|
||
```
|
||
GET /api/gateway/streams/{adapter}/{deviceId}/live
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码，如 `Owl:main` |
|
||
| `deviceId` | string | ✅ | 通道 SourceId |
|
||
|
||
**返回参数 (StreamUrls)**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `wsFlv` | string? | WebSocket-FLV 地址（推荐，低延迟） |
|
||
| `httpFlv` | string? | HTTP-FLV 地址 |
|
||
| `hls` | string? | HLS (m3u8) 地址 |
|
||
| `webrtc` | string? | WebRTC 地址 |
|
||
| `rtmp` | string? | RTMP 地址 |
|
||
|
||
### B6b: 获取录像回放地址
|
||
|
||
```
|
||
GET /api/gateway/streams/{adapter}/{deviceId}/playback?start={start}&end={end}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
| `deviceId` | string | ✅ | 通道 SourceId |
|
||
| `start` | DateTime | ✅ | 回放起始时间 (ISO 8601) |
|
||
| `end` | DateTime | ✅ | 回放结束时间 (ISO 8601) |
|
||
|
||
**返回**: 同 `StreamUrls`
|
||
|
||
### 截图: 获取通道实时截图
|
||
|
||
```
|
||
POST /api/gateway/streams/{adapter}/{deviceId}/snapshot
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
| `deviceId` | string | ✅ | 通道 SourceId |
|
||
|
||
**返回**: JPEG 图片 Base64 或 URL
|
||
|
||
### B7: 云台控制
|
||
|
||
```
|
||
POST /api/gateway/streams/{adapter}/{deviceId}/ptz
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
| `deviceId` | string | ✅ | 通道 SourceId |
|
||
|
||
**请求体 (PtzRequest)**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `direction` | string | ❌ | 方向：`up`/`down`/`left`/`right`/`zoom_in`/`zoom_out` |
|
||
| `action` | string | ✅ | 动作：`continuous`(持续)/`stop`(停止)/`preset`/`patrol` |
|
||
| `speed` | float | ❌ | 速度 (0.1~1.0)，默认 0.5 |
|
||
|
||
---
|
||
|
||
## 4. IoT 实时数据
|
||
|
||
### B4: 获取设备实时点位值
|
||
|
||
```
|
||
GET /api/gateway/realtime/{adapter}/{deviceId}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码，如 `MC4:31ku` |
|
||
| `deviceId` | string | ✅ | 设备 SourceId |
|
||
|
||
**返回参数**: `PointValue[]`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `pointIndex` | int | 点位索引 |
|
||
| `pointName` | string | 点位名称 |
|
||
| `value` | decimal | 当前值 |
|
||
| `unit` | string? | 单位（如 `℃`、`%`） |
|
||
| `updateTime` | DateTime | 更新时间 |
|
||
| `interval` | int | 采集间隔（秒） |
|
||
|
||
### B4-batch: 批量获取实时点位值
|
||
|
||
```
|
||
POST /api/gateway/realtime/{adapter}/batch
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
|
||
**请求体 (BatchRealtimeRequest)**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `deviceIds` | string[] | ✅ | 设备 SourceId 列表 |
|
||
|
||
**返回**: `Dictionary<string, PointValue[]>` — 以 deviceId 为键的实时值字典
|
||
|
||
### B5: 设备反向控制
|
||
|
||
```
|
||
POST /api/gateway/realtime/{adapter}/control
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
|
||
**请求体 (ControlRequest)**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `deviceId` | string | ✅ | 设备 SourceId |
|
||
| `pointIndex` | int | ✅ | 目标点位索引 |
|
||
| `value` | double | ✅ | 目标值（如开关 0/1，温度设定值等） |
|
||
|
||
---
|
||
|
||
## 5. 告警管理
|
||
|
||
### B8: 分页查询告警列表
|
||
|
||
```
|
||
GET /api/gateway/alarms/{adapter}?page={page}&size={size}&from={from}&to={to}&level={level}&state={state}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|:--:|------|------|
|
||
| `adapter` | string | ✅ | — | 适配器编码 |
|
||
| `page` | int | ❌ | 1 | 页码 |
|
||
| `size` | int | ❌ | 20 | 每页条数 |
|
||
| `from` | DateTime | ❌ | MinValue | 告警起始时间 |
|
||
| `to` | DateTime | ❌ | MinValue | 告警结束时间 |
|
||
| `level` | string | ❌ | null | 告警等级过滤 |
|
||
| `state` | string | ❌ | null | 告警状态过滤：`未确认`/`已确认`/`已结束` |
|
||
|
||
**返回参数**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `items` | array | 告警列表 |
|
||
| `total` | int | 总告警数 |
|
||
|
||
**items[].StandardAlarm**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `alarmId` | string | 告警 ID |
|
||
| `adapterCode` | string | 适配器编码 |
|
||
| `deviceId` | string? | 关联设备 ID |
|
||
| `level` | string | 告警等级：`提示`/`普通`/`重要`/`紧急` |
|
||
| `title` | string | 告警标题 |
|
||
| `content` | string? | 告警详细内容 |
|
||
| `occurTime` | DateTime | 发生时间 |
|
||
| `status` | string | 状态：`未确认`/`已确认`/`已结束` |
|
||
| `actualValue` | string? | 实际值（超标告警） |
|
||
| `thresholdValue` | string? | 阈值（超标告警） |
|
||
|
||
### B9-confirm: 确认告警
|
||
|
||
```
|
||
POST /api/gateway/alarms/{adapter}/{alarmId}/confirm
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
| `alarmId` | string | ✅ | 告警 ID（子系统告警源 ID） |
|
||
|
||
### B9-end: 结束告警
|
||
|
||
```
|
||
POST /api/gateway/alarms/{adapter}/{alarmId}/end
|
||
```
|
||
|
||
**请求参数**: 同 B9-confirm
|
||
|
||
---
|
||
|
||
## 6. 录像查询
|
||
|
||
```
|
||
GET /api/gateway/recordings/{adapter}/{deviceId}?start={start}&end={end}&page={page}&size={size}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
| `deviceId` | string | ✅ | 通道 SourceId |
|
||
| `start` | DateTime | ✅ | 录像起始时间 |
|
||
| `end` | DateTime | ✅ | 录像结束时间 |
|
||
| `page` | int | ❌ | 页码，默认 1 |
|
||
| `size` | int | ❌ | 每页条数，默认 20 |
|
||
|
||
**返回**: 录像文件列表（含文件名、起止时间、时长、大小）
|
||
|
||
---
|
||
|
||
## 7. 设备控制 (通用)
|
||
|
||
### B10: 下发控制指令
|
||
|
||
```
|
||
POST /api/gateway/control/{adapter}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码，如 `KMS:main` |
|
||
|
||
**请求体 (GatewayControlRequest)**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `deviceId` | string | ✅ | 设备 SourceId |
|
||
| `command` | string | ✅ | 指令名：`open`(开门)/`close`(关门)/`authorize`(授权) |
|
||
| `parameters` | object | ❌ | 指令参数，如 `{"staffIds": [1,2], "lockholeSort": 3}` |
|
||
|
||
**返回 (ControlResult)**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `success` | bool | 操作是否成功 |
|
||
| `message` | string? | 失败时的错误信息 |
|
||
|
||
---
|
||
|
||
## 8. 业务记录查询
|
||
|
||
### B11: 查询子系统业务记录
|
||
|
||
```
|
||
GET /api/gateway/logs/{adapter}?logType={logType}&from={from}&to={to}&page={page}&size={size}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
| `logType` | string | ✅ | 记录类型：`borrow`(借还)/`handover`(交接)/`permission`(授权) |
|
||
| `from` | DateTime | ❌ | 起始时间 |
|
||
| `to` | DateTime | ❌ | 结束时间 |
|
||
| `page` | int | ❌ | 页码，默认 1 |
|
||
| `size` | int | ❌ | 每页条数，默认 20 |
|
||
|
||
**返回参数**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `items` | array | 业务记录列表 |
|
||
| `total` | int | 总记录数 |
|
||
|
||
**items[].BusinessLogEntry**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `logId` | string | 记录唯一 ID |
|
||
| `logType` | string | 记录类型 |
|
||
| `deviceSourceId` | string? | 关联设备 SourceId |
|
||
| `staffName` | string? | 关联员工姓名 |
|
||
| `description` | string? | 记录描述 |
|
||
| `createdAt` | DateTime? | 记录时间 |
|
||
| `extra` | object? | 扩展属性 |
|
||
|
||
---
|
||
|
||
## 9. 数据同步
|
||
|
||
### B12: 向子系统写入数据
|
||
|
||
```
|
||
POST /api/gateway/sync/{adapter}
|
||
```
|
||
|
||
**请求参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `adapter` | string | ✅ | 适配器编码 |
|
||
|
||
**请求体 (SyncRequest)**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `dataType` | string | ✅ | 数据类型，当前支持 `staff`（员工） |
|
||
| `items` | object[] | ✅ | 待同步数据列表 |
|
||
|
||
**返回 (SyncResult)**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `successCount` | int | 成功数量 |
|
||
| `failCount` | int | 失败数量 |
|
||
| `message` | string? | 错误信息 |
|
||
|
||
### B13: 从子系统删除数据
|
||
|
||
```
|
||
DELETE /api/gateway/sync/{adapter}
|
||
```
|
||
|
||
**请求参数**: 同 B12
|
||
|
||
**请求体 (SyncDeleteRequest)**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `dataType` | string | ✅ | 数据类型，当前支持 `staff` |
|
||
| `ids` | string[] | ✅ | 待删除 ID 列表 |
|
||
|
||
**返回**: 同 `SyncResult`
|
||
|
||
---
|
||
|
||
## 10. 错误代码
|
||
|
||
### 通用 HTTP 状态码
|
||
|
||
| 状态码 | 含义 | 触发条件 |
|
||
|:---:|------|------|
|
||
| 200 | OK | 请求成功 |
|
||
| 400 | Bad Request | 请求参数格式错误 |
|
||
| 401 | Unauthorized | `X-Gateway-Key` 缺失或不匹配 |
|
||
| 404 | Not Found | 适配器不存在或不支持该能力 |
|
||
| 500 | Internal Server Error | 适配器内部异常 |
|
||
| 502 | Bad Gateway | 子系统返回错误或不可达 |
|
||
|
||
### 业务错误码
|
||
|
||
所有非 200 响应包含 JSON body：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `error` | string | 错误码 |
|
||
| `message` | string? | 人类可读的错误详情 |
|
||
|
||
| error 值 | HTTP | 说明 |
|
||
|------|:---:|------|
|
||
| `ADAPTER_NOT_FOUND` | 404 | 指定适配器编码不存在 |
|
||
| `CAPABILITY_NOT_SUPPORTED` | 404 | 适配器不支持该接口能力 |
|
||
| — (control 接口) | 502 | `ControlResult.Success=false` 时返回 `ControlResult.Message` |
|
||
|
||
---
|
||
|
||
> **接口总数**: 19 个 REST 端点
|
||
> **适配器**: Owl / MC4 / KMS（通过 `adapter` 参数路由）
|