> ## 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. # 建立基本排行榜 > 使用 C# SDK 建立基本的 PlayFab 排行榜：定義欄和排序方向、新增玩家項目、查詢排名，以及處理分數平手決勝。 # 建立基本排行榜 在本教學課程中，我們將示範如何使用新的排行榜服務建立基本排行榜。讓我們從一個大型電玩遊戲的 範例開始，這款遊戲的目標是在被擊敗之前盡可能擊敗最多的敵人。當您被擊敗時， 就會獲得一個分數。現在，我們想要建立排行榜，協助這款遊戲判斷誰是最佳玩家。 ## 建立排行榜 第一步是建立排行榜定義，其中包含為玩家排名的主要元素。對於我們的大型電玩遊戲， 我們只需要一個分數欄。下列範例示範如何使用 C# SDK 建立排行榜定義。 ```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() { new LeaderboardColumn() { Name = "arcadeScore", SortDirection = LeaderboardSortDirection.Descending, } } }; PlayFabResult createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest); } ``` 現在，讓我們說明此範例的一些重要元素： * `AuthenticationContext`：此參數會處理對我們服務之每個要求背後的所有驗證。如需詳細說明， 您可以查看下列頁面：[排行榜快速入門](/zh-TW/services/playfab/community/leaderboards/quickstart-leaderboards)。 * `Name`：此參數可協助您識別排行榜定義。在此選擇相關的名稱很重要，因為它會用於提出其他要求以擷取資訊。此外，此名稱必須是唯一的，因此每次建立排行榜時都應使用新的名稱。 * `EntityType`：此參數會指定您要為其建立排行榜的實體類型。 您可以在此深入了解：[實體程式設計模型](/zh-TW/services/playfab/live-service-management/game-configuration/entities)。 * `title_player_acount`：此實體類型是指 PlayFab 中的玩家。若要建立玩家，您可以使用此處所述的 `LoginAsPlayer` 方法：[快速入門](/zh-TW/services/playfab/community/leaderboards/quickstart-leaderboards)。 * `group`：此實體類型是指一群玩家，通常這個概念適用於遊戲中的「氏族」、「公會」等。請在此查看更多資訊：[群組排行榜](/zh-TW/services/playfab/community/leaderboards/group-leaderboards)。 * `external`：此實體類型用於將自訂資料新增至我們的排行榜。每一列都不需要與 PlayFab 上的任何項目繫結，這是您自己的資料。只要識別碼是字串，您就可以在 `EntityId` 欄位中使用自己的識別碼。 * `master_player_account`：此實體類型是指跨遊戲的玩家。當工作室擁有多款遊戲，且有玩家從一款遊戲轉到另一款遊戲，或同時遊玩同一工作室的多款遊戲時，就適用這個概念。根據這個概念，您可以建立跨同一工作室多款遊戲的玩家排行榜。您需要使用：主要玩家帳戶 ID (也稱為 PlayFabId) 來將其對應至 `EntityId`。 * `character`：此實體類型與具有一系列角色的遊戲有關，玩家可以從中選擇角色並開始旅程。基於這個概念，若要建立角色排行榜，您需要先建立玩家，然後才能建立與該玩家關聯的角色。 之後，您可以使用 `CharacterId` 作為實體識別碼，並插入含有對應分數的一列。 * `VersionConfiguration`：此參數可讓您為在特定期間後自行重設的排行榜 設定版本控制策略。此概念在此有深入說明：[季節性排行榜](/zh-TW/services/playfab/community/leaderboards/seasonal-leaderboards)。 * `Columns`：我們在此定義排行榜將擁有的欄數。在此範例中，我們只為分數設定一個欄。 我們也將 `SortDirection` 定義為遞減，表示分數最高的玩家將位於頂端。每個定義允許的欄數上限為 5。 有了這些資訊，您現在就可以執行範例並建立您的第一個排行榜。 ### 取得排行榜定義 在將資料新增至此排行榜之前，我們想要確保它已正確建立。為了執行此動作，我們提供一個範例， 說明如何擷取排行榜定義。 ```C# theme={null} public static async Task GetLeaderboardDefinition(PlayFabAuthenticationContext context, string leaderboardName) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); GetLeaderboardDefinitionRequest leaderboardDefReq = new GetLeaderboardDefinitionRequest() { Name = leaderboardName }; PlayFabResult getleaderboardDefResult = await leaderboardsAPI.GetLeaderboardDefinitionAsync(leaderboardDefReq); } ``` 若要擷取排行榜定義，請指定您所建立排行榜的名稱。如果您有多個排行榜 定義，可以使用下一個範例取得一組定義。 ```C# theme={null} public static async Task ListLeaderboards(PlayFabAuthenticationContext context) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); ListLeaderboardDefinitionsRequest listLbRequest = new ListLeaderboardDefinitionsRequest() { AuthenticationContext = context, }; PlayFabResult lbResponse = await leaderboardsAPI.ListLeaderboardDefinitionsAsync(listLbRequest); } ``` ### 更新排行榜定義 如果您想要更新排行榜定義，可以依照下列方式進行： ```C# theme={null} public static async Task UpdateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName, int sizeLimit, VersionConfiguration version) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); UpdateLeaderboardDefinitionRequest updateLbDefinitionRequest = new UpdateLeaderboardDefinitionRequest() { AuthenticationContext = context, Name = leaderboardName, SizeLimit = sizeLimit, VersionConfiguration = version, }; PlayFabResult updateLbDefinitionResult = await leaderboardsAPI.UpdateLeaderboardDefinitionAsync(updateLbDefinitionRequest); } ``` 請注意，Columns、EntityType 和 `ResetInterval` 無法在更新中修改。 ### 刪除排行榜定義 如果您想要刪除排行榜定義，可以依照下列方式進行： ```C# theme={null} public static async Task DeleteLeaderboard(PlayFabAuthenticationContext context, string leaderboardName) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); DeleteLeaderboardDefinitionRequest deleteLbRequest = new DeleteLeaderboardDefinitionRequest() { AuthenticationContext = context, Name = leaderboardName, }; PlayFabResult lbResponse = await leaderboardsAPI.DeleteLeaderboardDefinitionAsync(deleteLbRequest); } ``` ## 將資料新增至排行榜 繼續我們的大型電玩遊戲範例，我們現在已經知道如何建立排行榜定義、擷取它，以及在必要時刪除它。 下一步是開始將資料新增至排行榜。 請記住，這些是以實體為基礎的排行榜，這表示項目都是實體。我們也支援使用您自己的外部身分識別，這會在[使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards)中詳細討論。 在我們的特定範例中，我們使用的是 title\_player\_account 實體類型，因此排行榜中填入的是玩家。 不過，請記住您也可以使用其他實體類型。 您可以在此查看：[可用的內建實體類型](/zh-TW/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types)。 現在讓我們深入了解如何將資料新增至排行榜。 ```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() { new LeaderboardEntryUpdate() { EntityId = entityId, Scores = new List { score.ToString()} } }, AuthenticationContext = context, LeaderboardName = leaderboardName, }; PlayFabResult updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest); } ``` 現在，讓我們說明此範例的一些重要元素： * `Entries`：此參數對應至新增到排行榜的實際列。它具有 `EntityId`，這是一個在排行榜中 識別實體的字串。由於此服務是獨立元件，您可以在此使用自己的識別碼。 不過，如果您使用其他 PlayFab 服務，此值在所有服務之間應保持一致。 * `Scores`：此參數對應至您可以新增至一個實體的分數清單。請記住，排行榜可以有多個欄。 您可以在此深入了解這些概念：[使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards) * `Name`：此參數對應至您建立排行榜定義時所設定的排行榜名稱。 您現在已準備好將資料新增至排行榜。 ## 從排行榜擷取資料 讓我們快速回顧一下。到目前為止，您已建立排行榜、檢查所有組態詳細資料， 並開始將實體新增至其中。現在，假設有些玩家已經開始玩您的遊戲， 而且分數都很亮眼。我們想要判斷誰是最佳玩家。在下列範例中， 我們將示範如何執行此動作。 ```C# theme={null} public static async Task> GetLeaderboard(PlayFabAuthenticationContext context, string leaderboardName) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); GetEntityLeaderboardRequest getLbRequest = new GetEntityLeaderboardRequest() { LeaderboardName = leaderboardName, StartingPosition = 1, PageSize = 20, AuthenticationContext = context, }; PlayFabResult lbResponse = await leaderboardsAPI.GetLeaderboardAsync(getLbRequest); return lbResponse.Result.Rankings; } ``` 現在，讓我們說明此範例的一些重要元素： * `StartingPosition`：此參數是指您要開始查詢資料的位置。在此案例中， 我們想要取得排名第一的玩家，因此將此參數設定為 1。此參數也可以搭配 `PageSize` 參數， 視需要查詢整個排行榜。 * `PageSize`：此參數會指定在該要求中提取的記錄數目。 * `Name`：此參數對應至您建立排行榜定義時所設定的排行榜名稱。 ### 平手決勝 現在假設有些玩您遊戲的玩家正在一較高下，看看誰是最強的。 我們遇到了一個問題：兩位玩家擊敗了相同數量的敵人，因此分數相同。 那麼，誰應該是排名第一的玩家？ 為了回答這個問題，我們預設有一個簡單的平手決勝原則。我們會根據達成分數時的 時間戳記來選擇最佳玩家。最先達成分數的人就是排名第一的玩家。不過， 視遊戲的情境而定，這可能不夠充分或不夠精確。 如需更複雜的平手決勝功能，請參閱：[使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards)。 在我們目前的範例中，排名將會是： | 排名 | 實體識別碼 | 分數 | LastUpdated | | - | - | - | - | | 1 | "player 3" | 103 | "2024-08-27T20:24:36.738Z" | | 2 | "player 2" | 102 | "2024-08-27T20:24:29.251Z" | | 3 | **"player 1"** | 100 | "2024-08-27T19:52:26.642Z" | | 4 | **"player 4"** | 100 | "2024-08-27T20:24:44.552Z" | 在這個特定範例中，"player 1" 和 "player 4" 的分數相同。由誰排在前面取決於時間戳記。 由於 "player 1" 先達成該分數，這就是它排在前面的原因。 ## 刪除排行榜列 您的排行榜如預期般運作，而且您的遊戲中有許多玩家。不過， 您開始注意到一些異常行為，似乎有些玩家正在作弊以登上排行榜的 頂端。您不會容忍這種行為，因此想要將他們從排行榜中移除。在下一個範例中，您可以了解如何從排行榜刪除列。 ```C# theme={null} public static async Task DeleteLeaderboardEntries(PlayFabAuthenticationContext context, string leaderboardName, List entityIds) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); DeleteLeaderboardEntriesRequest leaderboardsDelReq = new DeleteLeaderboardEntriesRequest() { Name = leaderboardName, EntityIds = entityIds }; PlayFabResult delLeaderboardDefResult = await leaderboardsAPI.DeleteLeaderboardEntriesAsync(leaderboardsDelReq); } ``` 現在，讓我們說明此範例的一些重要元素： * `EntityIds`：此參數是您要刪除的實體識別碼清單。 * `Name`：此參數對應至您建立排行榜定義時所設定的排行榜名稱。 ## 結論 在本教學課程中，我們學到了如何執行下列作業： * 建立排行榜。 * 檢查排行榜的組態。 * 更新排行榜組態。 * 刪除排行榜組態。 * 填入排行榜。 * 了解平手決勝的運作方式。 * 刪除排行榜中的項目。 ## 另請參閱 * [使用排行榜執行更多操作](/zh-TW/services/playfab/community/leaderboards/doing-more-with-leaderboards)。 * [限制 ](/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)。 * [群組排行榜](/zh-TW/services/playfab/community/leaderboards/group-leaderboards)。 * [手動層級](/zh-TW/services/playfab/community/leaderboards/manual-tiers)。 * [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 - [排行榜 API 參考](/zh-TW/services/playfab/community/leaderboards/api-reference.md) - [群組排行榜](/zh-TW/services/playfab/community/leaderboards/group-leaderboards.md) - [排行榜配額](/zh-TW/services/playfab/community/leaderboards/quota-leaderboards.md) - [季節性排行榜](/zh-TW/services/playfab/community/leaderboards/seasonal-leaderboards.md) - [手動層級排行榜](/zh-TW/services/playfab/community/leaderboards/manual-tiers.md)