使用可重置的统计信息和排行榜 - XBOX Game Development Documentation

本教程提供了如何配置和管理带版本控制的统计信息的完整演练——这允许重置统计信息，并延伸到排行榜。我们将重点介绍如何使用 Admin API 方法，并提供有关如何使用客户端和 Server API 方法查询数据（当前版本以及旧版本）的其他信息。我们的目标是为你提供 PlayFab 中可重置统计信息如何工作的技术评审，以及可以在游戏中使用它们的所有方式。

统计信息和排行榜

首先，值得注意的是，PlayFab 中为游戏中的玩家定义的所有统计信息都属于一个排行榜。因此，定义统计信息也会定义你的排行榜。统计信息不一定对玩家可见，但它们是存在的。你可以使用它们通过你定义的分数获取玩家列表——无论是查找所有分数的最高、最低、以当前玩家为中心的玩家，还是用户好友列表上的玩家。许多游戏中的统计信息都旨在成为终身值——这意味着玩家不断更新其分数，旧的分数会保留，直到每个玩家超越自己的个人最好成绩。然而，对于某些玩家体验来说，能够不时“清空”排行榜非常重要。这可以鼓励用户在给定时间段内成为排名靠前的玩家，或者简单地从排名中删除一段时间内不活跃的玩家。如本教程所述，PlayFab 中的统计信息可以配置为按预定的时间间隔重置。这不仅对上述情境有用——它还可以用于需要拥有独立的最近分数排行榜的标题，可用于游戏挑战等场景，你希望让玩家向具有类似技能水平的人发出邀请。设置重置周期意味着在调用 GetLeaderboardAroundPlayer 时返回的玩家（例如）是最近玩过游戏且与本地玩家分数相似的玩家。也可以将统计信息重置作为手动操作。这是清除你从预发布测试或 alpha/beta 玩法中获得的任何数据的方便系统。对于最糟糕的情况也很有用，即游戏代码中引入了导致失控分数的 bug。在每种情况下，你都需要能够彻底清空排行榜，让玩家觉得他们有公平的机会上榜。

重置统计信息不会删除这些值，你将在下面看到。重置时，PlayFab 中的统计信息会进行版本化，使新版本成为权威版本，同时保留以前的版本以供以后分析（这样你可以根据玩家的旧分数奖励他们）。

配置可重置的统计信息

统计信息的重置周期使用 Admin API 集或 Game Manager 进行配置。然后，可以通过 Game Manager、Server API 和 Client API 更新和查询它们（尽管从客户端发布统计信息确实需要在 Game Manager 的游戏 Settings->API Features 选项卡中设置 allow client to post statistics 选项）。我们将描述用于此操作的 API 方法，尽管此处定义的参数与在 Game Manager 本身中使用的参数相同。若要设置统计信息，可以使用 Admin 的 CreatePlayerStatisticDefinition 方法，并使用 UpdatePlayerStatisticDefinition 方法在之后进行更改。在这两种情况下，只有两个参数：

StatisticName - 玩家统计信息的字符串标识符。
VersionChangeInterval - 定义应何时自动重置统计信息的周期。

VersionChangeInterval 是此功能的关键，它可以定义为每小时、每日、每周或每月。如果你稍后决定不再希望统计信息定期重置，还可以将其设置为 never。在下面的示例中，对 CreatePlayerStatisticDefinition 方法的调用设置了 Headshots 统计信息，并设定每日重置，这意味着游戏中此统计信息的排行榜将在每天 00:00 UTC 重置。

public void CreatePlayerStatisticDefinition() {
    PlayFabAdminAPI.CreatePlayerStatisticDefinition(
        new CreatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Day
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

以下显示了上述 API 调用的响应。

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Day"
        }
    }
}

下面显示的代码是另一个示例。

public void UpdatePlayerStatisticDefinition() {
    PlayFabAdminAPI.UpdatePlayerStatisticDefinition(
        new UpdatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Week
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

该调用演示了将统计信息的重置周期设置为每周，响应如下所示。

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Week"
        }
    }
}

在每种情况下，结果是 PlayerStatisticDefinition，包含：

统计信息的字符串 ID (StatisticName)。
统计信息已重置的次数 (CurrentVersion)。
定义的统计信息重置周期 (VersionChangeInterval)。

重置周期在定义后立即生效，因此在这种情况下，第二次调用意味着重置现在被定义为 00:00 UTC，星期一早上（星期日晚上/星期一凌晨的午夜，使用 UTC 时区），无论调用之前是什么。其余重置间隔也使用 UTC 定义，其中 Month 使重置在每个月的第一天 00:00 UTC 发生。对于完整的列表，重置周期为：

Never：停止基于时间对统计信息进行版本化。
Hour：在每个小时的开始（XX:00 UTC）对统计信息进行版本化。
Day：每天午夜（00:00 UTC）对统计信息进行版本化。
Week：每周一午夜（00:00 UTC）对统计信息进行版本化。
Month：每个月第一天午夜（00:00 UTC）对统计信息进行版本化。

预先存在的统计信息

无论是否设置为重置的统计信息，都可以查询游戏中定义的所有统计信息的定义。值得注意的是，可以使用 UpdatePlayerStatistics 调用创建统计信息。任何未使用重置周期 (VersionChangeInterval) 创建的统计信息一开始都没有重置周期，因此对统计信息配置的查询将返回此参数设置为 Never。使用上面的示例，如果该标题还有一个名为 FlagsCaptured 的统计信息，它使用 UpdatePlayerStatistics（或直接在 Game Manager 中的玩家上创建），并且过了几周，它将如下面所示的调用中出现。

public void GetPlayerStatisticDefinitions() {
    PlayFabAdminAPI.GetPlayerStatisticDefinitions(
        new GetPlayerStatisticDefinitionsRequest(),
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

将产生以下结果。

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 2,
            "VersionChangeInterval": "Week"
        },
        {
            "StatisticName": "FlagsCaptured",
            "CurrentVersion": 0,
            "VersionChangeInterval": “Never”
        }]
    }
}

在这种情况下，名为 Headshots 的统计信息已定义重置间隔，而 CurrentVersion 表示统计信息已重置两次。与此同时，FlagsCaptured 没有 VersionChangeInterval，这也是 CurrentVersion 为 0 的原因（因为它从未进行过版本化）。通过 UpdatePlayerStatistics（或 PlayFab Game Manager）创建的统计信息仍可以使用 UpdatePlayerStatisticDefinition 定义为具有重置周期，如上所述。一旦完成，它们将完全按照最初使用 CreatePlayerStatisticDefinition 定义时的方式在该间隔重置。

手动重置统计信息

对于游戏 bug 允许在统计信息上作弊的情况，或者你只需要重置以从预发布游戏玩法中删除分数的情况，可以在 Game Manager 中强制重置统计信息，或通过调用 IncrementPlayerStatisticVersion 强制重置。这会立即重置你指定的当前统计信息，清空游戏的排行榜，并为报告新值提供空白页面。对于我们的示例，此调用可能类似于下面所示的调用。

public void IncrementPlayerStatisticVersion() {
    PlayFabAdminAPI.IncrementPlayerStatisticVersion(
        new IncrementPlayerStatisticVersionRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

这会再一次递增 Headshots 统计信息，返回有关刚刚变为活动状态的版本的信息。

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersion":
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }
    }
}

在这种情况下，返回 PlayerStatisticVersion 信息，其中包含统计信息的 ID (StatisticName)，以及其版本号、变为权威版本的时间 (ActivationTime) 和 ArchivalStatus（对于当前版本，它始终为 NotScheduled）。但是，对于同时具有 VersionChangeInterval 的统计信息，手动重置不会更改下一次计划的重置时间。如果统计信息计划每日重置——并在 UTC 时间下午 11:30 手动重置——它仍将在 UTC 时间午夜再次重置。

重置何时发生

如前所述，当重置间隔发生时，统计信息将进行版本化，因此新版本立即可用，而该统计信息的旧版本被存档以供以后检索。一旦重置间隔发生（或执行手动重置），并且统计信息已被版本化，将接受对旧版本的写入长达十分钟。超过该时间点，统计信息将被锁定，防止未来更新。一旦过期，统计信息将开始存档过程，以便标题可以稍后检索它们。统计信息存档过程的阶段是：

NotScheduled - 统计信息的存档尚未开始（通常仅对当前活动的统计信息版本）。
Scheduled - 存档过程已计划，但尚未进行。
InProgress - 统计信息正在备份到存档。
Failed - 发生了意外故障（在这种情况下，请联系我们的支持论坛）。
Complete - 此版本的统计信息已被存档。

可以使用 GetPlayerStatisticVersions 查询统计信息的所有过去和当前版本。这将返回每个版本的信息，如前面的手动重置示例所示。换句话说，此调用应类似于下面显示的调用。

public void GetPlayerStatisticVersions() {
    PlayFabAdminAPI.GetPlayerStatisticVersions(
        new GetPlayerStatisticVersionsRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

这可能导致我们的示例标题返回以下信息。

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersions": [
        {
            "StatisticName": "Headshots",
            "Version": 0,
            "ActivationTime": "2015-01-20T05:47:27.17Z",
            "DeactivationTime": "2016-01-25T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 1,
            "ActivationTime": "2016-01-25T00:00:00.000Z",
            "DeactivationTime": "2016-02-01T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 2,
            "ActivationTime": "2016-02-01T00:00:00.000Z",
            "DeactivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "InProgress"
        },
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }]
    }
}

除了 IncrementPlayerStatisticVersion 返回的值外，响应还包括当前活动版本之前的每个版本何时过期 (DeactivationTime) 的时间戳，以及一旦存档过程完成，用于下载包含旧排行榜完整记录的 CSV 的 URL (ArchiveDownloadUrl)。

读取和写入统计信息版本

最后，从服务器和客户端 API 方面来看，调用与你从原始 PlayFab 用户和角色统计信息调用中所了解的非常相似。区别在于，现在，版本是请求或响应的一部分。检索统计信息时，将返回当前统计信息版本的值以及版本号本身。以下示例显示了对 Headshots 统计信息进行调用以及返回的数据。

服务器请求

public void GetPlayerStatistics() {
    PlayFabServerAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

服务器响应

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "PlayFabId": {{PlayFabId}},
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

客户端请求

public void GetPlayerStatistics() {
    PlayFabClientAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

客户端响应

{
    "code": 200,
    "status": "OK",
    "data": {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

与此同时，Update 调用采用可选版本，以允许标题控制正在更新的版本，以应对版本可能在游戏过程中递增的情况。

在此示例中，如果标题在仍然可能的情况下写入前一个版本，则将写入版本 2，如下所示。

服务器请求

public void UpdatePlayerStatistics() {
    PlayFabServerAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

服务器响应

{
    "code": 200,
    "status": "OK",
    "data": {}
}

客户端请求

public void UpdatePlayerStatistics() {
    PlayFabClientAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

客户端响应

{
    "code": 200,
    "status": "OK",
    "data": {}
}

但请记住——尽管过期版本可以在长达 10 分钟内写入，但超出该时间对该版本的任何写入尝试都将失败，其响应如下所示。

{
    "code": 400,
    "status": "BadRequest",
    "error": "StatisticVersionClosedForWrites",
    "errorCode": 1197,
    "errorMessage": "The statistic version is not current and is no longer accepting updates"
}

资源

为完整起见，本节提供上面描述的所有枚举、类和 API 方法的列表，并附有简要说明。

基本枚举

Interval - 统计信息（排行榜）将被重置的周期：
- Never
- Hour
- Day
- Week
- Month
StatisticVersionArchivalStatus - 将某个版本的玩家统计信息值保存到可下载存档的过程状态：
- NotScheduled
- Scheduled
- InProgress
- Failed
- Complete

基本类及其成员

PlayerStatisticDefinition
- StatisticName (string) - 统计信息的唯一名称。
- CurrentVersion (string) - 统计信息的当前活动版本，每次统计信息重置时递增。
- VersionChangeInterval (Interval) - 所有玩家的统计信息值重置的间隔。
PlayerStatisticVersion
- StatisticName (string) - 版本变为活动状态时统计信息的名称。
- Version (string) - 统计信息的版本（编码为字符串的十六进制数）。
- ScheduledVersionChangeIntervalTime (DateTime) - 根据配置的 ResetInterval，计划统计信息版本变为活动状态的时间。
- CreatedTime (DateTime) - 统计信息版本变为活动状态的时间。
- ArchivalStatus (StatisticVersionArchivalStatus) - 如果配置，将此版本的玩家统计信息值保存到可下载存档的过程状态。
- ResetInterval (Interval) - 触发版本变为活动状态的重置间隔（如果已配置）。
StatisticValue
- StatisticName (string) - 统计信息的唯一名称。
- Value (Int32) - 该玩家的统计信息值。
- Version (string) - 对于玩家的现有统计信息值，加载时的统计信息版本。
StatisticUpdate
- StatisticName (string) - 统计信息的唯一名称。
- Version (string) - 对于玩家的统计信息值更新，要更新的统计信息版本
- Value (Int32) - 该玩家的统计信息值。

Admin API 方法

CreatePlayerStatisticDefinition
- CreatePlayerStatisticDefinitionRequest
  - Name (string) - 最小长度 1，最大长度 128 - 统计信息的唯一名称。
  - (VersionChangeInterval) (Interval) - 所有玩家的统计信息值重置的间隔（重置从下一个间隔边界开始）。
- CreatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - 已创建统计信息的定义。
UpdatePlayerStatisticDefinition
- UpdatePlayerStatisticDefinitionRequest
  - StatisticName (string) - 统计信息的唯一名称。
  - VersionChangeInterval (Interval) - 所有玩家的统计信息值重置的间隔（重置从下一个间隔边界开始）。
- UpdatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - 已创建统计信息的定义。
GetPlayerStatisticDefinitions
- GetPlayerStatisticDefinitionsRequest（无参数）。
- GetPlayerStatisticDefinitionsResult
  - Statistics (PlayerStatisticDefinition[]) - 用于重置的定义数组。
GetPlayerStatisticVersions
- GetPlayerStatisticVersionsRequest
  - StatisticName (string) - 统计信息的唯一名称。
- GetPlayerStatisticVersionsResult
  - StatisticVersions (PlayerStatisticVersion[]) - 统计信息的版本更改历史记录（所有版本）。
IncrementPlayerStatisticVersion
- IncrementPlayerStatisticVersionRequest
  - StatisticName (string) - 统计信息的唯一名称。
- IncrementPlayerStatisticVersionResult
  - StatisticVersion (PlayerStatisticVersion) - 由于此操作而过期的统计信息版本（及其存档状态）。

Client API 方法

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - StatisticNames (string[]) - 要返回的统计信息数组，按其唯一名称。
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - 请求的所有统计信息的 StatisticValue 数据数组。
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - Statistics (StatisticUpdate[]) - 要使用提供的值更新的统计信息。
- UpdatePlayerStatisticsResult（无参数）。

Server API 方法

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - PlayFabId (string) - 正在更新其统计信息的玩家的 PlayFab ID。
  - StatisticNames (string[]) - 要返回的统计信息数组，按其唯一名称。
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - 请求的所有统计信息的 StatisticValue 数据数组。
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - PlayFabId (string) - 正在更新其统计信息的玩家的 PlayFab ID。
  - Statistics (StatisticUpdate[]) - 要使用提供的值更新的统计信息。
- UpdatePlayerStatisticsResult（无参数）。

​统计信息和排行榜

​配置可重置的统计信息

​预先存在的统计信息

​手动重置统计信息

​重置何时发生

​读取和写入统计信息版本

​服务器请求

​服务器响应

​客户端请求

​客户端响应

​服务器请求

​服务器响应

​客户端请求

​客户端响应

​资源

​基本枚举

​基本类及其成员

​Admin API 方法

​Client API 方法

​Server API 方法

统计信息和排行榜

配置可重置的统计信息

预先存在的统计信息

手动重置统计信息

重置何时发生

读取和写入统计信息版本

服务器请求

服务器响应

客户端请求

客户端响应

服务器请求

服务器响应

客户端请求

客户端响应

资源

基本枚举

基本类及其成员

Admin API 方法

Client API 方法

Server API 方法