查询沙箱管理列表

按目标工作区筛选跨工作区托管沙箱;不是临时运行环境或池资源清单。

GET https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes

调用前准备

准备当前环境有效身份、已配置的管理员资格和可用鉴权工作区;工作区Owner或Genesis的taas:admin并不自动等于这类管理员。示例使用个人访问令牌与唯一 X-Workspace-ID。见AI Studio。

当前Provider每批最多200、扫描最多2000个远端条目。过滤临时/池/无工作区和隐藏的业务创建/删除意图后才应用offset;不承诺全量、稳定排序或一致性快照。has_more不是无限翻页保证。

请求参数

curl --get "https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0" \
  --data-urlencode "workspace_id=$TARGET_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $AUTH_WORKSPACE_ID"

参数

类型

是否必填

说明

X-API-Key

string

示例是

当前环境有效个人访问令牌;需对应已配置管理员主体。Bearer等其他普通认证方式按环境确认。

X-Workspace-ID

string

是

唯一非空鉴权工作区头;不是目标筛选或目标配额工作区。

limit

integer

否

默认50;显式0在service中也按50,合法范围1至200。

offset

integer

否

默认0、非负;还须满足offset+limit+1≤2000,不能写到1999就一定可用。

workspace_id

string

否

目标工作区过滤;省略跨工作区,区别于鉴权头。

成功响应

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "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
      }
    ],
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

字段

类型

说明

code

string

成功为OK。

msg

string

成功为OK。

data

object

成功数据。

data.items

object(对象数组)

当前页托管沙箱数组,不包括临时/池资源。

data.limit

integer

本页上限;无total字段。

data.offset

integer

在过滤后的匹配集合中偏移。

data.has_more

string

可能还有结果;扫描达到预算时也可能为true,不保证可继续无界翻页。

data.items[].workspace

object,可省略

可选管理投影。当前Provider至少提供ID/owner_id,不保证名称或账号名。

data.items[].id

string

对象标识;沙箱当前为远端资源名。

data.items[].workspace_id

string

资源所属工作区;不是鉴权头中的工作区。

data.items[].user_id

string

远端资源标签中的用户事实。

data.items[].name

string

展示名称。

data.items[].phase

string

unknown、provisioning、ready、error或deleting;不是完整IAM清理状态。

data.items[].edge_agent_id

string

关联执行环境标识。

data.items[].network_mode

string

当前定义limited或unrestricted;历史标签缺失可为空。本更新不切换模式。

data.items[].network_tools

string(字符串数组),可省略

工具出网允许列表;为空时可省略。

data.items[].egress_endpoints

object(对象数组),可省略

显式host/ports出网允许列表;为空时可省略。

data.items[].spec

string

规格投影;读取历史标签可为空,不以创建枚举推断历史必填。

data.items[].disk_gi

integer

磁盘GiB;远端标签缺失/不可解析时可为0,不代表可按0创建。

data.items[].compute_resource_id

string,可省略

可选关联计算资源ID。

data.items[].created_at

string

创建时间,RFC3339。

data.items[].updated_at

string

更新时间,RFC3339;不保证可用于并发版本控制。

data.items[].update_available

boolean / null

boolean或null;null表示当前镜像比较信息不足,不能当false。

嵌套对象的全部公开字段见公共对象,省略与null分别说明。

错误响应

{"code":"ErrParamInvalid","msg":"Bad Request"}

字段

类型

说明

code

string

当前阶段错误代码。

msg

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。

不同恢复阶段见错误与恢复。

最后更新于