# 更新目标工作区沙箱配额

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

部分更新目标工作区的托管/临时上限和自动临时沙箱覆盖值。

```text
PATCH https://api.moi.matrixorigin.cn/v5/admin/workspaces/{id}/sandbox-quota
```

## 调用前准备

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

更新配额本身不删除已有沙箱，也不证明Provider已启用。没有这些接口管理员完整配额GET接口；普通quota读取不含max_ephemeral_count/auto_ephemeral_override，不能作完整恢复备份。修改前由负责人确认原存储值或已保存的完整可信配置，不为读出旧值先发写请求。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X PATCH "https://api.moi.matrixorigin.cn/v5/admin/workspaces/target-workspace/sandbox-quota" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $AUTH_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{"max_managed_count":0,"auto_ephemeral":"inherit"}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `X-API-Key` | string | 示例是 | 当前环境有效个人访问令牌；需对应已配置管理员主体。Bearer等其他普通认证方式按环境确认。 |
| `X-Workspace-ID` | string | 是 | 唯一非空鉴权工作区头；不是目标筛选或目标配额工作区。 |
| `id` | string | 是 | 目标工作区路径ID；与鉴权头分别传递。 |
| `max_managed_count` | integer / null | 至少一有效字段 | 0至100，显式0有效；省略/null保留旧值。 |
| `max_ephemeral_count` | integer / null | 至少一有效字段 | 0至100，临时上限独立于托管上限；省略/null保留。 |
| `auto_ephemeral` | string / null | 至少一有效字段 | inherit、enabled、disabled；省略/null保留，空字符串无效。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace_id": "target-workspace",
    "max_managed_count": 0,
    "max_ephemeral_count": 10,
    "auto_ephemeral_override": 0,
    "updated_by": "admin-example",
    "updated_at": "2026-11-12T06:00:00Z"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功为OK。 |
| `msg` | string | 成功为OK。 |
| `data` | object | 成功数据。 |
| `data.workspace_id` | string | 资源所属工作区；不是鉴权头中的工作区。 |
| `data.max_managed_count` | integer | 托管沙箱上限，0至100；0可持久化，不立即删除已有资源。 |
| `data.max_ephemeral_count` | integer | 临时沙箱独立上限，0至100；不是托管沙箱上限。 |
| `data.auto_ephemeral_override` | integer | 数字0继承部署默认，1启用，2停用；请求使用字符串auto_ephemeral。 |
| `data.updated_by` | string | 最近更新主体。 |
| `data.updated_at` | string | 更新时间，RFC3339；不保证可用于并发版本控制。 |

嵌套对象的全部公开字段见[公共对象](objects.md)，省略与null分别说明。
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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。 |

不同恢复阶段见[错误与恢复](errors-recovery.md)。
:::::
::::::
:::::::
