> ## 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 統計資料，然後寫入玩家值以追蹤一段時間內的進度。

在本教學課程中，我們將示範如何使用新的統計資料服務建立基本統計資料。讓我們以一款射擊遊戲為例，該遊戲想要追蹤玩家每次命中遠距離射擊的情況。

## 建立統計資料

第一步是建立統計資料定義，其中包含追蹤遠距離射擊的主要元素。對於我們的射擊遊戲，我們只需要一個資料行來記錄遠距離射擊的距離。下列範例示範如何使用 C# SDK 建立統計資料定義。

```C# theme={null}
public static async Task CreateStatisticDefinitionAsync(PlayFabAuthenticationContext context, string statName)
{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateStatisticDefinitionRequest statDefinitionRequest = new CreateStatisticDefinitionRequest()
    {
        Name = statName,
        AuthenticationContext = context,
        EntityType = "title_player_account",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<StatisticColumn>()
        {
            new StatisticColumn()
            {
                Name = "Distance",
                AggregationMethod = StatisticAggregationMethod.Max,
            }
        },
    };
    
    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createStatDefResult = await statsAPI.CreateStatisticDefinitionAsync(statDefinitionRequest);
}
```

現在，讓我們說明此範例的一些關鍵元素：

* `AuthenticationContext`：此參數處理我們服務每個要求背後的所有驗證。如需詳細說明，您可以查看下列頁面：[統計資料快速入門](/zh-TW/services/playfab/player-progression/statistics/quickstart-statistics)。
* `Name`：此參數可協助您識別統計資料定義。請務必在此使用相關的名稱，因為它將用於發出其他要求以擷取資訊
* `EntityType`：此參數指定您要為其建立統計資料的實體類型。您可以在此深入了解：[實體程式設計模型](/zh-TW/services/playfab/live-service-management/game-configuration/entities)。
* `VersionConfiguration`：此參數可讓您為在特定期間後自行重設的統計資料設定版本控制策略。此概念在此深入說明：[季節性統計資料](/zh-TW/services/playfab/player-progression/statistics/seasonal-statistics)。
* `Columns`：在這裡，我們定義統計資料的資料行數目，每個定義最多 5 個。在此範例中，我們只為遠距離射擊設定一個資料行。我們也將 `AggregationMethod` 定義為 Max，這表示只有在新值大於先前的值時，才會更新統計資料。
  * `AggregationMethod` 有四個可能的值：
    * `Max`：新值必須大於先前的值。
    * `Min`：新值必須小於先前的值。
    * `Last`：一律以最新的值更新。
    * `Sum`：將先前的值與新值相加。

了解所有資訊後，您現在已準備好執行範例並建立您的第一個統計資料。

### 取得統計資料定義

在將資料新增至此統計資料之前，我們想要確保它已正確建立。為了執行此動作，我們提供一個如何擷取統計資料定義的範例。

```C# theme={null}
public static async Task GetStatisticDefinition(PlayFabAuthenticationContext context, string statName)
{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    GetStatisticDefinitionRequest statDefReq = new GetStatisticDefinitionRequest()
    {
        Name = statName
    };

    PlayFabResult<GetStatisticDefinitionResponse> getStatDefResult = await statsAPI.GetStatisticDefinitionAsync(statDefReq)
}
```

若要擷取統計資料定義，請指定您所建立之統計資料的名稱。如果您有多個統計資料定義，可以使用下一個範例，透過單一要求取得所有統計資料定義。

```C# theme={null}
public static async Task GetStatisticDefinitions(PlayFabAuthenticationContext context)
{
     PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
     ListStatisticDefinitionsRequest request = new ListStatisticDefinitionsRequest();
     PlayFabResult<ListStatisticDefinitionsResponse> getStatDefsResult = await leaderboardsAPI.ListStatisticDefinitionsAsync(request);
           
}
```

### 更新統計資料定義

如果您想要更新統計資料定義，可以如下所示進行：

```C# theme={null}
public static async Task UpdateStatisticDefinitionAsync(PlayFabAuthenticationContext context, string statisticName, VersionConfiguration version)
{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateStatisticDefinitionRequest updateStatDefinitionRequest = new UpdateStatisticDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = statisticName,
        VersionConfiguration = version

    };
    PlayFabResult<PlayFab.ProgressionModels.EmptyResponse> updateStatDefinitionResult = await statsAPI.UpdateStatisticDefinitionAsync(updateStatDefinitionRequest);

}

```

請注意，Columns、EntityType 和 ResetInterval 無法在更新過程中修改。

````C# theme={null}

### Deleting statistic definition

If you want to delete your statistic definition to add more columns or fix some errors, you can do so as follows:

 
``` C#

public static async Task DeleteStatisticDefinition(PlayFabAuthenticationContext context, string statName)
\{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteStatisticDefinitionRequest deleteStatDefRequest = new DeleteStatisticDefinitionRequest()
    \{
        AuthenticationContext = context,
        Name = statName,
    \};
    
    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> statResponse = await statsAPI.DeleteStatisticDefinitionAsync(deleteStatDefRequest);    
\}
````

## 將資料新增至統計資料

繼續我們的射擊範例，我們現在知道如何建立統計資料定義、擷取它，以及在必要時刪除它。我們的下一步是開始將資料新增至統計資料。

請記住，這些統計資料是以實體為基礎的統計資料，這表示項目是實體。在我們的特定範例中，我們使用的是實體類型 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 UpdateStatisticForPlayer(PlayFabAuthenticationContext context, string statName, string entityId, int score)
\{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateStatisticsRequest updateStatRequest = new UpdateStatisticsRequest()
    \{
        Entity = new PlayFab.LeaderboardsModels.EntityKey()
        \{
            Id = entityId,
            Type = EntityType
        \},
        AuthenticationContext = context,
        Statistics = new List<PlayFab.LeaderboardsModels.StatisticUpdate>() 
        \{
            new PlayFab.LeaderboardsModels.StatisticUpdate() 
            \{
                Name = statName,
                Scores = new List<string> \{ score.ToString()\},
            \}
        \}
    \};

    PlayFabResult<UpdateStatisticsResponse> updateResult = await statsAPI.UpdateStatisticsAsync(updateStatRequest);
\}
```

現在，讓我們說明此範例的一些關鍵元素：

* `Entity`：此參數對應於我們想要更新其統計資料的實體。
* `Statistics`：此參數對應於實體的實際統計資料集。
* `StatisticUpdate`：此參數對應於要新增的統計值。
  * `Scores`：此參數對應於您可以新增至一個實體的分數清單。請記住，統計資料可以有多個資料行。您可以在此深入查看這些概念：[統計資料的進階運用](/zh-TW/services/playfab/player-progression/statistics/doing-more-statistics)
  * `Name`：此參數對應於您建立統計資料定義時所設定的統計資料名稱。

了解這些概念後，您現在已準備好將資料新增至統計資料。

## 從統計資料擷取資料

讓我們快速回顧一下。此時，您已建立統計資料、檢查所有設定詳細資料，並開始將資料新增至其中。現在，讓我們想像一些玩家已經開始玩您的遊戲，而且都有令人印象深刻的遠距離射擊。我們想要查詢其中一位。在下列範例中，我們將示範如何執行此動作。

```C# theme={null}
public static async Task GetStatsForEntity(PlayFabAuthenticationContext context, string entityId)
\{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);

    GetStatisticsRequest request = new GetStatisticsRequest()
    \{
        AuthenticationContext = context,
        Entity = new PlayFab.LeaderboardsModels.EntityKey()
        \{
            Id = entityId,
            Type = EntityType
        \},
    \};
    
    PlayFabResult<GetStatisticsResponse> result = await statsAPI.GetStatisticsAsync(request);

    Console.WriteLine("Stats for entity: " + result.Result.Entity.ToString());
    foreach (KeyValuePair<string, PlayFab.LeaderboardsModels.EntityStatisticValue> statValuePair in result.Result.Statistics)
    \{
        Console.WriteLine($"\{statValuePair.Value.Name\} : \{string.Join('|', statValuePair.Value.Scores)\}");
    \}
\}
```

在這裡，我們查詢與實體相關聯的所有統計資料，然後列印名稱及其對應的值。

## 刪除統計值

我們的統計資料如預期般運作，而且您的遊戲中有許多玩家。不過，我們開始注意到遊戲中有一些不尋常的行為。因此，我們決定重新開始並刪除統計資料的資料。在下一個範例中，您可以看到如何刪除統計資料中的資料。

```C# theme={null}

 public static async Task DeleteStats(PlayFabAuthenticationContext context, string entityId, List<StatisticDelete> stats)
 \{
     PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
     DeleteStatisticsRequest statsDelReq = new DeleteStatisticsRequest()
     \{
         Entity = new PlayFab.LeaderboardsModels.EntityKey()
         \{
            Id = entityId,
            Type = EntityType
         \},
         Statistics = stats
     \};
 
     PlayFabResult<DeleteStatisticsResponse> delStatsResult = await statsAPI.DeleteStatisticsAsync(statsDelReq);     
 \}
```

現在，讓我們說明此範例的一些關鍵元素：

* `Entity`：此參數是您要從中刪除資料的實體。
* `List<StatisticDelete>`：此參數是您要刪除之統計資料名稱的清單。

## 結論

在本教學課程中，我們學到了如何執行下列作業：

* 建立統計資料
* 檢查統計資料的設定
* 更新統計資料的設定
* 刪除統計資料設定
* 填入統計資料
* 刪除統計資料中的項目。

## 另請參閱

* [統計資料的進階運用](/zh-TW/services/playfab/player-progression/statistics/doing-more-statistics)。
* [季節性統計資料](/zh-TW/services/playfab/player-progression/statistics/seasonal-statistics)。
* [將內容資料新增至統計資料](/zh-TW/services/playfab/player-progression/statistics/metadata-statistics)。
* [交易式寫入](/zh-TW/services/playfab/player-progression/statistics/transactional-writes)
* [API 參考](/zh-TW/services/playfab/player-progression/statistics/api-reference)。
* [限制](/zh-TW/services/playfab/player-progression/statistics/limits-statistics)。
* [配額](/zh-TW/services/playfab/player-progression/statistics/quota-statistics)


## Related topics

- [中繼資料統計資料](/zh-TW/services/playfab/player-progression/statistics/metadata-statistics.md)
- [統計資料 API 參考](/zh-TW/services/playfab/player-progression/statistics/api-reference.md)
- [社群統計資料](/zh-TW/services/playfab/player-progression/statistics/community-statistics.md)
- [統計資料的進階運用](/zh-TW/services/playfab/player-progression/statistics/doing-more-statistics.md)
- [統計資料配額](/zh-TW/services/playfab/player-progression/statistics/quota-statistics.md)