统计数据接口

管理统计数据的接口。

阅读时间9分钟

开发者可以使用 统计数据接口（Stats Interface） 管理用户的应用程序 统计数据，其中可包括开发者希望追踪的任何统计数据，例如收集的物品数量、玩家通关的最快时间、胜利或失败的总次数、用户执行某个动作的次数。你可以利用统计数据来决定何时解锁成就以及如何利用排行榜中的用户排名数据。

访问统计数据接口

要访问统计数据接口函数，需从 Platform Interface调用 EOS_Platform_GetStatsInterface 函数，获取EOS_HStats柄。与所有其他接口类似，需要tick EOS_HPlatform 句柄，确保完成请求后触发相应回调。

摄取统计数据

要使统计数据接口与用户的统计信息交互，必须在 开发者门户 上定义游戏的统计数据。然后可以调用 EOS_Stats_IngestStat 在应用程序中摄取统计数据，这会将统计数据提交到 EOS后端。

在统计数据被摄取后，后端上的更新可能不会立即生效，因为提交和处理统计数据都需要时间。因此，基于统计数据的成就也可能需要一些时间才能解锁。此外，数据摄取并不能保证处理一定成功。例如，如果在摄取调用中提供了不正确的 StatName 值，处理仍然可能失败。

EOS_Stats_IngestStat 函数所采用的的参数如下：

参数	说明
`Handle`	有效的 `EOS_HStats` 柄。
`Options`	包含正摄取的统计数据相关信息的 `EOS_Stats_IngestStatOptions` 结构。
`ClientData`	`CompletionDelegate` 中传回的任意数据。
`CompletionDelegate`	签名与 `EOS_Stats_OnIngestStatCompleteCallback` 一致的函数。在摄取统计数据操作完成后调用。

若成功完成，此函数将返回 EOS_EResult，值为 EOS_Success；若出现任何选项错误，则返回值 EOS_InvalidParameters。

摄取统计数据选项

EOS_Stats_IngestStatOptions 结构体的参数如下：

参数	说明
`ApiVersion`	设为EOS_STATS_INGESTSTAT_API_LATEST。
`UserId`	一个有效 `EOS_ProductUserId`，代表正在被摄取的统计数据所属用户的帐户ID。
`Stats`	包含想要摄取的统计数据信息的 `EOS_Stats_IngestData` 结构列表。
`StatsCount`	要摄取的统计数据数量。
`TargetUserId`	需要摄取的目标用户ID。

摄取数据

EOS_Stats_IngestData 结构包含特定统计数据的信息。其参数如下：

参数	说明
`ApiVersion`	设为 `EOS_STATS_INGESTDATA_API_LATEST`。
`StatName`	要摄取的统计数据名称。
`IngestAmount`	要提交给统计数据的整数值。

摄取统计数据完成回调信息

操作完成后，将调用提供给 CompletionDelegate 的所有 CompletionDelegate。它们返回 EOS_Stats_IngestStatCompleteCallbackInfo 结构，其参数如下：

参数	说明
`ResultCode`	若成功完成请求，则 `EOS_EResult` 包含值 `EOS_Success`。其他所有代码代表出错。
`ClientData`	使用 `ClientData` 参数传入 `EOS_Stats_IngestStat` 的情境。
`UserId`	一个有效 `EOS_ProductUserId`，代表正在被摄取的统计数据所属用户的帐户ID。

查询统计数据

EOS_Stats_QueryStats 函数可用于从EOS后端请求用户统计数据列表。操作完成时将在本地缓存统计数据，而不是通过函数本身返回统计数据。欲了解详情，参见复制统计数据部分。

EOS_Stats_QueryStats 函数采用以下参数：

参数	说明
`Handle`	有效的 `EOS_HStats` 柄。
`Options`	一个`EOS_Stats_QueryStatsOptions` 结构，包含正在获取统计数据所属用户的相关信息。
`ClientData`	`CompletionDelegate` 中传回的任意数据。
`CompletionDelegate`	签名与 `EOS_Stats_OnQueryStatsCompleteCallback` 一致的函数。在摄取统计数据操作完成后调用。

查询统计数据选项

EOS_Stats_QueryStatOptions 结构包含尝试查询的用户的相关信息，以及可选参数（其能缩小要获取的统计数据的范围）。其参数如下：

参数	说明
`ApiVersion`	设为 `EOS_STATS_QUERYSTATS_API_LATEST`。
`UserId`	一个有效 `EOS_ProductUserId`，代表正在被获取的统计数据所属用户的帐户ID。
`StartTime`（可选）	若不是 `EOS_STATS_TIME_UNDEFINED`，则它为开始时间的POSIX时间戳。
`EndTime`（可选）	若不是 `EOS_STATS_TIME_UNDEFINED`，则它为结束时间的POSIX时间戳。
`StatNames`（可选）	要查询的特定统计数据名称的列表。
`StatNamesCount` (Optional)	`StatNames` 中列出的名称列表。

若设置了 StartTime 和 EndTime 参数，查询将限定在给定的开始时间与结束时间之间。

查询统计数据完成时调用信息

操作完成后，将调用提供给 EOS_Stats_QueryStats 的 CompletionDelegate。它们将返回 EOS_Stats_OnQueryStatsCompleteCallbackInfo 结构，拥有以下参数：

参数	说明
`ResultCode`	若成功完成请求，则 `EOS_EResult` 包含值 `EOS_Success`。其他所有代码代表出错。
`ClientData`	使用 `ClientData` 参数传入 `EOS_Stats_QueryStats` 的情境。
`UserId`	一个有效 `EOS_ProductUserId`，代表正在被摄取的统计数据所属用户的帐户ID。

复制统计数据

EOS_Stats_QueryStats 成功完成操作后，将在本地缓存所请求的统计数据。然后可利用 EOS_Stats_CopyStatByIndex 或 EOS_Stats_CopyStatByName 从本地缓存获得给定统计数据的副本。

EOS统计数据结构体

用于复制统计数据信息的函数将返回 EOS_Stats_Stat 结构，其表示单个特定用户统计数据的信息。其属性如下：

属性	说明
`ApiVersion`	设为 `EOS_STATS_STAT_API_LATEST`。
`Name`	开发者门户中显示的统计数据的名称。
`StartTime`	若不是 `EOS_STATS_TIME_UNDEFINED`，则这是返回此统计数据的查询的开始时间POSIX时间戳。
`EndTime`	若不是 `EOS_STATS_TIME_UNDEFINED`，则这是返回此统计数据的查询的结束时间POSIX时间戳。
`Value`	统计数据的当前值（整数）。

获取统计数据计数

成功查询玩家的统计数据后，即可使用 EOS_Stats_GetStatsCount 来检查本地缓存的统计数据数量。此函数采用以下参数：

参数	说明
`Handle`	有效的 `EOS_HStats` 柄。
`Options`	`EOS_Stats_GetStatCountOptions` 结构，包含设为 `EOS_STATS_GETSTATCOUNT_API_LATEST` 值的 `ApiVersion`，以及设为有效 `EOS_ProductUserId`（针对正在获取统计数据数量所属用户）的 `UserId`。

此函数将返回整数，表示当前缓存的统计数据数量。

按索引复制统计数据

函数 EOS_Stats_CopyStatByIndex 根据缓存统计数据列表中的给定索引来获取统计数据副本。其参数如下：

参数	说明
`Handle`	有效的 `EOS_HStats` 柄。
`Options`	`EOS_Stats_CopyStatByIndexOptions` 结构，包含要从中获取统计数据的缓存中的所需索引。
`OutStat`	`EOS_Stats_Stat` 类型的输出参数，包含所需统计数据的信息。完成时使用 `EOS_Stats_Stat_Release`。

输出参数 OutStat 用于在操作完成时输出所需的 EOS_Stats_Stat。函数返回值为 EOS_EResult。若信息可用且成功通过 OutStat 传递，则其值为 EOS_Success。若任意参数无效，或为输出参数提供了空指针，则其值为 EOS_InvalidParameters；若未找到请求的统计数据，则其值为 EOS_NotFound。

按索引选项复制统计数据

EOS_Stats_CopyStatByIndexOptions 结构，包含请求的 EOS_Stats_CopyStatByIndex 统计数据索引。其参数如下：

参数	说明
`ApiVersion`	设为 `EOS_STATS_COPYSTATBYINDEX_API_LATEST`。
`UserId`	有效的 `EOS_ProductUserId`，表示正在获取其统计数据副本的帐户ID。
`StatIndex`	一个整数，指统计数据缓存列表中的索引。

按名称复制统计数据

EOS_Stats_CopyStatByName 函数根据开发者门户中给定的统计数据名称来获取该统计数据的副本。其参数如下：

参数	说明
`Handle`	有效的 `EOS_HStats` 柄。
`Options`	`EOS_Stats_CopyStatByNameOptions` 结构，包含要从缓存中获取的统计数据名称。
`OutStat`	`EOS_Stats_Stat` 类型的输出参数，包含所需统计数据的信息。完成时使用 `EOS_Stats_Stat_Release`。

输出参数 OutStat 用于在操作完成时输出所需的 EOS_Stats_Stat。函数返回值为 EOS_EResult。若信息可用且成功通过 OutStat 传出，则其值为 EOS_Success。若任意参数无效，或为输出参数提供了空指针，则其值为 EOS_InvalidParameters。若未找到请求的统计数据，则其值为 EOS_NotFound。

按名称选项复制统计数据

EOS_Stats_CopyStatByNameOptions 结构包含请求的 EOS_Stats_CopyStatByName 统计数据索引。其参数如下：

参数	说明
`ApiVersion`	设为 `EOS_STATS_COPYSTATBYNAME_API_LATEST`。
`UserId`	一个有效 `EOS_ProductUserId`，代表正在被获取的统计数据副本所属用户的帐户ID。
`StatName`	正在获取其副本的统计数据的名称。

从缓存统计数据释放内存

使用 EOS_Stats_CopyStatByIndex 获取统计数据后，必须调用 EOS_Stats_Stat_Release 释放与该统计数据关联的内存。此函数接受 EOS_Stats_CopyStatByName 或 EOS_Stats_CopyStatByIndex 的 OutStat 参数输出的 EOS_Stats_Stat 结构。

使用限制

统计接口管理应用程序中用户的统计数据，其中可以包括开发者希望跟踪的任何统计数据，例如收集的物品数量、玩家最快完成关卡的时间、胜利或失败的总次数，或者用户执行某个动作的次数。你可以使用统计信息来决定何时解锁成就，以及如何利用排行榜中用户的排名信息。有关限制、使用配额和最佳实践的信息，请参阅服务使用限制。

以下限制适用于整个统计信息系统：

功能	限制
统计数据数目	500（每个部署）
统计数据名称长度	256个字符
单次调用最大获取的统计数据（Max stats ingested per call）	3000
最大里程碑数（默认）	100

统计数据摄取是向服务提交统计数据变更的端点，它存在速率限制（按用户）。当专用服务器代表用户提交统计数据时，限制（按用户）将不适用；在这类情况下，限制会根据当时每个部署的并发用户数（CCU）而定。

使用类型（Usage Type）	限制（按用户）（Per-User Limit）	限制（部署）（Per-Deployment Limit）
摄取统计数据（Ingest stats）	每分钟60次请求，每次请求500条统计数据	每分钟每5个CCU有一次请求
根据玩家ID获取统计数据（Get stats by Player ID）	每分钟100次请求	-
根据多个玩家ID获取统计数据（Get stats by Player IDs）	每分钟100次请求，每次请求64位玩家，每位玩家25条统计数据	-
创建统计数据（Create Stat）	-	每分钟100次请求
删除统计数据（Delete Stat）	-	每分钟100次请求

测试你的成就和统计数据

如果你想在测试沙盒中测试你的成就，你必须在该沙盒的部署中包括你的统计数据。你需要在部署到Live环境前这样做，以便检查统计数据中的的错误，确保玩家可以成功解锁成就。

有关为游戏创建测试沙盒的更多详情，请参见产品、沙盒和部署ID。