> ## 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 services 使用。全域沙箱 (例如 `RETAIL`) 由 Microsoft 管理；開發沙箱 (例如 `ABCDEF.1`) 則屬於您的帳戶。請參閱遊戲發行指南中的[沙箱](https://learn.microsoft.com/gaming/game-publishing/concepts/sandboxes)。若要切換 Windows PC 使用的沙箱，請參閱 [PC](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/pc.md)。

每個命令都會作用於一個賣方，該賣方來自 `--seller-id` 或您已儲存的賣方；請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。如果那不是您上次在 Partner Center 中選取的賣方，請參閱[此已知問題](https://docs.xbox.com/zh-TW/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-TW/tools/xbox-cli/commands/xbl) 命令的 `--sandbox-id` 選項。

### 沙箱 ID

沙箱 ID 由字母和數字組成，可選擇加上以句點分隔的尾碼，最多 64 個字元。CLI 會將其轉換為大寫。

* `get` 接受任何沙箱 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-TW/tools/xbox-cli/known-issues.md#xbox-sandbox-commands-show-only-global-sandboxes)：沙箱可能會建立在另一個賣方中。

命令只會傳送一次要求，並最多等候建立作業兩分鐘。作業成功時，它會以與 `sandbox get` 相同的形式寫入新的沙箱。作業 ID、相互關聯識別碼以及接下來要檢查的項目會傳送到 stderr。當結束代碼為 `3` 或 `4` 時，請使用 `sandbox get <sandbox-id>` 進行檢查，不要再次建立沙箱。

| 結束代碼 | 意義 |
| - | - |
| `0` | 已建立沙箱。 |
| `1` | 未建立沙箱：輸入或確認遭到拒絕、要求未傳送，或服務拒絕了要求 (例如沙箱已存在時傳回 `409`)。請修正問題，然後再次執行命令。 |
| `2` | 建立作業失敗。作業及其 `errors` 會寫入 stdout。 |
| `3` | 已傳送要求，但結果不明。請使用 `sandbox get` 進行檢查。 |
| `4` | 作業已被接受，但等候在確認沙箱之前就已結束。不會寫入任何內容至 stdout。請使用 `sandbox get` 進行檢查。 |

## 錯誤

無論 `--output` 為何，失敗時都會將文字寫入 stderr：相互關聯識別碼、針對 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-TW/publishing/game-publishing/concepts/sandboxes.md)
- [設定沙箱](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes.md)
- [進階 XBOX 服務沙箱](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/sandboxes/live-advanced-sandboxes.md)
- [XBOX 服務沙箱概觀](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [建立及管理開發沙箱](https://docs.xbox.com/zh-TW/publishing/game-publishing/how-to/how-to-create-and-manage-sandboxes.md)
