| title | titleSuffix | description | ms.service | ms.subservice | ms.topic | ms.author | author | manager | ms.collection | ms.localizationpriority | appliesto | ms.date | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Deploy feature updates |
Windows Update for Business deployment service |
Use Windows Update for Business deployment service to deploy feature updates to devices in your organization. |
windows-client |
itpro-updates |
conceptual |
mstewart |
mestew |
aaroncz |
|
medium |
|
08/29/2023 |
The Windows Update for Business deployment service is used to approve and schedule software updates. The deployment service exposes its capabilities through the Microsoft Graph API. You can call the API directly, through a Graph SDK, or integrate them with a management tool such as Microsoft Intune.
This article uses Graph Explorer to walk through the entire process of deploying a feature update to clients. In this article, you will:
In this article, you will:
[!div class="checklist"]
All of the prerequisites for the Windows Update for Business deployment service must be met.
[!INCLUDE Windows Update for Business deployment service permissions using Graph Explorer]
[!INCLUDE Graph Explorer sign in]
[!INCLUDE Graph Explorer device queries]
When you enroll devices into feature update management, the deployment service becomes the authority for feature updates coming from Windows Update. As long as a device remains enrolled in feature update management through the deployment service, the device doesn't receive any other feature updates from Windows Update unless explicitly deployed using the deployment service. A device is offered the specified feature update if it hasn't already received the update. For example, if you deploy Windows 11 feature update version 22H2 to a device that's enrolled into feature update management and is currently on an older version of Windows 11, the device updates to version 22H2. If the device is already running version 22H2 or a later version, it stays on its current version.
Tip
Windows Update for Business reports has a workbook that displays the current operating system version for devices. In the workbook, go to the Feature updates tab and in the In Service feature update tile, select the View details link to open the details flyout. The OS version and Microsoft Entra ID of devices can easily be exported into a .csv file or opened in Azure Monitor Logs to help when creating a deployment audience.
[!INCLUDE Graph Explorer enroll devices]
Each feature update is associated with a unique catalog entry. The id returned is the Catalog ID and is used to create a deployment. Feature updates are deployable until they reach their support retirement dates. For more information, see the support lifecycle dates for Windows 10 and Windows 11 Enterprise and Education editions. The following query lists all deployable feature update catalog entries:
GET https://graph.microsoft.com/beta/admin/windows/updates/catalog/entries?$filter=isof('microsoft.graph.windowsUpdates.featureUpdateCatalogEntry')
The following truncated response displays a Catalog ID of d9049ddb-0ca8-4bc1-bd3c-41a456ef300f for the Windows 11, version 22H2 feature update:
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries",
"value": [
{
"@odata.type": "#microsoft.graph.windowsUpdates.featureUpdateCatalogEntry",
"id": "d9049ddb-0ca8-4bc1-bd3c-41a456ef300f",
"displayName": "Windows 11, version 22H2",
"deployableUntilDateTime": "2025-10-14T00:00:00Z",
"releaseDateTime": "2022-09-20T00:00:00Z",
"version": "Windows 11, version 22H2",
"buildNumber": "22621"
}
]
}When creating a deployment for a feature update, there are multiple options available to define how the deployment behaves. The deployment and monitoring settings are optional. The following deployment settings are defined in the example request body for deploying the Windows 11, version 22H2 feature update (Catalog ID of d9049ddb-0ca8-4bc1-bd3c-41a456ef300f):
- Deployment start date of February 14, 2023 at 5 AM UTC
- Gradual rollout at a rate of 100 devices every three days
- Monitoring rule that will pause the deployment if five devices rollback the feature update
- Default safeguard hold behavior of applying all applicable safeguards to devices in a deployment
- When safeguard holds aren't explicitly defined, the default safeguard hold behavior is applied automatically
POST https://graph.microsoft.com/beta/admin/windows/updates/deployments
content-type: application/json
{
"content": {
"@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
"catalogEntry": {
"@odata.type": "#microsoft.graph.windowsUpdates.featureUpdateCatalogEntry",
"id": "d9049ddb-0ca8-4bc1-bd3c-41a456ef300f"
}
},
"settings": {
"@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
"schedule": {
"startDateTime": "2023-02-14T05:00:00Z",
"gradualRollout": {
"@odata.type": "#microsoft.graph.windowsUpdates.rateDrivenRolloutSettings",
"durationBetweenOffers": "P3D",
"devicesPerOffer": "100"
}
},
"monitoring": {
"monitoringRules": [
{
"signal": "rollback",
"threshold": 5,
"action": "pauseDeployment"
}
]
}
}
}
The response body will contain:
-
The new Deployment ID,
de910e12-3456-7890-abcd-ef1234567890in the example -
The new Audience ID,
d39ad1ce-0123-4567-89ab-cdef01234567in the example -
Any settings defined in the deployment request body
{ "@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments/$entity", "id": "de910e12-3456-7890-abcd-ef1234567890", "createdDateTime": "2023-02-07T19:21:15.425905Z", "lastModifiedDateTime": "2023-02-07T19:21:15Z", "state": { "effectiveValue": "scheduled", "requestedValue": "none", "reasons": [] }, "content": { "@odata.type": "#microsoft.graph.windowsUpdates.catalogContent", "catalogEntry@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments('de910e12-3456-7890-abcd-ef1234567890')/content/microsoft.graph.windowsUpdates.catalogContent/catalogEntry/$entity", "catalogEntry": { "@odata.type": "#microsoft.graph.windowsUpdates.featureUpdateCatalogEntry", "id": "d9049ddb-0ca8-4bc1-bd3c-41a456ef300f", "displayName": "Windows 11, version 22H2", "deployableUntilDateTime": "2025-10-14T00:00:00Z", "releaseDateTime": "0001-01-01T00:00:00Z", "version": "Windows 11, version 22H2" } }, "settings": { "contentApplicability": null, "userExperience": null, "expedite": null, "schedule": { "startDateTime": "2023-02-14T05:00:00Z", "gradualRollout": { "@odata.type": "#microsoft.graph.windowsUpdates.rateDrivenRolloutSettings", "durationBetweenOffers": "P3D", "devicesPerOffer": 100 } }, "monitoring": { "monitoringRules": [ { "signal": "rollback", "threshold": 5, "action": "pauseDeployment" } ] } }, "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": [] } }
To update deployment, PATCH the deployment resource by its Deployment ID and supply the updated settings in the request body. The following example keeps the existing gradual rollout settings that were defined when creating the deployment but changes the deployment start date to February 28, 2023 at 5 AM UTC:
PATCH https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890
content-type: application/json
{
"settings": {
"@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
"schedule": {
"startDateTime": "2023-02-28T05:00:00Z",
"gradualRollout": {
"@odata.type": "#microsoft.graph.windowsUpdates.rateDrivenRolloutSettings",
"durationBetweenOffers": "P3D",
"devicesPerOffer": "100"
}
}
}
}
Verify the deployment settings for the deployment with a Deployment ID of de910e12-3456-7890-abcd-ef1234567890:
GET https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890
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 offered.
The following example adds three 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"
},
{
"@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
"id": "01234567-89ab-cdef-0123-456789abcde1"
}
]
}
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
To pause a deployment, PATCH the deployment to have a requestedValue of paused for the deploymentState. To resume the deployment, use the value none and the state will either update to offering or scheduled if the deployment hasn't reached the start date yet.
The following example pauses the deployment with a Deployment ID of de910e12-3456-7890-abcd-ef1234567890:
PATCH https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890
content-type: application/json
{
"@odata.type": "#microsoft.graph.windowsUpdates.deployment",
"state": {
"@odata.type": "microsoft.graph.windowsUpdates.deploymentState",
"requestedValue": "paused"
}
}
To remove the deployment completely, 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
[!INCLUDE Graph Explorer enroll devices]