获取 Xbox Live 运行状况数据Get Xbox Live health data

在 Microsoft Store 分析 API 中使用此方法获取你的支持 Xbox Live 的游戏的运行状况数据。Use this method in the Microsoft Store analytics API to get health 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 health data. Yes
metricTypemetricType 字符串string 指定要检索的 Xbox Live 分析数据的类型的字符串。A string that specifies the type of Xbox Live analytics data to retrieve. 对于此方法,指定值 callingpatternFor this method, specify the value callingpattern. Yes
startDatestartDate 日期date 要检索的运行状况数据日期范围中的开始日期。The start date in the date range of health data to retrieve. 默认值为当前日期之前 30 天。The default is 30 days before the current date. No
endDateendDate 日期date 要检索的运行状况数据日期范围中的结束日期。The end date in the date range of health 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
filterfilter 字符串string 在响应中筛选行的一条或多条语句。One or more statements that filter the rows in the response. 每条语句包含的响应正文中的字段名称和值使用 eqne 运算符进行关联,并且语句可以使用 andor 进行组合。Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. filter 参数中的字符串值必须使用单引号引起来。String values must be surrounded by single quotes in the filter parameter. 可以指定响应正文中的以下字段:You can specify the following fields from the response body:

  • deviceTypedeviceType
  • packageVersionpackageVersion
  • sandboxIdsandboxId
No
groupbygroupby 字符串string 仅将数据聚合应用于指定字段的语句。A statement that applies data aggregation only to the specified fields. 可以指定响应正文中的以下字段:You can specify the following fields from the response body:

  • datedate
  • deviceTypedeviceType
  • packageVersionpackageVersion
  • sandboxIdsandboxId

如果你指定一个或多个 groupby 字段,则在响应正文中,你未指定的任何其他 groupby 字段都为值 AllIf you specify one or more groupby fields, any other groupby fields you do not specify will have the value All in the response body.

No

请求示例Request example

以下示例演示了一个请求,该请求用于获取你的支持 Xbox Live 的游戏的运行状况数据。The following example demonstrates a request for getting health 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=callingpattern&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

响应Response

Value 类型Type 说明Description
Value arrayarray 包含运行状况数据的对象数组。An array of objects that contain health data. 有关每个对象中的数据的详细信息,请参阅下表。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
applicationIdapplicationId 字符串string 要检索其运行状况数据的游戏的 Store ID。The Store ID of the game for which you are retrieving health data.
datedate 字符串string 运行状况数据的日期范围内的第一个日期。The first date in the date range for the health data. 如果请求指定了某一天,此值就是该日期。If the request specified a single day, this value is that date. 如果请求指定了一周、月或其他日期范围,此值是该日期范围内的第一个日期。If the request specified a week, month, or other date range, this value is the first date in that date range.
deviceTypedeviceType 字符串string 用于指定在其上使用你的游戏的设备类型的以下字符串之一:One of the following strings that specifies the type of device on which your game was used:

  • XboxOneXboxOne
  • WindowsOneCore(此值指示电脑)WindowsOneCore (this value indicates a PC)
  • UnknownUnknown
sandboxIdsandboxId 字符串string 为游戏创建的沙盒的 ID。The sandbox ID created for the game. 这可以为值 RETAIL,或者是私有沙盒的 ID。This can be the value RETAIL or the ID for a private sandbox.
packageVersionpackageVersion 字符串string 游戏的四个部分程序包版本。The four-part package version for the game.
callingPatterncallingPattern 对象 (object)object callingPattern 对象为指定日期范围内你的游戏所使用的每个 Xbox Live 服务返回的每个状态代码提供服务响应、设备和用户数据。A callingPattern object that provides service responses, devices, and user data for each status code returned by each Xbox Live service used by your game for the specified date range.

callingPatterncallingPattern

Value 类型Type 描述Description
服务service 字符串string 运行状况数据与之相关的 Xbox Live 服务的名称。The name of the Xbox Live service that the health data relates to.
endpointendpoint 字符串string 运行状况数据与之相关的 Xbox Live 服务的端点。The endpoint of the Xbox Live service that the health data relates to.
httpStatusCodehttpStatusCode 字符串string 这一组运行状况数据的 HTTP 状态代码。The HTTP status code for this set of health data.

Note   注意  状态代码429E指示服务调用成功,因为调用期间,不会有精细的速率限制Note  The status code 429E indicates that the service call succeeded only because fine grained rate limiting was exempt during the call. 如果对服务的需求很高,则可以强制实施精细的速率限制,在这种情况下呼叫服务可能会获得 HTTP 429 状态代码Fine grained rate limited could be enforced in the future if the service experiences high volume, and in that case the call would result in an HTTP 429 status code.

serviceResponsesserviceResponses 数字number 返回指定状态代码的服务响应的数量。The number of service responses that returned the specified status code.
uniqueDevicesuniqueDevices 数字number 呼叫服务并接收状态代码的不同设备的数量。The number of unique devices that called the service and received the specified status code.
uniqueUsersuniqueUsers 数字number 接收指定状态代码的不同用户的数量。The number of unique users who received the specified status code.

响应示例Response example

以下示例举例说明此请求的 JSON 响应正文。The following example demonstrates an example JSON response body for this request. 在此示例中显示的服务名称和端点并不是真实的,仅在示例中使用。The service names and endpoints shown in this example are not real, and are used for example purposes only.

{
  "Value": [
    {
      "applicationId": "9NBLGGGZ5QDR",
      "date": "2018-01-30",
      "deviceType": "All",
      "sandboxId": "RETAIL",
      "packageVersion": "Unknown",
      "callingpattern": [
        {
          "service": "userstats",
          "endpoint": "UserStats.BatchReadHandler.POST",
          "httpStatusCode": "200",
          "serviceResponses": 160891,
          "uniqueDevices": 410,
          "uniqueUsers": 410
        },
        {
          "service": "userstats",
          "endpoint": "UserStats.BatchStatReadHandler.GET",
          "httpStatusCode": "200",
          "serviceResponses": 422,
          "uniqueDevices": 0,
          "uniqueUsers": 30
        }
      ],
    }
  ],
  "@nextLink": null,
  "TotalCount": 1
}