获取应用评价Get app reviews

使用 Microsoft Store 分析 API 中的此方法,可获取给定日期范围和其他可选筛选器的评价数据(格式为 JSON)。Use this method in the Microsoft Store analytics API to get review data in JSON format for a given date range and other optional filters. 此信息也可在合作伙伴中心的 "查看" 报表中获得。This information is also available in the Reviews report in Partner Center.

在检索评价后,可使用 Microsoft Store 评价 API 中的获取应用评价的回复信息提交对应用评价的回复方法以可编程方式回复评价。After you retrieve reviews, you can use the get response info for app reviews and submit responses to app reviews methods in the Microsoft Store reviews API to programmatically respond to reviews.

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

请求Request

请求语法Request syntax

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

请求头Request header

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

请求参数Request parameters

参数Parameter 类型Type 说明Description 必需Required
applicationIdapplicationId 字符串string 要检索评价数据的应用的 Store IDThe Store ID of the app for which you want to retrieve review data. Yes
startDatestartDate datedate 要检索的评价数据日期范围中的开始日期。The start date in the date range of review data to retrieve. 默认值为当前日期。The default is the current date. No
endDateendDate 日期date 要检索的评价数据日期范围中的结束日期。The end date in the date range of review 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. 有关详细信息,请参阅下面的筛选器字段部分。For more information, see the filter fields section below. No
orderbyorderby stringstring 对结果数据值进行排序的语句。A statement that orders the result data values. 语法为 orderby=field [order],field [order],...,其中 field 参数可以是以下字符串之一:The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • osVersionosVersion
  • marketmarket
  • deviceTypedeviceType
  • isRevisedisRevised
  • packageVersionpackageVersion
  • deviceModeldeviceModel
  • productFamilyproductFamily
  • deviceScreenResolutiondeviceScreenResolution
  • isTouchEnabledisTouchEnabled
  • reviewerNamereviewerName
  • reviewTitlereviewTitle
  • reviewTextreviewText
  • helpfulCounthelpfulCount
  • notHelpfulCountnotHelpfulCount
  • responseDateresponseDate
  • responseTextresponseText
  • deviceRAMdeviceRAM
  • deviceStorageCapacitydeviceStorageCapacity
  • 定额rating

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

筛选器字段Filter fields

请求中的 filter 参数包含一条或多条语句,用于在响应中筛选行。The filter parameter of the request contains one or more statements that filter the rows in the response. 每条语句包含的字段和值使用 eqne 运算符进行关联,并且某些字段还支持 containsgtltgele 运算符。Each statement contains a field and value that are associated with the eq or ne operators, and some fields also support the contains, gt, lt, ge, and le operators. 语句可以使用 andor 进行组合。Statements can be combined using and or or.

下面是一个 filter 字符串的示例:filter=contains(reviewText,'great') and contains(reviewText,'ads') and deviceRAM lt 2048 and market eq 'US'Here is an example filter string: filter=contains(reviewText,'great') and contains(reviewText,'ads') and deviceRAM lt 2048 and market eq 'US'

有关支持的字段列表和每个字段支持的运算符,请参阅下表。For a list of the supported fields and support operators for each field, see the following table. filter 参数中的字符串值必须使用单引号引起来。String values must be surrounded by single quotes in the filter parameter.

字段Fields 支持的运算符Supported operators 描述Description
marketmarket eq、neeq, ne 包含设备市场的 ISO 3166 国家/地区代码的字符串。A string that contains the ISO 3166 country code of the device market.
osVersionosVersion eq、neeq, ne 以下字符串之一:One of the following strings:
  • Windows Phone 7.5Windows Phone 7.5
  • Windows Phone 8Windows Phone 8
  • Windows Phone 8.1Windows Phone 8.1
  • Windows Phone 10Windows Phone 10
  • Windows 8Windows 8
  • Windows 8.1Windows 8.1
  • Windows 10Windows 10
  • UnknownUnknown
deviceTypedeviceType eq、neeq, ne 以下字符串之一:One of the following strings:
  • PCPC
  • 移动Phone
  • 控制台-Xbox OneConsole-Xbox One
  • 控制台-Xbox 系列 XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
isRevisedisRevised eq、neeq, ne 指定 true 可筛选已修改的评价,否则指定 falseSpecify true to filter for reviews that have been revised; otherwise false.
packageVersionpackageVersion eq、neeq, ne 已评价的应用程序包版本。The version of the app package that was reviewed.
deviceModeldeviceModel eq、neeq, ne 应用已评价的设备的类型。The type of device on which the app was reviewed.
productFamilyproductFamily eq、neeq, ne 以下字符串之一:One of the following strings:
  • PCPC
  • 平板电脑Tablet
  • 移动Phone
  • 可穿戴设备Wearable
  • ServerServer
  • CollaborativeCollaborative
  • 其他Other
deviceRAMdeviceRAM eq、ne、gt、lt、ge、leeq, ne, gt, lt, ge, le 物理 RAM(以 MB 为单位)。The physical RAM, in MB.
deviceScreenResolutiondeviceScreenResolution eq、neeq, ne 设备屏幕分辨率,格式为 " 宽度x " 。The device screen resolution in the format "width x height".
deviceStorageCapacitydeviceStorageCapacity eq、ne、gt、lt、ge、leeq, ne, gt, lt, ge, le 主存储器磁盘容量(以 GB 为单位)。The capacity of the primary storage disk, in GB.
isTouchEnabledisTouchEnabled eq、neeq, ne 指定 true 可筛选支持触摸的设备,否则指定 falseSpecify true to filter for touch-enabled devices; otherwise false.
reviewerNamereviewerName eq、neeq, ne 评价者名称。The reviewer name.
ratingrating eq、ne、gt、lt、ge、leeq, ne, gt, lt, ge, le 应用评分(以星级为单位)。The app rating, in stars.
reviewTitlereviewTitle eq, ne, containseq, ne, contains 评价的标题。The title of the review.
reviewTextreviewText eq, ne, containseq, ne, contains 评价的文本内容。The text contents of the review.
helpfulCounthelpfulCount eq、neeq, ne 评价标记为有用的次数。The number of times the review was marked helpful.
notHelpfulCountnotHelpfulCount eq、neeq, ne 评价标记为无用的次数。The number of times the review was marked not helpful.
responseDateresponseDate eq、neeq, ne 回复的提交时间。The date that the response was submitted.
responseTextresponseText eq, ne, containseq, ne, contains 回复的文本内容。The text contents of the response.
idid eq、neeq, ne 评价的 ID(这是一个 GUID)。The ID of the review (this is a GUID).

请求示例Request example

以下示例演示用于获取评价数据的多个请求。The following examples demonstrate several requests for getting review data. applicationId 值替换为你的应用的 Store ID。Replace the applicationId value with the Store ID for your app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/reviews?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/reviews?applicationId=9NBLGGGZ5QDR&startDate=8/1/2015&endDate=8/31/2015&skip=0&filter=contains(reviewText,'great') and contains(reviewText,'ads') and deviceRAM lt 2048 and market eq 'US' HTTP/1.1
Authorization: Bearer <your access token>

响应Response

响应正文Response body

Value 类型Type 说明Description
ValueValue arrayarray 包含评价数据的对象数组。An array of objects that contain review data. 有关每个对象中的数据的详细信息,请参阅以下评价值部分。For more information about the data in each object, see the review 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 reviews data for the query.
TotalCountTotalCount intint 查询的数据结果中的行总数。The total number of rows in the data result for the query.

 

评价值Review 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 review 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.
applicationIdapplicationId stringstring 要检索评价数据的应用的应用商店 ID。The Store ID of the app for which you are retrieving review data.
applicationNameapplicationName stringstring 应用的显示名称。The display name of the app.
marketmarket stringstring 评价已提交的市场的 ISO 3166 国家/地区代码。The ISO 3166 country code of the market where the review was submitted.
osVersionosVersion stringstring 评价已提交的操作系统版本。The OS version on which the review was submitted. 有关支持的字符串列表,请参阅上述筛选器字段部分。For a list of the supported strings, see the filter fields section above.
deviceTypedeviceType stringstring 评价已提交的设备的类型。The type of device on which the review was submitted. 有关支持的字符串列表,请参阅上述筛选器字段部分。For a list of the supported strings, see the filter fields section above.
isRevisedisRevised 布尔Boolean 值为 true 表示评价已修改;否则为 falseThe value true indicates that the review was revised; otherwise false.
packageVersionpackageVersion stringstring 已评价的应用程序包版本。The version of the app package that was reviewed.
deviceModeldeviceModel stringstring 应用已评价的设备的类型。The type of device on which the app was reviewed.
productFamilyproductFamily stringstring 设备系列名称。The device family name. 有关支持的字符串列表,请参阅上述筛选器字段部分。For a list of the supported strings, see the filter fields section above.
deviceRAMdeviceRAM 数字number 物理 RAM(以 MB 为单位)。The physical RAM, in MB.
deviceScreenResolutiondeviceScreenResolution stringstring 设备屏幕分辨率的格式为 "宽度x高度"。The device screen resolution in the format "width x height".
deviceStorageCapacitydeviceStorageCapacity 数字number 主存储器磁盘容量(以 GB 为单位)。The capacity of the primary storage disk, in GB.
isTouchEnabledisTouchEnabled 布尔Boolean 值为 true 表示触摸受支持;否则为 falseThe value true indicates that touch is enabled; otherwise false.
reviewerNamereviewerName stringstring 评价者名称。The reviewer name.
ratingrating 数字number 应用评分(以星级为单位)。The app rating, in stars.
reviewTitlereviewTitle stringstring 评价的标题。The title of the review.
reviewTextreviewText stringstring 评价的文本内容。The text contents of the review.
helpfulCounthelpfulCount 数字number 评价标记为有用的次数。The number of times the review was marked helpful.
notHelpfulCountnotHelpfulCount 数字number 评价标记为无用的次数。The number of times the review was marked not helpful.
responseDateresponseDate stringstring 回复的提交时间。The date a response was submitted.
responseTextresponseText stringstring 回复的文本内容。The text contents of the response.
idid 字符串string 评价的 ID(这是一个 GUID)。The ID of the review (this is a GUID). 你可以在获取应用评价的回复信息提交对应用评价的回复方法中使用此 ID。You can use this ID in the get response info for app reviews and submit responses to app reviews methods.

响应示例Response example

以下示例举例说明此请求的 JSON 响应正文。The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2015-07-29",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso demo",
      "market": "US",
      "osVersion": "10.0.10240.16410",
      "deviceType": "PC",
      "isRevised": true,
      "packageVersion": "",
      "deviceModel": "Microsoft Corporation-Virtual Machine",
      "productFamily": "PC",
      "deviceRAM": -1,
      "deviceScreenResolution": "1024 x 768",
      "deviceStorageCapacity": 51200,
      "isTouchEnabled": false,
      "reviewerName": "ALeksandra",
      "rating": 5,
      "reviewTitle": "Love it",
      "reviewText": "Great app for demos and great dev response.",
      "helpfulCount": 0,
      "notHelpfulCount": 0,
      "responseDate": "2015-08-07T01:50:22.9874488Z",
      "responseText": "1",
      "id": "6be543ff-1c9c-4534-aced-af8b4fbe0316"
    }
  ],
  "@nextLink": null,
  "TotalCount": 1
}