获取应用评分
使用 Microsoft Store 分析 API 中的此方法，可以以 JSON 格式获取给定日期范围内和使用其他可选筛选器时的聚合评分数据。 还可以在合作伙伴中心的评价报告中获取此信息。
先决条件
若要使用此方法，首先需要执行以下操作：
- 完成 Microsoft Store 分析 API 的所有先决条件（如果尚未这样做）。
- 获取 Azure AD 访问令牌，以供在此方法的请求标头中使用。 获取访问令牌后，在它到期前，你有 60 分钟的使用时间。 该令牌到期后，可以获取新的令牌。
请求
请求语法
| 方法 | 请求 URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings |
请求头
| 标头 | 类型 | 说明 |
|---|---|---|
| 授权 | 字符串 | 必需。 Azure AD 访问令牌的格式为 Bearertoken<>。 |
请求参数
| 参数 | 类型 | 描述 | 必需 |
|---|---|---|---|
| applicationId | 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=osVersion,market&aggregationLevel=week |
否 |
筛选器字段
请求中的 filter 参数包含一条或多条用来在响应中筛选行的语句。 每条语句包含的字段和值使用 eq 或 ne 运算符进行关联，并且语句可以使用 and 或 or 进行组合。
下面是一个示例筛选器字符串：filter=market eq 'US' and deviceType eq 'phone' and isRevised eq true
有关支持的字段列表，请参阅下表。 filter 参数中的字符串值必须使用单引号引起来。
| 字段 | 说明 |
|---|---|
| market | 一个包含应用评分所在地市场的 ISO 3166 国家/地区代码的字符串。 |
| osVersion | 以下字符串之一：
|
| deviceType | 以下字符串之一：
|
| isRevised | 指定 true 以筛选已修订的评分；否则指定 false。 |
请求示例
如下示例展示了一些用来获取评分数据的请求。 将 applicationId 值替换为你的应用的 Store ID。
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?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/ratings?applicationId=9NBLGGGZ5QDR&startDate=8/1/2015&endDate=8/31/2015&skip=0&filter=market eq 'US' and deviceType eq 'phone' HTTP/1.1
Authorization: Bearer <your access token>
响应
响应正文
| 值 | 类型 | 说明 |
|---|---|---|
| Value | array | 一组包含聚合评分数据的对象。 有关每个对象中的数据的更多信息，请参阅下面的评分值部分。 |
| @nextLink | string | 如果存在其他数据页，则此字符串包含一个你可用来请求下一页数据的 URI。 例如，当请求的 top 参数设置为 10000，但查询的评分数据超过 10000 行时，将会返回此值。 |
| TotalCount | int | 查询的数据结果中的行总数。 |
评分值
Value 数组中的元素包含以下值。
| Value | 类型 | 说明 |
|---|---|---|
| date | string | 评分数据的日期范围中的第一个日期。 如果请求指定了某一天，此值就是该日期。 如果请求指定了一周、月或其他日期范围，此值是该日期范围内的第一个日期。 |
| applicationId | string | 要检索其评分数据的应用的 Store ID。 |
| applicationName | string | 应用的显示名称。 |
| market | string | 提交评分的市场的 ISO 3166 国家/地区代码。 |
| osVersion | string | 提交评分时所使用的 OS 版本。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| deviceType | string | 提交评分时所在的设备的类型。 有关支持的字符串列表，请参阅上述筛选器字段部分。 |
| isRevised | 布尔 | 如果值为 true，则表明评分已修订；否则为 false。 |
| oneStar | 数字 | 一星评分的数量。 |
| twoStars | 数字 | 两星评分的数量。 |
| threeStars | 数字 | 三星级评分的数量。 |
| fourStars | 数字 | 四星评分的数量。 |
| fiveStars | 数字 | 五星评分的数量。 |
请求和响应示例
如下代码片段展示了这些请求的一些示例请求和 JSON 响应正文。
示例请求
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
示例响应
{
"Value": [
{
"date": "2012-09-01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"oneStar": 1,
"twoStars": 0,
"threeStars": 0,
"fourStars": 1,
"fiveStars": 3
},
{
"date": "2012-09-02",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"oneStar": 3,
"twoStars": 0,
"threeStars": 1,
"fourStars": 2,
"fiveStars": 17
},
{
"date": "2012-09-03",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"oneStar": 1,
"twoStars": 1,
"threeStars": 1,
"fourStars": 5,
"fiveStars": 17
},
],
"TotalCount": 3
}
示例请求
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?applicationId=9NBLGGGZ5QDR&startDate=06/19/2022&endDate=07/20/2022&top=10&skip=0&groupby=date,applicationName,market,osVersion,deviceType,isRevised
HTTP/1.1
Authorization: Bearer <your access token>
示例响应
{
"Value": [
{
"date": "2022-06-22",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "CL",
"osVersion": "Windows 11",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-06-22",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "TR",
"osVersion": "Windows 11",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-06-29",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "FR",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 1,
"fiveStars": 0
},
{
"date": "2022-07-01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "BR",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-07-04",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "ES",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-07-06",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "ES",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-07-07",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "AE",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "true",
"oneStar": 1,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 0
},
{
"date": "2022-07-10",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "BR",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "true",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-07-13",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "EG",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "false",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 0,
"fiveStars": 1
},
{
"date": "2022-07-14",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"market": "BR",
"osVersion": "Windows 10",
"deviceType": "PC",
"isRevised": "true",
"oneStar": 0,
"twoStars": 0,
"threeStars": 0,
"fourStars": 1,
"fiveStars": 0
}
],
"TotalCount": 10
}