> ## 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」遊戲範例開始。身為玩家，您需要在每顆行星上建造和發展建築，
收集資源、建立自己的太空船，還要設置防禦，因為其他玩家可能會攻擊您以竊取您的物品。
這款遊戲的一個關鍵面向是，玩家可以組成聯盟，目標是建立團隊並以群組方式攻擊其他玩家。

基於這樣的背景，我們想要為聯盟建立一個排行榜，以便知道整個宇宙中
哪個聯盟最強大。

在深入了解群組排行榜的運作方式之前，請先記住以下幾個重點：

* 在此深入了解實體程式設計模型：[實體程式設計模型](/zh-TW/services/playfab/live-service-management/game-configuration/entities)。
* 在此查看群組的運作方式：[群組](/zh-TW/services/playfab/community/associations/groups/quickstart)。

## 建立排行榜

根據遊戲以及您將面對的情境類型，您很可能會建立多個排行榜。
在這個特定情境中，我們想要展示此遊戲的兩種不同情境，以及如何使用此服務來處理每一種情境。

### 玩家排行榜

在此範例中，玩家正在為行星進行地球化，並藉由在遊戲中執行特定動作來獲得經驗值。
因此，我們將建立一個排行榜，在玩家層級追蹤該經驗值。此流程與其他教學課程
（例如[建立基本排行榜](/zh-TW/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);
}
```

在此情境中，將項目新增至玩家排行榜或群組排行榜的程式碼是相同的。但此行為並非
總是如此，因為我們可能有一個玩家排行榜具有五個欄，但另一個群組排行榜只有一個欄。
我們會在此教學課程中進一步說明多欄排行榜：[使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards)。

請務必記住，您必須將正確的 `EntityId` 提供給服務。如果您有玩家排行榜，
實體就是 `"title_player_account"`；如果排行榜由群組組成，則您需要提供 `"group` 實體。

## 從排行榜擷取資料

現在，若要取得排行榜的資料，除了 GetFriendLeaderboard API 之外，我們可以使用此處所述的所有選項：[使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards)。

## 群組排行榜的顯示名稱

最後，群組排行榜還可以做到的另一個細節，是使用實體的群組名稱來設定顯示名稱。
因此，如果您有一個名為「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，使其能顯示群組名稱。

## 另請參閱

* [使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards)。
* [建立基本排行榜](/zh-TW/services/playfab/community/leaderboards/create-basic-leaderboard)
* [手動層級](/zh-TW/services/playfab/community/leaderboards/manual-tiers)。
* [限制 ](/zh-TW/services/playfab/community/leaderboards/limits-leaderboards)。
* [配額 ](/zh-TW/services/playfab/community/leaderboards/quota-leaderboards)。
* [季節性排行榜](/zh-TW/services/playfab/community/leaderboards/seasonal-leaderboards)。
* [依統計資料為玩家排名](/zh-TW/services/playfab/community/leaderboards/leaderboards-linked-to-stats)
* [將內容相關資料新增至排行榜](/zh-TW/services/playfab/community/leaderboards/metadata-leaderboards)
* [API 參考](/zh-TW/services/playfab/community/leaderboards/api-reference)
* [排行榜與 Cloudscript](/zh-TW/services/playfab/community/leaderboards/leaderboards-cloudscript)。
* [排行榜與 Playstream](/zh-TW/services/playfab/community/leaderboards/leaderboards-with-playstream-and-telemetry)


## Related topics

- [排行榜配額](/zh-TW/services/playfab/community/leaderboards/quota-leaderboards.md)
- [季節性排行榜](/zh-TW/services/playfab/community/leaderboards/seasonal-leaderboards.md)
- [排行榜的限制](/zh-TW/services/playfab/community/leaderboards/limits-leaderboards.md)
- [手動層級排行榜](/zh-TW/services/playfab/community/leaderboards/manual-tiers.md)
- [建立基本排行榜](/zh-TW/services/playfab/community/leaderboards/create-basic-leaderboard.md)