千问办公企业旗舰版开发者文档:查询沙箱状态与桌面地址。
认证方式见APP开发者文档 → 认证接入。
请求不包含请求体。接口不接受 Agent 凭据或管理后台 API Key。
当前用户必须拥有一条未删除、且绑定该沙箱 ID 的会话。知道沙箱 ID 不代表具有访问权限,调用方不得自行构造可信用户身份头。
媒体类型:
- 模块:会话服务(session)
- 接口:GET
/api/openapi/app/v1/sessions/sandboxes/{sandbox_id}/info
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| sandbox_id | path | string | 是 | 产物事件中的完整沙箱 ID。保留 qw- 等前缀,不使用 session_id 替代。 |
响应
| HTTP | 说明 |
|---|---|
| 200 | 返回当前沙箱快照。 |
| 401 | 登录身份或可信入口认证未通过。 |
| 404 | 沙箱不存在、无权访问,或上游沙箱句柄已释放;这些情况使用相同状态码。 |
| 422 | 请求校验失败,具体原因见错误响应。 |
| 500 | 获取归属或沙箱信息时发生服务错误。 |
| 503 | 当前部署未接通所需的归属查询或沙箱信息服务。 |
application/json。成功响应携带 Cache-Control: no-store。
响应 200 SandboxInfo
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sandbox_id | string | 是 | 本次查询对应的完整沙箱 ID。 |
| vnc_url | string | 是 | 最新授权桌面访问地址;没有可用桌面时为空字符串。该地址为临时地址,不应持久保存。 |
| state | string | 是 | 当前状态,已知值为 RUNNING、PAUSED、RELEASED。出现未知状态时按暂不可用处理。 |
错误响应 ErrorBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 是 | 稳定的机器可读错误码,用于区分同一 HTTP 状态下的不同错误。 |
| message | string | 是 | 可读错误说明,文案可能变化。 |
| detail | JSON 值或 null | 是 | 与错误码相关的结构化上下文,无附加信息时为 null。 |
| trace_id | string | 是 | 请求的追踪标识,反馈问题时用于定位请求。 |
状态与访问地址处理
RUNNING:可继续展示对应预览;只有vnc_url非空时才使用该地址打开桌面。PAUSED:显示暂停状态,不把此次查询当作恢复操作。RELEASED:沙箱已释放,停止使用此前的预览或桌面地址;沙箱句柄消失时也可能直接返回 404。- 认证失败或 500、503 等临时错误不能证明沙箱已释放,应先处理登录或服务故障,再重新查询。