网关 API 文档

本文档描述 ThingsGatewayRuntime 网关提供的 RESTful API 接口。

基础信息

项目	说明
基础URL	http://{"{ip}"}:{"{port}"}
默认端口	6100
数据格式	JSON
字符编码	UTF-8
认证方式	Bearer Token (JWT)，Token有效期默认15天（可通过JWTOptions.ExpiredTime配置，单位分钟）

统一响应格式

所有 API 接口均返回统一的响应格式：

字段	类型	说明
code	number	状态码，200 表示成功
data	object	返回数据
msg	string	返回消息
time	string	服务器响应时间

认证接口

登录

POST /api/GatewayAuthService/Login

请求参数：

参数	类型	说明
Name	string	用户名
Password	string	密码

返回数据：

字段	类型	说明
Token	string	JWT Token
Name	string	用户名
UserId	string	用户ID
RoleId	number	角色ID
IsSuperAdmin	boolean	是否超级管理员
Permissions	object	用户权限信息

请求示例：

{
  "Name": "admin",
  "Password": "123456"
}

返回示例：

{
  "code": 200,
  "data": {
    "Token": "eyJhbGciOiJIUzI1NiIs...",
    "Name": "admin",
    "UserId": "1",
    "RoleId": 1,
    "IsSuperAdmin": true,
    "Permissions": {
      "IsSuperAdmin": true,
      "MenuIds": [1, 2, 3],
      "ButtonIds": [1, 2],
      "ButtonCodes": ["add", "edit"]
    }
  },
  "msg": "success",
  "time": "2024-01-01T00:00:00"
}

刷新Token

POST /api/GatewayAuthService/RefreshToken

请求头：

头部	说明
Authorization	Bearer {"{token}"}

获取用户权限

POST /api/GatewayAuthService/GetUserPermissions

请求头：

头部	说明
Authorization	Bearer {"{token}"}

数据接口

获取通道设备统计

GET /api/GatewayDataService/GetGatewayTotal

请求头：

头部	说明
Authorization	Bearer {"{token}"}

返回数据：

字段	类型	说明
ChannelTotal	number	通道总数
ChannelEnable	number	启用通道数
ChannelDisable	number	禁用通道数
DeviceTotal	number	设备总数
DeviceOnline	number	在线设备数
DeviceNotOnline	number	离线设备数
VariableTotal	number	变量总数
VariableNormal	number	正常变量数
VariableAbnormal	number	异常变量数
AlarmVariableTotal	number	报警变量总数
AlarmTotal	number	报警数量
FinishTotal	number	已完成数量

获取通道设备树

GET /api/GatewayDataService/GetChannelDeviceTree

请求参数：

参数	类型	说明
key	string	搜索关键字（可选）
deviceOnline	boolean	设备在线状态过滤（可选）

请求头：

头部	说明
Authorization	Bearer {"{token}"}

返回数据： 通道设备树形结构数组

获取通道详情

GET /api/GatewayDataService/GetChannel

请求参数：

参数	类型	说明
id	number	通道ID

请求头：

头部	说明
Authorization	Bearer {"{token}"}

返回数据： 通道详情对象

获取变量状态分页列表

POST /api/GatewayDataService/GetVariableStatusPageList

请求参数：

参数	类型	说明
PageIndex	number	页码
PageSize	number	每页条数
DeviceId	number	设备ID（可选）
Name	string	变量名称（可选）
RegisterAddress	string	寄存器地址（可选）
OnlineOnly	boolean	仅在线变量（可选）

请求头：

头部	说明
Authorization	Bearer {"{token}"}

返回数据： 变量分页列表

写入变量值

POST /api/GatewayWriteVariableService/SetVariableValue

注意

写入变量值需要变量配置为"读写"类型且开启"RPC写使能"，否则写入操作将被拒绝。

请求参数：

参数	类型	说明
inputs	object	设备变量写入参数，格式为 { "设备名称": { "变量名称": 值 } }

返回数据：

字段	类型	说明
data	object	写入结果，格式为 { "设备名称": { "变量名称": OperResult } }

OperResult 结构：

字段	类型	说明
Success	boolean	是否成功
ErrorMessage	string	错误信息（失败时）
Value	any	返回值

请求示例：

{
  "device1": {
    "temperature": 25.5,
    "humidity": 60
  },
  "device2": {
    "pressure": 101.3
  }
}

返回示例：

{
  "code": 200,
  "data": {
    "device1": {
      "temperature": {
        "Success": true
      },
      "humidity": {
        "Success": true
      }
    },
    "device2": {
      "pressure": {
        "Success": false,
        "ErrorMessage": "变量不可写"
      }
    }
  },
  "msg": "success",
  "time": "2024-01-01T00:00:00"
}

报警接口

获取实时报警变量列表

POST /api/GatewayRealAlarmService/GetRealAlarmVariables

请求参数：

参数	类型	说明
PageIndex	number	页码
PageSize	number	每页条数

请求头：

头部	说明
Authorization	Bearer {"{token}"}

返回数据： 报警变量分页列表

确认报警

POST /api/GatewayRealAlarmService/ConfirmAlarm

请求参数：

参数	类型	说明
Id	number	报警变量ID
ConfirmText	string	确认说明（可选）

请求示例：

{
  "Id": 12345,
  "ConfirmText": "已处理"
}

返回数据： boolean，确认是否成功

错误码

错误码	说明
200	成功
401	未认证，需要登录
403	无权限
404	资源不存在
500	服务器内部错误

提示

• 所有接口（除登录接口外）均需在请求头中携带 Authorization: Bearer {"{token}"}
• Token有效期默认15天（可通过JWTOptions.ExpiredTime配置，单位分钟），过期后需重新登录获取
• 建议在 Token 即将过期时调用刷新接口

相关链接

• 数据管理 - 通道、设备、变量配置
• 实时报警 - 报警监控和处理
• 快速开始 - 部署和使用指南