Upraviť

Zdieľať cez

Programmatic controls for Windows feature updates

Important

The information in section applies to Business premium, A3+, E3+ and F3 licenses. For more information, see Features and capabilities and Licenses and entitlements.

Windows Autopatch programmatic controls are used to approve and schedule software updates through 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:

Prerequisites

All of the Windows Autopatch prerequisites must be met.

Permissions

The following permissions are needed for the queries listed in this article:

Some roles, such as the Windows Update deployment administrator, already have these permissions.

Required endpoints

You must have access to the following endpoints:

Windows Update endpoints

  • *.prod.do.dsp.mp.microsoft.com
  • *.windowsupdate.com
  • *.dl.delivery.mp.microsoft.com
  • *.update.microsoft.com
  • *.delivery.mp.microsoft.com
  • tsfe.trafficshaping.dsp.mp.microsoft.com

Graph API endpoints:

  • devicelistenerprod.microsoft.com
  • login.windows.net
  • payloadprod*.blob.core.windows.net

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.

  1. From a browser, go to Graph Explorer and sign in using a Microsoft Entra user account.

  2. You may need to enable the WindowsUpdates.ReadWrite.All permission to use the queries in this article. To enable the permission:

    1. Select the Modify permissions tab in Graph Explorer.
    2. In the permissions dialog box, select the WindowsUpdates.ReadWrite.All permission then select Consent. You may need to sign in again to grant consent. Screenshot of the modify permissions tab in Graph Explorer

  3. To make requests:

    1. Select either GET, POST, PUT, PATCH, or DELETE from the drop-down list for the HTTP method.
    2. Enter the request into the URL field. The version will populate automatically based on the URL.
    3. If you need to modify the request body, edit the Request body tab.
    4. 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. Specifying content-type typically isn't required for Graph Explorer, but you can add it to the request by selecting the Headers tab and adding the content-type to the Request headers field as the Key and application/json as the Value.

Run queries to identify devices

Use the device resource type to find clients to enroll into Windows Autopatch. 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,displayName

  • Displays 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.

  1. In Graph Explorer, select the Request headers tab.

  2. For Key type in ConsistencyLevel and for Value, type eventual.

  3. Select the Add button. When you're finished, remove the request header by selecting the trash can icon.

    Screenshot of the request headers tab in Graph Explorer

  • Display the Name and Operating system version for the device that has 01234567-89ab-cdef-0123-456789abcdef as the AzureAD Device ID:

    GET https://graph.microsoft.com/v1.0/devices?$search="deviceid:01234567-89ab-cdef-0123-456789abcdef"&$select=displayName,operatingSystemVersion

  • To 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 deviceid is the Microsoft Entra Device ID and will be used in this article.
    • Later in this article, this deviceid will be used as an id when you make certain requests such as adding a device to a deployment audience.
  • The id from the device resource type is usually the Microsoft Entra Object ID, which won't be used in this article.

Enroll devices

When you enroll devices into feature update management, Windows Autopatch becomes the authority for feature updates coming from Windows Update. As long as a device remains enrolled in feature update management through Windows Autopatch, the device doesn't receive any other feature updates from Windows Update unless explicitly deployed using Windows Autopatch. 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.

You enroll devices based on the types of updates you want them to receive. Currently, you can enroll devices to receive feature updates (feature) or drivers (driver). You can enroll devices to receive updates from multiple update classifications.

  1. To enroll devices, POST to updatableAssets using enrollAssets. The following example enrolls three devices to receive driver updates:

    1. In Graph Explorer, select POST from the drop-down list for the HTTP verb.

    2. Enter the following request into the URL field:
      https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/enrollAssets

    3. In the Request body tab, enter the following JSON, supplying the following information:

      • Microsoft Entra Device ID as id
      • Either feature or driver for the updateCategory
      {
  "updateCategory": "driver",
  "assets": [
    {
      "@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"
    }
  ]
}

    4. Select the Run query button. The results will appear in the Response window. In this case, the HTTP status code of 202 Accepted.

      Screenshot of successfully enrolling assets through Graph Explorer.

List catalog entries for feature updates

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"
        }
    ]
}

Create a deployment

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 pauses 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 contains:

  • The new Deployment ID, de910e12-3456-7890-abcd-ef1234567890 in the example

  • The new Audience ID, d39ad1ce-0123-4567-89ab-cdef01234567 in 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": []
     }
}

Edit a deployment

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

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 is 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

Pause a deployment

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"
  }
}

Delete a deployment

To remove the deployment completely, DELETE the deployment. Deleting the deployment prevents the content from being offered to devices if they haven't already received it. To resume offering the content, a new approval needs 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

Unenroll devices

When a device no longer requires management, unenroll it from Windows Autopatch. Just like enrolling a device, specify either driver or feature as the value for the updateCategory. The device will no longer receive updates from Windows Autopatch for the specified update category. Depending on the device's configuration, it may start to receive updates from Windows Update. For instance, if a device is still enrolled for feature updates, but it's unenrolled from drivers:

  • Existing driver deployments from the service won't be offered to the device
  • The device continues to receive feature updates from Windows Autopatch
  • Drivers may start being installed from Windows Update depending on the device's configuration

To unenroll a device, POST to updatableAssets using unenrollAssets. In the request body, specify:

  • Microsoft Entra Device ID as id for the device
  • Either feature or driver for the updateCategory

The following example removes driver enrollment for two devices, 01234567-89ab-cdef-0123-456789abcdef and 01234567-89ab-cdef-0123-456789abcde0:

POST https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/unenrollAssets
content-type: application/json

{
  "updateCategory": "driver",
  "assets": [
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcde0"
    }
  ]
}