> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙盒

> 列出、获取和创建已登录的开发人员可用的 XBOX 沙盒。

XBOX 沙盒是 Partner Center 帐户中用于 Microsoft Store
产品和 XBOX 服务的隔离环境。全局沙盒(例如 `RETAIL`)由 Microsoft 管理;
开发沙盒(例如 `ABCDEF.1`)属于你的帐户。请参阅游戏发布指南中的
[沙盒](https://learn.microsoft.com/gaming/game-publishing/concepts/sandboxes)。若要切换 Windows 电脑使用的沙盒,请参阅[电脑](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/pc.md)。

每个命令都作用于一个卖家,该卖家来自 `--seller-id` 或你已保存的卖家;请参阅
[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。如果它不是你上次在 Partner Center 中选择的卖家,请参阅
[此已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md#xbox-sandbox-commands-show-only-global-sandboxes)。

## 命令

| 命令 | 说明 |
| - | - |
| `sandbox list` | 列出卖家的沙盒和全局沙盒,与 Partner Center 的“沙盒”页面中显示的相同。 |
| `sandbox get <sandbox-id>` | 获取一个沙盒(包括全局沙盒或隔离沙盒):其 ID、类型、所属卖家以及是否为全局沙盒。 |
| `sandbox create <sandbox-id>` | 创建共享开发沙盒,然后等待其创建作业。 |

## 参数和选项

| 参数或选项 | 适用于 | 必需 | 说明 |
| - | - | - | - |
| `<sandbox-id>` | `get`、`create` | 是 | 沙盒 ID,例如 `ABCDEF.1`。不区分大小写。请参阅[沙盒 ID](#sandbox-ids)。 |
| `--seller-id <id>` | 全部 | 如果未保存 | Partner Center 卖家 ID。 |
| `--base-url <url>` | 全部 | 否 | 请求的基 URL,覆盖 `XboxPartner:BaseUrl` 配置键。 |
| `--confirm`, `--yes`, `-y` | `create` | 否 | 创建沙盒,不显示确认提示。 |
| `--output <format>` | 全部 | 否 | `json`(默认)或 `json-compact`;`table` 仅适用于 `list` 和 `get`。 |

请将 `list` 中的 `sandboxId` 传递给其他命令,例如 [`xbl`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl) 命令的
`--sandbox-id` 选项。

### 沙盒 ID

沙盒 ID 由字母和数字组成,可带有以句点分隔的可选后缀,最多 64
个字符。CLI 会将其转换为大写。

* `get` 接受任何沙盒 ID,包括全局沙盒 ID,例如 `RETAIL` 和 `CERT.DEBUG`。
* `create` 需要 4 到 60 个字母或数字、一个句点,以及一个从 `0` 到 `999` 且不带前导零的数字,例如 `ABCDEF.1`。后缀 `.58` 保留给隔离沙盒,并且不能使用
  `UNDEFINED` 和全局沙盒名称。

## 输出

`sandbox get` 写入一个沙盒:

```json theme={null}
{ "sandboxId": "ABCDEF.58", "type": "Isolated", "sellerId": "1234567", "global": false }
```

| 字段 | 说明 |
| - | - |
| `sandboxId` | 沙盒 ID。 |
| `type` | `Shared`、`Isolated` 或 `Unknown`。`create` 仅创建共享沙盒。 |
| `sellerId` | 所属卖家;对于全局沙盒为 `null`。 |
| `global` | 对于全局沙盒(例如 `RETAIL`)为 `true`。 |

`sandbox list` 写入一个由相同对象组成的 `sandboxes` 数组:

```json theme={null}
{
  "sandboxes": [
    { "sandboxId": "RETAIL", "type": "Shared", "sellerId": null, "global": true },
    { "sandboxId": "ABCDEF.1", "type": "Shared", "sellerId": "1234567", "global": false }
  ]
}
```

`list --output table` 包含 `SANDBOX`、`TYPE` 和 `GLOBAL` 列,`get --output table` 包含
`SANDBOX ID`、`TYPE` 和 `SELLER ID` 列。`create` 拒绝 `--output table`。

## 创建沙盒

```bash theme={null}
xbox sandbox create ABCDEF.1 --seller-id 1234567 --confirm
```

`sandbox create` 会在创建沙盒之前进行询问;如果没有终端,则需要 `--confirm`。
CLI 无法删除沙盒。如果你属于多个卖家,请先查看
[该已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md#xbox-sandbox-commands-show-only-global-sandboxes):沙盒可能会在其他卖家中创建。

该命令只发送一次请求,并最多等待两分钟以完成创建作业。作业成功后,它会以与 `sandbox get` 相同的结构写入新沙盒。作业 ID、关联 ID 以及接下来要检查的内容会输出到 stderr。当退出代码为 `3` 或 `4` 时,请使用
`sandbox get <sandbox-id>` 进行检查,不要再次创建沙盒。

| 退出代码 | 含义 |
| - | - |
| `0` | 已创建沙盒。 |
| `1` | 未创建沙盒:输入或确认被拒绝、请求未发送,或者服务拒绝了请求(例如沙盒已存在时返回 `409`)。请解决问题,然后再次运行该命令。 |
| `2` | 创建作业失败。作业及其 `errors` 会写入 stdout。 |
| `3` | 请求已发送,但结果未知。请使用 `sandbox get` 进行检查。 |
| `4` | 作业已被接受,但等待在确认沙盒之前结束。不会向 stdout 写入任何内容。请使用 `sandbox get` 进行检查。 |

## 错误

无论 `--output` 是什么,失败时都会向 stderr 写入文本:关联 ID、针对 HTTP 状态的指导,以及服务的错误详细信息(如果有)。`--verbose` 会添加响应正文。脚本应根据退出代码而不是措辞进行分支。

## 示例

列出沙盒,并获取其中两个:

```bash theme={null}
xbox sandbox list --output table
xbox sandbox get ABCDEF.1
xbox sandbox get RETAIL
```

创建沙盒,不显示确认提示:

```bash theme={null}
xbox sandbox create ABCDEF.2 --seller-id 1234567 --confirm --output json-compact
```


## Related topics

- [沙盒](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/sandboxes.md)
- [设置沙盒](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes.md)
- [高级 XBOX 服务沙盒](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/sandboxes/live-advanced-sandboxes.md)
- [XBOX 服务沙盒概述](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [创建和管理开发沙盒](https://docs.xbox.com/zh-CN/publishing/game-publishing/how-to/how-to-create-and-manage-sandboxes.md)
