Skip to main content

发起连接器授权

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

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

请求参数

参数位置类型必填说明
originpathstring是沿用当前响应中的资源身份。
idpathstring是沿用当前响应中的资源身份。
If-Matchheaderstring是最近 auth_revision,禁止传 安装/启停 state_etag。
Idempotency-Keyheaderstring是8–128 字符,同请求重试保持相同键。

响应

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

WebassetsConnectResponse

字段类型必填说明
attempt_idstring是当前授权尝试 UUID,用于关联本次授权流程。
auth_revisionstring是授权状态版本;授权写操作按接口要求原样作为 If-Match 传入。
connect_linkstring是打开授权流程的链接,可能省略。
expires_atstring是本次授权会话的过期时间,按返回值使用。
provider_config_keystring是授权提供方配置标识,沿用服务端值,不自行拼接。
session_reissuedboolean是是否重新签发了本次授权会话。
state_etagstring是安装/启停状态版本;与 auth_revision 不可互换。
tokenstring是本次连接授权所需的临时 Token,按授权流程使用,勿记录或泄露。

使用说明

旗舰 Web 当前采用直接 OAuth + WebSocket 流程:connect_link 用于解析本环境授权服务 origin;不将它当作已开放的完整 Connect UI 页面。复用 SDK 在该 origin 建立根 WebSocket,收到 ws_client_id 后打开 /oauth/connect/{provider_config_key},携带本次限定 connect_session_token 和 ws_client_id;成功后回到 App 确认接口。仅公开授权入口,不公开管理、凭据和 privileged Session API。 写入携带 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。不要持久保存授权会话令牌或服务提供方凭据。