获取游戏和应用的附加设备购置数据Get add-on acquisitions data for your games and apps

在 Microsoft Store analytics API 中使用此方法,以 JSON 格式获取已通过 Xbox 开发人员门户(XDP)引入并可在 XDP Analytics 合作伙伴中心仪表板中使用的的聚合外接程序获取数据。Use this method in the Microsoft Store analytics API to get aggregate add-on 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 Partner Center dashboard.

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

备注

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

请求Request

请求语法Request syntax

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

请求头Request header

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

请求参数Request parameters

ApplicationIdaddonProductId参数是必需的。The applicationId or addonProductId parameter is required. 若要检索注册到该应用的所有加载项的购置数据,请指定 applicationId 参数。To retrieve acquisition data for all add-ons registered to the app, specify the applicationId parameter. 若要检索单个外接程序的获取数据,请指定addonProductId参数。To retrieve acquisition data for a single add-on, specify the addonProductId parameter. 如果同时指定这两个参数,会忽略 inAppProductId 参数。If you specify both, the applicationId parameter is ignored.

参数Parameter 类型Type 说明Description 必需Required
applicationIdapplicationId 字符串string 要为其检索获取数据的 Xbox one 游戏的产品 idThe productId of the Xbox One game for which you are retrieving acquisition data. 若要获取你的游戏的productId ,请导航到 XDP Analytics 计划中的游戏,并从 URL 中检索productIdTo get the productId of your game, navigate to your game in the XDP Analytics Program and retrieve the productId from the URL. 或者,如果您从 "合作伙伴中心分析" 报表下载您的购买数据,则productId将包含在 tsv 文件中。Alternatively, if you download your acquisitions data from the Partner Center analytics report, the productId is included in the .tsv file. Yes
addonProductIdaddonProductId stringstring 要检索其获取数据的外接程序的productIdThe productId of the add-on for which you want to retrieve acquisition data. Yes
startDatestartDate datedate 要检索的加载项购置数据日期范围中的开始日期。The start date in the date range of add-on acquisition data to retrieve. 默认值为当前日期。The default is the current date. No
endDateendDate 日期date 要检索的加载项购置数据日期范围中的结束日期。The end date in the date range of add-on acquisition 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 stringstring 在响应中筛选行的一条或多条语句。One or more statements that filter the rows in the response. 每条语句包含的响应正文中的字段名称和值使用 eq 或 ne 运算符进行关联,并且语句可以使用 and 或 or 进行组合。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
  • marketmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • sandboxIdsandboxId
No
aggregationLevelaggregationLevel stringstring 指定用于检索聚合数据的时间范围。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 stringstring 对每个加载项购置的结果数据值进行排序的语句。A statement that orders the result data values for each add-on 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
  • marketmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName
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 stringstring 仅将数据聚合应用于指定字段的语句。A statement that applies data aggregation only to the specified fields. 可以指定的字段如下所示:You can specify the following fields:
  • datedate
  • applicationNameapplicationName
  • addonProductNameaddonProductName
  • acquisitionTypeacquisitionType
  • age
  • storeClientstoreClient
  • 性别gender
  • marketmarket
  • 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
  • addonProductIdaddonProductId
  • acquisitionQuantityacquisitionQuantity
groupby 参数可以与 aggregationLevel 参数结合使用。The groupby parameter can be used with the aggregationLevel parameter. 例如: &groupby = age,marketplace&aggregationLevel = weekFor example: &groupby=age,market&aggregationLevel=week
No

请求示例Request example

以下示例演示了用于获取加载项购置数据的多个请求。The following examples demonstrates several requests for getting add-on acquisition data. addonProductIdapplicationId值替换为外接程序或应用程序的适当存储 ID。Replace the addonProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0 HTTP/1.1 

Authorization: Bearer <your access token> 

 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

响应Response

响应正文Response body

Value 类型Type 说明Description
ValueValue arrayarray 包含聚合加载项购置数据的对象数组。An array of objects that contain aggregate add-on acquisition data. 有关每个对象中的数据的详细信息,请参阅下面的加载项购置值部分。For more information about the data in each object, see the add-on acquisition values section below.
@nextLink stringstring 如果存在其他数据页,则此字符串包含一个你可用来请求下一页数据的 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 add-on acquisition data for the query.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

加载项购置值Add-on acquisition values

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

Value 类型Type 说明Description
datedate stringstring 购置数据的日期范围内的第一个日期。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.
addonProductIdaddonProductId stringstring 要为其检索获取数据的外接程序的productIdThe productId of the add-on for which you are retrieving acquisition data.
addonProductNameaddonProductName stringstring 加载项的显示名称。The display name of the add-on. 如果aggregationLevel参数设置为day,则此值仅出现在响应数据中,除非在groupby参数中指定addonProductName字段。This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the addonProductName field in the groupby parameter.
applicationIdapplicationId 字符串string 要检索其外接程序获取数据的应用程序的productIdThe productId of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring 游戏的显示名称。The display name of the game.
deviceTypedeviceType stringstring 用于指定完成购置的设备类型的以下字符串之一:One of the following strings that specifies the type of device that completed the acquisition:
  • 计算机"PC"
  • 移动"Phone"
  • "控制台-Xbox One""Console-Xbox One"
  • "控制台-Xbox 系列 X""Console-Xbox Series X"
  • IoT"IoT"
  • 服务"Server"
  • Tablet"Tablet"
  • 全息"Holographic"
  • 未知"Unknown"
storeClientstoreClient stringstring 用于指示发生购置的 Microsoft Store 版本的以下字符串之一:One of the following strings that indicates the version of the Store where the acquisition occurred:
  • "Windows Phone 存储(客户端)""Windows Phone Store (client)"
  • "Microsoft Store (客户端)" (或 "Windows 应用商店(客户端)")(如果在2018年3月23日之前查询数据)"Microsoft Store (client)" (or "Windows Store (client)" if querying for data before March 23, 2018)
  • "Microsoft Store (web)" (如果在2018年3月23日之前查询数据,则为 "Windows 应用商店(web)")"Microsoft Store (web)" (or "Windows Store (web)" if querying for data before March 23, 2018)
  • "按组织批量购买""Volume purchase by organizations"
  • 以外"Other"
osVersionosVersion stringstring 发生购置行为的操作系统版本。The OS version on which the acquisition occurred. 对于此方法,此值始终为 "Windows 10"。For this method, this value is always "Windows 10".
marketmarket stringstring 发生购置行为的市场的 ISO 3166 国家/地区代码。The ISO 3166 country code of the market where the acquisition occurred.
gendergender stringstring 用于指定进行购置的用户的性别的以下字符串之一:One of the following strings that specifies the gender of the user who made the acquisition:
  • “m”"m"
  • “f”"f"
  • 未知"Unknown"
ageage stringstring 用于指示进行购置的用户的年龄段的以下字符串之一:One of the following strings that indicates the age group of the user who made the acquisition:
  • "小于 13""less than 13"
  • "13-17""13-17"
  • "18-24""18-24"
  • "25-34""25-34"
  • "35-44""35-44"
  • "44-55""44-55"
  • "大于 55""greater than 55"
  • 未知"Unknown"
acquisitionTypeacquisitionType stringstring 下列字符串之一,用于指示购置类型:One of the following strings that indicates the type of acquisition:
  • "Free"
  • 到期"Trial"
  • 付费"Paid"
  • "促销代码""Promotional code"
  • "Iap""Iap"
  • "订阅 Iap""Subscription Iap"
  • "专用群体""Private Audience"
  • "前置顺序""Pre Order"
  • "Xbox 游戏 Pass" (如果在2018年3月23日之前查询数据,则为 "游戏传递")"Xbox 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"
acquisitionQuantityacquisitionQuantity integerinteger 发生的购置数。The number of acquisitions that occurred.
inAppProductIdinAppProductId stringstring 使用此外接程序的产品的产品 ID。Product ID of the product where this add-on is used.
inAppProductNameinAppProductName stringstring 使用此外接程序的产品的产品名称。Product Name of the product where this add-on is used.
paymentInstrumentTypepaymentInstrumentType stringstring 用于获取的付款方式类型。Payment instrument type used for the acquisition.
sandboxIdsandboxId stringstring 为游戏创建的沙箱 ID。The Sandbox ID created for the game. 此值可以是 "零售" 或 "私有沙箱 ID"。This can be the value RETAIL or a private sandbox ID.
xboxTitleIdxboxTitleId stringstring XDP 中产品的 Xbox 标题 ID (如果适用)。Xbox Title ID of the product from XDP, if applicable.
localCurrencyCodelocalCurrencyCode stringstring 基于合作伙伴中心帐户的国家/地区的本地货币代码。Local Currency code based on the country of the Partner Center account.
xboxProductIdxboxProductId stringstring XDP 中产品的 Xbox 产品 ID (如果适用)。Xbox Product ID of the product from XDP, if applicable.
availabilityIdavailabilityId stringstring XDP 中产品的可用性 ID (如果适用)。Availability ID of the product from XDP, if applicable.
skuIdskuId stringstring XDP 中产品的 SKU ID (如果适用)。SKU ID of the product from XDP, if applicable.
skuDisplayNameskuDisplayName stringstring XDP 中产品的 SKU 显示名称(如果适用)。SKU Display Name of the product from XDP, if applicable.
xboxParentProductIdxboxParentProductId stringstring XDP 中产品的 Xbox 父产品 ID (如果适用)。Xbox Parent Product ID of the product from XDP, if applicable.
parentProductNameparentProductName stringstring XDP 中产品的父产品名称(如果适用)。Parent Product Name of the product from XDP, if applicable.
productTypeNameproductTypeName stringstring XDP 中产品的产品类型名称(如果适用)。Product Type Name of the product from XDP, if applicable.
purchaseTaxTypepurchaseTaxType stringstring 从 XDP 购买产品的税务类型(如果适用)。Purchase Tax Type of the product from XDP, if applicable.
purchasePriceUSDAmountpurchasePriceUSDAmount 数字number 客户为外接程序支付的金额,转换为美元。The amount paid by the customer for the add-on, converted to USD.
purchasePriceLocalAmountpurchasePriceLocalAmount 数字number 应用于外接程序的税额。The tax amount applied to the add-on.
purchaseTaxUSDAmountpurchaseTaxUSDAmount 数字number 应用于外接程序的税费,转换为美元。The tax amount applied to the add-on, converted to USD.
purchaseTaxLocalAmountpurchaseTaxLocalAmount 数字number 如果适用,请从 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": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

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