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

# 群組

> 管理 PlayFab 實體群組及其角色、成員、邀請、申請和封鎖。

`playfab group` 命令系列為實驗性功能。其 CLI 介面可能會根據意見反應而變更或移除。

管理 PlayFab 實體群組及其角色、成員、邀請、申請和封鎖，並列出實體所屬的群組。

大多數命令會以 `--group-id` 指定目標群組；`group get` 可以改用 `--group-name`。請一起傳遞 `--entity-id` 和 `--entity-type`，例如 `--entity-type title_player_account`。若是玩家，請傳遞其遊戲玩家帳戶 ID，而不是其主要玩家帳戶 ID；[`playfab player account get`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/player) 會以 `UserInfo.TitleInfo.TitlePlayerAccount.Id` 傳回該 ID。

`group delete` 和 `group role delete` 會在終端機中先詢問，在其他環境中則需要 `--confirm`。其他會變更群組的命令 (包括 `group member remove`) 會在不詢問的情況下執行。請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)。

## 群組生命週期

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group create` | `/Group/CreateGroup` | `--group-name` 為必要；選用的擁有者 `--entity-id`、`--entity-type`。 |
| `playfab group get` | `/Group/GetGroup` | `--group-id` 或 `--group-name`。 |
| `playfab group update` | `/Group/UpdateGroup` | `--group-id` 為必要；選用的 `--group-name`、`--admin-role-id`、`--member-role-id`、`--expected-profile-version`。 |
| `playfab group delete` | `/Group/DeleteGroup` | `--group-id` 為必要。 |

## 群組成員

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group member add` | `/Group/AddMembers` | `--group-id`、`--member-ids`、`--member-type` 為必要；選用的 `--role-id`。 |
| `playfab group member remove` | `/Group/RemoveMembers` | `--group-id`、`--member-ids`、`--member-type` 為必要；選用的 `--role-id`。 |
| `playfab group member change-role` | `/Group/ChangeMemberRole` | `--group-id`、`--member-ids`、`--member-type`、`--origin-role-id` 和 `--destination-role-id` 為必要。 |
| `playfab group member list` | `/Group/ListGroupMembers` | `--group-id` 為必要。 |
| `playfab group member is-member` | `/Group/IsMember` | `--group-id`、`--entity-id` 和 `--entity-type` 為必要；選用的 `--role-id`。只會讀取。 |

## 群組角色

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group role create` | `/Group/CreateRole` | `--group-id`、`--role-id` 和 `--role-name` 為必要。 |
| `playfab group role update` | `/Group/UpdateRole` | `--group-id`、`--role-id` 和 `--role-name` 為必要；選用的 `--expected-profile-version`。 |
| `playfab group role delete` | `/Group/DeleteRole` | `--group-id` 和 `--role-id` 為必要。 |

## 群組邀請

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group invite send` | `/Group/InviteToGroup` | `--group-id`、`--entity-id` 和 `--entity-type` 為必要；選用的 `--role-id`、`--auto-accept`。 |
| `playfab group invite accept` | `/Group/AcceptGroupInvitation` | `--group-id` 為必要；選用的接受者 `--entity-id`、`--entity-type`。 |
| `playfab group invite remove` | `/Group/RemoveGroupInvitation` | `--group-id`、`--entity-id` 和 `--entity-type` 為必要。 |
| `playfab group invite list` | `/Group/ListGroupInvitations` | `--group-id` 為必要。 |

對於 `invite send`，`--auto-accept` 預設為 `true`：當實體已申請加入群組時，PlayFab 會接受該申請，而不是傳送邀請。

## 群組申請

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group application apply` | `/Group/ApplyToGroup` | `--group-id` 為必要；選用的申請者 `--entity-id`、`--entity-type`、`--auto-accept`。 |
| `playfab group application accept` | `/Group/AcceptGroupApplication` | `--group-id` 為必要；選用的申請者 `--entity-id`、`--entity-type`。 |
| `playfab group application remove` | `/Group/RemoveGroupApplication` | `--group-id`、`--entity-id` 和 `--entity-type` 為必要。 |
| `playfab group application list` | `/Group/ListGroupApplications` | `--group-id` 為必要。 |

對於 `application apply`，`--auto-accept` 預設為 `true`：當群組已邀請該實體時，PlayFab 會接受該邀請，而不是建立申請。

## 群組封鎖

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group block add` | `/Group/BlockEntity` | `--group-id`、`--entity-id` 和 `--entity-type` 為必要。 |
| `playfab group block remove` | `/Group/UnblockEntity` | `--group-id`、`--entity-id` 和 `--entity-type` 為必要。 |
| `playfab group block list` | `/Group/ListGroupBlocks` | `--group-id` 為必要。 |

## 實體成員資格

| 命令 | PlayFab API 路徑 | 選項 |
| - | - | - |
| `playfab group membership list` | `/Group/ListMembership` | 選用的 `--entity-id`、`--entity-type`；兩者皆省略即以呼叫實體為目標。 |
| `playfab group membership opportunity list` | `/Group/ListMembershipOpportunities` | 選用的 `--entity-id`、`--entity-type`；兩者皆省略即以呼叫實體為目標。 |

## 表格輸出

這些命令接受 `--output table`；其他命令則不接受。請參閱[表格輸出](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands.md#table-output)。

| 命令 | 欄 |
| - | - |
| `playfab group member list` | `MEMBER ID`、`MEMBER TYPE`、`ROLE ID` |
| `playfab group invite list` | `INVITED ENTITY`、`ROLE ID`、`EXPIRES` |
| `playfab group application list` | `ENTITY`、`EXPIRES` |
| `playfab group block list` | `BLOCKED ENTITY`、`ENTITY TYPE` |
| `playfab group membership list` | `GROUP ID`、`GROUP NAME` |
| `playfab group membership opportunity list` | `TYPE`、`GROUP ID`、`ROLE ID`、`EXPIRES` |

`member list` 會為每個角色中的每個成員各列一列，因此屬於兩個角色的成員會有兩列，而沒有成員的角色會有一列，其成員顯示為 `-`。`membership opportunity list` 會在一個表格中顯示邀請和申請：`TYPE` 為 `invitation` 或 `application`，而申請的 `ROLE ID` 為 `-`。

## 範例

讀取群組、列出其成員、檢查玩家是否屬於該群組，並列出其未處理的邀請：

```bash theme={null}
xbox --playfab-title-id ABC123 playfab group get --group-id GROUP123
xbox --playfab-title-id ABC123 playfab group member list --group-id GROUP123 --data-only --output json-compact
xbox --playfab-title-id ABC123 playfab group member is-member --group-id GROUP123 --entity-id TITLEPLAYER123 --entity-type title_player_account
xbox --playfab-title-id ABC123 playfab group invite list --group-id GROUP123 --output table
```

邀請玩家加入群組：

```bash theme={null}
xbox --playfab-title-id ABC123 playfab group invite send --group-id GROUP123 --entity-id TITLEPLAYER123 --entity-type title_player_account
```

刪除群組：

```bash theme={null}
xbox --playfab-title-id ABC123 playfab group delete --group-id GROUP123 --confirm
```


## Related topics

- [產品群組](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/product-groups.md)
- [實體群組](https://docs.xbox.com/zh-TW/services/playfab/community/associations/groups/quickstart.md)
- [取得群組](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/groups/groups/get-group.md)
- [刪除群組](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/groups/groups/delete-group.md)
- [建立群組](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/groups/groups/create-group.md)
