通过

获取游戏和应用的附加设备购置数据

在 Microsoft Store 分析 API 中使用此方法来获取通过 Xbox 开发人员门户 (XDP) 引入并在 XDP 分析合作伙伴中心仪表板中提供的 UWP 应用和 Xbox One 游戏的聚合加载项购置数据（JSON 格式）。

先决条件

若要使用此方法，首先需要执行以下操作：

  • 完成 Microsoft Store 分析 API 的所有先决条件（如果尚未这样做）。
  • 获取 Azure AD 访问令牌，以供在此方法的请求标头中使用。 获取访问令牌后，在它到期前，你有 60 分钟的使用时间。 该令牌到期后，可以获取新的令牌。

注意

此 API 不提供 2016 年 10 月 1 日之前的每日聚合数据。

请求

请求语法

方法 请求 URI
获取 https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

请求标头

标题 类型 说明
授权 字符串 必填。 Azure AD 访问令牌的格式为 Bearer<token>。

请求参数

applicationId 或 addonProductId 参数是必需参数。 若要检索注册到应用的所有加载项的购置数据，请指定 applicationId 参数。 若要检索单个加载项的购置数据，请指定 addonProductId 参数。 如果同时指定这两个参数，则忽略 applicationId 参数。

参数 类型 说明 必选
应用ID 字符串 要检索其购置数据的 Xbox One 游戏的 productId。 若要获取游戏的 productId，请在 XDP 分析程序中导航到你的游戏并从 URL 中检索 productId。 或者，如果你从合作伙伴中心分析报告下载购置数据，productId就会包含在 .tsv 文件中。 是
附加产品ID 字符串 要检索购置数据的加载项的 productId。 是
开始日期 日期 要检索的加载项购置数据日期范围中的开始日期。 默认是当前日期。 否
结束日期 日期 要检索的加载项购置数据日期范围中的结束日期。 默认是当前日期。 否
过滤器 字符串 用于筛选响应中的行的一个或多个语句。 每条语句包含的响应正文中的字段名称和值使用 eq 或 ne 运算符进行关联，并且语句可以使用 and 或 or 进行组合。 filter 参数中的字符串值必须使用单引号引起来。 例如，filter=market eq 'US' and gender eq 'm'。
可以指定响应正文中的以下字段：
  • 获取类型
  • 年龄
  • storeClient
  • 性别
  • 市场
  • 操作系统版本
  • 设备类型
  • sandboxId
 否
聚合级别 字符串 指定用于检索聚合数据的时间范围。 可以是以下字符串之一：day、week 或 month。 如果未指定，默认值为 day。 否
排序 字符串 对每个加载项购置的结果数据值进行排序的语句。 语法为 orderby=field [order],field [order],...，其中 field 参数可以是以下字符串之一：
  • 日期
  • 获取类型
  • 年龄
  • storeClient
  • 性别
  • 市场
  • 操作系统版本
  • 设备类型
  • 订单名称
order 参数是可选的，可以是 asc 或 desc，用于指定每个字段的升序或降序排列。 默认值为 asc。
下面是一个 orderby 字符串的示例：orderby=date,market		 否
按组分类 字符串 仅将数据聚合应用于指定字段的语句。 可以指定以下字段：
  • 日期
  • 应用程序名称
  • 附加产品名称
  • 获取类型
  • 年龄
  • storeClient
  • 性别
  • 市场
  • 操作系统版本
  • 设备类型
  • 支付工具类型
  • sandboxId
  • xboxTitleIdHex
返回的数据行将包含 groupby 参数中指定的字段以及以下字段：
  • 日期
  • 应用程序 ID
  • addonProductId
  • 购买数量
groupby 参数可以与 aggregationLevel 参数结合使用。 例如：&groupby=age,market&aggregationLevel=week		 否

请求示例

以下示例演示用于获取加载项购置数据的多个请求。 将 addonProductId 和 applicationId 值替换为你的加载项或应用的相应 Store ID。

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&top=10&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&top=10&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

响应

响应正文

值 类型 说明
值 数组 包含聚合加载项购置数据的对象数组。 有关每个对象中的数据的详细信息，请参阅以下加载项购置值部分。
总计数 整数 (int) 查询的数据结果中的行总数。

加载项购置值

Value 数组中的元素包含以下值。

值 类型 说明
日期 字符串 购置数据的日期范围内的第一个日期。 如果请求指定了某一天，此值就是该日期。 如果请求指定了一周、月或其他日期范围，此值是该日期范围内的第一个日期。
附加产品ID 字符串 要检索购置数据的加载项的 productId。
附加产品名称 字符串 加载项的显示名称。 当 aggregationLevel 参数设置为 day 时，该值仅显示在响应数据中，除非在 groupby 参数中指定 addonProductName 字段。
应用ID 字符串 要检索加载项购置数据的应用的 productId。
应用程序名称 字符串 游戏的显示名称。
设备类型 字符串 以下字符串之一，指定完成购置的设备类型：
  • “PC”
  • “电话”
  • 游戏机-Xbox One
  • “Console-Xbox 系列 X”
  • “IoT”
  • 服务器
  • “平板电脑”
  • 全息
  • “未知”
storeClient 字符串 以下字符串之一，指示发生购置的 Microsoft Store 版本：
  • "Windows Phone Store（客户端）"
  • "Microsoft Store (client)"（或 "Windows Store (client)"，前提是查询 2018 年 3 月 23 日之前的数据）
  • "Microsoft Store (web)"（或 "Windows Store (web)"，前提是查询 2018 年 3 月 23 日之前的数据）
  • "组织批量购买"
  • 其他
osVersion 字符串 发生购置的 OS 版本。 对于此方法，此值始终是 "Windows 10" 或 "Windows 11"。
市场 字符串 发生购置的市场的 ISO 3166 国家/地区代码。
性别 字符串 以下字符串之一，指定进行购置的用户的性别：
  • “m”
  • “f”
  • “未知”
年龄 字符串 以下字符串之一，指示进行购置的用户的年龄组：
  • “小于 13”
  • "13-17"
  • "18-24"
  • 25到34岁
  • "35-44"
  • 44-55
  • “大于 55”
  • “未知”
获取类型 字符串 以下字符串之一，指示购置类型：
  • “免费”
  • "Trial"
  • 已付款
  • "Promotional code"
  • “Iap”
  • “订阅 Iap”
  • 私人会见
  • “预购”
  • "Xbox Game Pass"（或者为 "Game Pass"，前提是在 2018 年 3 月 23 之前查询数据）
  • 磁盘
  • 预付费代码
  • “收费预购”
  • “已取消预购”
  • “预购失败”
获取数量 整数 发生的收购次数。
应用内产品ID 字符串 在其中使用此加载项的产品的产品 ID。
应用内产品名称 字符串 在其中使用此加载项的产品的产品名称。
支付工具类型 字符串 用于购置的付款方式类型。
sandboxId 字符串 为游戏创建的沙盒 ID。 它可以是值 RETAIL，也可以是私有沙盒 ID。
xboxTitleId 字符串 XDP 产品的 Xbox 标题 ID（如果适用）。
本地货币代码 字符串 基于合作伙伴中心帐户所在国家/地区的当地货币代码。
Xbox产品编号 字符串 XDP 产品的 Xbox 产品 ID（如果适用）。
可用性ID 字符串 XDP 产品的可用性 ID（如果适用）。
skuId 的 字符串 XDP 产品的 SKU ID（如果适用）。
skuDisplayName 字符串 XDP 产品的 SKU 显示名称（如果适用）。
xboxParentProductId 字符串 XDP 产品的 Xbox 父产品 ID（如果适用）。
父产品名称 字符串 XDP 产品的父产品名称（如果适用）。
产品类型名称 字符串 XDP 产品的产品类型名称（如果适用）。
购置税类型 字符串 XDP 产品的购买税款类型（如果适用）。
购买价格美元金额 数字 客户为加载项支付的金额（已转换为美元）。
购买价格本地金额 数字 客户为加载项支付的金额（以所在地区的货币为单位）。
购买税款美元金额 数字 加载项税额（已转换为美元）。
购置税地方金额 数字 XDP 产品的购买税款本地金额（如果适用）。

响应示例

以下示例举例说明此请求的 JSON 响应正文。

{ 
  "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 
}