使用可重設的統計資料與排行榜 - XBOX Game Development Documentation

本教學課程完整逐步說明如何設定和管理具有版本控制的統計資料 (這可讓統計資料重設)，以及延伸至排行榜的部分。我們將著重於如何使用 Admin API 方法，並額外說明如何使用用戶端與 Server API 方法來查詢資料，包括目前版本與舊版本。我們的目標是為您提供技術性的回顧，說明可重設的統計資料在 PlayFab 中如何運作，以及在遊戲中使用它們的所有方式。

統計資料與排行榜

首先，請務必注意，在 PlayFab 中為遊戲玩家定義的所有統計資料都是排行榜的一部分。因此，定義統計資料也就定義了排行榜。統計資料不一定會對玩家顯示，但它們確實存在。您可以使用它們依您定義的分數取得玩家清單，無論是要找出所有分數中最高的、最低的、以目前玩家為中心的，還是使用者好友清單上的玩家。遊戲中的許多統計資料都是作為終身值，這表示玩家會持續更新分數，舊的分數會一直保留，直到每位玩家打破自己的個人最佳成績為止。不過，對於某些玩家體驗而言，能夠不時「清除」排行榜是很重要的。這可用來鼓勵使用者嘗試在特定期間內成為排名第一的玩家，或只是將一段時間未活動的玩家從排名中移除。如本教學課程所述，PlayFab 中的統計資料可以設定為依預先決定的間隔重設。這不僅適用於上述情境，也可用於需要有獨立近期分數排行榜的遊戲，例如遊戲挑戰，讓玩家可以向技術水準相近的人發出邀請。設定重設期間表示，例如在呼叫 GetLeaderboardAroundPlayer 時傳回的玩家，會是最近玩過遊戲且分數與本機玩家相近的玩家。您也可以透過手動作業重設統計資料。這是一個方便的系統，可清除您在上市前測試或 Alpha/Beta 遊玩期間的任何資料。它在最糟的情況下也很有用，例如遊戲程式碼中引入了錯誤，導致分數失控。在每種情況下，您都需要能夠將排行榜清除乾淨，讓玩家覺得自己有公平的機會登上排行榜。

重設統計資料並不會刪除這些值，如下所示。在重設時，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 是此功能的關鍵，可以定義為每小時、每天、每週或每月。如果您稍後決定不再希望統計資料定期重設，也可以將其設定為永不。在下列範例中，對 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，其中包含：

統計資料的字串識別碼 (StatisticName)。
統計資料已重設的次數 (CurrentVersion)。
統計資料重設時機的定義期間 (VersionChangeInterval)。

重設期間在定義後會立即生效，因此在此情況下，第二個呼叫表示重設現在定義為星期一早上 00:00 UTC (使用 UTC 時區，即星期日晚上/星期一早上的午夜)，無論呼叫之前的設定為何。其餘的重設間隔也是使用 UTC 定義，Month 會讓重設在每個月第一天的 00:00 UTC 發生。完整的重設期間清單如下：

Never：停止以時間為基礎對統計資料進行版本控制。
Hour：在每個 Hour 的整點 (XX:00 UTC) 對統計資料進行版本控制。
Day：在每 Day 的午夜 (00:00 UTC) 對統計資料進行版本控制。
Week：在每週一的午夜 (00:00 UTC) 對統計資料進行版本控制。
Month：在每個月第一天的午夜 (00:00 UTC) 對統計資料進行版本控制。

既有的統計資料

遊戲中定義的所有統計資料都可以查詢其定義，無論它們是否設定為重設統計資料。請務必注意這一點，因為統計資料可以使用 UpdatePlayerStatistics 呼叫來建立。任何未以重設期間 (VersionChangeInterval) 建立的統計資料，一開始都不會有重設期間，因此查詢統計資料設定時，傳回的此參數會設定為 Never。以上述範例而言，如果遊戲還有一個使用 UpdatePlayerStatistics 建立 (或直接在 Game Manager 中針對玩家建立) 的統計資料，名稱為 FlagsCaptured，且已經過了幾週，則它在下方所示的呼叫中會如下所示。

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 定義的一樣。

手動重設統計資料

當遊戲錯誤導致統計資料可被作弊，或您只是需要重設以移除上市前遊玩的分數時，可以在 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 資訊，其中包含統計資料的識別碼 (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 方法