千问办公企业旗舰版开发者文档:前端集成快速开始。
认证方式见APP开发者文档 → 认证接入。
本文串起客户后台、浏览器 HTTP、SSE 和三个 WS。完成后,客户后台只负责验证用户及取得用户凭据,业务流量由浏览器直接访问 QwenWork,不需要后台转发长连接。示例只查询现有会话,不创建任务或发送聊天指令。
将下面的 HTML 保存为 index.html,同目录保存 app-client.js 和下述 demo.js。开发期间使用客户自己的网页服务打开该页面。
以下三个 JavaScript 代码块依次放入 demo.js。错误显示到页面,示例不自动重放请求。
网络块不等于 SSE 帧:下面的解析器处理 UTF-8 分块、跨块换行、注释和多行 data,以空行结束一帧。断线后点击“订阅 SSE / 重连”,沿用该会话已成功处理的消息边界 id;首次演示从 0 补历史。正式应用可增加有上限的退避重连,但遇到鉴权失败、不可恢复错误或会话终止时应停止。
这里只把显示消息作为业务处理。正式应用应处理状态刷新、内容撤回与交互事件;回合结束不代表会话终止。不要把状态帧、HTTP 分页游标或错误里的 resume_from 写成已处理位置。cursor 与 Last-Event-ID 同传必须一致,否则 422;示例每次只传一种。fetch 不提供原生 EventSource 的自动重连行为。
HTTP + SSE 与聊天 WS 可按业务需求选择,不要通过两个通道重复发送同一条业务指令。以下示例聊天只执行 join,通知只执行 ping;语音使用用户选择的 16 kHz、单声道 PCM16LE 原始文件,不支持直接把 WAV、MP3 或 MediaRecorder 默认编码当作 PCM 发送。
聊天收到 join_ack、通知收到 init/pong、语音收到最终文本及 finished,才说明业务交互成功。示例仅演示一次连接;长期运行需按对应 WS 接口实现心跳、重放和到期重建。原生 WebSocket 连接失败时不能像 fetch 一样读取握手 HTTP 状态,不要仅凭 onerror 就判定凭据过期,也不要无限重取凭据。
浏览器退出或切换账号时停止请求和连接并重新加载页面;新账号重新读取后台凭据。对象存储直传使用签名 URL,其跨域策略独立维护,不能套用 APP 请求封装。
1. 准备客户后台与客户端模块
- 按“认证接入”配置应用权限和用户范围;测试用户须已激活、具备网页访问资格,并拥有至少一个会话。
- 在客户站点实现“认证接入”约定的 POST /api/app-token:验证自己的登录身份,从可信绑定读取 QID,再向 QwenWork 申请凭据。这个端点属于客户后台,不是 APP 业务接口;不要把后台密钥或任意用户选择权交给页面。
- 将“认证接入”中凭据读取、统一请求封装、WS 创建三个 JavaScript 代码块依次保存为客户站点的 app-client.js,设置其中的环境地址。它已包含凭据读取实现、内存缓存、并发合并和导出的三个函数。
- 页面与 /api/app-token 同源部署;不要直接双击 HTML 以 file 协议打开。HTTPS 页面连接 HTTPS/WSS 环境;如站点配置 CSP,connect-src 须允许目标 HTTPS 与 WSS Origin。
2. 建立最小页面并读取会话
将下面的 HTML 保存为 index.html,同目录保存 app-client.js 和下述 demo.js。开发期间使用客户自己的网页服务打开该页面。
3. 使用 fetch 订阅和恢复 SSE
网络块不等于 SSE 帧:下面的解析器处理 UTF-8 分块、跨块换行、注释和多行 data,以空行结束一帧。断线后点击“订阅 SSE / 重连”,沿用该会话已成功处理的消息边界 id;首次演示从 0 补历史。正式应用可增加有上限的退避重连,但遇到鉴权失败、不可恢复错误或会话终止时应停止。
4. 连接聊天、通知和语音 WS
HTTP + SSE 与聊天 WS 可按业务需求选择,不要通过两个通道重复发送同一条业务指令。以下示例聊天只执行 join,通知只执行 ping;语音使用用户选择的 16 kHz、单声道 PCM16LE 原始文件,不支持直接把 WAV、MP3 或 MediaRecorder 默认编码当作 PCM 发送。
5. 验收与排查
| 现象 | 检查位置 |
|---|---|
| 客户后台申请失败 | 当前登录身份、可信 QID 映射、应用用户范围和用户资格 |
| HTTP/SSE 浏览器报跨域错误 | OPTIONS 是否成功、实际响应是否有匹配的允许来源与请求头;不要关闭浏览器安全策略 |
| 跨域响应来源是具体域名 | 正常,允许任意来源的网关也可能返回当前 Origin;不要求响应字面值一定为星号 |
| HTTP 返回 401 / 403 | 分别检查凭据有效性、用户及资源权限;不要把可读取的拒绝响应当成 CORS 失败 |
| SSE 返回 422 | cursor 与 Last-Event-ID 是否冲突,是否误用其他游标 |
| SSE 已连接但没有新消息 | 可能暂时没有业务事件;检查补历史位置,不重复发送任务 |
| WS 仅建立连接 | 继续验证 join_ack、init/pong 或最终转写等实际业务结果 |