创建 Sandbox 实例

创建一个连接真实供应商、会产生费用的 Sandbox。获取报价不会创建资源；只有调用本接口后， 服务才会预留费用并开始供应实例。 ## 选择创建方式 `selection` 中必须且只能提供以下一种方式： | 方式 | 适用场景 | 需要注意 | | --- | --- | --- | | `quoteId` | **推荐。** 先按能力、资源和预算调用 `POST /v1/quotes`，确认匹配结果后立即创建 | 报价有效期较短且只用于一个业务创建；过期或对应 offering 已变化时需要重新报价 | | `offeringId` | 已通过 `GET /v1/offerings` 确认并希望固定使用某个具体规格 | 不会按 requirements 重新选择，也没有 `maxEstimatedHourlyUsd` 创建时价格上限 | | `requirements` | 希望服务在创建时动态选择兼容 offering，或允许供应商/规格变化 | 可同时提供 `maxEstimatedHourlyUsd` 作为硬性价格上限；没有兼容规格时返回 `404` | `maxEstimatedHourlyUsd` 只适用于 `requirements` 方式。需要 Shell、文件、端口或 GPU 时， 应显式声明相应 capability/资源，不要假设所有 offering 都支持。 ## 幂等重试 每次业务创建生成一个稳定且唯一的 `idempotencyKey`（最长 160 个字符），并在请求超时、 连接中断或未收到响应时复用同一个值。这样可以取回同一次创建，而不是误建第二个计费实例。 - 同一个业务创建重试：复用原 key，并保持 `selection`、`policy` 等创建参数不变。 - 新建另一个实例：使用新的 key。 - 使用 `quoteId` 时，同一 key 的重试可复用该报价；不同 key 复用同一报价会返回 `409`。 - 同一 key 搭配不兼容的选择或策略：返回 `409 Conflict`。 ## `202 Accepted` 之后 `202` 仅表示服务已受理创建请求。响应会立即返回实例 `id`，此时 `observedState` 通常是 `PROVISIONING`，**还不能执行命令或读写文件**。 1. 立即保存响应中的 `id`，它也是后续查询、操作和清理实例的唯一标识。 2. 轮询 `GET /v1/sandboxes/{id}`，例如每 2 秒一次，并设置客户端总超时（建议不超过 5 分钟）。 3. `RUNNING` 表示实例已就绪；只有此时才能调用 exec、files 或 ports 接口。 4. `FAILED` 或 `TERMINATED` 是终态，不能继续等待 `RUNNING`；应查看操作与事件审计定位原因。 5. 客户端等待超时不代表实例没有创建。先按 `id` 查询并清理，不要换新 key 盲目重试。 ## 计费与清理 创建前服务会检查账户余额并预留初始运行费用及关机费用，余额不足返回 `402`。 供应中或运行中的实例都可能产生费用；响应中的初始 `totalCost` 为 `0` 不代表后续免费。 将 `POST /v1/sandboxes/{id}/terminate` 放在 `finally` 中，并继续轮询实例，直到 `observedState` 为 `TERMINATED` 或 `FAILED`。最后读取 `totalCost`、operations、events、 usage segments 和 billing periods，确认没有开放账期或遗留活动实例。 ## 常见失败 - `400`：选择方式不合法、requirements 无效、quote 无效/过期，或 offering 不支持 `resumeOnAccess`。 - `402`：余额不足，无法完成初始费用预留。 - `404`：offering 不可用，或 requirements 没有匹配的 offering。 - `409`：报价对应的 offering 已变化、报价被另一业务创建使用、达到活动实例上限、幂等参数冲突，或供应商暂时不能创建。 - `429`：请求过快；遵循响应中的重试提示，并继续复用原 `idempotencyKey`。