Deploy expedited updates with Windows Update for Business deployment service
In this article, you will:
Prerequisites
All of the prerequisites for the Windows Update for Business deployment service must be met, including ensuring that the Update Health Tools is installed on the clients.
- The Update Health Tools are installed starting with KB4023057. To confirm the presence of the Update Health Tools on a device, use one of the following methods:
- Run a readiness test for expedited updates
- Look for the folder C:\Program Files\Microsoft Update Health Tools or review Add Remove Programs for Microsoft Update Health Tools.
- Example PowerShell script to verify tools installation:
Get-CimInstance -ClassName Win32_Product \| Where-Object {$_.Name -match "Microsoft Update Health Tools"}
Permissions
The following permissions are needed for the queries listed in this article:
- WindowsUpdates.ReadWrite.All for Windows Update for Business deployment service operations.
- At least Device.Read.All permission to display device information.
Some roles, such as the Windows Update deployment administrator, already have these permissions.
Open Graph Explorer
For this article, you'll use Graph Explorer to make requests to the Microsoft Graph APIs to retrieve, add, delete, and update data. Graph Explorer is a developer tool that lets you learn about Microsoft Graph APIs. For more information about using Graph Explorer, see Get started with Graph Explorer.
Warning
- Requests listed in this article require signing in with a Microsoft 365 account. If needed, a free one month trial is available for Microsoft 365 Business Premium.
- Using a test tenant to learn and verify the deployment process is highly recommended. Graph Explorer is intended to be a learning tool. Ensure you understand granting consent and the consent type for Graph Explorer before proceeding.
From a browser, go to Graph Explorer and sign in using a Microsoft Entra user account.
You may need to enable the
WindowsUpdates.ReadWrite.Allpermission to use the queries in this article. To enable the permission:Select the Modify permissions tab in Graph Explorer.
In the permissions dialog box, select the WindowsUpdates.ReadWrite.All permission then select Consent. You may need to sign in again to grant consent.
To make requests:
- Select either GET, POST, PUT, PATCH, or DELETE from the drop-down list for the HTTP method.
- Enter the request into the URL field. The version will populate automatically based on the URL.
- If you need to modify the request body, edit the Request body tab.
- Select the Run query button. The results will appear in the Response window.
Tip
When reviewing Microsoft Graph documentation, you may notice example requests usually list
content-type: application/json. Specifyingcontent-typetypically isn't required for Graph Explorer, but you can add it to the request by selecting the Headers tab and adding thecontent-typeto the Request headers field as the Key andapplication/jsonas the Value.
Run queries to identify devices
Use the device resource type to find clients to enroll into the deployment service. Change the query parameters to fit your specific needs. For more information, see Use query parameters.
Displays the AzureAD Device ID and Name of all devices:
GET https://graph.microsoft.com/v1.0/devices?$select=deviceid,displayNameDisplays the AzureAD Device ID and Name for devices that have a name starting with
Test:GET https://graph.microsoft.com/v1.0/devices?$filter=startswith(displayName,'Test')&$select=deviceid,displayName
Add a request header for advanced queries
For the next requests, set the ConsistencyLevel header to eventual. For more information about advanced query parameters, see Advanced query capabilities on Microsoft Entra directory objects.
In Graph Explorer, select the Request headers tab.
For Key type in
ConsistencyLeveland for Value, typeeventual.Select the Add button. When you're finished, remove the request header by selecting the trash can icon.
Display the Name and Operating system version for the device that has
01234567-89ab-cdef-0123-456789abcdefas the AzureAD Device ID:GET https://graph.microsoft.com/v1.0/devices?$search="deviceid:01234567-89ab-cdef-0123-456789abcdef"&$select=displayName,operatingSystemVersionTo find devices that likely aren't virtual machines, filter for devices that don't have virtual machine listed as the model but do have a manufacturer listed. Display the AzureAD Device ID, Name, and Operating system version for each device:
GET https://graph.microsoft.com/v1.0/devices?$filter=model ne 'virtual machine' and NOT(manufacturer eq null)&$count=true&$select=deviceid,displayName,operatingSystemVersion
Tip
Requests using the device resource type typically have both an id and a deviceid:
- The
deviceidis the Microsoft Entra Device ID and will be used in this article.- Later in this article, this
deviceidwill be used as anidwhen you make certain requests such as adding a device to a deployment audience.
- Later in this article, this
- The
idfrom the device resource type is usually the Microsoft Entra Object ID, which won't be used in this article.
List catalog entries for expedited updates
Each update is associated with a unique catalog entry. You can query the catalog to find updates that can be expedited. The id returned is the Catalog ID and is used to create a deployment. The following query lists all security and nonsecurity quality updates that can be deployed as expedited updates by the deployment service. Using $top=2 and ordering by ReleaseDateTimeshows displays the most recent updates that can be deployed as expedited.
GET https://graph.microsoft.com/beta/admin/windows/updates/catalog/entries?$filter=isof('microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry') and microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/isExpeditable eq true&$orderby=releaseDateTime desc&$top=2
The following truncated response displays a Catalog ID of e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5 for the 08/08/2023 - 2023.08 B SecurityUpdate for Windows 10 and later security update:
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries",
"value": [
{
"@odata.type": "#microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry",
"id": "e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5",
"displayName": "08/08/2023 - 2023.08 B SecurityUpdate for Windows 10 and later",
"deployableUntilDateTime": null,
"releaseDateTime": "2023-08-08T00:00:00Z",
"isExpeditable": true,
"qualityUpdateClassification": "security",
"catalogName": "2023-08 Cumulative Update for Windows 10 and later",
"shortName": "2023.08 B",
"qualityUpdateCadence": "monthly",
"cveSeverityInformation": {
"maxSeverity": "critical",
"maxBaseScore": 9.8,
"exploitedCves@odata.context": "https://graph.microsoft.com/$metadata#admin/windows/updates/catalog/entries('e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5')/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/cveSeverityInformation/exploitedCves",
"exploitedCves": [
{
"number": "ADV230003",
"url": "https://msrc.microsoft.com/update-guide/vulnerability/ADV230003"
},
{
"number": "CVE-2023-38180",
"url": "https://msrc.microsoft.com/update-guide/vulnerability/CVE-2023-38180"
}
]
}
}
]
}
The deployment service can display more information about updates that were released on or after January 2023. Using product revision gives you additional information about the updates, such as the KB numbers, and the MajorVersion.MinorVersion.BuildNumber.UpdateBuildRevision. Windows 10 and 11 share the same major and minor versions, but have different build numbers.
Use the following to display the product revision information for the most recent quality update:
GET https://graph.microsoft.com/beta/admin/windows/updates/catalog/entries?$expand=microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/productRevisions&$orderby=releaseDateTime desc&$top=1
The following truncated response displays information about KB5029244 for Windows 10, version 22H2, and KB5029263 for Windows 11, version 22H2:
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries(microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/productRevisions())",
"value": [
{
"@odata.type": "#microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry",
"id": "e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5",
"displayName": "08/08/2023 - 2023.08 B SecurityUpdate for Windows 10 and later",
"deployableUntilDateTime": null,
"releaseDateTime": "2023-08-08T00:00:00Z",
"isExpeditable": true,
"qualityUpdateClassification": "security",
"catalogName": "2023-08 Cumulative Update for Windows 10 and later",
"shortName": "2023.08 B",
"qualityUpdateCadence": "monthly",
"cveSeverityInformation": {
"maxSeverity": "critical",
"maxBaseScore": 9.8,
"exploitedCves@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries('e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5')/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/cveSeverityInformation/exploitedCves",
"exploitedCves": [
{
"number": "ADV230003",
"url": "https://msrc.microsoft.com/update-guide/vulnerability/ADV230003"
},
{
"number": "CVE-2023-38180",
"url": "https://msrc.microsoft.com/update-guide/vulnerability/CVE-2023-38180"
}
]
},
"productRevisions@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries('e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5')/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/productRevisions",
"productRevisions": [
{
"id": "10.0.19045.3324",
"displayName": "Windows 10, version 22H2, build 19045.3324",
"releaseDateTime": "2023-08-08T00:00:00Z",
"version": "22H2",
"product": "Windows 10",
"osBuild": {
"majorVersion": 10,
"minorVersion": 0,
"buildNumber": 19045,
"updateBuildRevision": 3324
},
"knowledgeBaseArticle@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries('e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5')/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/productRevisions('10.0.19045.3324')/knowledgeBaseArticle/$entity",
"knowledgeBaseArticle": {
"id": "KB5029244",
"url": "https://support.microsoft.com/help/5029244"
}
},
{
"id": "10.0.22621.2134",
"displayName": "Windows 11, version 22H2, build 22621.2134",
"releaseDateTime": "2023-08-08T00:00:00Z",
"version": "22H2",
"product": "Windows 11",
"osBuild": {
"majorVersion": 10,
"minorVersion": 0,
"buildNumber": 22621,
"updateBuildRevision": 2134
},
"knowledgeBaseArticle@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries('e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5')/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/productRevisions('10.0.22621.2134')/knowledgeBaseArticle/$entity",
"knowledgeBaseArticle": {
"id": "KB5029263",
"url": "https://support.microsoft.com/help/5029263"
}
},
Create a deployment
When creating a deployment, there are multiple options available to define how the deployment behaves. The following example creates a deployment for the 08/08/2023 - 2023.08 B SecurityUpdate for Windows 10 and later security update with catalog entry ID e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5, and defines the expedite and userExperience deployment options in the request body.
POST https://graph.microsoft.com/beta/admin/windows/updates/deployments
content-type: application/json
{
"@odata.type": "#microsoft.graph.windowsUpdates.deployment",
"content": {
"@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
"catalogEntry": {
"@odata.type": "#microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry",
"id": "e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5"
}
},
"settings": {
"@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
"expedite": {
"isExpedited": true
},
"userExperience": {
"daysUntilForcedReboot": 2
}
}
}
The request returns a 201 Created response code and a deployment object in the response body for the newly created deployment, which includes:
- The Deployment ID
de910e12-3456-7890-abcd-ef1234567890of the newly created deployment. - The Audience ID
d39ad1ce-0123-4567-89ab-cdef01234567of the newly created deployment audience.
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments/$entity",
"id": "de910e12-3456-7890-abcd-ef1234567890",
"createdDateTime": "2024-01-30T19:43:37.1672634Z",
"lastModifiedDateTime": "2024-01-30T19:43:37.1672644Z",
"state": {
"effectiveValue": "offering",
"requestedValue": "none",
"reasons": []
},
"content": {
"@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
"catalogEntry@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments('073fb534-5cdd-4326-8aa2-a4d29037b60f')/content/microsoft.graph.windowsUpdates.catalogContent/catalogEntry/$entity",
"catalogEntry": {
"@odata.type": "#microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry",
"id": "e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5",
"displayName": null,
"deployableUntilDateTime": null,
"releaseDateTime": "2023-08-08T00:00:00Z",
"isExpeditable": false,
"qualityUpdateClassification": "security",
"catalogName": null,
"shortName": null,
"qualityUpdateCadence": "monthly",
"cveSeverityInformation": null
}
},
"settings": {
"schedule": null,
"monitoring": null,
"contentApplicability": null,
"userExperience": {
"daysUntilForcedReboot": 2,
"offerAsOptional": null
},
"expedite": {
"isExpedited": true,
"isReadinessTest": false
}
},
"audience@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments('de910e12-3456-7890-abcd-ef1234567890')/audience/$entity",
"audience": {
"id": "d39ad1ce-0123-4567-89ab-cdef01234567",
"applicableContent": []
}
}
Add members to the deployment audience
The Audience ID, d39ad1ce-0123-4567-89ab-cdef01234567, was created when the deployment was created. The Audience ID is used to add members to the deployment audience. After the deployment audience is updated, Windows Update starts offering the update to the devices according to the deployment settings. As long as the deployment exists and the device is in the audience, the update will be expedited.
The following example adds two devices to the deployment audience using the Microsoft Entra ID for each device:
POST https://graph.microsoft.com/beta/admin/windows/updates/deploymentAudiences/d39ad1ce-0123-4567-89ab-cdef01234567/updateAudience
content-type: application/json
{
"addMembers": [
{
"@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
{
"@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
"id": "01234567-89ab-cdef-0123-456789abcde0"
}
]
}
To verify the devices were added to the audience, run the following query using the Audience ID of d39ad1ce-0123-4567-89ab-cdef01234567:
GET https://graph.microsoft.com/beta/admin/windows/updates/deploymentAudiences/d39ad1ce-0123-4567-89ab-cdef01234567/members
Delete a deployment
To stop an expedited deployment, DELETE the deployment. Deleting the deployment will prevent the content from being offered to devices if they haven't already received it. To resume offering the content, a new approval will need to be created.
The following example deletes the deployment with a Deployment ID of de910e12-3456-7890-abcd-ef1234567890:
DELETE https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890
Readiness test for expediting updates
You can verify the readiness of clients to receive expedited updates by using isReadinessTest. Create a deployment that specifies it's an expedite readiness test, then add members to the deployment audience. The service will check to see if the clients meet the prerequisites for expediting updates. The results of the test are displayed in the Windows Update for Business reports workbook. Under the Quality updates tab, select the Expedite status tile, which opens a flyout with a Readiness tab with the readiness test results.
POST https://graph.microsoft.com/beta/admin/windows/updates/deployments
content-type: application/json
{
"@odata.type": "#microsoft.graph.windowsUpdates.deployment",
"content": {
"@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
"catalogEntry": {
"@odata.type": "#microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry",
"id": "317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5"
}
},
"settings": {
"@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
"expedite": {
"isExpedited": true,
"isReadinessTest": true
}
}
}
The truncated response displays that isReadinessTest is set to true and gives you a DeploymentID of de910e12-3456-7890-abcd-ef1234567890. You can then add members to the deployment audience to have the service check that the devices meet the preresquites then review the results in the Windows Update for Business reports workbook.
"expedite": {
"isExpedited": true,
"isReadinessTest": true
}
},
"audience@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments('6a6c03b5-008e-4b4d-8acd-48144208f179_Readiness')/audience/$entity",
"audience": {
"id": "de910e12-3456-7890-abcd-ef1234567890",
"applicableContent": []
}
Log location for the Update Health Tools
The Update Health Tools are used when you deploy expedited updates. In some cases, you may wish to review the logs for the Update Health Tools.
Log location: %ProgramFiles%\Microsoft Update Health Tools\Logs
- The logs are in
.etlformat.- Microsoft offers PerfView as a download on GitHub, which displays
.etlfiles.
- Microsoft offers PerfView as a download on GitHub, which displays
For more information, see Troubleshooting expedited updates.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for