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

# 季节性排行榜

> 使用 VersionConfiguration 配置季节性 PlayFab 排行榜，以每月或自定义节奏重置排名，并查询以前的锦标赛版本。

在本教程中，我们将解释排行榜的版本控制概念。有多种情况我们希望某个排行榜有不同版本。例如，在具有每月锦标赛模式的游戏中，排行榜结构保持不变，但玩家很可能会改变，尤其是在竞争激烈的游戏中。

我们继续沿用[创建基本排行榜](/services/playfab/community/leaderboards/create-basic-leaderboard)中的示例。设想我们的街机游戏现在非常受欢迎。因此，引入了一个名为“Top of the Mountain”的新模式。每月，游戏都会举办一场任何玩家都可以参加的锦标赛。前 100 名将显示在主菜单的特殊排行榜中，这样每个人都可以看到谁是游戏中的最佳玩家。

## 为版本控制创建排行榜定义

在之前的示例中，创建排行榜定义时，有一处提示表明 `VersionConfiguration` 参数对于版本控制的重要性。下面我们详细介绍如何使用它以及它的工作方式。

```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 = 12,
            ResetInterval = ResetInterval.Month,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "arcadeScoreTournament",
                SortDirection = LeaderboardSortDirection.Descending,
            }          
        }
    };

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

此示例与基本排行榜相比的主要区别是 `VersionConfiguration` 参数。此参数允许我们定义一个 `MaxQueryableVersions` 设置，指定我们可以查询同一排行榜的多少个版本。在本例中，我们将其设置为查询 12 个版本，这允许查询最近的 12 个排行榜。`ResetInterval` 参数定义重置过程发生的频率。此操作涉及创建一个与之前配置相同但为空的排行榜，并且版本参数按如下方式变化：N = N + 1，在排行榜定义创建时 N = 0。

例如，假设我们有一个排行榜，其版本参数为二，排行榜上有一百个条目。现在，当我们递增该排行榜的版本时，结果将是一个版本参数为三且为空的新排行榜。同时，先前的排行榜仍保留在系统中以供查询。

`ResetInterval` 可以有多种工作方式。在此示例中，它是按月的，但可以根据开发者的需要进行更改。在此特定情况下，这意味着排行榜将从其配置时刻起每月自动重置。我们支持以下重置策略：

* Day
* Hour
* Manual
* Month
* Week

有关所有可用配置的更多信息，请查看此处的 API 文档：
[创建排行榜的 API 参考](https://learn.microsoft.com/en-us/rest/api/playfab/progression/leaderboards/create-leaderboard-definition)

## 递增排行榜的版本

有了这个新配置，我们可以为锦标赛模式拥有同一排行榜的多个版本。但是，如果我们由于某个问题需要手动重置排行榜并重新开始锦标赛，会发生什么呢？在这种情况下，我们可以使用 API 执行手动重置。以下是使用 SDK 的示例：

```C# theme={null}

public static async Task ResetLeaderboards(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    IncrementLeaderboardVersionRequest resetLeaderboardRequest = new IncrementLeaderboardVersionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.IncrementLeaderboardVersionResponse> resetLeaderboardResponse = await leaderboardsAPI.IncrementLeaderboardVersionAsync(resetLeaderboardRequest);
}

```

## 查询较旧版本

现在，如果我们需要查询排行榜的较旧版本，我们可以使用所有 GetLeaderboards API 上都可用的 `version` 参数。以下是使用 SDK 的示例：

```C# theme={null}
public static async Task<List<EntityLeaderboardEntry>> GetLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetEntityLeaderboardRequest getLbRequest = new GetEntityLeaderboardRequest()
    {
        LeaderboardName = leaderboardName,
        StartingPosition = 1,
        PageSize = 20,
        AuthenticationContext = context,
        Version = 1
    };

    PlayFabResult<GetEntityLeaderboardResponse> lbResponse = await leaderboardsAPI.GetLeaderboardAsync(getLbRequest);
    
    return lbResponse.Result.Rankings;
}
```

现在我们已准备好应对排行榜版本控制的任何挑战。这里的一个重要方面是，我们决定作为版本保留的排行榜定义数量将被计量，因为它们使用了服务内的存储。有关这方面的更多信息，请参见：

* [排行榜写入](/services/playfab/pricing/meters/leaderboard-meters)。

## 结论

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

* 使用正确的重置策略创建排行榜。
* 递增排行榜的版本。
* 查询排行榜的较旧版本。

## 另请参阅

* [排行榜的更多用法](/services/playfab/community/leaderboards/doing-more-with-leaderboards)。
* [创建基本排行榜](/services/playfab/community/leaderboards/create-basic-leaderboard)。
* [按统计信息对玩家排名](/services/playfab/community/leaderboards/leaderboards-linked-to-stats)。
* [组排行榜](/services/playfab/community/leaderboards/group-leaderboards)。
* [手动分级](/services/playfab/community/leaderboards/manual-tiers)。
* [限制](/services/playfab/community/leaderboards/limits-leaderboards)。
* [配额](/services/playfab/community/leaderboards/quota-leaderboards)。
* [向排行榜添加上下文数据](/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/limits-leaderboards.md)
- [排行榜快速入门](/zh-CN/services/playfab/community/leaderboards/quickstart-leaderboards.md)
- [PlayFab 排行榜概述](/zh-CN/services/playfab/community/leaderboards/index.md)
- [季节性统计信息](/zh-CN/services/playfab/player-progression/statistics/seasonal-statistics.md)