---
docStatus: current
---

# 渠道资源管理 API

用工作区、Runtime 与完整 Module Locator 管理机器人连接、策略、身份和会话。

工作区管理员通过渠道 Owner 的资源管理接口选择渠道服务。资源身份使用完整 Module Resource Locator；连接编号、会话键、外部用户身份和策略键保留各自业务含义。

```text
POST /partner/v1/channel-gateway/api/admin/workspaces/{workspaceId}/resource-connection-management/{action}
```

使用所在环境的正式登录身份或工作区授权凭据。`workspaceId` 位于路径中，渠道 Owner 校验当前用户的工作区管理权限，并确认该 Runtime 的当前渠道登记。请求中的 `resourceLocator` 指向渠道提供方 Module，例如飞书连接器；它不是渠道网关自身的 Module Locator。

下面是只读连接目录查询：

```json
{
  "contractVersion": "1.0.0",
  "applicationRuntimeId": "runtime-id",
  "resourceLocator": "source/connector/MODULE/provider",
  "parameters": {
    "contractVersion": "1.0.0",
    "keyword": null,
    "cursor": null,
    "limit": 50
  }
}
```

成功响应遵循 CModel。`data` 返回相同的工作区、Runtime、完整 Locator，以及动作业务结果：

```json
{
  "contractVersion": "1.0.0",
  "errorCode": "0",
  "data": {
    "contractVersion": "1.0.0",
    "workspaceId": "42",
    "applicationRuntimeId": "runtime-id",
    "resourceLocator": "source/connector/MODULE/provider",
    "result": { "items": [], "nextCursor": null }
  }
}
```

接收结果时核对整个身份范围。资源选择不使用 `channel`、`businessId` 或 `serviceId`；这些执行地址由 Owner 从当前绑定解析。`connectionId`、`sessionKey` 和 `userRef` 中的业务标识原样传递，不改写大小写或路径字符。

| action                          | parameters                                               |
| ------------------------------- | -------------------------------------------------------- |
| `listChannelConnections`        | `contractVersion: "1.0.0"`、`keyword`、`cursor`、`limit`    |
| `listChannelStrategies`         | `{}`；每项返回 `key`、`resourceLocator`、`callable`             |
| `getConnectionStrategyMapping`  | `connectionId`、可选 `sessionKey`                           |
| `setConnectionDefaultStrategy`  | `connectionId`、必填 `strategyKey`；显式 `null` 清除默认策略         |
| `setSessionStrategy`            | `connectionId`、`sessionKey`、`policy`                     |
| `getConnectionIdentityConfig`   | `connectionId`                                           |
| `setConnectionIdentityConfig`   | `connectionId`、`bindingMode`、`defaultInternalUserId`     |
| `setConnectionUserBinding`      | `connectionId`、`userRef`、`internalUserId`、`enabled`      |
| `listConnectionSessions`        | `connectionId`、`keyword`、`cursor`、`limit`                |
| `listConnectionSessionMessages` | `connectionId`、`sessionKey`、`cursor`、`limit`             |
| `listConnectionUsers`           | `connectionId`、`keyword`、`cursor`、`limit`                |
| `simulateConnectionMessage`     | `connectionId`、`sessionKey`、`content`；当前返回 `unsupported` |
| `sendConnectionMessage`         | `connectionId`、`sessionKey`、`content`；向已观测会话发送消息         |

`policy` 的 `mode` 为 `inherit`、`paused` 或 `assigned`；只有 `assigned` 携带策略 `key`。`bindingMode` 为 `per_sender` 时，`defaultInternalUserId` 为 `null`；`default_user` 模式需要明确的工作区成员 ID。用户绑定的 `userRef` 包含 `identityScopeId`、`channelUserType`、`channelUserId`，由当前连接的用户目录返回。

分页响应的 `nextCursor` 为 `null` 表示结束。使用返回的原游标继续查询。错误按 CModel 返回，不转换为空目录，也不自动改用旧执行地址。

网关运行设置的本地 key 和历史消息身份继续由渠道 Owner 管理。改用本接口不等于已经迁移 ServiceReferenceMap 的历史键；历史映射及引用路径应由相应 Owner 单独迁移。