取得傳統型應用程式的升級區塊詳細資料Get upgrade block details for your desktop application

使用此 REST URI 來取得 Windows 10 裝置的詳細資料,讓您的桌面應用程式中的特定可執行檔封鎖執行中的 Windows 10 升級。Use this REST URI to get details for Windows 10 devices on which a specific executable in your desktop application is blocking a Windows 10 upgrade from running. 您只能針對已新增至 Windows 桌面應用程式的桌面應用程式使用此 URI。You can use this URI only for desktop applications that you have added to the Windows Desktop Application program. 這項資訊也可在合作夥伴中心的桌面應用程式的 [應用程式區塊] 報表 中取得。This information is also available in the Application blocks report for desktop applications in Partner Center.

此 URI 類似于 取得傳統型應用程式的升級區塊,但會針對您的桌面應用程式中的特定可執行檔傳回裝置區塊資訊。This URI is similar to Get upgrade blocks for your desktop application, but it returns device block info for a specific executable in your desktop application.

先決條件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/desktop/blockdetails

要求標頭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 您要用來取得區塊資料之桌面應用程式的產品識別碼。The product ID of the desktop application for which you want to retrieve block data. 若要取得傳統型應用程式的產品識別碼,請 在合作夥伴中心 (中開啟桌面應用程式的任何分析報表 ,例如「 區塊」報表) ,並從 URL 取出產品識別碼。To get the product ID of a desktop application, open any analytics report for your desktop application in Partner Center (such as the Blocks report) and retrieve the product ID from the URL. Yes
fileNamefileName 字串string 封鎖的可執行檔名稱The name of the blocked executable
startDatestartDate datedate 要取出之區塊資料的日期範圍內的開始日期。The start date in the date range of block data to retrieve. 預設值為目前日期前的90天。The default is 90 days prior to the current date. No
endDateendDate datedate 要取出之區塊資料的日期範圍中的結束日期。The end date in the date range of block 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. 每個陳述式包含一個與 eqne 運算子關聯的欄位名稱 (來自回應主體) 和值,而陳述式可以使用 andor 結合。Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. 篩選 參數中的字串值必須由單引號括住。String values must be surrounded by single quotes in the filter parameter. 您可以在回應本文中指定下列欄位:You can specify the following fields from the response body:

  • applicationVersionapplicationVersion
  • 建築architecture
  • blockTypeblockType
  • deviceTypedeviceType
  • 市場market
  • osReleaseosRelease
  • osVersionosVersion
  • 名稱productName
  • targetOstargetOs
No
orderbyorderby 字串string 排序每個區塊之結果資料值的語句。A statement that orders the result data values for each block. 語法為 orderby=field [order],field [order],...,其中 field 參數可以是下列來自回應本文欄位的其中一個︰The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following fields from the response body:

  • applicationVersionapplicationVersion
  • 建築architecture
  • blockTypeblockType
  • datedate
  • deviceTypedeviceType
  • 市場market
  • osReleaseosRelease
  • osVersionosVersion
  • 名稱productName
  • targetOstargetOs
  • deviceCountdeviceCount

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
groupbygroupby 字串string 將資料彙總僅套用至指定欄位的陳述式。A statement that applies data aggregation only to the specified fields. 您可以在回應本文中指定下列欄位:You can specify the following fields from the response body:

  • applicationVersionapplicationVersion
  • 建築architecture
  • blockTypeblockType
  • deviceTypedeviceType
  • 市場market
  • osReleaseosRelease
  • osVersionosVersion
  • targetOstargetOs

傳回的資料列將包含 groupby 參數中指定的欄位,以及下列項目:The returned data rows will contain the fields specified in the groupby parameter as well as the following:

  • applicationIdapplicationId
  • datedate
  • 名稱productName
  • deviceCountdeviceCount

No

要求範例Request example

下列範例示範一些取得桌面應用程式區塊資料的要求。The following example demonstrates several requests for getting desktop application block data. applicationId 值取代為桌面應用程式的產品識別碼。Replace the applicationId value with the Product ID for your desktop application.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/desktop/blockdetails?applicationId=10238467886765136388&fileName=contoso.exe&startDate=2018-05-01&endDate=2018-06-07&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/desktop/blockdetails?applicationId=10238467886765136388&fileName=contoso.exe&startDate=2018-05-01&endDate=2018-06-07&filter=market eq 'US' and deviceType eq 'PC' HTTP/1.1
Authorization: Bearer <your access token>

回應Response

回應本文Response body

Value 類型Type 描述Description
Value arrayarray 包含匯總區塊資料的物件陣列。An array of objects that contain aggregate block data. 如需有關每個物件中資料的詳細資訊,請參閱下表。For more information about the data in each object, see the following table.
@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 block data for the query.
TotalCountTotalCount intint 查詢之資料結果的資料列總數。The total number of rows in the data result for the query.

Value 陣列中的元素包含下列值。Elements in the Value array contain the following values.

Value 類型Type 說明Description
applicationIdapplicationId 字串string 您已抓取區塊資料的桌面應用程式產品識別碼。The product ID of the desktop application for which you retrieved block data.
datedate 字串string 與區塊點擊值相關聯的日期。The date associated with the block hits value.
productNameproductName 字串string 從相關聯的可執行檔中繼資料衍生的傳統型應用程式的顯示名稱。The display name of the desktop application as derived from the metadata of its associated executable(s).
fileNamefileName 字串string 已封鎖的可執行檔。The executable that was blocked.
applicationVersionapplicationVersion 字串string 已封鎖的應用程式可執行檔版本。The version of the application executable that was blocked.
osVersionosVersion 字串string 下列其中一個字串指定桌面應用程式目前執行所在的作業系統版本:One of the following strings that specifies the OS version on which the desktop application is currently running:

  • Windows 7Windows 7
  • Windows 8.1Windows 8.1
  • Windows 10Windows 10
  • Windows Server 2016Windows Server 2016
  • Windows Server 1709Windows Server 1709
  • UnknownUnknown
osReleaseosRelease 字串string 下列其中一個字串指定作業系統版本或試驗環形 (為桌面應用程式目前執行所在) 作業系統版本內的 subpopulation。One of the following strings that specifies the OS release or flighting ring (as a subpopulation within OS version) on which the desktop application is currently running.

適用於 Windows 10:For Windows 10:

  • 版本1507Version 1507
  • 版本 1511Version 1511
  • 版本1607Version 1607
  • 版本1703Version 1703
  • 版本1709Version 1709
  • 發行預覽Release Preview
  • 測試人員 - 快Insider Fast
  • 測試人員 - 慢Insider Slow

若是 Windows Server 1709:For Windows Server 1709:

  • RtmRTM

若是 Windows Server 2016:For Windows Server 2016:

  • 版本1607Version 1607

適用於 Windows 8.1:For Windows 8.1:

  • Update 1Update 1

適用於 Windows 7:For Windows 7:

  • Service Pack 1Service Pack 1

如果 OS 版本或正式發行前小眾測試通道不明,此欄位會有不明值。If the OS release or flighting ring is unknown, this field has the value Unknown.

marketmarket 字串string 桌面應用程式被封鎖的市場的 ISO 3166 國家/地區代碼。The ISO 3166 country code of the market in which the desktop application is blocked.
deviceTypedeviceType 字串string 下列其中一個字串,指定封鎖桌面應用程式的裝置類型:One of the following strings that specifies the type of device on which the desktop application is blocked:

  • PcPC
  • ServerServer
  • 平板電腦Tablet
  • UnknownUnknown
blockTypeblockType 字串string 下列其中一個字串指定在裝置上找到的區塊類型:One of the following strings that specifies the type of block found on the device:

  • 可能的 SedimentPotential Sediment
  • 暫存 SedimentTemporary Sediment
  • 執行時間通知Runtime Notification

如需這些區塊類型以及它們對開發人員和使用者之意義的詳細資訊,請參閱 應用程式區塊報表的描述。For more information about these block types and what they mean to developers and users, see the description of the Application blocks report.

架構architecture 字串string 區塊所在裝置的架構:The architecture of the device on which the block exists:

  • ARM64ARM64
  • X86X86
targetOstargetOs 字串string 下列其中一個字串,指定已封鎖桌面應用程式執行所在的 Windows 10 OS 版本:One of the following strings that specifies the Windows 10 OS release on which the desktop application is blocked from running:

  • 版本1709Version 1709
  • 版本1803Version 1803
deviceCountdeviceCount numbernumber 在指定的匯總層級具有區塊的相異裝置數目。The number of distinct devices that have blocks at the specified aggregation level.

回應範例Response example

下列範例針對此要求示範範例 JSON 回應主體。The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
     "applicationId": "10238467886765136388",
     "date": "2018-06-03",
     "productName": "Contoso Demo",
     "fileName": "contosodemo.exe",
     "applicationVersion": "2.2.2.0",
     "osVersion": "Windows 8.1",
     "osRelease": "Update 1",
     "market": "ZA",
     "deviceType": "All",
     "blockType": "Runtime Notification",
     "architecture": "X86",
     "targetOs": "RS4",
     "deviceCount": 120
    }
  ],
  "@nextLink": "desktop/blockdetails?applicationId=123456789&startDate=2018-01-01&endDate=2018-02-01&top=10000&skip=10000&groupby=applicationVersion,deviceType,osVersion,osRelease",
  "TotalCount": 23012
}