获取 Xbox Live 分析数据Get Xbox Live analytics data

在 Microsoft Store 分析 API 中使用此方法来获取玩你的支持 Xbox Live 的游戏的客户的前 30 天常规分析数据,包括设备附件使用情况、Internet 连接类型、玩家分数分布、游戏统计数据,以及好友和关注者数据。Use this method in the Microsoft Store analytics API to get the last 30 days of general analytics data for customers playing your Xbox Live-enabled game, including device accessory usage, internet connection type, gamerscore distribution, game statistics, and friends and followers data. 合作伙伴中心的 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.

针对支持 Xbox Live 的游戏的额外分析数据通过以下方法提供:Additional analytics data for Xbox Live-enabled games is available via the following methods:

必备条件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 general Xbox Live analytics data. Yes
metricTypemetricType 字符串string 指定要检索的 Xbox Live 分析数据的类型的字符串。A string that specifies the type of Xbox Live analytics data to retrieve. 对于此方法,指定值 productvaluesFor this method, specify the value productvalues. Yes

请求示例Request example

以下示例演示了一个请求,该请求用于获取玩你的支持 Xbox Live 的游戏的客户的常规分析数据。The following example demonstrates a request for getting general analytics data for customers playing 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=productvalues HTTP/1.1
Authorization: Bearer <your access token>

响应Response

此方法返回一个包含以下对象的 Value 数组。This method returns a Value array that contains the following objects.

对象Object 描述Description
ProductDataProductData 包含一个 DeviceProperties 对象以及一个 UserProperties 对象,它们包含过去 30 天内您的游戏的设备和用户分析数据。Contains one DeviceProperties object and one UserProperties object that contain the last 30 days of device and user analytics data for your game.
XboxwideDataXboxwideData 包含一个 DeviceProperties 对象以及一个 UserProperties 对象,它们包含过去 30 天内所有 Xbox Live 客户的平均设备和用户分析数据(百分比形式)。Contains one DeviceProperties object and one UserProperties object that contain the last 30 days of average device and user analytics data for all Xbox Live customers, as percentages. 包含此数据是为了对您的游戏数据进行比较。This data is included for comparison purposes with the data for your game.

DevicePropertiesDeviceProperties

此资源包含过去 30 天内您的游戏的设备使用情况数据或所有 Xbox Live 客户的平均设备使用情况数据。This resource contains device usage data for your game or average device usage data for all Xbox Live customers during the last 30 days.

Value 类型Type 描述Description
applicationIdapplicationId 字符串string 检索其分析数据的游戏的 Store IDThe Store ID of the game for which you retrieved analytics data.
connectionTypeDistributionconnectionTypeDistribution arrayarray 包含指示 Xbox 有多少客户使用有线 Internet 连接,多少客户使用无线 Internet 连接的对象。Contains objects that indicate how many customers use a wired internet connection versus a wireless internet connection on Xbox. 每个对象都有两个字符串字段:Each object has two string fields:
  • conType:指定连接类型。conType: Specifies the connection type.
  • deviceCount:在 ProductData 对象中,此字段指定使用该连接类型的游戏客户的数量。deviceCount: In the ProductData object, this field specifies the number of your game's customers that use the connection type. XboxwideData 对象中,此字段指定使用该连接类型的所有 Xbox Live 客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that use the connection type.
deviceCountdeviceCount 字符串string ProductData 对象中,此字段指定过去 30 天内用于玩你的游戏的客户设备的数量。In the ProductData object, this field specifies the number of customer devices on which your game has been played during the last 30 days. XboxwideData 对象中,此字段将为始终为 1,指示所有 Xbox Live 客户的数据的起始百分比为 100%。In the XboxwideData object, this field is always 1, indicating a starting percentage of 100% for data for all Xbox Live customers.
eliteControllerPresentDeviceCounteliteControllerPresentDeviceCount 字符串string ProductData 对象中,此字段指定使用 Xbox Elite 无线控制器的游戏客户的数量。In the ProductData object, this field specifies the number of your game's customers that use the Xbox Elite Wireless Controller. XboxwideData 对象中,此字段指定使用 Xbox Elite 无线控制器的所有 Xbox Live 客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that use the Xbox Elite Wireless Controller.
externalDrivePresentDeviceCountexternalDrivePresentDeviceCount 字符串string ProductData 对象中,此字段指定在 Xbox 上使用外部硬盘驱动器的游戏客户的数量。In the ProductData object, this field specifies the number of your game's customers that use an external hard drive on Xbox. XboxwideData 对象中,此字段指定在 Xbox 上使用外部硬盘驱动器的所有 Xbox Live 客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that use an external hard drive on Xbox.

UserPropertiesUserProperties

此资源包含过去 30 天内您的游戏的用户数据或所有 Xbox Live 客户的平均用户数据。This resource contains user data for your game or average user data for all Xbox Live customers during the last 30 days.

Value 类型Type 描述Description
applicationIdapplicationId 字符串string 检索其分析数据的游戏的 Store IDThe Store ID of the game for which you retrieved analytics data.
UserCountuserCount 字符串string ProductData 对象中,此字段指定过去 30 天内玩你的游戏的客户的数量。In the ProductData object, this field specifies the number of customers that have played your game during the last 30 days. XboxwideData 对象中,此字段将为始终为 1,指示所有 Xbox Live 客户的数据的起始百分比为 100%。In the XboxwideData object, this field is always 1, indicating a starting percentage of 100% for data for all Xbox Live customers.
dvrUsageCountsdvrUsageCounts arrayarray 包含表明多少客户使用了游戏 DVR 来录制和查看游戏的对象。Contains objects that indicate how many customers have used game DVR to record and view gameplay. 每个对象都有两个字符串字段:Each object has two string fields:
  • dvrName:指定所使用的游戏 DVR 功能。dvrName: Specifies the game DVR feature used. 可能的值为 gameClipUploadsgameClipViewsscreenshotUploadsscreenshotViewsPossible values are gameClipUploads, gameClipViews, screenshotUploads, and screenshotViews.
  • userCount:在 ProductData 对象中,此字段指定使用指定游戏 DVR 功能的游戏客户的数量。userCount: In the ProductData object, this field specifies the number of your game's customers that used the specified game DVR feature. XboxwideData 对象中,此字段指定使用指定游戏 DVR 功能的所有 Xbox Live 客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that used the specified game DVR feature.
followerCountPercentilesfollowerCountPercentiles arrayarray 包含提供有关客户关注者数的详细信息的对象。Contains objects that provide details about the number of followers for customers. 每个对象都有两个字符串字段:Each object has two string fields:
  • percentage:目前,此值始终是 50,指示关注者数据以中值形式提供。percentage: Currently, this value is always 50, indicating that the follower data is provided as a median value.
  • value:在 ProductData 对象中,此字段指定您的游戏客户的关注者的中值数量。value: In the ProductData object, this field specifies the median number of followers for your game's customers. XboxwideData 对象中,此字段指定所有 Xbox Live 客户的关注者的中值数量。In the XboxwideData object, this field specifies the median number of followers for all Xbox Live customers.
friendCountPercentilesfriendCountPercentiles arrayarray 包含提供有关客户好友数的详细信息。Contains objects that provide details about the number of friends for customers. 每个对象都有两个字符串字段:Each object has two string fields:
  • percentage:目前,此值始终是 50,指示好友数据以中值形式提供。percentage: Currently, this value is always 50, indicating that the friends data is provided as a median value.
  • value:在 ProductData 对象中,此字段指定您的游戏客户的好友的中值数量。value: In the ProductData object, this field specifies the median number of friends for your game's customers. XboxwideData 对象中,此字段指定所有 Xbox Live 客户的好友的中值数量。In the XboxwideData object, this field specifies the median number of friends for all Xbox Live customers.
gamerScoreRangeDistributiongamerScoreRangeDistribution arrayarray 包含提供有关客户玩家分数分布情况的详细信息。Contains objects that provide details about the gamerscore distribution for customers. 每个对象都有两个字符串字段:Each object has two string fields:
  • scoreRange:以下字段提供其使用情况数据的玩家分数范围。scoreRange: The gamerscore range for which the following field provides usage data. 例如 10K-25KFor example, 10K-25K.
  • userCount:在 ProductData 对象中,此字段指定你的游戏客户在其玩过的所有游戏中其玩家分数属于指定范围的客户的数量。userCount: In the ProductData object, this field specifies the number of your game's customers that have a gamerscore in the specified range for all games they have played. XboxwideData 对象中,此字段指定所有 Xbox Live 客户在其玩过的所有游戏中其玩家分数属于指定范围的客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that have a gamerscore in the specified range for all games they have played.
titleGamerScoreRangeDistributiontitleGamerScoreRangeDistribution arrayarray 包含提供有关游戏玩家分数分布情况的详细信息的对象。Contains objects that provide details about the gamerscore distribution for your game. 每个对象都有两个字符串字段:Each object has two string fields:
  • scoreRange:以下字段提供其使用情况数据的玩家分数范围。scoreRange: The gamerscore range for which the following field provides usage data. 例如 100-200For example, 100-200.
  • userCount:在 ProductData 对象中,此字段指定你的游戏客户在你的游戏中的玩家分数属于指定范围的客户的数量。userCount: In the ProductData object, this field specifies the number of your game's customers that have a gamerscore in the specified range for your game. XboxwideData 对象中,此字段指定所有 Xbox Live 客户在你的游戏中其玩家分数属于指定范围的客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that have a gamerscore in the specified range for your game.
socialUsageCountssocialUsageCounts arrayarray 包含提供有关客户社交使用情况的详细信息的对象。Contains objects that provide details about the social usage for customers. 每个对象都有两个字符串字段:Each object has two string fields:
  • scName:社交使用情况类型。scName: The type of social usage. 例如 gameInvitestextMessagesFor example, gameInvites and textMessages.
  • userCount:在 ProductData 对象中,此字段指定在你的游戏中参与指定社交使用情况类型的客户的数量。userCount: In the ProductData object, this field specifies the number of your game's customers that have participated in the specified social usage type. XboxwideData 对象中,此字段指定所有参与指定社交使用情况类型的 Xbox Live 客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that have participated in the specified social usage type.
streamingUsageCountsstreamingUsageCounts arrayarray 包含提供有关客户流式处理使用情况的详细信息。Contains objects that provide details about the streaming usage for customers. 每个对象都有两个字符串字段:Each object has two string fields:
  • stName:流式处理平台的类型。stName: The type of streaming platform. 例如,youtubeUsagetwitchUsagemixerUsageFor example, youtubeUsage, twitchUsage, and mixerUsage.
  • userCount:在 ProductData 对象中,此字段指定你的游戏中使用指定流式处理平台的客户的数量。userCount: In the ProductData object, this field specifies the number of your game's customers that have used the specified streaming platform. XboxwideData 对象中,此字段指定使用指定流式处理平台的所有 Xbox Live 客户的百分比。In the XboxwideData object, this field specifies the percentage of all Xbox Live customers that have used the specified streaming platform.

响应示例Response example

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

{
  "Value": [
    {
      "ProductData": {
        "DeviceProperties": [
          {
            "applicationId": "9NBLGGGZ5QDR",
            "connectionTypeDistribution": [
              {
                "conType": "WIRED",
                "deviceCount": "43806"
              },
              {
                "conType": "WIRELESS",
                "deviceCount": "104035"
              }
            ],
            "deviceCount": "148063",
            "eliteControllerPresentDeviceCount": "10615",
            "externalDrivePresentDeviceCount": "46388"
          }
        ],
        "UserProperties": [
          {
            "applicationId": "9NBLGGGZ5QDR",
            "userCount": "142345",
            "dvrUsageCounts": [
              {
                "dvrName": "gameClipUploads",
                "userCount": "31264"
              },
              {
                "dvrName": "gameClipViews",
                "userCount": "52236"
              },
              {
                "dvrName": "screenshotUploads",
                "userCount": "27051"
              },
              {
                "dvrName": "screenshotViews",
                "userCount": "45640"
              }
            ],
            "followerCountPercentiles": [
              {
                "percentage": "50",
                "value": "11"
              }
            ],
            "friendCountPercentiles": [
              {
                "percentage": "50",
                "value": "11"
              }
            ],
            "gamerScoreRangeDistribution": [
              {
                "scoreRange": "10K-25K",
                "userCount": "30015"
              },
              {
                "scoreRange": "25K-50K",
                "userCount": "20495"
              },
              {
                "scoreRange": "3K-10K",
                "userCount": "32438"
              },
              {
                "scoreRange": "50K-100K",
                "userCount": "10608"
              },
              {
                "scoreRange": "<3K",
                "userCount": "45726"
              },
              {
                "scoreRange": ">100K",
                "userCount": "3063"
              }
            ],
            "titleGamerScoreRangeDistribution": [
              {
                "scoreRange": "400-600",
                "userCount": "133875"
              },
              {
                "scoreRange": "800-1000",
                "userCount": "45960"
              },
              {
                "scoreRange": "<100",
                "userCount": "269137"
              },
              {
                "scoreRange": "≥1K",
                "userCount": "11634"
              },
              {
                "scoreRange": "100-200",
                "userCount": "334471"
              },
              {
                "scoreRange": "600-800",
                "userCount": "123044"
              },
              {
                "scoreRange": "200-400",
                "userCount": "396725"
              }
            ],
            "socialUsageCounts": [
              {
                "scName": "gameInvites",
                "userCount": "82390"
              },
              {
                "scName": "textMessages",
                "userCount": "91880"
              },
              {
                "scName": "partySessionCount",
                "userCount": "68129"
              }
            ],
            "streamingUsageCounts": [
              {
                "stName": "youtubeUsage",
                "userCount": "74092"
              },
              {
                "stName": "twitchUsage",
                "userCount": "13401"
              }
              {
                "stName": "mixerUsage",
                "userCount": "22907"
              }
            ]
          }
        ]
      },
      "XboxwideData": {
        "DeviceProperties": [
          {
            "applicationId": "XBOXWIDE",
            "connectionTypeDistribution": [
              {
                "conType": "WIRED",
                "deviceCount": "0.213677732584786"
              },
              {
                "conType": "WIRELESS",
                "deviceCount": "0.786322267415214"
              }
            ],
            "deviceCount": "1",
            "eliteControllerPresentDeviceCount": "0.0476609278128012",
            "externalDrivePresentDeviceCount": "0.173747147416134"
          }
        ],
        "UserProperties": [
          {
            "applicationId": "XBOXWIDE",
            "userCount": "1",
            "dvrUsageCounts": [
              {
                "dvrName": "gameClipUploads",
                "userCount": "0.173210623993245"
              },
              {
                "dvrName": "gameClipViews",
                "userCount": "0.202104713778096"
              },
              {
                "dvrName": "screenshotUploads",
                "userCount": "0.136682414274251"
              },
              {
                "dvrName": "screenshotViews",
                "userCount": "0.158057895120314"
              }
            ],
            "followerCountPercentiles": [
              {
                "percentage": "50",
                "value": "5"
              }
            ],
            "friendCountPercentiles": [
              {
                "percentage": "50",
                "value": "5"
              }
            ],
            "gamerScoreRangeDistribution": [
              {
                "scoreRange": "10K-25K",
                "userCount": "0.134709282586519"
              },
              {
                "scoreRange": "25K-50K",
                "userCount": "0.0549468789343825"
              },
              {
                "scoreRange": "50K-100K",
                "userCount": "0.017301313342277"
              },
              {
                "scoreRange": "3K-10K",
                "userCount": "0.216512780268453"
              },
              {
                "scoreRange": "<3K",
                "userCount": "0.573515440094644"
              },
              {
                "scoreRange": ">100K",
                "userCount": "0.00301430477372488"
              }
            ],
            "titleGamerScoreRangeDistribution": [
              {
                "scoreRange": "100-200",
                "userCount": "0.178055695637076"
              },
              {
                "scoreRange": "200-400",
                "userCount": "0.173283639825241"
              },
              {
                "scoreRange": "400-600",
                "userCount": "0.0986865193958259"
              },
              {
                "scoreRange": "600-800",
                "userCount": "0.0506375775462092"
              },
              {
                "scoreRange": "800-1000",
                "userCount": "0.0232398822856435"
              },
              {
                "scoreRange": "<100",
                "userCount": "0.456443551582991"
              },
              {
                "scoreRange": "≥1K",
                "userCount": "0.0196531337270126"
              }
            ],
            "socialUsageCounts": [
              {
                "scName": "gameInvites",
                "userCount": "0.460375855738335"
              },
              {
                "scName": "textMessages",
                "userCount": "0.429256324070832"
              },
              {
                "scName": "partySessionCount",
                "userCount": "0.378446577751268"
              },
              {
                "scName": "gamehubViews",
                "userCount": "0.000197115778147329"
              }
            ],
            "streamingUsageCounts": [
              {
                "stName": "youtubeUsage",
                "userCount": "0.330320919178683"
              },
              {
                "stName": "twitchUsage",
                "userCount": "0.040666241835399"
              }
              {
                "stName": "mixerUsage",
                "userCount": "0.140193816053558"
              }
            ]
          }
        ]
      }
    }
  ],
  "@nextLink": null,
  "TotalCount": 4
}