获取桌面应用程序的升级块详情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. 只能将此 URI 用于已添加到 Windows 桌面应用程序的桌面应用程序。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 要为其检索块数据的桌面应用程序的产品 ID。The product ID of the desktop application for which you want to retrieve block data. 若要获取桌面应用程序的产品 ID,请在合作伙伴中心 ((例如 "块") 报表中打开适用于桌面应用程序的任何分析报表,并从 URL 中检索产品 ID。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 日期date 要检索的块数据的日期范围的开始日期。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 日期date 要检索的块数据的日期范围的结束日期。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. filter 参数中的字符串值必须使用单引号引起来。String values must be surrounded by single quotes in the filter parameter. 可以指定响应正文中的以下字段:You can specify the following fields from the response body:

  • applicationVersionapplicationVersion
  • architecturearchitecture
  • blockTypeblockType
  • deviceTypedeviceType
  • 营销market
  • osReleaseosRelease
  • osVersionosVersion
  • productNameproductName
  • 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
  • architecturearchitecture
  • blockTypeblockType
  • datedate
  • deviceTypedeviceType
  • 营销market
  • osReleaseosRelease
  • osVersionosVersion
  • productNameproductName
  • 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,marketHere 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
  • architecturearchitecture
  • 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
  • productNameproductName
  • deviceCountdeviceCount

No

请求示例Request example

下面的示例演示了获取桌面应用程序块数据的几个请求。The following example demonstrates several requests for getting desktop application block data. 用桌面应用程序的产品 ID 替换 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 你为其检索了阻止数据的桌面应用程序的产品 ID。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 以下字符串之一,指定 OS release 或试验环形 (为当前运行桌面应用程序) 操作系统版本中的一个 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 PreviewRelease 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:

  • 更新 1Update 1

对于 Windows 7:For Windows 7:

  • Service Pack 1Service Pack 1

如果操作系统版本或外部测试 Ring 未知,则此字段的值为 UnknownIf the OS release or flighting ring is unknown, this field has the value Unknown.

marketmarket stringstring 阻止桌面应用程序的市场的 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:

  • 计算机PC
  • 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 数字number 在指定聚合级别具有块的不同设备的数目。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
}