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

# 遊戲

> 列出賣方的 Partner Center 遊戲、查閱遊戲、建立遊戲，以及檢查其建立作業。

`game` 命令可列出賣方的 Partner Center 遊戲、依 Store ID、XBOX 遊戲識別碼或名稱查閱遊戲、建立遊戲，以及檢查其建立作業。

每個命令都會作用於一個賣方，該賣方來自 `--seller-id` 或您已儲存的賣方；請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。如果您屬於多個賣方，請參閱[此已知問題](https://docs.xbox.com/zh-TW/tools/xbox-cli/known-issues.md#xbox-game-commands-ignore---seller-id)：這些命令可能會使用另一個賣方。

## 命令

| 命令 | 描述 |
| - | - |
| `game list` | 列出賣方的所有遊戲。 |
| `game get` | 依 Store ID、XBOX 遊戲識別碼或名稱關鍵字取得遊戲。 |
| `game create` | 建立遊戲，然後等候其建立作業。 |
| `game job get` | 讀取遊戲建立作業的目前狀態。 |

## 引數

| 引數 | 命令 | 描述 |
| - | - | - |
| `[title-id]` | `get` | XBOX 遊戲識別碼：一到八個十六進位數字，可選擇加上 `0x` 前置詞，例如 `1234ABCD`。`42` 表示 `0x00000042`。 |
| `<job-id>` | `job get` | `game create` 列印的建立作業 ID。 |

## 選項

| 選項 | 命令 | 描述 |
| - | - | - |
| `--seller-id <id>` | 全部 | Partner Center 賣方 ID。 |
| `--base-url <url>` | 全部 | 要求的基底 URL，會覆寫 `XboxPartner:BaseUrl` 設定索引鍵。 |
| `--store-id <id>` | `get` | 遊戲的 Microsoft Store ID，例如 `9N0000000000`。可與 `title-id` 合併使用以縮小結果範圍。 |
| `--keyword <text>` | `get` | 尋找名稱包含此文字的遊戲，不區分大小寫。無法與 `title-id` 或 `--store-id` 合併使用。 |
| `-d`、`--details` | `list`、`get` | 每個遊戲顯示一個文字區塊。無法與 `--output` 合併使用。 |
| `--name <name>` | `create` | 必要。遊戲的名稱。 |
| `--supported-device <device>` | `create` | 必要。`xbox` 或 `desktop`；兩者都要時請重複指定此選項。 |
| `--sandbox-id <id>` | `create` | 遊戲的開發沙箱。它必須是現有的共用沙箱；[`sandbox get`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/sandbox) 會顯示沙箱的類型。 |
| `--confirm`、`--yes`、`-y` | `create` | 建立遊戲而不顯示確認提示。 |
| `--output <format>` | 全部 | `json` (預設) 或 `json-compact`；`table` 僅適用於 `list` 和 `get`。 |

`game get` 至少需要 `title-id`、`--store-id` 或 `--keyword` 其中之一。位置值一律為 XBOX 遊戲識別碼；當它看起來像 Store ID 時，錯誤會建議使用搭配 `--store-id` 的相同命令：

```text theme={null}
title-id must be one to eight hexadecimal digits, with an optional 0x prefix. 9N0000000000 looks like a Store ID. Did you mean:
  xbox game get --store-id 9N0000000000 --seller-id 1234567
```

## 列出和查閱

```bash theme={null}
xbox game list --output table
xbox game get --store-id 9N0000000000
xbox game get 1234ABCD --details
xbox game get --keyword "nod arena" --output table
```

`game list` 會傳回賣方的整個目錄，而搭配 `--keyword` 的 `game get` 會搜尋整個目錄。讀取大型目錄可能需要幾分鐘，命令會在 stderr 上顯示其[進度](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands.md#progress)。沒有分頁選項；請使用 `less` 或 `more` 將輸出分頁。如果要求失敗，命令不會列印部分結果，並會將相互關聯識別碼寫入 stderr。每個要求會在兩分鐘後逾時；若要變更此值，請設定 `XboxPartner:TimeoutSeconds` (請參閱[組態](https://docs.xbox.com/zh-TW/tools/xbox-cli/configuration.md))。

## 輸出

JSON 輸出是一個 `games` 陣列。每個遊戲都有下列欄位：

| 欄位 | 描述 |
| - | - |
| `productId` | Partner Center 產品 ID。 |
| `storeId` | Microsoft Store ID。 |
| `xboxTitleId` | XBOX 遊戲識別碼：八個大寫十六進位數字，不含 `0x`，例如 `"1234ABCD"`。當遊戲沒有有效的遊戲識別碼時為 `null`。 |
| `SCID` | 服務設定識別碼 (SCID)，例如 `"00000000-0000-0000-0000-00001234ABCD"`。索引鍵為大寫。當 `xboxTitleId` 為 `null` 時為 `null`。 |
| `name` | 遊戲的名稱。 |
| `primaryDevelopmentSandbox` | 遊戲的開發沙箱，或 `null`。 |
| `deviceFamilies` | 支援的裝置，例如 `["xbox", "desktop"]`。未列出任何裝置時為 `null` 或 `[]`。 |
| `packageIdentityName`、`packageIdentityPublisher`、`packageFamilyName` | 遊戲的套件身分識別。 |
| `msaAppId` | Microsoft 帳戶 (MSA) 應用程式 ID。 |

`game create` 和 `game job get` 會寫入建立作業。遊戲建立之後，就會出現具有相同欄位的 `game` 欄位。

### 表格輸出

`list` 和 `get` 接受 `--output table`，每個 XBOX 遊戲識別碼一列，並包含下列欄：`TITLE ID`、`STORE IDS`、`PRODUCT NAME`、`MSA APP ID` 和 `PACKAGE FAMILY NAME`。遊戲的 Store ID 和其他值會共用同一列，過長的值會被截斷。`create` 和 `job get` 會拒絕 `--output table`。

### 詳細資料檢視

`--details` 會為每個遊戲識別碼列印一個區塊，其中包含其下的每個遊戲及其所有識別碼 (包括 SCID 和開發沙箱)，且不會截斷。遺漏的值會顯示為 `-`。使用 `--details` 或 `--output table` 時，結果計數和持續時間會傳送到 stderr。

## 建立遊戲

```bash theme={null}
xbox game create --name "Nod Arena" \
  --supported-device xbox --supported-device desktop \
  --sandbox-id TESTSB.42 --seller-id 1234567 --confirm
```

`game create` 在建立遊戲之前會先詢問；沒有終端機時，需要 `--confirm`。CLI 無法刪除遊戲。如果您屬於多個賣方，請先查看[此已知問題](https://docs.xbox.com/zh-TW/tools/xbox-cli/known-issues.md#xbox-game-commands-ignore---seller-id)：遊戲可能會建立在另一個賣方中。

命令只會傳送一次要求、最多等候建立作業兩分鐘，並將作業寫入 stdout。作業 ID、相互關聯識別碼以及用來檢查作業的命令會傳送到 stderr。如果等候先結束，作業會繼續執行：請使用 `game job get` 檢查它，不要再次建立遊戲。

如果要求失敗，stderr 會指出是否可能已建立遊戲：

* 當要求未傳送，或服務拒絕要求 (例如針對遊戲無法使用的沙箱傳回 `400`) 時，表示**未建立任何遊戲**。請修正問題，然後再次執行命令。
* 在發生伺服器錯誤、逾時或連線中斷之後，表示**結果不明**。在重試之前，請使用 stderr 上列印的命令檢查 `game list`。

## 檢查建立作業

```bash theme={null}
xbox game job get 11111111-2222-3333-4444-555555555555 --output json-compact
```

`job get` 只會讀取，因此您可以隨意執行任意次數。已成功的作業仍可能會在其 `errors` 欄位中回報問題。

## 結束代碼

| 結束代碼 | 意義 |
| - | - |
| `0` | 作業已成功或仍在執行中。`create` 在等候結束時也會以 `0` 結束，因此 `0` 並不保證遊戲已存在。 |
| `1` | 命令失敗。若是 `create`，stderr 會指出是否可能已建立遊戲。 |
| `2` | 作業已結束，但未建立遊戲。請參閱其 `errors` 欄位。 |
| `130` | 您在命令讀取時，或在 `create` 等候其要求的回應時按下了 Ctrl+C。若是 `create`，stderr 會指出結果不明。 |

請勿根據結束代碼來決定是否再次執行 `create`。如果 stderr 指出未建立任何遊戲，請修正錯誤並再次執行；否則請使用它所列印的 `game job get` 或 `game list` 命令進行檢查。

## 端對端範例

儲存一次賣方，然後建立遊戲，該遊戲會使用此賣方：

```bash theme={null}
xbox context set seller-id 1234567

xbox game create --name "Nod Arena" \
  --supported-device xbox --supported-device desktop \
  --sandbox-id TESTSB.42 --confirm
```

如果等候在作業完成之前結束，請檢查作業，而不要再次建立遊戲。請使用 `game create` 在 stderr 上列印的作業 ID：

```bash theme={null}
xbox game job get 11111111-2222-3333-4444-555555555555 --output json-compact
```

作業成功後，尋找該遊戲：

```bash theme={null}
xbox game get --keyword "Nod Arena" --output table
```


## Related topics

- [遊戲設定](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/game-setup-overview.md)
- [遊戲繫結](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/game-binding/game-binding-overview.md)
- [多人遊戲](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/index.md)
- [遊戲資料](https://docs.xbox.com/zh-TW/services/playfab/live-service-management/game-configuration/titledata/index.md)
- [認證遊戲](https://docs.xbox.com/zh-TW/publishing/game-publishing/tutorial-xbox-managed/how-to-certify-a-game.md)
