获取 Xbox Live 游戏中心数据Get Xbox Live Game Hub data

在 Microsoft Store 分析 API 中使用此方法获取你的支持 Xbox Live 的游戏的游戏中心数据。Use this method in the Microsoft Store analytics API to get Game Hub data for your Xbox Live-enabled game. 合作伙伴中心的 Xbox analytics 报告 中也提供了此信息。This information is also available in the Xbox analytics report in Partner Center.

重要

该方法只支持 Xbox 游戏或使用 Xbox Live 服务的游戏。This method only supports games for Xbox or games that use Xbox Live services. 这些游戏必须经过概念审批流程,其中包括 Microsoft 合作伙伴发布的游戏以及通过 ID@Xbox 计划提交的游戏。These games must go through the concept approval process, which includes games published by Microsoft partners and games submitted via the ID@Xbox program. 该方法当前不支持通过 Xbox Live 创意者计划发布的游戏。This method does not currently support games published via the Xbox Live Creators Program.

必备条件Prerequisites

若要使用此方法,首先需要执行以下操作:To use this method, you need to first do the following:

  • 完成 Microsoft Store 分析 API 的所有先决条件(如果尚未这样做)。If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • 获取 Azure AD 访问令牌,以供在此方法的请求标头中使用。Obtain an Azure AD access token to use in the request header for this method. 获取访问令牌后,在它到期前,你有 60 分钟的使用时间。After you obtain an access token, you have 60 minutes to use it before it expires. 该令牌到期后,可以获取新的令牌。After the token expires, you can obtain a new one.

请求Request

请求语法Request syntax

方法Method 请求 URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics

请求头Request header

标头Header 类型Type 描述Description
授权Authorization 字符串string 必需。Required. Azure AD 访问令牌的格式为 Bearer <token> 。The Azure AD access token in the form Bearer <token>.

请求参数Request parameters

参数Parameter 类型Type 描述Description 必需Required
applicationIdapplicationId 字符串string 你要检索 Xbox Live 游戏中心数据的游戏的 Store IDThe Store ID of the game for which you want to retrieve Xbox Live Game Hub data. Yes
metricTypemetricType 字符串string 指定要检索的 Xbox Live 分析数据的类型的字符串。A string that specifies the type of Xbox Live analytics data to retrieve. 对于此方法,指定值 communitymanagergamehubFor this method, specify the value communitymanagergamehub. Yes
startDatestartDate 日期date 要检索的游戏中心数据日期范围中的开始日期。The start date in the date range of Game Hub data to retrieve. 默认值为当前日期之前 30 天。The default is 30 days before the current date. No
endDateendDate 日期date 要检索的游戏中心数据日期范围中的结束日期。The end date in the date range of Game Hub data to retrieve. 默认值为当前日期。The default is the current date. No
toptop intint 要在请求中返回的数据行数。The number of rows of data to return in the request. 如果未指定,最大值和默认值为 10000。The maximum value and the default value if not specified is 10000. 当查询中存在多行数据时,响应正文中包含的下一个链接可用于请求下一页数据。If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. No
skipskip intint 要在查询中跳过的行数。The number of rows to skip in the query. 使用此参数可以浏览较大的数据集。Use this parameter to page through large data sets. 例如,top=10000 和 skip=0,将检索前 10000 行数据;top=10000 和 skip=10000,将检索之后的 10000 行数据,依此类推。For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. No

请求示例Request example

以下示例演示了一个请求,该请求用于获取你的支持 Xbox Live 的游戏的游戏中心数据。The following example demonstrates a request for getting Game Hub data for your Xbox Live-enabled game. applicationId 值替换为你的游戏的 Store ID。Replace the applicationId value with the Store ID for your game.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics?applicationId=9NBLGGGZ5QDR&metrictype=communitymanagergamehub&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

响应Response

Value 类型Type 说明Description
Value arrayarray 一个对象数组,其中包含指定时间范围内每个日期的游戏中心数据。An array of objects that contain Game Hub data for each date in the specified date range. 有关每个对象中的数据的详细信息,请参阅下表。For more information about the data in each object, see the following table.
@nextLink 字符串string 如果存在其他数据页,则此字符串包含一个你可用来请求下一页数据的 URI。If there are additional pages of data, this string contains a URI that you can use to request the next page of data. 例如,当请求的 top 参数设置为 10000,但查询的数据超过 10000 行时,就会返回此值。For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of data for the query.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

Value 数组中的元素包含以下值。Elements in the Value array contain the following values.

Value 类型Type 描述Description
datedate 字符串string 此项目中游戏中心数据的日期。The date for the Game Hub data in this object.
applicationIdapplicationId 字符串string 你要为其检索游戏中心数据的游戏的 Store ID。The Store ID of the game for which you are retrieving Game Hub data.
gameHubLikeCountgameHubLikeCount 数字number 在指定日期添加到游戏中心页面上的赞的数量。The number of likes added to the Game Hub page on the specified date.
gameHubCommentCountgameHubCommentCount 数字number 在指定日期添加到你的应用的游戏中心页面上的评论的数量。The number of comments added to the Game Hub page for your app on the specified date.
gameHubShareCountgameHubShareCount 数字number 客户在指定日期共享你的应用的游戏中心页面的次数。The number of times the Game Hub page for your app was shared by customers on the specified date.
gameHubFollowerCountgameHubFollowerCount 数字number 应用的戏中心页面的历来的关注者数量。The number of all-time followers for the Game Hub page for your app.

响应示例Response example

以下示例举例说明此请求的 JSON 响应正文。The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2018-01-04",
      "applicationId": "9NBLGGGZ5QDR",
      "gameHubLikeCount": 10,
      "gameHubCommentCount": 1,
      "gameHubShareCount": 0,
      "gameHubFollowerCount": 15924
    },
    {
      "date": "2018-01-05",
      "applicationId": "9NBLGGGZ5QDR",
      "gameHubLikeCount": 12,
      "gameHubCommentCount": 1,
      "gameHubShareCount": 0,
      "gameHubFollowerCount": 15931
    }
  ],
  "@nextLink": null,
  "TotalCount": 26
}