> ## 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.

# Playtest

> 列出、取得、比較、建立、更新、發佈及刪除 XBOX 遊戲的試玩測試。

試玩測試可讓選定的玩家群組在發行之前試玩遊戲。`playtest` 命令會讀取 Partner Center 中遊戲的試玩測試，並可建立、更新、發佈及刪除試玩測試。`create`、`update`、`publish` 和 `delete` 在進行變更之前會先詢問。

`create`、`update`、`publish` 和 `delete` 為實驗性功能：其選項和輸出可能會變更或移除。請參閱[實驗性命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/cli-command-lifecycle.md)。

## 命令

| 命令 | 描述 |
| - | - |
| `playtest list` | 列出遊戲的試玩測試。 |
| `playtest get <playtest-id>` | 取得一個試玩測試：其詳細資料、套件、圖像、對象和 `etag`。 |
| `playtest diff <playtest-id>` | 將試玩測試與其最近一次發佈的版本或另一個試玩測試進行比較。 |
| `playtest create` | 建立私人草稿試玩測試 (實驗性)。 |
| `playtest update <playtest-id>` | 變更試玩測試。已發佈的試玩測試會回到草稿狀態 (實驗性)。 |
| `playtest publish <playtest-id>` | 發佈試玩測試 (這會從其開始日期起將試玩測試提供給其對象)，並等候直到它已排程或上線 (實驗性)。 |
| `playtest delete <playtest-id>` | 刪除試玩測試，並等候直到它已刪除 (實驗性)。 |

## 引數和選項

| 引數或選項 | 適用於 | 必要 | 描述 |
| - | - | - | - |
| `<playtest-id>` | `get`、`diff`、`update`、`publish`、`delete` | 是 | 來自 `list` 的 `playtestId`，例如 `11111111-2222-3333-4444-555555555555`。 |
| `--store-id <id>` | 全部 | 兩者之一 | 遊戲的 Store ID，例如 `9N0000000000`。 |
| `--xbox-title-id <id>` | 全部 | 兩者之一 | 遊戲的 XBOX 遊戲識別碼 (而非其 PlayFab 遊戲識別碼)，例如 `1234ABCD`。如果它未對應到任何遊戲或對應到多個遊戲，錯誤會列出應改為傳遞的 Store ID。 |
| `--compare-to <playtest-id>` | `diff` | 否 | 要比較的另一個試玩測試，而不是最近一次發佈的版本。 |
| `--name <name>` | `create`、`update` | `create` | 試玩測試的名稱，會向玩家顯示。不可空白。 |
| `--description <text>` | `create`、`update` | 否 | 簡短描述。在 `update` 上，`""` 會清除它。 |
| `--long-description <text>` | `create`、`update` | 否 | 詳細描述。在 `update` 上，`""` 會清除它。 |
| `--start <date>` | `create`、`update` | `create` | 試玩測試開始的時間。請參閱[日期](#dates)。 |
| `--end <date>` | `create`、`update` | `create` | 試玩測試結束的時間。必須晚於 `--start`。 |
| `--audience-id <id>` | `create`、`update` | 否 | 可以加入的對象，來自 [`audience list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/audience)。重複指定以加入更多對象。請參閱[選擇對象](#choosing-audiences)。 |
| `--pc-package-id <id>` | `create`、`update` | 否 | 玩家取得的 PC 套件。請參閱[套件](#packages)。 |
| `--console-package-id <id>` | `create`、`update` | 否 | 玩家取得的主機套件。請參閱[套件](#packages)。 |
| `--idempotency-key <key>` | `create` | 否 | 1 到 50 個可列印的 ASCII 字元，用來取代新的 GUID。請參閱[建立試玩測試](#creating-a-playtest)。 |
| `--if-match <etag>` | `update` | 否 | 只有在試玩測試仍具有來自 `playtest get` 的此 `etag` 時才更新。請參閱[更新試玩測試](#updating-a-playtest)。 |
| `--no-wait` | `publish`、`delete` | 否 | 發佈或刪除排入佇列後立即傳回。無法與 `--timeout` 合併使用。 |
| `--timeout <duration>` | `publish`、`delete` | 否 | 等候的時間長度，例如 `90s`、`10m` 或 `2h`。預設為 `5m`；最多 `7d`。 |
| `--confirm` (`--yes`、`-y`) | `create`、`update`、`publish`、`delete` | 否 | 略過確認提示。未指定此選項且沒有終端機時，命令會拒絕進行變更。 |
| `--seller-id <id>` | 全部 | 若未儲存 | Partner Center 賣方 ID。請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。 |
| `--base-url <url>` | 全部 | 否 | 要求的基底 URL，會覆寫 `XboxPartner:BaseUrl` 設定索引鍵。 |
| `--output <format>` | 全部 | 否 | `json` (預設)、`json-compact` 或 `table`。`create`、`update`、`publish` 和 `delete` 會拒絕 `table`。 |

## 範例

列出試玩測試、取得其中一個，並比較兩個：

```bash theme={null}
xbox playtest list --store-id 9N0000000000
xbox playtest list --xbox-title-id 1234ABCD --output table
xbox playtest get 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
xbox playtest diff 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --compare-to 22222222-3333-4444-5555-666666666666 --output table
```

為對象建立試玩測試：

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976
```

變更試玩測試的結束日期：

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

發佈試玩測試：

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

刪除試玩測試：

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

## 讀取試玩測試

`playtest list` 會寫入 `playtests` 陣列。其表格有 `PLAYTEST ID`、`NAME`、`STATUS`、`TYPE`、`START` 和 `END` 欄。摘錄如下：

```json theme={null}
{ "playtests": [ { "playtestId": "11111111-2222-3333-4444-555555555555", "name": "Alpha", "status": "Live", "type": "Private" } ] }
```

`playtest get` 會依服務傳回的內容寫入試玩測試。`etag` 是要傳遞給 `update --if-match` 的版本，而 `audiences.audienceIds` 會列出可以加入的對象。其表格有 `FIELD` 和 `VALUE` 列。

`playtest diff` 會寫入 `hasDiffData`、`current` 和 `compared`。當 `hasDiffData` 為 `false` 時，表示沒有可比較的內容，並會省略 `compared`。其表格只會在 `FIELD`、`CURRENT` 和 `COMPARED` 欄中顯示不同的欄位。圖像不會進行比較。

## 建立試玩測試

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15
```

`playtest create` 會建立私人草稿試玩測試，並以與 `playtest get` 相同的方式寫入它。再次執行它會建立另一個試玩測試；請使用 [`playtest delete`](#deleting-a-playtest) 移除您不需要的試玩測試。

每次建立都會傳送等冪索引鍵；除非您傳遞 `--idempotency-key`，否則它會是新的 GUID。重複使用某個索引鍵的建立，會傳回該索引鍵所建立的試玩測試，並忽略任何不同的選項。

當結果不明時 (例如發生逾時之後)，命令會以 `3` 結束，並列印以相同索引鍵重試的命令：

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --idempotency-key 11111111-2222-3333-4444-555555555555
```

如果第一個要求已建立試玩測試，重試會傳回該試玩測試，否則會建立它。當選項包含換行符號時，只會列印索引鍵；請搭配 `--idempotency-key` 和該索引鍵執行相同的命令。如果重試遭到拒絕 (例如因為結束日期已過)，請先檢查 `playtest list`，再以新的索引鍵建立試玩測試。

## 套件

試玩測試可以有一個 PC 套件和一個主機套件。請從 [`xbox package list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/package#listing-packages) 選擇已準備好用於試玩測試的套件，並將其 `id` 傳遞給其平台的選項：

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --pc-package-id 11111111-2222-3333-4444-555555555555
```

在 `update` 上，您省略的套件選項會保留其套件，新的 ID 會取代它，而 `""` 會移除它：

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --pc-package-id 22222222-3333-4444-5555-666666666666 --console-package-id ""
```

## 更新試玩測試

> [!WARNING]
>
> 任何更新都會讓已發佈的試玩測試回到草稿狀態，就像在 Partner Center 中編輯它一樣。請使用 `playtest publish` 再次發佈它，讓玩家可以使用。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

`playtest update` 只會變更您傳遞的選項，且至少需要一個選項。它會以與 `playtest get` 相同的方式寫入更新後的試玩測試。在 Partner Center 中設定的遊戲美術圖案會保留；連結至試玩測試的其他美術圖案則會以預留位置取代。

若要避免覆寫其他人的變更，請在 `--if-match` 中傳遞來自 `playtest get` 的 `etag`。其周圍的雙引號為選用，而 `*`、弱式 (`W/`) etag 和 etag 清單會遭到拒絕：

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30 --if-match 0x8DD1234ABCD5678
```

當結果不明時，命令會以 `3` 結束。請先使用 `playtest get` 檢查試玩測試，再重試。

## 選擇對象

對象是賣方在 Partner Center 中管理的玩家群組，例如測試人員。請將來自 [`audience list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/audience) 的 `id` 傳遞給 `--audience-id`，並重複指定以加入更多對象：

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976 --audience-id 1152921504606846977
```

未指定 `--audience-id` 時，`create` 會建立沒有對象的試玩測試，而 `update` 會保留現有對象。在 `update` 上，您傳遞的 ID 會取代試玩測試的所有對象。若要移除每個對象，請只傳遞 `""`：

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --audience-id ""
```

`""` 無法與對象 ID 合併使用，且 `create` 會拒絕它。試玩測試至少需要一個對象才能發佈。

## 發佈試玩測試

如果遊戲使用 XBOX services，請在發佈之前設定其設定和禁運。請參閱[在試玩測試中使用 XBOX services](https://docs.xbox.com/zh-TW/tools/xbox-cli/xbox-services-in-a-playtest.md)。

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

發佈會從試玩測試的開始日期起，將其提供給其對象。命令會發佈它最先讀取的版本；如果試玩測試在這之間有所變更，發佈會失敗並傳回 `412`，且不會變更任何內容。

在要求您確認之前，命令會檢查遊戲的 XBOX services 設定 (例如其禁運日期是否晚於試玩測試的結束日期)，並在 stderr 上列出任何需要檢閱的項目。這些檢查僅供參考；`--confirm` 會直接發佈而不詢問。

接著，服務會執行自己的檢查。當其中一項檢查封鎖發佈時，不會將任何內容排入佇列，而命令會在 stderr 上列出每項檢查，並以 `1` 結束。請修正錯誤，然後再次發佈。因缺少年齡分級而遭封鎖的試玩測試，需要在 Partner Center 中完成年齡分級問卷。

發佈排入佇列後，命令會等候直到試玩測試為 `Scheduled`、`Live` 或 `PublishFailed`，並以與 `playtest get` 相同的方式寫入它。按下 Ctrl+C 會停止等候，但發佈會繼續進行。搭配 `--no-wait` 時，命令會在發佈排入佇列後立即寫入 `publishJobId` 和任何 `warnings`；請使用 `playtest get` 追蹤它。

| 結束代碼 | 意義 |
| - | - |
| `0` | 試玩測試為 `Scheduled` 或 `Live`。搭配 `--no-wait` 時，表示發佈已排入佇列。 |
| `1` | 未發佈，例如因為某項檢查封鎖了它，或試玩測試已變更。 |
| `2` | 發佈失敗：試玩測試為 `PublishFailed`。 |
| `3` | 要求已傳送，但其結果不明。請先使用 `playtest get` 檢查試玩測試，再重新發佈。 |
| `4` | 發佈已排入佇列，但等候在發佈完成之前結束。請使用 `playtest get` 檢查它。 |

## 刪除試玩測試

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

`playtest delete` 會刪除它最先讀取的試玩測試版本。它會等候直到試玩測試為 `Deleted` 或已消失，然後寫入服務的回應 (含 `status`)。按下 Ctrl+C 會停止等候，但刪除會繼續進行。搭配 `--no-wait` 時，它會在刪除排入佇列後立即寫入回應。發生 `412` 之後，刪除可能已排入佇列，因此請等候一分鐘，並先使用 `playtest get` 檢查，再重新刪除。

| 結束代碼 | 意義 |
| - | - |
| `0` | 已刪除。搭配 `--no-wait` 時，表示刪除已排入佇列。 |
| `1` | 未刪除，例如因為試玩測試已變更，或其狀態不允許刪除。 |
| `3` | 要求已傳送，但其結果不明。請先使用 `playtest get` 檢查試玩測試，再重新刪除。 |
| `4` | 刪除已排入佇列，但試玩測試在等候結束之前尚未成為 `Deleted`。請使用 `playtest get` 檢查它。 |

## 日期

`--start` 和 `--end` 接受 ISO 8601 日期和時間，例如 `2026-11-01T09:00:00-07:00` 或 `2026-11-01T16:00:00Z`。沒有時間的日期表示 UTC 午夜，而沒有時差的時間為 UTC。當更新只傳遞一個日期時，服務會將它與試玩測試的另一個日期進行比對檢查。

## 錯誤

除非上述結束代碼表格另有說明，否則失敗會寫入 stderr 並以 `1` 結束。`create` 和 `update` 在結果不明時會以 `3` 結束。服務傳回的失敗會包含其 HTTP 狀態，而 `--verbose` 會加入服務的回應，其 `code` 欄位如下所示：

| 狀態 | `code` | 意義 |
| - | - | - |
| 400 | `invalid_playtest_request` | `create` 或 `update` 傳送了無效的要求，例如結束時間不晚於開始時間。 |
| 400 | `playtest_audience_not_found` | 某個 `--audience-id` 不是賣方的對象之一。訊息會顯示用於檢查的 `audience list` 命令。 |
| 400 | `playtest_package_not_found` | 遊戲沒有具有該 ID 的套件。 |
| 400 | `playtest_package_ambiguous` | 套件 ID 對應到多個套件集，且其中沒有任何一個位於遊戲的 Main 分支上，或對應到多個市場群組，且其中沒有任何一個是 `default`。 |
| 400 | `playtest_package_platform_mismatch` | 套件與其選項的平台不符，例如在 `--pc-package-id` 中指定了主機套件。請使用 `xbox package list` 檢查其平台。 |
| 400 | `playtest_request_rejected` | Partner Center 拒絕了要求，例如結束日期已過或套件尚無法用於試玩測試的 `create` 或 `update`，或對已刪除之試玩測試執行的 `publish`。 |
| 403 | `audience_permission_denied` | 您在沒有賣方 Partner Center 客戶群組讀取權限的情況下傳遞了 `--audience-id`。未變更任何內容。請向 Partner Center 帳戶的管理員要求存取權。 |
| 403 | `package_permission_denied` | 在 `list`、`get` 和 `diff` 上，表示您沒有遊戲的套件讀取權限 (開發人員角色包含此權限)。在其他命令上，表示您沒有變更遊戲試玩測試的權限。請向 Partner Center 帳戶的管理員要求存取權。 |
| 403 | `playtest_not_enabled` | 遊戲和賣方未啟用試玩測試，或服務目前無法檢查。如果應該已啟用，請稍後再試。 |
| 404 | `playtest_not_found` | 遊戲沒有具有該 ID 或 `--compare-to` ID 的試玩測試。訊息會顯示用於檢查的 `playtest list` 命令。 |
| 404 | `game_not_found` | 賣方沒有具有該 Store ID 的遊戲。請檢查 `--store-id` 和 `--seller-id`。 |
| 409 | `playtest_not_editable` | 試玩測試的狀態目前不允許 `update`，例如正在發佈時。請使用 `playtest get` 檢查它。 |
| 409 | `playtest_ended` | 試玩測試已結束，且 `update` 未傳遞 `--end`。請在變更中傳遞未來的 `--end`。 |
| 409 | `playtest_not_publishable` | 試玩測試的狀態不允許 `publish`，或它在讀取後已變更。請使用 `playtest get` 檢查它。 |
| 409 | `playtest_not_deletable` | 試玩測試的狀態不允許 `delete`。請使用 `playtest get` 檢查它。 |
| 412 | `playtest_precondition_failed` | 試玩測試在讀取後已變更。若為 `update`，請執行 `playtest get`、檢查您的變更是否仍然適用，然後以新的 `etag` 重試。若為 `publish` 和 `delete`，請檢查試玩測試並重試。 |
| 422 | `playtest_publish_blocked` | 服務的發佈檢查失敗，因此未將任何內容排入佇列。命令會列出每項檢查。 |

對於其他失敗，命令會顯示服務的訊息。429 表示您傳送了過多要求；請依照訊息所述的時間等候，然後再試一次。


## Related topics

- [使用 Playtest](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/playtest-preview.md)
- [Playtest 概觀](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/playtest.md)
- [發行前測試選項](https://docs.xbox.com/zh-TW/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-prerelease.md)
- [產品變更和內容更新](https://docs.xbox.com/zh-TW/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-post-release-lifecycle.md)
- [沙箱](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/sandboxes.md)
