开发接口：网关 API 文档

本页汇总 TGateway、Studio 和 Watchdog 常用接口。调用受保护接口前请先完成登录，并在请求中携带有效 Token（登录后拿到的访问凭证）。Studio 的普通语言服务接口允许匿名访问；涉及工程路径的分析仍需认证。

阅读路线：获取接口定义 → 接入与认证 → 接口参考 → 调用排障。MCP 是可选客户端；使用它时再阅读MCP 接入与授权。

接入与认证

接口术语对照

基础约定

Studio 和 Watchdog 默认监听 0.0.0.0，当前版本允许客户端通过普通 http://IP:端口 调用。使用普通 HTTP 时必须启用远程管理和 AllowInsecureRemoteHttp；Watchdog 的项目部署与进程控制还必须启用 RemoteDeploymentEnabled。

浏览器跨域调用

TGateway 的 Web API 在 CorsOrigins 留空时默认允许任意网页来源，浏览器可从不同域名或端口发起请求。显式填写来源列表后，按完整 Origin 匹配，需包含协议、主机及非默认端口；域名后缀、子串和另一个端口不属于同一来源。

来源许可与接口鉴权分别检查。跨域允许后，受保护接口仍要求有效 Token、角色和 API 权限；浏览器请求中按接口契约发送 Bearer Token。服务端程序不受浏览器 CORS 机制限制，也仍需通过对应鉴权。

语言服务默认地址为 https://roslyn.thingsgateway.cn，自建 Studio 使用自己的根地址。反向代理需要转发允许来源响应头，并让 OPTIONS 预检到达服务或返回等价响应。不要把 HTTP 200 单独当作浏览器调用成功：检查正文是预期 JSON，并确认响应中有匹配的 Access-Control-Allow-Origin，以及预检允许实际方法和请求头。

例如在命令行检查语言服务的来源响应：

# 使用实际 Gateway 网页的 Origin 检查响应头及 JSON。
curl -i \
  -H 'Origin: http://192.168.10.30:6100' \
  https://roslyn.thingsgateway.cn/api/completion/assemblies

普通语言响应应包含 Access-Control-Allow-Origin: *。该模式不授予浏览器跨站 Cookie 凭据权限，调用方不要依赖跨站 Cookie 完成认证。最终仍从实际 Gateway 编辑器检查连接、补全和分析，详见代码编辑器操作。

获取 OpenAPI JSON

TGateway 提供标准的 OpenAPI JSON 文档，可通过以下地址获取：

GET http://<网关IP>:6100/api/openapi.json

也可以使用 curl 将文档保存为本地文件：

curl http://<网关IP>:6100/api/openapi.json -o openapi.json

返回的 JSON 可导入 Swagger Editor、Postman 或其他支持 OpenAPI 的客户端和代码生成工具。接口定义以目标 TGateway 当前版本返回的文档为准。

Studio 与 Watchdog 登录密码加密

调用 Studio 或 Watchdog 登录接口时，先获取临时公钥，再加密密码并提交：

1. 调用对应的公钥接口，获取 keyId、publicKey、algorithm、nonce 和 expiresAt。
2. 确认 algorithm 等于 RSA-OAEP-SHA256。
3. 使用 publicKey 中的 RSA 2048 SubjectPublicKeyInfo DER Base64 公钥，加密以下 UTF-8 JSON。字段名大小写固定。

{
  "Password": "实际密码",
  "Nonce": "公钥响应中的nonce"
}

4. 将 RSA-OAEP-SHA256 密文进行 Base64 编码，作为登录请求的 password；同时把 keyId 作为 passwordKeyId 提交。
5. 登录成功后，后续受保护请求统一发送 Authorization: Bearer <token>。

临时公钥有效期为两分钟，每次只能提交一次登录请求。请求成功或失败后，该公钥都会失效；重试时必须重新获取公钥。接口只接受上述加密格式。

浏览器客户端可以在普通 HTTP IP 页面中使用 node-forge 执行 RSA-OAEP-SHA256，并使用 crypto.getRandomValues 生成 OAEP 随机种子；不要依赖该场景通常不可用的 crypto.subtle.importKey。

TGateway 认证接口

外部身份与单点登录

外部身份流程要求同源浏览器、原流程状态和相应用途；不要把短期完成码当作访问令牌。操作步骤见身份认证与单点登录。

TGateway 接口参考

系统监控

快照可能复用 30 秒内的样本。监控查看、包清单和手动 GC 按对应权限检查；请求 GC 不保证立即降低工作集。指标口径和页面操作见系统监控与内存分析。

状态与调试 WebSocket

1. 携带当前 Bearer 令牌调用 POST /api/gatewaywebsocketcontroller/createstatusticket 或 createdebugticket，分别申请状态或只读调试连接票据。
2. 在 30 秒内使用票据建立 /ws/gateway/status?ticket=<票据> 或 /ws/gateway/debug?ticket=<票据> 连接；HTTPS 站点使用 wss。
3. 每张票据只能消费一次，状态与调试用途不能互换。重连前重新申请，不能复用已消费或过期票据，也不在连接地址中传入长期访问令牌。

状态票据需要变量读取权限，调试票据需要调试查询权限；取得票据不授予写入权限。

TGateway 总览与元数据

采集配置接口

插件方法 RPC

POST /api/gatewayrpccontroller/invokepluginmethod 使用 Bearer Token 和 rpc:invoke_plugin_method API 权限，执行被调用实例已允许的直接方法，无需变量绑定。

{"subjectType":"CollectDevice","subjectId":1001,"methodName":"ReadAsync","parameters":["400001","UInt16",1],"timeoutMs":30000}

subjectType 还可为 DataForwardTarget。将 subjectId 替换为实际设备或目标编号，并开启其“允许方法调用”。没有额外方法白名单、业务请求编号、去重或方法并发配额。统一响应的 data 包含 status、isSuccess、operCode、message、content、executionTime 和 executionMayHaveOccurred；业务成功与 HTTP 成功分别检查。

调试接口 POST /api/debugController/invokespecialmethod 继续要求危险调试权限，请求使用 subjectType、subjectId、methodName、parametersJson。其中 parametersJson 是位置数组的 JSON 文本，响应的 contentJson 也是完整 JSON 文本，消费端应保留数值精度。正式接口使用真正的 parameters JSON 值，两者不能混填。

MQTT 固定方法主题、UA 原生 Method、参数约定、超时和日志见插件方法调用。

数据转发接口

数据转发接口中，转发组变量关系决定变量是否属于某个转发组；目标变量属性只描述某个目标如何使用该变量。组变量关系和目标变量属性均按单组或单目标分页读取，页面最大为 200 条；组内变量远程候选最多返回 50 条。手动选择范围下，保存目标变量属性前应先通过 savegroupvariablechanges 把变量加入转发组。

数据查询与实时报警接口

历史查询请求契约

历史分页接口使用统一请求字段：

普通历史接口返回目标配置时区的墙钟时间；类型化历史接口 GetTypedHisDataRecordsByTarget 和 GetTypedHisNumberDataRecordsByTarget 使用 UTC 起止时间并返回 UTC 时间点。自定义 SQL 接口返回目标表的原始列和值：IoTDB、QuestDB 的宽表时间可能带 Z 后缀，表示 UTC，不应重复转换。

自定义 SQL 列查询

调用 /api/customsqldatacontroller/GetCustomSqlColumns?targetName=... 后，以返回的列集合构造表格和筛选条件。第一列是目标时间列，页面使用它进行时间范围和降序查询；其它列由 CustomTemplateConfig.Columns 决定。不要把普通历史表的 CreateTime、VariableId 或 Value 字段强行套到自定义宽表。

自定义 SQL 查询仍返回分页 records 和 total。total 是当前目标、时间范围和条件下的数据库总数，不是当前页 records.length；调用方必须使用服务端总数驱动分页。

查询资源限制

类型化历史查询、数值序列和导出接口受 Configuration/HisDataQueryOptions.json 的变量数、时间跨度、分页大小、序列点数、源记录数和导出行数上限保护。大范围查询应拆分时间窗口或使用序列聚合，不要绕过分页一次拉取百万级原始记录。

类型化历史查询应使用 UTC 起止时间，并受变量数、时间跨度、分页大小、序列点数、源记录数和导出行数上限保护。默认上限在 Configuration/HisDataQueryOptions.json 中维护；集成方应按分页和数值序列聚合能力设计请求，不要通过超大时间范围一次拉取全部原始记录。

MQTT 客户端和 MQTT 服务端生产者还可通过默认主题 RpcHistory 调用同一组历史能力：请求主题为 RpcHistory/<32位十六进制请求号>，响应主题为 RpcHistory/<请求号>/Response。协议支持目标、记录、数值序列、历史报警、确认报警和取消请求；大响应使用 gzip 后 Base64 分块，并受请求体、响应体、分块大小、并发数和超时限制。

设备与转发目标调试接口

规则、脚本、节点接口

规则定义保存在 DefinitionJson，通过稳定节点类型身份与端口名称表达执行图；画布布局独立保存。POST validateruleflow 返回带节点、端口和连线位置的诊断，启用流程必须通过校验。

POST setruleflowenabled 显式传 id、enabled 和当前 controlRevision。保存和启停返回的 runtimeReloaded、runtimeReloadError 用于区分配置已保存与运行重载结果；不要只凭请求成功认定新实例已经装载。发生版本冲突时重新读取详情再处理。

节点运行值同时包含当前活动、最近执行结果与连接观察。Skipped 表示显式未执行，waitingReason 表示空闲条件；连接最近活动不覆盖上次真实投递结果。具体状态与验证步骤见规则引擎。

插件、证书和系统设置接口

日志接口

管理权限接口

Studio 与 Watchdog 接口

Studio 认证

Studio 首次安装直接使用 admin / 111111 登录，账号配置缺失时自动创建默认账号。登录成功后返回七天有效的 JWT Bearer，可从用户菜单修改密码。

Watchdog 认证

Watchdog 默认使用 admin / 111111 直接登录，已有配置中的有效账号密码优先。登录成功后返回 accessToken、username 和 expiresAt。Token 是八小时有效的随机不透明值，服务端只在内存中保存 SHA-256 摘要；登出或 Watchdog 重启后失效。

调用排障

保留请求时间、接口路径、状态码及去敏后的错误消息；不要记录登录密文、令牌、账号密码或完整生产载荷。导入和批量修改失败后，先查询实际已写入范围，再决定是否重试。

使用注意

• 接口路径请按表格中的大小写和路径调用。
• 导入导出、上传、下载接口可能返回文件或接收表单文件，请按接口文档中的请求格式调用。
• 管理类接口受菜单、按钮、API 权限共同限制；角色授权不足时，即使 Token 有效也可能返回无权限。