获取加载项购置
使用 Microsoft Store 分析 API 中的此方法，可获取使用给定日期范围和其他可选筛选器时，应用的加载项聚合购置数据（JSON 格式）。 还可以在合作伙伴中心的加载项购置报告中获取此信息。
先决条件
若要使用此方法，首先需要执行以下操作：
- 完成 Microsoft Store 分析 API 的所有先决条件（如果尚未这样做）。
- 获取 Azure AD 访问令牌，以供在此方法的请求标头中使用。 获取访问令牌后，在它到期前，你有 60 分钟的使用时间。 该令牌到期后，可以获取新的令牌。
请求
请求语法
| 方法 | 请求 URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions |
请求头
| 标头 | 类型 | 说明 |
|---|---|---|
| 授权 | 字符串 | 必需。 Azure AD 访问令牌的格式为 Bearertoken<>。 |
请求参数
需要 applicationId 或 inAppProductId 参数。 若要检索注册到应用的所有加载项的购置数据，请指定 applicationId 参数。 若要检索单个加载项的购置数据，请指定 inAppProductId 参数。 如果同时指定这两个参数，则忽略 applicationId 参数。
| 参数 | 类型 | 描述 | 必需 |
|---|---|---|---|
| applicationId | string | 要检索加载项购置数据的应用的 Store ID。 | 是 |
| inAppProductId | string | 要检索购置数据的加载项的 Store ID。 | 是 |
| startDate | date | 要检索的加载项购置数据日期范围中的开始日期。 默认是当前日期。 | 否 |
| endDate | date | 要检索的加载项购置数据日期范围中的结束日期。 默认是当前日期。 | 否 |
| top | int | 要在请求中返回的数据行数。 如果未指定，最大值和默认值为 10000。 当查询中存在多行数据时，响应正文中包含的下一个链接可用于请求下一页数据。 | 否 |
| skip | int | 要在查询中跳过的行数。 使用此参数可以浏览较大的数据集。 例如，top=10000 和 skip=0，将检索前 10000 行数据；top=10000 和 skip=10000，将检索之后的 10000 行数据，依此类推。 | 否 |
| filter | string | 在响应中筛选行的一条或多条语句。 有关详细信息，请参阅下面的筛选器字段部分。 | 否 |
| aggregationLevel | string | 指定用于检索聚合数据的时间范围。 可以是以下字符串之一：day、week 或 month。 如果未指定，默认值为 day。 | 否 |
| orderby | string | 对每个加载项购置的结果数据值进行排序的语句。 语法为 orderby=field [order],field [order],...，其中 field 参数可以是以下字符串之一：
order 参数是可选的，可以是 asc 或 desc，用于指定每个字段的升序或降序排列。 默认值为 asc。 下面是一个 orderby 字符串的示例：orderby=date,market |
否 |
| groupby | string | 仅将数据聚合应用于指定字段的语句。 可以指定以下字段：
返回的数据行将包含 groupby 参数中指定的字段以及以下字段：
groupby 参数可以与 aggregationLevel 参数结合使用。 例如：&groupby=ageGroup,market&aggregationLevel=week |
否 |
筛选器字段
请求中的 filter 参数包含一条或多条用来在响应中筛选行的语句。 每条语句包含的字段和值使用 eq 或 ne 运算符进行关联，并且语句可以使用 and 或 or 进行组合。 下面是一些示例 filter 参数：
- filter=market eq 'US' and gender eq 'm'
- filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)
有关支持的字段列表，请参阅下表。 filter 参数中的字符串值必须使用单引号引起来。
| 字段 | 说明 |
|---|---|
| acquisitionType | 以下字符串之一：
|
| ageGroup | 以下字符串之一：
|
| storeClient | 以下字符串之一：
|
| gender | 以下字符串之一：
|
| market | 包含发生购置之市场的 ISO 3166 国家/地区代码的字符串。 |
| osVersion | 以下字符串之一：
|
| deviceType | 以下字符串之一：
|
| orderName | 一个字符串，指定用于获取加载项的促销代码的订单名称（这仅适用于用户通过兑换促销代码获取加载项时）。 |
请求示例
以下示例演示用于获取加载项购置数据的多个请求。 将 inAppProductId 和 applicationId 值替换为你的加载项或应用的相应 Store ID。
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&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/inappacquisitions?applicationId=9NBLGGGZ5QDR&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/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=7/3/2015&top=100&skip=0&filter=market ne 'US' and gender ne 'Unknown' and gender ne 'm' and market ne 'NO' and ageGroup ne '>55' HTTP/1.1
Authorization: Bearer <your access token>
响应
响应正文
| 值 | 类型 | 说明 |
|---|---|---|
| Value | array | 包含聚合加载项购置数据的对象数组。 有关每个对象中的数据的详细信息，请参阅以下加载项购置值部分。 |
| @nextLink | string | 如果存在其他数据页，则此字符串包含一个你可用来请求下一页数据的 URI。 例如，当请求的 top 参数设置为 10000，但查询的加载项购置数据超过 10000 行时，就会返回此值。 |
| TotalCount | int | 查询的数据结果中的行总数。 |
加载项购置值
Value 数组中的元素包含以下值。
| Value | 类型 | 说明 |
|---|---|---|
| date | string | 购置数据的日期范围内的第一个日期。 如果请求指定了某一天，此值就是该日期。 如果请求指定了一周、月或其他日期范围，此值是该日期范围内的第一个日期。 |
| inAppProductId | string | 要为其检索购置数据的加载项的 Store ID。 |
| inAppProductName | string | 加载项的显示名称。 当 aggregationLevel 参数设置为 day 时，该值仅显示在响应数据中，除非在 groupby 参数中指定 inAppProductName 字段。 |
| applicationId | string | 要检索加载项购置数据的应用的 Store ID。 |
| applicationName | string | 应用的显示名称。 |
| deviceType | string | 完成购置的设备类型。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| orderName | string | 订单的名称。 |
| storeClient | string | 发生购置的 Microsoft Store 的版本。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| osVersion | string | 发生购置的 OS 版本。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| market | string | 发生购置的市场的 ISO 3166 国家/地区代码。 |
| gender | string | 进行购置的用户的性别。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| ageGroup | string | 进行购置的用户的年龄组。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| acquisitionType | string | 购置类型（免费、付费等）。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| acquisitionQuantity | integer | 发生的购置次数。 |
请求和响应示例
如下代码片段展示了这些请求的一个示例请求和 JSON 响应正文。
示例请求
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
示例响应
{
"Value": [
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Deluxe Collector's Edition",
"addonProductId": "9NBLGGAAGZDQ",
"date": "2022-07-29",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 18.12,
"purchasePriceLocalAmount": 18.12,
"purchaseTaxUSDAmount": 1.13,
"purchaseTaxLocalAmount": 1.13
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Episode 4",
"addonProductId": "9NAAAAAAAAAQ",
"date": "2017-01-07",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 4.147206,
"purchasePriceLocalAmount": 3.99,
"purchaseTaxUSDAmount": 0.686004,
"purchaseTaxLocalAmount": 0.66
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Deluxe Collector's Edition",
"addonProductId": "9NALGGGZ5QDQ",
"date": "2018-04-01",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.99,
"purchasePriceLocalAmount": 1.99,
"purchaseTaxUSDAmount": 0.0,
"purchaseTaxLocalAmount": 0.0
},
{
"applicationId": "9NBLGGGZ5QDR",
"inAppProductName": "Strategy Guide Episode 4",
"addonProductId": "9NBLGGGZ5QDQ",
"date": "2021-11-25",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.31902922876179,
"purchasePriceLocalAmount": 150.0,
"purchaseTaxUSDAmount": 0.114315866492689,
"purchaseTaxLocalAmount": 13.0
},
],
"TotalCount": 4,
"DataFreshnessTimestamp": "2022-07-29T05:54:00"
}
相关主题