读取沙箱管理详情¶
读取一个可管理的托管沙箱,并应用已保存的网络覆盖配置。
GET https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes/{id}
调用前准备¶
准备当前环境有效身份、已配置的管理员资格和可用鉴权工作区;工作区Owner或Genesis的taas:admin并不自动等于这类管理员。示例使用个人访问令牌与唯一 X-Workspace-ID。见AI Studio。
404也可能是临时/池或被业务创建/删除意图隐藏;单次404不能证明所有远端资源、凭据和Ownership都已清理。update_available:null保留未知含义。
请求参数¶
curl --get "https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes/sandbox-example" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $AUTH_WORKSPACE_ID"
参数 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
示例是 |
当前环境有效个人访问令牌;需对应已配置管理员主体。Bearer等其他普通认证方式按环境确认。 |
|
string |
是 |
唯一非空鉴权工作区头;不是目标筛选或目标配额工作区。 |
|
string |
是 |
路径为沙箱ID。 |
成功响应¶
{
"code": "OK",
"msg": "OK",
"data": {
"workspace": {
"id": "target-workspace",
"owner_id": "owner-example"
},
"id": "sandbox-example",
"workspace_id": "target-workspace",
"user_id": "owner-example",
"name": "示例沙箱",
"phase": "ready",
"edge_agent_id": "sandbox-example",
"network_mode": "limited",
"network_tools": [
"curl"
],
"egress_endpoints": [
{
"host": "example.com",
"ports": [
443
]
}
],
"spec": "small",
"disk_gi": 10,
"created_at": "2026-11-12T06:00:00Z",
"updated_at": "2026-11-12T06:00:00Z",
"update_available": null
}
}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
成功为OK。 |
|
string |
成功为OK。 |
|
object |
成功数据。 |
|
object,可省略 |
可选管理投影。当前Provider至少提供ID/owner_id,不保证名称或账号名。 |
|
string |
对象标识;沙箱当前为远端资源名。 |
|
string |
资源所属工作区;不是鉴权头中的工作区。 |
|
string |
远端资源标签中的用户事实。 |
|
string |
展示名称。 |
|
string |
unknown、provisioning、ready、error或deleting;不是完整IAM清理状态。 |
|
string |
关联执行环境标识。 |
|
string |
当前定义limited或unrestricted;历史标签缺失可为空。本更新不切换模式。 |
|
string(字符串数组),可省略 |
工具出网允许列表;为空时可省略。 |
|
object(对象数组),可省略 |
显式host/ports出网允许列表;为空时可省略。 |
|
string |
规格投影;读取历史标签可为空,不以创建枚举推断历史必填。 |
|
integer |
磁盘GiB;远端标签缺失/不可解析时可为0,不代表可按0创建。 |
|
string,可省略 |
可选关联计算资源ID。 |
|
string |
创建时间,RFC3339。 |
|
string |
更新时间,RFC3339;不保证可用于并发版本控制。 |
|
boolean / null |
boolean或null;null表示当前镜像比较信息不足,不能当false。 |
嵌套对象的全部公开字段见公共对象,省略与null分别说明。
错误响应¶
{"code":"ErrParamInvalid","msg":"Bad Request"}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
当前阶段错误代码。 |
|
string |
错误文本,service分类通常本地化。 |
HTTP / code |
条件与处理 |
|---|---|
400 / ErrParamInvalid |
缺少鉴权工作区、请求解码/整数解析失败或配额字段无效。 |
400 / SANDBOX_INVALID_SPEC |
列表窗口或网络工具等service校验失败,名称虽含SPEC也不只指创建规格。 |
403 / COMPUTE_RESOURCE_SPEC_FORBIDDEN |
当前主体不是配置管理员或权限检查边界身份不匹配。 |
503 / COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE |
已分类的管理员目录/授权事实不可用。 |
404 / SANDBOX_NOT_FOUND |
非托管/临时/池资源,资源不存在,或处于被隐藏的创建/删除阶段。 |
503 / SANDBOX_IAM_UNAVAILABLE 或 SANDBOX_NETWORK_STORAGE_UNAVAILABLE |
生命周期身份或网络持久化依赖不可用。 |
500 / SANDBOX_ERROR 或 ErrServer |
未专门分类的Provider等失败,或本地化失败;不能一律写成503。 |
不同恢复阶段见错误与恢复。