Skip to main content

添加 Web 手动安装登记

千问办公企业旗舰版开发者文档:添加 Web 手动安装登记。

认证方式见APP开发者文档 → 认证接入。
  • 模块:技能中心
  • 权限:按当前用户的资源范围校验,不要求管理员权限。
  • 接口:POST/api/openapi/app/v1/ai-assets/installations

请求参数

参数位置类型必填说明
If-Matchheaderstring是最近响应中的 state_etag,原样传入;不支持通配符。
Idempotency-Keyheaderstring是8–128 字符;同一请求重试保持相同键和请求内容。
请求体为 application/json。

WebassetsInstallRequest

字段类型必填说明
idstring是资源 UUID,不是市场条目 ID。
market_item_idstring是目录返回的市场条目 UUID,必须与当前资源来源匹配。
originstring是org 或 public,沿用目录返回的来源。 可选值:org, public。
resource_typestring是支持 skill、expert_kit 和 connector。 可选值:skill, expert_kit, connector。

响应

200 返回 application/json,直接返回下述对象。

WebassetsMutationResult

字段类型必填说明
resourceWebassetsResource是本人资源身份、安装登记及偏好;不包含资源包或凭据。
state_etagstring是当前组织/用户/Web 状态版本;写入时作为 If-Match 原样传入。

WebassetsResource

字段类型必填说明
confirmed_generationstring否恢复后该资源的已确认代际;客户端不得自行设置。
enabledboolean否用户启停选择;false 同样覆盖自动下发资源,不能为 null。
idstring是资源 UUID,不是市场条目 ID。
lifecycle_epochinteger是服务端资源生命周期代际,仅用于控制一致性。
manual_installWebassetsInstallation否手动登记实例;自动资源不因下发而创建该字段。
originstring是org 或 public,沿用目录返回的来源。 可选值:org, public。
resource_typestring是支持 skill、expert_kit 和 connector。 可选值:skill, expert_kit, connector。

WebassetsInstallation

字段类型必填说明
installation_idstring是服务端生成的手动安装实例 UUID;完整卸载后重装生成新实例。
registered_atstring是手动登记时间,RFC 3339。
source_channelstring是登记来源渠道。
source_market_item_idstring是登记时绑定的市场条目 UUID,不会自动切换到新条目。

使用说明

支持三类资源,按 capabilities 决定动作;连接器默认关闭,完成必要授权后方可启用。 使用目录中的资源身份和 market_item_id 添加手动登记。重复添加保留安装实例和启停选择;自动资源的禁用偏好不会被覆盖。安装登记成功不代表资源包已经下载,Agent 在下一次工作时按当前权限准备资源。 状态保存在服务端按组织/用户/Web 隔离的 PostgreSQL 状态行,与桌面端独立;客户端不直接读写 JSON,不使用 biz_hub_install。preparation 仅为最近观察,prepared 不保证本轮已加载,pending 不应显示为下载失败。套件 required 依赖必须全部就绪;optional 依赖不可用时仅省略相应能力。无法映射的内联依赖仍阻止执行。

并发与错误处理

写请求必须携带 If-Match 和 Idempotency-Key。先从目录详情、偏好或登记列表读取 state_etag。响应中的新 state_etag 用于下一次写入;不能继续复用旧版本。
  • 428(state_precondition_required):缺少 If-Match。
  • 412(state_conflict):状态已变化,重新读取并确认用户意图后以新键提交。
  • 409(idempotency_conflict):同一幂等键对应不同请求;响应丢失重试必须保持原键及原请求。
  • 503(state_unavailable):数据库或状态依赖不可用,不应显示写入成功或假定状态已重置。
资源身份或请求非法返回 400/404;未登录或身份不匹配按 IAM 返回处理。