千问办公企业旗舰版开发者文档:查询内置连接器详情。
认证方式见APP开发者文档 → 认证接入。
200 直接返回内置连接器对象。与列表采用同一 Web 策略过滤,无权限的直接链接返回 404,不回退市场详情。
按 connector_publish / DISCOVER / qwenwork_web 计算权限,沿用默认策略组、白名单及黑名单规则;不以旧 PC 策略兜底,不以 OAuth 登录成功代替资源权限。
Web 目录仅含钉钉、飞书、企业微信;浏览器、Microsoft 365、LINE、macOS 应用和计算机控制均不展示,详情返回 404。内置没有普通市场条目,不要求市场开关或市场条目 ID。响应不含凭据、命令、第三方 token 或 Bot Secret。可选 state 返回用户管理状态;读接口不产生安装或授权副作用。返回
可选 state 包含 available、installed、enabled、connected、configured、pending、auth_mode、state_etag、auth_revision、unavailable_reason 及四项 can_* 管理能力。auth_mode 为 oauth(钉钉、飞书)或 configuration(企微)。configured 按上表的连接健康状态及配置授权模式计算,不证明沙箱已完成调用。状态失败不扩大权限,前端须禁用写操作并重新查询。
添加/卸载使用固定 key 的 /builtin-connectors/{key}/installations;启停、OAuth、取消与断开复用 /preferences/connector/org/{id} 和 /connectors/org/{id}/...。添加/启停使用 state_etag,授权/配置/断开使用 auth_revision。新装默认关闭,授权不自动启用,断开同时停用,完整卸载重装默认关闭。
- 模块:技能中心
- 权限:按当前用户的资源范围校验,不要求管理员权限。
- 接口:GET
/api/openapi/app/v1/ai-assets/builtin-connectors/{key}
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| key | path | string | 是 | 固定 builtin_key,使用列表中的值;不能传市场条目 ID 或资源 UUID。 |
响应
200 直接返回内置连接器对象。与列表采用同一 Web 策略过滤,无权限的直接链接返回 404,不回退市场详情。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string(uuid) | 是 | 固定内置资源 UUID,可在连接器策略组中配置。 |
| builtin_key | string | 是 | 仅 dws(钉钉)、lark(飞书)或 wecom(企业微信)。 |
| source_type | string | 是 | 固定为 builtin,不是市场来源 org/public。 |
| name / name_cn | string | 是 | 英文名称、中文名称。 |
| description / description_cn | string | 是 | 英文描述、中文描述。 |
| surface_code | string | 是 | 固定为 qwenwork_web。 |
| supported_surfaces | array(string) | 是 | 固定目录声明的适配端,三项均为 qwenwork_pc、qwenwork_web;不是当前运行就绪或授权状态。 |
| support_status | string | 是 | management_available 表示管理能力已接入;状态服务未配置或不可用时保留 not_implemented。两者均不证明沙箱已可执行。 |
| capabilities | object | 是 | 管理能力,见下表;写入时仍由服务端重新校验。 |
| state | object | 否 | 当前用户管理状态,见下表;读取失败或未装配状态服务时可能省略。 |
capabilities
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| can_install | boolean | 是 | 当前是否允许添加。 |
| can_toggle | boolean | 是 | 当前是否允许切换启用状态。 |
| can_uninstall | boolean | 是 | 当前是否允许卸载手动安装的资源;自动提供的资源不能按手动安装卸载。 |
| can_authorize | boolean | 是 | 当前是否允许发起授权或配置操作。 |
| can_use | boolean | 是 | 此目录投影当前固定为 false,不能据此推断运行时已可用。 |
state
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| available | boolean | 是 | 管理状态是否成功读取;不表示沙箱执行可用。 |
| installed | boolean | 是 | 是否已手动安装或由系统自动提供。 |
| enabled | boolean | 是 | 用户当前是否启用。 |
| configured | boolean | 是 | 当前实现为 connected 且 auth_mode=configuration;不是仅判断配置是否已保存。 |
| connected | boolean | 是 | 当前权限允许,且上游返回唯一健康连接、绑定指纹匹配当前配置时为 true;不代表沙箱已成功调用。 |
| pending | boolean | 是 | 是否存在待完成操作或授权尝试。 |
| auth_mode | string | 是 | oauth:钉钉、飞书;configuration:企业微信。 |
| state_etag | string | 是 | 用户资源状态版本,供安装、卸载及启停操作的 If-Match 使用。 |
| auth_revision | string | 是 | 授权状态版本,供授权、配置、断开等操作的 If-Match 使用;状态不可用时可能为空。 |
| unavailable_reason | string | 否 | 不可用原因;如 permission_unavailable、permission_denied、state_recovery_required、state_unavailable、operation_in_progress、authorization_unavailable。非穷举,未知值不能当作可用。 |
| can_install | boolean | 是 | 当前是否允许添加。 |
| can_toggle | boolean | 是 | 当前是否允许切换启用状态。 |
| can_uninstall | boolean | 是 | 当前是否允许卸载手动安装的资源;自动提供的资源不能按手动安装卸载。 |
| can_authorize | boolean | 是 | 当前是否允许发起授权或配置操作。 |
权限与行为
按 connector_publish / DISCOVER / qwenwork_web 计算权限,沿用默认策略组、白名单及黑名单规则;不以旧 PC 策略兜底,不以 OAuth 登录成功代替资源权限。
Web 目录仅含钉钉、飞书、企业微信;浏览器、Microsoft 365、LINE、macOS 应用和计算机控制均不展示,详情返回 404。内置没有普通市场条目,不要求市场开关或市场条目 ID。响应不含凭据、命令、第三方 token 或 Bot Secret。可选 state 返回用户管理状态;读接口不产生安装或授权副作用。返回 Cache-Control: no-store。
错误
| 状态码 | 说明 |
|---|---|
| 400 | 参数无效。 |
| 401 / 403 | 会话、可信身份或业务准入失败。 |
| 404 | 详情 key 不存在、被排除或当前策略无权查看。 |
| 503 | IAM 不可用或返回未知 selector;拒绝展示,不回退固定全量目录。 |