Skip to main content

调用流程

千问办公企业旗舰版开发者文档:调用流程。

APP 完整调用流程

全流程图

从接入到任务结果,按下图组织调用。文件、技能和语音按需准备;立即执行与计划执行是两个入口,最终都通过会话状态、事件和产物确认结果。图中的模块名称对应左侧目录,具体字段与错误码以单接口文档为准。
调用流程
实线表示主要调用顺序;虚线表示可选操作或恢复路径。问题反馈可独立提交,日志采集为可选步骤。文件管理、技能管理和积分查询也可以独立使用,不要求先创建会话。

1. 完成接入并确认用户与额度

认证方式见APP开发者文档 → 认证接入。 通过 GET /api/openapi/app/v1/quota 展示本人额度,通过 GET /api/openapi/app/v1/sessions/session-modes 查询可用档位。展示不替代执行时的权限与余额校验;不要写死模型 ID。

2. 按需准备资源和输入

功能调用顺序交给后续步骤的结果
技能与专家套件查询目录和详情 → 查询安装、偏好状态 → 按需安装并启用;卸载和停用使用各自接口保存资源标识,消费服务端可用状态;安装登记不等于本轮已加载
市场连接器查询详情与 connection → 按需安装 → 发起 connect-session → 用户完成授权 → complete → 再查 connection → 按需启用授权状态与启用状态分别判断;可取消授权尝试,断开授权会停用连接器
内置连接器查询列表、详情 → 添加 → 按类型配置或 OAuth 授权 → 查询状态当前 can_use 为 false;配置或授权成功不能当作沙箱已可执行
已有文件浏览目录或搜索 → GET / HEAD 文件确认 → 按需复制、重命名或建立目录file_id 用于稳定定位;Session 附件按契约传 path,计划附件按其字段传 oss_id,不能直接互换
新文件查询 drive/quota → 申请 direct-uploads → 向 OSS PUT 文件或分片 → complete 登记;放弃时取消未完成上传完成响应中的 file;只上传 OSS 字节尚不能作为已登记附件使用
语音输入建立 voice-input/stream WebSocket → 上传 PCM → finish → 收齐 final 和 finished → 调用润色 → 用户确认文本输入框草稿;不创建会话,不自动发送,失败时不采用未完成转写
技能与连接器写操作按接口要求携带版本及幂等键:安装/偏好使用 state_etag,授权使用 auth_revision,不可混用。412/428 时先读取最新状态;不可把 unknown 当成未安装或未启用。 文件字节只通过 OSS 直传;向 OSS 发请求使用返回的 URL 与 headers,不附带业务认证凭据。下载同样使用文件接口返回的有效 presigned_url。

3. 选择立即执行或计划执行

入口调用顺序关键语义
新会话立即执行POST /api/openapi/app/v1/sessions,提交 initial_prompt首条指令随创建开始执行,不再重复发送;保存 session_id,成功响应不代表任务完成
继续已有会话查询本人会话 → POST /api/openapi/app/v1/sessions/{session_id}/prompt空闲时执行,忙碌时可能排队;通过事件和队列确认
计划执行POST /api/openapi/app/v1/scheduler/tasks → 查询任务及 next_fire_at → 到期由服务端触发 → 查询 executions 和关联 sessions用户无需在触发时保持页面在线;从执行记录找到实际会话,再进入事件与结果流程
计划支持单次、按天、按周、按月及已公开的 every 规则。Cron 应显式提供时区;周期规则有 0~59 秒固定错峰,停机错过多次时补执行一次,再安排未来触发,不启用日历过滤。 默认 isolated 每次触发创建新会话,同一次执行重试保持幂等;显式 bound 绑定本人已有会话,以独立 Turn 跟踪。任务可查询、编辑、暂停、恢复和删除;run-once 与 execution rerun 分别用于手动执行和重跑,返回接纳结果后仍需查询执行状态。

4. 跟随执行、处理交互和恢复连接

以 /api/openapi/app/v1/sessions 为共同前缀:
场景接口或通道客户端处理
实时进度GET /{session_id}/events/stream(SSE)持续保存 SSE id;连接结束不等于任务结束
等待用户回答POST /{session_id}/question-response按 pending_action 和接口字段回应,再跟随事件
追加指令POST /{session_id}/prompt只发送一次业务操作,保存返回标识,确认执行或入队
管理排队指令查询 prompt-queue,编辑或删除队列项只管理尚未执行的指令;删除队列项不等于取消当前执行
取消当前执行POST /{session_id}/cancel等待状态或事件确认取消结果,不将请求发出视为已停止
浏览器刷新或断线查询会话 → GET events 补历史 → 带 cursor 或 Last-Event-ID 恢复 SSE按事件标识去重;不重复创建会话,不把断线标成 Agent 失败
使用会话 SDKchat-ws 的 join / replay / live 与控制消息,notify-ws 的列表通知与 HTTP + SSE 按客户端方案选择,同一业务操作不要双通道重复发送
HTTP 历史与 SSE 使用同一 seq_id 游标空间,跨月不需要切换接口。语音 WebSocket 用于输入转写,与会话执行通道不同。

5. 读取结果与整理会话

查询会话状态、Turn 列表和单个 Turn,结合事件判断完成、失败或等待交互,再读取 output。产物包含沙箱 ID 时,可查询 sandboxes/{sandbox_id}/info 获取当前状态与最新桌面地址;不长期缓存旧地址。
功能调用方式边界
浏览历史会话列表、pinned、recent、children;读取 events、turns 和 output各列表按自己的分页契约读取,不混用 cursor 与 offset
整理会话修改名称、置顶/取消置顶、删除会话所有操作校验当前用户归属
整理计划结果查询任务关联会话、session-groups 及组内会话;按需删除分组清理会话分组不会暂停或删除计划,也不删除执行流水;停止未来触发需单独暂停或删除计划
文件后续管理文件详情、下载、复制、重命名、删除、目录和搜索只有已登记且有权访问的文件才能通过 drive 操作;不把任意沙箱产物直接当成网盘文件
继续工作时,向原会话发送新 prompt;需要独立上下文时,再创建新会话。

6. 积分与问题反馈

  • 积分明细调用 GET /api/openapi/app/v1/billings?source=all。当前页面对返回集合进行来源、正负金额筛选和前端分页;接口不支持 cursor。金额是精确十进制字符串,不能按 quota 的 minor 单位解释。余额与流水是不同查询,不将流水求和作为当前余额。
  • 问题反馈使用 /api/openapi/app/v1/feedback 员工浏览器入口:上传截图 → 可选采集会话日志 → 提交反馈 → 查询本人反馈历史。诊断包可选,采集失败不阻断正文和截图提交。排障关联信息不应包含凭据及敏感正文。

最小立即执行示例

示例使用认证接入定义的 appRequest。文件、档位等可选参数见“创建会话”接口页。
const response = await appRequest('/api/openapi/app/v1/sessions', {
  method: 'POST',

  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    initial_prompt: { text: '总结这份任务的执行步骤' },
    locale: 'zh-CN',
  }),
});
if (!response.ok) throw new Error(`创建会话失败:${response.status}`);
const session = await response.json();
// 保存 session_id,订阅事件并查询状态;不要再次发送同一条首轮指令。

失败与重试边界

读取操作可在可恢复错误下退避重试。创建、发送或派发请求超时不能推断服务端未接纳;优先查询已知资源和执行状态。仅在单接口明确支持时使用 Idempotency-Key,且按该接口要求复用原键、参数与版本。 401 处理登录态;403/404 检查权限、归属与资源状态;409/412/428 按对应接口处理冲突与版本;依赖失败不显示为零余额、空历史或任务成功。浏览器断线、上传对象完成、授权成功、计划接纳和任务执行完成是不同状态,分别由各自接口确认。