> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 组排行榜

> 通过创建使用组实体类型的 PlayFab 排行榜，对公会、氏族和联盟进行排名，以与玩家排行榜并列比较团队分数。

在本教程中，我们将学习如何在排行榜上使用组实体。为了理解这一概念，我们将以一款专注于对行星进行地球化改造的“RPG”游戏为例。作为玩家，您需要在每颗行星上建造和发展建筑、收集资源、创建自己的舰船，并设置防御工事，因为其他玩家可能会攻击您以窃取您的物品。现在，此游戏的一个关键方面是玩家可以建立联盟，目的是组建团队并作为一个组攻击其他玩家。

有了这样的背景，我们希望为联盟创建一个排行榜，以便能够知道整个宇宙中哪个联盟最强。

在深入了解组排行榜工作原理之前，需要牢记一些关键要点：

* 在此处了解有关实体编程模型的更多信息：[实体编程模型](/services/playfab/live-service-management/game-configuration/entities)。
* 在此处了解组的工作原理：[组](/services/playfab/community/associations/groups/quickstart)。

## 创建排行榜

根据游戏和您将要遇到的场景类型，您很可能会创建多个排行榜。在此特定上下文中，我们希望展示此游戏的两种不同场景，以及如何使用该服务解决这些场景。

### 玩家排行榜

在此示例中，我们有玩家正在对行星进行地球化改造，并且他们通过在游戏中执行某些操作获得经验值。因此，我们将有一个排行榜来跟踪玩家级别的经验。此过程遵循与其他教程（如 [创建基础排行榜](/services/playfab/community/leaderboards/create-basic-leaderboard)）中呈现的相同行为。这里的关键点是 EntityType 参数需要为 `"title_player_account"`，因此它只针对玩家。

```C# theme={null}
public static async Task CreateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateLeaderboardDefinitionRequest leaderboardDefinitionRequest = new CreateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = 1000,
        EntityType = "title_player_account",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest);
}
```

### 组排行榜

现在让我们进入示例中提到的游戏方面：联盟。我们可以通过使用 `"group"` 实体在 PlayFab 中创建联盟。此组实体允许我们拥有一种玩家可以加入的结构，它还有角色和其他有趣的功能，为游戏中这类场景赋予能力。要创建排行榜，我们需要弄清楚两件事。

* EntityType 参数需要为 `"group"`。
* 此排行榜是独立的。因此，为联盟添加分数是与玩家排行榜相分离的手动过程。此行为允许分数与玩家有多种不同的关联方式，或者它可以是仅适用于组的新指标。

```C# theme={null}
public static async Task CreateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateLeaderboardDefinitionRequest leaderboardDefinitionRequest = new CreateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = 1000,
        EntityType = "group",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "Group XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest);
}
```

## 向排行榜添加数据

创建两个排行榜后，我们需要了解如何向它们添加数据。如前所述，这些排行榜彼此独立；这让开发者可以自由控制如何为联盟（组）应用有关分数运作方式的自定义逻辑。

```C# theme={null}
public static async Task UpdateLeaderboardForPlayer(PlayFabAuthenticationContext context, string leaderboardName, string entityId, int score)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardEntriesRequest updateLeaderboardRequest = new UpdateLeaderboardEntriesRequest()
    {
        Entries = new List<LeaderboardEntryUpdate>()
        {
            new LeaderboardEntryUpdate()
            {
                EntityId = entityId,
                Scores = new List<string> { score.ToString()}                
            }
        },
        AuthenticationContext = context,
        LeaderboardName = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest);
}
```

在此场景中，向玩家排行榜或组排行榜添加条目的代码相同。但此行为并非总是如此，因为我们可能有一个针对玩家的五列排行榜，但也可能有另一个针对组的只有一列的排行榜。我们在本教程中更详细地介绍了多列排行榜：[排行榜的更多用法](/services/playfab/community/leaderboards/doing-more-with-leaderboards)。

需要始终牢记的一点是，您需要向服务提供正确的 `EntityId`。如果您有一个玩家排行榜，则实体是 `"title_player_account"`；如果排行榜由组组成，则您需要提供为 `"group"` 的实体。

## 从排行榜检索数据

现在，若要获取排行榜的数据，我们拥有 [排行榜的更多用法](/services/playfab/community/leaderboards/doing-more-with-leaderboards) 中所述的所有选项，除了 GetFriendLeaderboard API。

## 组排行榜的显示名称

最后，我们可以对组排行榜执行的另一项操作是将显示名称设置为实体的组名称。因此，如果您有一个称为“Raiders”的联盟，此组名称将通过 `DisplayName` 属性映射到实体。

```C# theme={null}
public static async Task<CreateGroupResponse> CreateGroup(string groupName, PlayFabAuthenticationContext context)
{
    var request = new CreateGroupRequest
    {
        GroupName = groupName,
        AuthenticationContext = context
    };
    var response = await PlayFabGroupsAPI.CreateGroupAsync(request);

    SetDisplayNameRequest displayRequest = new SetDisplayNameRequest()
    {
        AuthenticationContext = context,
        DisplayName = groupName,
        Entity = new PlayFab.ProfilesModels.EntityKey()
        {
            Id = response.Result.Group.Id,
            Type = "group",
        },
    };

    PlayFabResult<SetDisplayNameResponse> updateNameResult = await PlayFabProfilesAPI.SetDisplayNameAsync(displayRequest);

    return response.Result;
}
```

在此示例中，我们通过调用 `CreateGroupAsync` 方法创建一个组。此执行的第一步是返回 Group 对象，我们将使用该对象来设置显示名称。我们通过使用 `SetDisplayNameRequest` 对象将组名称映射到实体，然后执行 `PlayFabProfilesAPI.SetDisplayNameAsync` 方法来完成此过程。

## 结论

在本教程中，我们学习了如何执行以下操作：

* 创建组排行榜。
* 了解如何向该排行榜提供数据。
* 检索排行榜。
* 更改 displayName，使其可以显示组名称。

## 另请参阅

* [排行榜的更多用法](/services/playfab/community/leaderboards/doing-more-with-leaderboards)。
* [创建基础排行榜](/services/playfab/community/leaderboards/create-basic-leaderboard)
* [手动等级](/services/playfab/community/leaderboards/manual-tiers)。
* [限制](/services/playfab/community/leaderboards/limits-leaderboards)。
* [配额](/services/playfab/community/leaderboards/quota-leaderboards)。
* [赛季排行榜](/services/playfab/community/leaderboards/seasonal-leaderboards)。
* [根据统计信息为玩家排名](/services/playfab/community/leaderboards/leaderboards-linked-to-stats)
* [向排行榜添加上下文数据](/services/playfab/community/leaderboards/metadata-leaderboards)
* [API 参考](/services/playfab/community/leaderboards/api-reference)
* [排行榜和 Cloudscript](/services/playfab/community/leaderboards/leaderboards-cloudscript)。
* [使用 Playstream 的排行榜](/services/playfab/community/leaderboards/leaderboards-with-playstream-and-telemetry)


## Related topics

- [排行榜配额](/zh-CN/services/playfab/community/leaderboards/quota-leaderboards.md)
- [季节性排行榜](/zh-CN/services/playfab/community/leaderboards/seasonal-leaderboards.md)
- [排行榜的限制](/zh-CN/services/playfab/community/leaderboards/limits-leaderboards.md)
- [创建基础排行榜](/zh-CN/services/playfab/community/leaderboards/create-basic-leaderboard.md)
- [手动分级排行榜](/zh-CN/services/playfab/community/leaderboards/manual-tiers.md)