> ## 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`：此参数处理对我们服务的每个请求背后的所有身份验证。有关详细说明，您可以查看以下页面：[统计数据快速入门](/services/playfab/player-progression/statistics/quickstart-statistics)。
* `Name`：此参数可帮助您识别统计数据定义。在此处保留一些相关内容非常重要，因为它将用于发出其他请求以检索信息。
* `EntityType`：此参数指定要为其创建统计数据的实体类型。您可以在此处了解更多信息：[实体编程模型](/services/playfab/live-service-management/game-configuration/entities)。
* `VersionConfiguration`：此参数允许您为在特定时间段后重置自身的统计数据设置版本控制策略。此概念在此处深入介绍：[季节性统计数据](/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}

### 删除统计数据定义

如果您想删除统计数据定义以添加更多列或修复某些错误，可以按以下方式操作：

 
``` 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，因此我们的统计数据跟踪玩家的信息。但是，请记住您也可以使用其他实体类型。您可以在此处查看它们：[可用的内置实体类型](/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`：此参数对应于可以添加到一个实体的分数列表。请记住，统计数据可以具有多列。您可以在此处深入了解这些概念：[使用统计数据做更多](/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>`：此参数是要删除的统计数据名称列表。

## 结论

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

* 创建统计数据
* 检查统计数据的配置
* 更新统计数据的配置
* 删除统计数据配置
* 填充统计数据
* 删除统计数据中的条目。

## 另请参阅

* [使用统计数据做更多](/services/playfab/player-progression/statistics/doing-more-statistics)。
* [季节性统计数据](/services/playfab/player-progression/statistics/seasonal-statistics)。
* [向统计数据添加上下文数据](/services/playfab/player-progression/statistics/metadata-statistics)。
* [事务性写入](/services/playfab/player-progression/statistics/transactional-writes)
* [API 参考](/services/playfab/player-progression/statistics/api-reference)。
* [限制](/services/playfab/player-progression/statistics/limits-statistics)。
* [配额](/services/playfab/player-progression/statistics/quota-statistics)


## Related topics

- [统计数据 API 参考](/zh-CN/services/playfab/player-progression/statistics/api-reference.md)
- [社区统计数据](/zh-CN/services/playfab/player-progression/statistics/community-statistics.md)
- [统计数据限制](/zh-CN/services/playfab/player-progression/statistics/limits-statistics.md)
- [使用统计数据做更多](/zh-CN/services/playfab/player-progression/statistics/doing-more-statistics.md)
- [元数据统计](/zh-CN/services/playfab/player-progression/statistics/metadata-statistics.md)