配置、受管出网与集成连接

后端插件经常需要三件事：读已绑定连接的配置（地址、凭据）、访问外部系统的 HTTP 接口、调用平台连接器。这一页讲这三个能力和一个地理辅助方法。

这些能力通过全局对象 platform 和 connector 使用，在 HTTP 回调、事件回调和流程脚本三条路线里都可用（权限照常申报）。

能力与权限对照

方法	需要的权限	用途
`platform.getConfig()`	`config:get`	读当前连接的配置
`connector.fetch(req)`	`egress:fetch`	受管出网（HTTP 请求外部系统）
`connector.invoke(id, payload)`	`integration:write` 或 `integration.gis:read`	调平台连接器
`platform.resolveSegment(lat, lng)`	`geo.segment:read`	坐标解析路段

连接配置：声明形状，部署填值

插件清单只声明"我需要哪些配置项"，真实值由部署方在受控连接配置中提供。装载时平台校验缺键、多键和类型，不匹配即启动失败。

源清单 fh2-plugin.json：

{
  "connections": [{
    "id": "traffic.connector.cascade",
    "requires": [
      { "name": "baseUrl", "type": "string", "required": true },
      { "name": "password", "type": "string", "required": true, "secret": true }
    ]
  }]
}

真实连接值由部署方维护。插件作者提供连接 ID、字段声明和目标环境需求，并请部署方确认连接已绑定且可用；声明权限或方法已注入都不代表连接就绪。secret: true 只让启动日志不打印值，不加密配置本身，真实凭据不写入插件包。

在流程的 run_script 步里，用常量指定这次脚本用哪个连接：

{
  "action": "run_script",
  "inputs": {
    "script": { "const": "pull" },
    "connectorId": { "const": "traffic.connector.cascade" }
  }
}

platform.getConfig()

返回该连接配置的深拷贝，并带上 connectorId。每次返回新对象，你在脚本里改它不影响后续调用。

const cfg = platform.getConfig()
// { baseUrl: "https://partner.example.com", password: "...", connectorId: "traffic.connector.cascade" }

注意：

配置在进程启动时读取一次；改了部署配置要由部署方重启后端运行时，插件热更不会刷新它。

连接 ID 写错（或没绑定）会直接抛错，错误信息里会点名是哪个连接。

connector.fetch()：受管出网

后端脚本环境没有裸网络（没有 fetch / XMLHttpRequest），访问外部系统只能走 connector.fetch：

connector.fetch({
  method?: string,          // 缺省按无 method 处理，建议显式给
  url: string,              // 必填，绝对 http/https URL
  headers?: object,         // string -> string
  body?: string | object,   // 对象会被 JSON 序列化
  timeoutSec?: number
}) -> { status: number, headers: object, body: string }

const cfg = platform.getConfig()
const response = connector.fetch({
  method: "POST",
  url: cfg.baseUrl + "/events",
  headers: { Authorization: "Bearer " + cfg.password },
  body: { cursor: input.cursor },
  timeoutSec: 10
})
if (response.status < 200 || response.status >= 300) {
  throw { code: "UPSTREAM_REJECTED", message: "上游返回 " + response.status }
}
const data = JSON.parse(response.body)   // body 不自动解析

硬限制（超出直接报错）：

限制	值
默认超时 / 单次上限	15 秒 / 25 秒
响应体上限	4 MiB
每次脚本调用请求次数	32 次
累计出网时间	40 秒
重定向	不跟随，3xx 原样返回

⚠️ 出网目标受目标环境的出网白名单限制，主机不在名单里会被拒绝（支持精确主机或 .suffix 后缀）。白名单由部署方维护；接入前提交目标主机和业务用途，请部署方确认放行。拥有 egress:fetch 权限不代表任意目标都可访问。

⚠️ fetch 不帮你生成幂等键，也不拦副作用请求。发 POST/PUT 时用 run.idempotencyKey 派生稳定键，并把流程步的 maxAttempts 按上游语义收紧。

connector.invoke()：调平台连接器

const accepted = connector.invoke("custA.command-center", { recordId: "r-1", level: 2 })

integration:write 和 integration.gis:read 两个权限对应同一个方法。当前内置连接器多为演示用途，错误细节会被吞掉，不能作为可靠的外部集成通道——生产接入外部系统请用 connector.fetch。

platform.resolveSegment()：坐标转路段

const segment = platform.resolveSegment(39.9, 116.4)

⚠️ 当前实现是固定值桩（无论坐标是什么都返回同一路段名），不要据此做生产地理判断。

常见问题

现象	原因与处理
`platform is not defined`	清单没申报 `config:get`（或当前脚本路线没配 allowlist）
`connector is not defined`	没申报 `egress:fetch` 或 `integration:*`
出网请求因目标主机未获允许而被拒绝	出网白名单没放行该主机，提交目标主机和用途，请部署方确认
`fetch 出网次数超限`	一次脚本调用最多 32 个请求；拆分或减少调用
拿到的配置是旧值	配置启动时读取；请部署方确认新配置并重启后端运行时
`invoke` 返回了但对方系统没收到	内置连接器是演示用途；生产改用 `connector.fetch`

连接声明的完整字段见 plugin.json 契约。

配置、受管出网与集成连接

能力与权限对照#

连接配置：声明形状，部署填值#

platform.getConfig()#

connector.fetch()：受管出网#

connector.invoke()：调平台连接器#

platform.resolveSegment()：坐标转路段#