Skip to main content

确认连接器授权

千问办公企业旗舰版开发者文档:确认连接器授权。

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

请求参数

参数位置类型必填说明
originpathstring是沿用当前响应中的资源身份。
idpathstring是沿用当前响应中的资源身份。
If-Matchheaderstring是最近 auth_revision,禁止传 安装/启停 state_etag。
Idempotency-Keyheaderstring是8–128 字符,同请求重试保持相同键。
attempt_idpathstring是沿用当前响应中的资源身份。
请求体:{"connection_id":"选定的连接 ID"};省略该字段时只允许唯一有效候选。

响应

200 返回当前授权状态或限定授权会话;断开恢复中可返回 202。

WebassetsConnectionResponse

字段类型必填说明
attempt_idstring否当前授权尝试 UUID,用于关联本次授权流程。
auth_revisionstring是授权状态版本;授权写操作按接口要求原样作为 If-Match 传入。
auth_typestring否连接器使用的授权方式,按实际响应返回。
can_authorizeboolean是当前用户是否可以发起授权。
can_useboolean是当前状态是否允许使用;不能仅凭 connected 判断可执行。
cleanup_pendingboolean是是否仍有后台凭据清理待完成。
connectedboolean是是否已建立连接/完成必要配置。
connection_idstring否授权连接标识,可能省略;不是用户身份。
operation_idstring否后台操作标识,用于后续查询操作结果。
operation_pendingboolean是是否仍有操作待完成,不能将 true 当作已完成。
operation_statusstring否查询到的操作状态,按实际响应返回。
state_availableboolean是服务端是否能够提供当前授权状态。
state_etagstring否安装/启停状态版本;与 auth_revision 不可互换。
unavailable_reasonstring否当前不可用原因;省略不代表所有执行条件均满足。
user_enabledboolean是用户是否选择启用该连接器;授权成功不自动等于启用。

使用说明

写入携带 Idempotency-Key 和 If-Match。授权写入使用 auth_revision;安装/启停仍使用 state_etag,两者不能互换。响应不可缓存。 发起后使用限定会话完成 OAuth,再将当前 attempt_id 和 connection_id 提交确认。多候选必须显式选择;旧窗口不能确认或取消新的尝试。授权成功不自动启用。断开同时停用,恢复中返回 202;通过 connection 查询 operation_id 进度。取消、停用和完整卸载保留已确认授权,完整卸载后重装默认关闭。 403/404 表示无权或不可用;409 表示冲突或操作未完成;412 要求刷新版本后确认意图;428 表示缺少版本;503 表示依赖暂不可用。失败不代表状态已重置,不要自动发起新授权。

English usage

授权写操作以 auth_revision 作为 If-Match,安装与启停等生命周期操作使用 state_etag。只确认当前授权尝试和所选连接。授权不会自动启用连接器;断开会停用连接器,等待恢复处理时可能返回 202。不要持久保存授权会话令牌或服务提供方凭据。