Skip to main content

查询沙箱状态与桌面地址

千问办公企业旗舰版开发者文档:查询沙箱状态与桌面地址。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:GET/api/openapi/app/v1/sessions/sandboxes/{sandbox_id}/info
显示会话产物中的网页预览或浏览器窗口前,查询对应沙箱的当前状态和最新桌面访问地址。该查询不启动、暂停、恢复或续期沙箱。

请求参数

参数位置类型必填说明
sandbox_idpathstring是产物事件中的完整沙箱 ID。保留 qw- 等前缀,不使用 session_id 替代。
请求不包含请求体。接口不接受 Agent 凭据或管理后台 API Key。 当前用户必须拥有一条未删除、且绑定该沙箱 ID 的会话。知道沙箱 ID 不代表具有访问权限,调用方不得自行构造可信用户身份头。

响应

HTTP说明
200返回当前沙箱快照。
401登录身份或可信入口认证未通过。
404沙箱不存在、无权访问,或上游沙箱句柄已释放;这些情况使用相同状态码。
422请求校验失败,具体原因见错误响应。
500获取归属或沙箱信息时发生服务错误。
503当前部署未接通所需的归属查询或沙箱信息服务。
媒体类型:application/json。成功响应携带 Cache-Control: no-store。

响应 200 SandboxInfo

字段类型必填说明
sandbox_idstring是本次查询对应的完整沙箱 ID。
vnc_urlstring是最新授权桌面访问地址;没有可用桌面时为空字符串。该地址为临时地址,不应持久保存。
statestring是当前状态,已知值为 RUNNING、PAUSED、RELEASED。出现未知状态时按暂不可用处理。
{
  "sandbox_id": "qw-example-sandbox",
  "vnc_url": "https://preview.example.com/vnc?ticket=example-ticket",
  "state": "RUNNING"
}

错误响应 ErrorBody

字段类型必填说明
codestring是稳定的机器可读错误码,用于区分同一 HTTP 状态下的不同错误。
messagestring是可读错误说明,文案可能变化。
detailJSON 值或 null是与错误码相关的结构化上下文,无附加信息时为 null。
trace_idstring是请求的追踪标识,反馈问题时用于定位请求。

状态与访问地址处理

  • RUNNING:可继续展示对应预览;只有 vnc_url 非空时才使用该地址打开桌面。
  • PAUSED:显示暂停状态,不把此次查询当作恢复操作。
  • RELEASED:沙箱已释放,停止使用此前的预览或桌面地址;沙箱句柄消失时也可能直接返回 404。
  • 认证失败或 500、503 等临时错误不能证明沙箱已释放,应先处理登录或服务故障,再重新查询。
重新打开桌面时重新查询地址,不复用历史产物中保存的旧 VNC URL。访问地址可能携带临时凭据,不将其写入日志或持久存储。