取得應用程式評論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 識別碼The 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 datedate 要擷取評論資料之日期範圍的結束日期。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 字串string 一或多個篩選回應中資料列的陳述式。One or more statements that filter the rows in the response. 如需更多資訊,請參閱下方的<篩選欄位>一節。For more information, see the filter fields section below. No
orderbyorderby 字串string 將結果資料值排序的陳述式。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
  • 細分market
  • deviceTypedeviceType
  • isRevisedisRevised
  • packageVersionpackageVersion
  • Devicemodel 傳遞deviceModel
  • 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,市Here 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. 篩選 參數中的字串值必須由單引號括住。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
  • 全息影像Holographic
  • 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 評論 app 的裝置類型。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 App 評分 (以星星為單位)。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 評論的識別碼 (這是 GUID)。The ID of the review (this is a GUID).

要求範例Request example

下列範例示範取得評論資料的數個要求。The following examples demonstrate several requests for getting review data. applicationId 值取代為您 App 的 Store 識別碼。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
Value 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 字串string 如果還有其他資料頁面,此字串包含可以用來要求下一頁資料的 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 字串string 評論資料之日期範圍中的第一個日期。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 字串string 您正在擷取評論資料之 App 的 Store 識別碼。The Store ID of the app for which you are retrieving review data.
applicationNameapplicationName 字串string App 的顯示名稱。The display name of the app.
marketmarket 字串string 提交評論之市場的 ISO 3166 國家/地區碼。The ISO 3166 country code of the market where the review was submitted.
osVersionosVersion 字串string 提交評論的 OS 版本。The OS version on which the review was submitted. 如需支援的字串清單,請參閱上方的<篩選欄位>一節。For a list of the supported strings, see the filter fields section above.
deviceTypedeviceType 字串string 提交評論的裝置類型。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 字串string 已評論的應用程式套件版本。The version of the app package that was reviewed.
deviceModeldeviceModel 字串string 評論 app 的裝置類型。The type of device on which the app was reviewed.
productFamilyproductFamily 字串string 裝置系列名稱。The device family name. 如需支援的字串清單,請參閱上方的<篩選欄位>一節。For a list of the supported strings, see the filter fields section above.
deviceRAMdeviceRAM numbernumber 實體 RAM (以 MB 為單位)。The physical RAM, in MB.
deviceScreenResolutiondeviceScreenResolution 字串string 裝置螢幕解析度,格式為「寬度x高度」。The device screen resolution in the format "width x height".
deviceStorageCapacitydeviceStorageCapacity numbernumber 主要存放磁碟的容量 (以 GB 為單位)。The capacity of the primary storage disk, in GB.
isTouchEnabledisTouchEnabled 布林值Boolean true 值表示已啟用觸控功能,否則為 falseThe value true indicates that touch is enabled; otherwise false.
reviewerNamereviewerName 字串string 評論者名稱。The reviewer name.
ratingrating numbernumber App 評分 (以星星為單位)。The app rating, in stars.
reviewTitlereviewTitle 字串string 評論的標題。The title of the review.
reviewTextreviewText 字串string 評論的文字內容。The text contents of the review.
helpfulCounthelpfulCount numbernumber 該評論被標記為「很有幫助」的次數。The number of times the review was marked helpful.
notHelpfulCountnotHelpfulCount numbernumber 該評論被標記為「沒有幫助」的次數。The number of times the review was marked not helpful.
responseDateresponseDate 字串string 提交回應的日期。The date a response was submitted.
responseTextresponseText 字串string 回應的文字內容。The text contents of the response.
idid 字串string 評論的識別碼 (這是 GUID)。The ID of the review (this is a GUID). 您可以在取得應用程式評論的回應資訊提交應用程式評論的回應方法中使用此識別碼。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
}