> ## 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-CN/tools/xbox-cli/commands/playfab/player) 会将其返回为
`UserInfo.TitleInfo.TitlePlayerAccount.Id`。

`group delete` 和 `group role delete` 在终端中会先询问,在其他环境中则需要 `--confirm`。其他更改组的命令(包括 `group member remove`)会直接运行,不进行询问。请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/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-CN/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-CN/services/playfab/community/associations/groups/index.md)
- [在 LampArray 上设置颜色](https://docs.xbox.com/zh-CN/build/core-features/common/lighting/lighting-colors.md)
- [Entity API 重构升级教程](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/game-configuration/entities/entity-api-restructure-upgrade-tutorial.md)
- [PlayFab Progression API](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/progression/overview.md)
- [PlayFab Services C API 参考](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/index.md)
