获取应用评分

使用 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 指定用于检索聚合数据的时间范围。 可以是以下字符串之一:dayweekmonth。 如果未指定,默认值为 day
orderby string 一个用来对每次评分的结果数据值进行排序的语句。 语法为 orderby=field [order],field [order],...,其中 field 参数可以是以下字符串之一:
  • date
  • osVersion
  • market
  • deviceType
  • isRevised

order 参数是可选的,可以是 ascdesc,用于指定每个字段的升序或降序排列。 默认值为 asc

下面是一个 orderby 字符串的示例:orderby=date,market

groupby string 仅将数据聚合应用于指定字段的语句。 可以指定以下字段:
  • date
  • applicationName
  • market
  • osVersion
  • deviceType
  • isRevised

返回的数据行将包含 groupby 参数中指定的字段以及以下字段:

  • date
  • applicationId
  • fiveStars
  • fourStars
  • threeStars
  • twoStars
  • oneStar

groupby 参数可以与 aggregationLevel 参数结合使用。 例如:&groupby=osVersion,market&aggregationLevel=week

 

筛选器字段

请求中的 filter 参数包含一条或多条用来在响应中筛选行的语句。 每条语句包含的字段和值使用 eqne 运算符进行关联,并且语句可以使用 andor 进行组合。

下面是一个示例筛选器字符串:filter=market eq 'US' and deviceType eq 'phone' and isRevised eq true

有关支持的字段列表,请参阅下表。 filter 参数中的字符串值必须使用单引号引起来。

字段 说明
market 一个包含应用评分所在地市场的 ISO 3166 国家/地区代码的字符串。
osVersion 以下字符串之一:
  • Windows Phone 7.5
  • Windows Phone 8
  • Windows Phone 8.1
  • Windows Phone 10
  • Windows 8
  • Windows 8.1
  • Windows 10
  • Windows 11
  • Unknown
deviceType 以下字符串之一:
  • 电脑
  • Phone
  • Console-Xbox One
  • Console-Xbox 系列 X
  • IoT
  • Holographic
  • Unknown
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
}