插件方法调用

插件方法调用用于直接执行采集设备或转发目标公开的业务方法，无需先创建变量。Web API、MQTT 方法请求、OPC UA 原生 Method、调试页和规则特殊方法节点共用实例的“允许方法调用”开关，执行结果进入 RPC 日志。

适用对象包括标准版和专业版中实际加载的采集插件、数据转发插件，以及按同一方式公开方法的自定义插件。例如，可调用 Modbus 设备的读写、S7 日期方法、DL/T 645 控制方法、Webhook 上传，以及当前插件目录中的其他直接方法。具体名称、参数和业务校验以实例的“特殊方法”目录为准；普通公开成员、未声明为直接调用的方法不会自动成为 RPC。

MQTT、OPC UA 是请求进入网关的协议入口，不限定被调用插件的类型。Web API、调试页或规则节点同样可以调用其他协议的设备和转发目标。协议专用调试工具按其自身功能操作，不能把所有页面按钮都当作特殊方法 RPC。

变量写入及变量绑定方法仍使用变量的读写权限和“RPC 写入”开关。两种方式的配置不能相互代替；通过方法直接访问地址时，不会再按地址匹配变量权限。

开启设备或目标的方法调用

采集设备：进入“开发配置 → 采集配置”，编辑要调用的设备。
转发目标：进入“开发配置 → 数据转发”，选中所属组，编辑要调用的目标。
在基本配置中开启“允许方法调用”，保存后重新打开配置，确认开关已保存。
确认设备及通道，或目标及所属组均已启用，运行实例初始化和启动成功，且当前不是备用状态。采集设备还不能处于暂停状态。

设备基本配置中的允许方法调用开关

配置项	说明
允许方法调用	默认关闭。开启后允许调用该实例公开的全部直接方法；没有逐方法或逐调用者白名单。
设备或目标名称	调试和 RPC 日志使用名称显示被调用对象。
启用	控制实例是否运行；仅开启方法调用而未启用实例，仍不能执行。

入口的认证仍然生效：Web API 使用登录账号及 API 权限，MQTT 使用 Broker 或连接认证，OPC UA 使用会话认证。MQTT 或 OPC UA 转发目标自身的“允许方法调用”，只控制它作为被调用对象的方法；通过它调用另一个设备或目标时，检查的是那个被调用实例的开关。

关闭开关后，尚在排队等待执行的调用会在取得插件执行锁后被拒绝；已进入方法本体的操作继续收尾。保存、停用、重建或切换备用状态后，不应把此前排队的请求当作仍可执行的控制命令。

在调试页验证一次调用

在设备或转发目标的调试工作区打开“特殊方法”。
刷新目录，选择当前插件实际列出的动作，阅读参数说明。
使用外层 JSON 数组按顺序填写业务参数，或通过“字段编辑”填写并应用草稿。
点击“执行”，等待结果。执行期间方法选择、参数编辑和目录刷新均不可操作。
在独立设备或接收端核对实际效果，再到“日志 → RPC日志”检查同次调用。

例如，Modbus 设备公开的 ReadAsync 可以填写：

["400001", "UInt16", 1]

未建立变量时直接读取 Modbus 地址并返回数值

地址规则以所选插件为准。字节数组可使用 Base64 字符串，也可按字段提示填写字节数字数组；正文字符串本身不等于字节载荷。修改方法或参数后，旧结果会清除；返回成功且附带诊断时，页面同时显示成功状态和诊断信息。

转发目标也使用同一操作方式。以下 Webhook 示例选择 UploadAsync，按 [URL, Base64载荷] 执行，随后在 HTTP 接收端核对收到的正文。其他目标按目录中声明的主题、路由键和参数调用。

Webhook 转发目标直接执行上传方法

Web API 调用

登录后使用 Bearer Token，账号需要 rpc:invoke_plugin_method API 权限。调试页执行继续使用危险调试权限。

POST /api/gatewayrpccontroller/invokepluginmethod
Authorization: Bearer <token>
Content-Type: application/json

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

参数	说明
`subjectType`	`CollectDevice` 表示采集设备，`DataForwardTarget` 表示转发目标。
`subjectId`	实际设备或目标编号；示例 `1001` 需替换。名称用于显示，编号用于定位对象。
`methodName`	方法目录中的真实名称，区分大小写，最长 256 个字符。
`parameters`	完整业务签名的位置参数数组。无参数使用 `[]` 或 `null`；只有一个数组参数时，使用双层数组。尾部可选参数可以省略，取消令牌不占业务位置。
`timeoutMs`	默认 30000 毫秒，允许 1～120000 毫秒，采用合作取消。

统一接口响应的 data 中是方法结果，例如：

{
  "status": "Success",
  "isSuccess": true,
  "operCode": 0,
  "message": null,
  "content": 1234,
  "executionTime": 12,
  "executionMayHaveOccurred": true
}

不能仅以 HTTP 请求成功判断方法成功，还要读取 status、isSuccess、业务码及消息。请求不包含调用来源、调用者或业务请求编号；身份和来源由入口确定。

MQTT 方法请求

MQTT 客户端转发和 MQTT 服务端转发提供“插件方法RPC Topic”，默认 RpcMethod。该项留空时，此连接不接收方法请求，其他变量或快照协议照常运行。

在 MQTT 目标配置中确认该主题，并配置连接认证和必要的 Topic 访问权限。
独立客户端先订阅 RpcMethod/Response。
向 RpcMethod 发布与上面 Web API 相同的 JSON 请求，关闭 Retain。
从响应主题读取方法结果，并在被调用对象或独立接收端验证实际效果。

项目	说明
请求主题	固定主题，例如 `RpcMethod`，不追加请求编号。
响应主题	请求主题加 `/Response`，例如 `RpcMethod/Response`，响应不保留。
载荷	方法入口不额外设置载荷大小上限；MQTT 协议和 Broker 的报文配置仍生效。retained 请求、未知字段、损坏或尾随 JSON 被拒绝并审计。
主题冲突	方法请求及响应不得与变量写入、历史或快照请求及响应主题重叠；冲突时目标初始化失败。
响应发布	预算 5 秒；发布失败记录运行日志，不会重新执行方法。

Gateway 连接外部 Broker 时，发布者的认证和 Topic ACL 由 Broker 管理，RPC 日志中的入口身份为 broker。内置 MQTT Server 按连接建立时验证的身份记录；未配置用户名认证时记录 anonymous。

同一固定响应主题不提供请求编号关联。多个调用者应分别安排主题或串行调用，避免把别人的响应当作自己的执行结果。原变量、历史和快照协议继续使用各自的主题与编号约定，不能把方法请求的格式套到它们上面。

OPC UA 原生 Method

先开启被调用设备或目标的“允许方法调用”。
启动或重启 OPC UA 服务端目标，使用外部 UA 客户端按该目标的安全策略和会话身份连接。
在 ThingsGateway/Methods 下按设备或目标名称找到方法。
第一个输入填写 TimeoutMs，随后按顺序填写业务参数，执行并读取输出。

输出依次为 Status、OperCode、Message、ExecutionTime、ExecutionMayHaveOccurred、Content。基础标量及一维数组使用 UA 原生类型；字节数组是 ByteString；复杂对象、Decimal 和可空值类型使用 JSON 字符串，保留精度和 null。

节点在 UA 目标启动时建立。之后才开启其他实例的方法调用，需要重启 UA 目标才能浏览新节点；关闭被调用实例的开关，则已有节点调用也会立即被拒绝。替换插件或改变方法定义后，旧节点返回不可用，重启 UA 目标后重新浏览当前方法。

UA 会话认证、安全策略和证书配置见 OPC UA 服务端。

日志、超时和重复提交

行为	当前规则
授权范围	每个被调用实例一个开关，开启其全部公开直接方法；没有入口方法白名单或逐参数授权。
并发及速率	方法 RPC 没有全局并发配额、MQTT 待处理数量上限、调用者配额或每秒请求数限流；仍按插件原有执行锁协调。协议宿主自身的资源配置不因此取消。
重复提交	每次独立执行，无请求编号和去重缓存，也不返回旧结果。
超时	发出合作取消并等待插件收尾，实际结束可能超过预算；超时不能证明设备没有执行。
自动重试	服务不自动重试控制命令。调用方先核对现场效果，再决定后续操作。
已确认业务结果	插件确认成功或明确拒绝后，返回内容序列化失败不会改写业务状态，诊断会保留。
RPC 日志	记录对象名称、方法、来源、参数、结果、耗时、状态和业务码。普通成功受“RPC成功日志”设置控制，失败及附带诊断的调用仍记录。

ExecutionMayHaveOccurred 表示已进入执行链，等待锁时也可能为真，不能当作设备已执行的证明。RPC 日志为异步写入，查看时可稍后刷新；它不提供异常停机时的持久消息投递保证。

RPC 日志详情显示被调用目标名称、方法、状态、耗时和原始参数

常见问题

现象	处理方法
`Forbidden`	检查被调用实例的“允许方法调用”和方法是否公开为直接方法；Web 入口还要检查账号 API 权限。
`NotFound`	检查实例类型、实际编号及方法名称大小写。
`Unavailable`	检查启用、暂停、备用、启动状态；UA 旧方法节点需重新发布。
`InvalidRequest` / `InvalidParameters`	检查超时、参数顺序、类型、必填项、数组层级及字节载荷格式。
`Rejected`	插件明确拒绝，结合业务码、消息及插件说明处理。
`Timeout` / `Cancelled` / `UnknownEffect`	核对现场和日志，不能直接重复下发控制命令。
看不到成功日志	检查“RPC成功日志”设置及查询时间范围；失败日志不受该成功开关影响。

相关操作：反向 RPC、采集与调试、数据转发、系统日志。

开启设备或目标的方法调用​

在调试页验证一次调用​

Web API 调用​

MQTT 方法请求​

OPC UA 原生 Method​

日志、超时和重复提交​

常见问题​