> ## 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 賣方的對象。

對象是具名的玩家或裝置群組 (例如測試人員)，賣方可以將內容鎖定給這些群組。Partner Center 將其稱為客戶群組。`audience` 命令可列出及取得賣方的對象、建立已知使用者對象，以及重新命名對象或取代其成員。若要讓對象加入試玩測試，請將其 `id` 傳遞給 `playtest create` 或 `playtest update`；請參閱[選擇對象](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playtest.md#choosing-audiences)。

`audience` 為實驗性功能：其命令、選項和輸出可能會變更或移除。請參閱[實驗性命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/cli-command-lifecycle.md)。列出及取得對象需要具備該賣方的 Partner Center 客戶群組讀取權限，而建立及更新對象則需要寫入權限。

## 命令

| 命令 | 描述 |
| - | - |
| `audience list` | 列出賣方的對象。 |
| `audience get <audience-id>` | 取得一個對象及其成員。 |
| `audience create` | 建立已知使用者對象。 |
| `audience update <audience-id>` | 重新命名已知使用者對象，或取代其完整成員清單。 |

CLI 無法刪除對象或變更其類型；請在 Partner Center 中執行這些操作。

## 引數和選項

| 引數或選項 | 適用於 | 必要 | 描述 |
| - | - | - | - |
| `<audience-id>` | `get`、`update` | 是 | 對象 ID，與 `list` 傳回的完全相同，例如 `1152921504606846976`。 |
| `--name <text>` | `list` | 否 | 只列出名稱包含此文字的對象，不區分大小寫。 |
| `--name <text>` | `create`、`update` | `create` | 對象的名稱，最多 200 個字元。不可空白，也不必是唯一的。 |
| `--members-file <path>` | `create`、`update` | 否 | 列出成員的檔案。請參閱[成員檔案](#members-files)。 |
| `--confirm` (`--yes`、`-y`) | `create`、`update` | 否 | 略過確認提示。未指定此選項時，命令會在終端機中詢問，否則會失敗。 |
| `--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`。 |

## 輸出

`audience get` 會寫入一個對象：

```json theme={null}
{
  "name": "Nod Arena testers",
  "id": "1152921504606846976",
  "members": ["dev@nodpublishers.com"],
  "dnaTags": ["AppFlighting"],
  "sellerId": "1234567",
  "groupType": "User",
  "groupUsage": "ForPackageFlight, ForLimitedDistribution"
}
```

| 欄位 | 描述 |
| - | - |
| `name` | 對象名稱，或 `null`。 |
| `id` | 對象 ID。請原封不動地將它傳遞給其他命令。 |
| `members` | 已儲存的成員。`list` 會省略此欄位。 |
| `dnaTags` | 對象的標籤。 |
| `sellerId` | 擁有該對象的賣方。 |
| `groupType` | 對象類型，例如 `User`、`PreCreated` 或 `XboxDevice`，或 `null`。只有 `User` 對象可以更新。 |
| `groupUsage` | 對象的用途，以逗號分隔的旗標表示，或 `null`。 |

`audience list` 會寫入由相同物件組成的 `audiences` 陣列 (不含 `members`)，沒有任何對象時則寫入 `{"audiences":[]}`。`create` 和 `update` 會以與 `get` 相同的方式寫入對象。

使用 `--output table` 時，每個命令都會顯示 `ID`、`NAME` 和 `TYPE` 欄，其中 `TYPE` 為 `groupType`。成員只會出現在 JSON 輸出中。

## 建立對象

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt
```

未指定 `--members-file` 時，對象沒有任何成員。每次執行都會建立新的對象，即使已有同名的對象也一樣。

## 更新對象

傳遞 `--name`、`--members-file` 或兩者；未指定的部分會保留。下列命令會重新命名對象：

```bash theme={null}
xbox audience update 1152921504606846976 --name "Nod Arena beta testers"
```

下列命令會以 `testers.txt` 中的位址取代其成員：

```bash theme={null}
xbox audience update 1152921504606846976 --members-file testers.txt
```

> [!WARNING]
>
> `--members-file` 會取代完整的成員清單。不在檔案中的成員會被移除，而空白檔案會移除所有成員。若要新增或移除一個成員，請使用 `audience get` 讀取清單、加以變更，然後傳遞整份清單。

更新不會與其他變更進行比對檢查：如果兩個人同時更新同一個對象，以最後一次更新為準。

## 成員檔案

成員檔案是 UTF-8 文字，每行一個電子郵件地址，最多 1000 個成員：

```text theme={null}
dev@nodpublishers.com
tester@nodpublishers.com
```

空白行及每行前後的空格都會被忽略。服務會檢查每個成員，但已儲存的成員並不保證能解析為可以看到鎖定給該對象之內容的帳戶。

## 結束代碼

| 結束代碼 | 意義 |
| - | - |
| `0` | 命令成功。 |
| `1` | 命令失敗，且未變更任何內容。 |
| `3` | `create` 或 `update` 已傳送其要求，但結果不明。相互關聯識別碼會顯示在 stderr 上。 |

`create` 和 `update` 只會傳送一次要求。結束代碼為 `3` 之後，請先檢查再重新執行命令：

* 在 `create` 之後，執行 stderr 所顯示的 `xbox audience list --name` 命令。找到相符項目只能作為參考，因為名稱不必是唯一的，而再次執行 `create` 可能會建立第二個對象。
* 在 `update` 之後，執行 `xbox audience get <audience-id>` 以檢查其名稱和成員。

## 錯誤

無論 `--output` 為何，錯誤都會以文字形式傳送到 stderr，其中包含相互關聯識別碼、針對 HTTP 狀態的指引，以及服務的錯誤詳細資料 (如果有的話)。`--verbose` 會加入服務的回應，其中可能包含成員。指令碼應根據結束代碼而非文字內容來分支。

403 可能表示缺少權限、您不屬於該賣方，或該賣方未啟用試玩測試。在 `list` 和 `get` 上，拒絕可能會改以 502 呈現；請檢查錯誤詳細資料以了解原因。建立及更新對象的功能正在逐步推出，您可能尚無法使用；在推出之前，`create` 和 `update` 會失敗，且不會變更任何內容。

## 範例

列出及取得對象：

```bash theme={null}
xbox audience list --name testers
xbox audience list --output table
xbox audience get 1152921504606846976 --seller-id 1234567
```

建立對象而不顯示確認提示：

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt --confirm
```

取代對象的成員，並以表格顯示結果：

```bash theme={null}
xbox audience update 1152921504606846976 --members-file testers.txt --output table
```


## Related topics

- [可見度 - 對象](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/availability/visibility-audiences.md)
- [XBOX 服務安全性權杖宣告](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/security-tokens/live-token-claims.md)
- [可見度](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/availability/visibility.md)
- [為遊戲設定定價和供應情況](https://docs.xbox.com/zh-TW/publishing/game-publishing/tutorial-xbox-managed/how-to-configure-pricing-and-availability.md)
- [Playtest](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playtest.md)
