获取游戏和应用的购置数据Get acquisitions data for your games and apps

在 Microsoft Store analytics API 中使用此方法,以 JSON 格式获取针对 UWP 应用的聚合获取数据,并使用 xbox 开发人员门户 (XDP) ,并在 XDP Analytics 仪表板中可用。Use this method in the Microsoft Store analytics API to get aggregate acquisition data in JSON format for UWP apps and Xbox One games that were ingested through the Xbox Developer Portal (XDP) and available in the XDP Analytics dashboard.

备注

此 API 在10月 2016 1 日之前未提供每日聚合数据。This API does not provide daily aggregate data before Oct 1st 2016.

必备条件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/acquisitions

请求头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 One 游戏的产品 ID。The product ID of the Xbox One game for which you are retrieving acquisition data. 若要获取游戏的产品 ID,请导航到 XDP Analytics 计划中的游戏,并从 URL 中检索产品 ID。To get the product ID of your game, navigate to your game in the XDP Analytics Program and retrieve the product ID from the URL. 或者,如果您从 "合作伙伴中心分析" 报表下载您的购买数据,则该产品 ID 将包含在 tsv 文件中。Alternatively, if you download your acquisitions data from the Partner Center analytics report, the product ID is included in the .tsv file. Yes
startDatestartDate 日期date 要检索的购置数据日期范围中的开始日期。The start date in the date range of acquisition data to retrieve. 默认值为当前日期。The default is the current date. No
endDateendDate 日期date 要检索的购置数据日期范围中的结束日期。The end date in the date range of acquisition data to retrieve. 默认值为当前日期。The default is the current date. 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. 例如,filter=market eq 'US' and gender eq 'm'For example, filter=market eq 'US' and gender eq 'm'.
可以指定响应正文中的以下字段:You can specify the following fields from the response body:
  • acquisitionTypeacquisitionType
  • age
  • storeClientstoreClient
  • 性别gender
  • 营销market
  • osVersionosVersion
  • deviceTypedeviceType
  • sandboxIdsandboxId
No
aggregationLevelaggregationLevel 字符串string 指定用于检索聚合数据的时间范围。Specifies the time range for which to retrieve aggregate data. 可以是以下字符串之一:dayweekmonthCan be one of the following strings: day, week, or month. 如果未指定,默认值为 dayIf unspecified, the default is day. No
orderbyorderby 字符串string 对每个购置的结果数据值进行排序的语句。A statement that orders the result data values for each acquisition. 语法为 orderby = field [order],field [order],...**字段 参数可以为以下字符串之一:The syntax is orderby=field [order],field [order],... The field parameter can be one of the following strings:
  • datedate
  • acquisitionTypeacquisitionType
  • age
  • storeClientstoreClient
  • 性别gender
  • 营销market
  • osVersionosVersion
  • deviceTypedeviceType
  • paymentInstrumentTypepaymentInstrumentType
  • sandboxIdsandboxId
  • xboxTitleIdHexxboxTitleIdHex
order 参数是可选的,可以是 ascdesc,用于指定每个字段的升序或降序排列。The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. 默认值为 ascThe default is asc. 下面是一个 orderby 字符串的示例:orderby=date,marketHere is an example orderby string: orderby=date,market
No
groupbygroupby 字符串string 仅将数据聚合应用于指定字段的语句。A statement that applies data aggregation only to the specified fields. 可以指定的字段如下所示:You can specify the following fields:
  • datedate
  • applicationNameapplicationName
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • storeClientstoreClient
  • 性别gender
  • 营销market
  • osVersionosVersion
  • deviceTypedeviceType
  • paymentInstrumentTypepaymentInstrumentType
  • sandboxIdsandboxId
  • xboxTitleIdHexxboxTitleIdHex
返回的数据行会包含 groupby 参数中指定的字段,以及以下字段:The returned data rows will contain the fields specified in the groupby parameter as well as the following:
  • datedate
  • applicationIdapplicationId
  • acquisitionQuantityacquisitionQuantity
groupby 参数可以与 aggregationLevel 参数结合使用。The groupby parameter can be used with the aggregationLevel parameter. 例如: &groupby = ageGroup,marketplace&aggregationLevel = 周For example: &groupby=ageGroup,market&aggregationLevel=week
No

请求示例Request example

以下示例演示用于获取 Xbox One 游戏购置数据的多个请求。The following example demonstrates several requests for getting Xbox One game acquisition data. 用游戏的产品 ID 替换 applicationId 值。Replace the applicationId value with the product ID for your game.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&top=10&skip=0 HTTP/1.1 
Authorization: Bearer <your access token> 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token> 

响应Response

响应正文Response body

Value 类型Type 描述Description
Value 数组array 包含游戏聚合购置数据的对象数组。An array of objects that contain aggregate acquisition data for the game. 有关每个对象中的数据的详细信息,请参阅以下购置值部分。For more information about the data in each object, see the acquisition values section below.
TotalCountTotalCount integerinteger 查询的数据结果中的行总数。The total number of rows in the data result for the query.

购置值Acquisition values

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

Value 类型Type 描述Description
datedate 字符串string 购置数据的日期范围内的第一个日期。The first date in the date range for the acquisition 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.
applicationIdapplicationId 字符串string 要检索其购置数据的 Xbox One 游戏的产品 ID。The product ID of the Xbox One game for which you are retrieving acquisition data.
applicationNameapplicationName 字符串string 游戏的显示名称。The display name of the game.
acquisitionTypeacquisitionType 字符串string 下列字符串之一,用于指示购置类型:One of the following strings that indicates the type of acquisition:
  • 免费Free
  • 试用Trial
  • 已付Paid
  • 促销代码Promotional code
  • IapIap
  • 订阅 IapSubscription Iap
  • 私人受众Private Audience
  • 前序Pre Order
  • Xbox Game Pass(或者,如果在 2018 年 3 月 23 之前查询数据,则是 Game PassXbox Game Pass (or Game Pass if querying for data before March 23, 2018)
  • 磁盘Disk
  • 预付码Prepaid Code
  • 收费的前序Charged Pre Order
  • 已取消的前置顺序Cancelled Pre Order
  • 失败的前置顺序Failed Pre Order
ageage 字符串string 用于指示进行购置的用户的年龄段的以下字符串之一:One of the following strings that indicates the age group of the user who made the acquisition:
  • 小于13Less than 13
  • 13-1713-17
  • 18-2418-24
  • 25-3425-34
  • 35-4435-44
  • 44-5544-55
  • 大于55Greater than 55
  • UnknownUnknown
deviceTypedeviceType 字符串string 用于指定完成购置的设备类型的以下字符串之一:One of the following strings that specifies the type of device that completed the acquisition:
  • PCPC
  • 电话Phone
  • 控制台-Xbox OneConsole-Xbox One
  • 控制台-Xbox 系列 XConsole-Xbox Series X
  • IoTIoT
  • 服务器Server
  • 平板电脑Tablet
  • HolographicHolographic
  • UnknownUnknown
gendergender 字符串string 用于指定进行购置的用户的性别的以下字符串之一:One of the following strings that specifies the gender of the user who made the acquisition:
  • mm
  • ff
  • UnknownUnknown
marketmarket stringstring 发生购置行为的市场的 ISO 3166 国家/地区代码。The ISO 3166 country code of the market where the acquisition occurred.
osVersionosVersion 字符串string 发生购置行为的操作系统版本。The OS version on which the acquisition occurred. 对于此方法,此值始终是 Windows 10For this method, this value is always Windows 10.
paymentInstrumentTypepaymentInstrumentType 字符串string 用于指示用于购置的付款说明的以下字符串之一:One of the following strings that indicates the payment instruction used for the acquisition:
  • 信用卡Credit Card
  • 直接借记卡Direct Debit Card
  • 推断的购买Inferred Purchase
  • MS 余额MS Balance
  • 移动运营商Mobile Operator
  • 在线银行转帐Online Bank Transfer
  • PayPalPayPal
  • 分割交易Split Transaction
  • 预付码兑换Token Redemption
  • 已支付金额为零Zero Amount Paid
  • eWalleteWallet
  • UnknownUnknown
sandboxIdsandboxId 字符串string 为游戏创建的沙盒的 ID。The sandbox ID created for the game. 此值可以是 " 零售 " 或 "私有沙箱 ID"。This can be the value RETAIL or a private sandbox ID.
storeClientstoreClient 字符串string 用于指示发生购置的 Microsoft Store 版本的以下字符串之一:One of the following strings that indicates the version of the Store where the acquisition occurred:
  • Windows Phone Store (client)Windows Phone Store (client)
  • Microsoft Store (client)(或 Windows Store (client),如果查询 2018 年 3 月 23 日之前的数据)Microsoft Store (client) (or Windows Store (client) if querying for data before March 23, 2018)
  • Microsoft Store (web)(或 Windows Store (web),如果查询 2018 年 3 月 23 日之前的数据)Microsoft Store (web) (or Windows Store (web) if querying for data before March 23, 2018)
  • Volume purchase by organizationsVolume purchase by organizations
  • 其他Other
xboxTitleIdxboxTitleId 字符串string Xbox 开发人员门户 (XDP) 为支持 Xbox Live 的游戏指定的 Xbox Live 标题 ID(以十六进制值表示)。The Xbox Live title ID (represented in hexadecimal value) assigned by the Xbox Developer Portal (XDP) for Xbox Live-enabled games.
acquisitionQuantityacquisitionQuantity numbernumber 在指定的聚合级别期间发生的购置数。The number of acquisitions that occurred during the specified aggregation level.
purchasePriceUSDAmountpurchasePriceUSDAmount numbernumber 客户为购置所付金额,已使用每月汇率转换为美元。The amount paid by the customer for the acquisition, converted to USD, using the monthly exchange rate.
purchaseTaxUSDAmountpurchaseTaxUSDAmount numbernumber 购置税额,已转换为美元。The tax amount applied to the acquisition, converted to USD.
localCurrencyCodelocalCurrencyCode 字符串string 基于合作伙伴中心帐户的国家/地区的本地货币代码。Local Currency code based on the country of the Partner Center account.
xboxProductIdxboxProductId 字符串string XDP 中产品的 Xbox 产品 ID (如果适用)。Xbox Product ID of the product from XDP, if applicable.
availabilityIdavailabilityId 字符串string XDP 中产品的可用性 ID (如果适用)。Availability ID of the product from XDP, if applicable.
skuIdskuId 字符串string XDP 中产品的 SKU ID (如果适用)。SKU ID of the product from XDP, if applicable.
skuDisplayNameskuDisplayName 字符串string XDP 中产品的 SKU 显示名称(如果适用)。SKU display name of the product from XDP, if applicable.
xboxParentProductIdxboxParentProductId 字符串string XDP 中产品的 Xbox 父产品 ID (如果适用)。Xbox Parent Product ID of the product from XDP, if applicable.
parentProductNameparentProductName 字符串string XDP 中产品的父产品名称(如果适用)。Parent Product Name of the product from XDP, if applicable.
productTypeNameproductTypeName 字符串string XDP 中产品的产品类型名称(如果适用)。Product Type Name of the product from XDP, if applicable.
purchaseTaxTypepurchaseTaxType 字符串string 从 XDP 购买产品的税务类型(如果适用)。Purchase Tax Type of the product from XDP, if applicable.
purchasePriceLocalAmountpurchasePriceLocalAmount numbernumber 从 XDP 购买产品的本地价格(如果适用)。Purchase Price Local Amount of the product from XDP, if applicable.
purchaseTaxLocalAmountpurchaseTaxLocalAmount numbernumber 如果适用,请从 XDP 购买产品的增值税当地金额。Purchase Tax Local Amount of the product from XDP, if applicable.

响应示例Response example

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

{ 
    "Value": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 10", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}