Edit

Share via

Programmatic controls for drivers and firmware updates

Windows Autopatch programmatic controls are used to approve and schedule software updates 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 driver update to clients. 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 driver management, Windows Autopatch becomes the authority for driver updates coming from Windows Update. Devices don't receive drivers or firmware from Windows Update until a deployment is manually created or they're added to a driver update policy with approvals.

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.

Create a deployment audience and add audience members

A deployment audience is a collection of devices that you want to deploy updates to. The audience needs to be created first, then members are added to the audience. Use the following steps to create a deployment audience, add members, and verify it:

  1. To create a new audience, POST to the deployment audience resource with a request body of {}.

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

{}

    The POST returns an HTTP status code of 201 Created as a response with the following body, where id is the Audience ID:

    {
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deploymentAudiences/$entity",
    "id": "d39ad1ce-0123-4567-89ab-cdef01234567",
    "reportingDeviceCount": 0,
    "applicableContent": []
}

  2. Add devices, using their Microsoft Entra ID, to the deployment audience so they become audience members. Specify the deployment Audience ID in the URL field and the devices to add in the request body. The id property specifies the Microsoft Entra ID of the 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"
    }
  ]
}

  3. 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

Once a device has been enrolled and added to a deployment audience, Windows Autopatch will start collecting scan results from Windows Update to build a catalog of applicable drivers to be browsed, approved, and scheduled for deployment.

Create an update policy

Update policies define how content is deployed to a deployment audience. An update policy ensures deployments to a deployment audience behave in a consistent manner without having to create and manage multiple individual deployments. When a content approval is added to the policy, it's deployed to the devices in the associated audiences. The deployment and monitoring settings are optional.

Important

Any deployment settings configured for a content approval will be combined with the existing update policy's deployment settings. If the content approval and update policy specify the same deployment setting, the setting from the content approval is used.

Create a policy and define the settings later

To create a policy without any deployment settings, in the request body specify the Audience ID as id. In the following example, the Audience ID is d39ad1ce-0123-4567-89ab-cdef01234567, and the id given in the response is the Policy ID:

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

{
  "audience": {
    "id": "d39ad1ce-0123-4567-89ab-cdef01234567"
  }
}

Response returning the policy, without any additional settings specified, that has a Policy ID of 9011c330-1234-5678-9abc-def012345678:

HTTP/1.1 202 Accepted
content-type: application/json
{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/updatePolicies/$entity",
  "id": "9011c330-1234-5678-9abc-def012345678",
  "createdDateTime": "2023-01-25T05:32:21.9721459Z",
  "autoEnrollmentUpdateCategories": [],
  "complianceChangeRules": [],
  "deploymentSettings": {
      "schedule": null,
      "monitoring": null,
      "contentApplicability": null,
      "userExperience": null,
      "expedite": null
  }
}

Specify settings during policy creation

To create a policy with additional settings, in the request body:

In the following driver update policy example, any deployments created by a content approval will start 7 days after approval for Audience ID d39ad1ce-0123-4567-89ab-cdef01234567:

POST https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies
content-type: application/json
   
{
  "@odata.type": "#microsoft.graph.windowsUpdates.updatePolicy",
  "audience": {
    "id": "d39ad1ce-0123-4567-89ab-cdef01234567"
  },
  "complianceChanges": [
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.contentApproval"
    }
  ],
  "complianceChangeRules": [
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.contentApprovalRule",
      "contentFilter": {
        "@odata.type": "#microsoft.graph.windowsUpdates.driverUpdateFilter"
      },
      "durationBeforeDeploymentStart": "P7D"
    }
  ]
}

Review and edit update policy settings

To review the policy settings, run the following query using the Policy ID, for example 9011c330-1234-5678-9abc-def012345678:

GET https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678

To edit the policy settings, PATCH the policy using the Policy ID. Run the following PATCH to automatically approve driver content that's recommended by Microsoftfor deployment for Policy ID 9011c330-1234-5678-9abc-def012345678:

PATCH https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678
content-type: application/json

{
    "complianceChangeRules": [
     {
        "@odata.type": "#microsoft.graph.windowsUpdates.contentApprovalRule",
         "contentFilter": {
          "@odata.type": "#microsoft.graph.windowsUpdates.driverUpdateFilter"
        }
    }
  ],
    "deploymentSettings": {
       "@odata.type": "#microsoft.graph.windowsUpdates.deploymentSettings",
        "contentApplicability": {
          "@odata.type": "#microsoft.graph.windowsUpdates.contentApplicabilitySettings",
          "offerWhileRecommendedBy": ["microsoft"]
        }
      }
}

Review applicable driver content

Once Windows Autopatch has scan results from devices, the applicability for driver and firmware updates can be displayed for a deployment audience. Each applicable update returns the following information:

  • An id for its catalog entry
  • The Microsoft Entra ID of the devices it's applicable to
  • Information describing the update such as the name and version.

To display applicable content, run a query using the Audience ID, for example d39ad1ce-0123-4567-89ab-cdef01234567:

GET https://graph.microsoft.com/beta/admin/windows/updates/deploymentAudiences/d39ad1ce-0123-4567-89ab-cdef01234567/applicableContent

The following truncated response displays:

  • An Microsoft Entra ID of 01234567-89ab-cdef-0123-456789abcdef

  • The Catalog ID of 5d6dede684ba5c4a731d62d9c9c2a99db12c5e6015e9f8ad00f3e9387c7f399c

    "matchedDevices": [
    {
        "recommendedBy": [
            "Microsoft"
        ],
        "deviceId": "01ea3c90-12f5-4093-a4c9-c1434657c976"
    }
],
"catalogEntry": {
    "@odata.type": "#microsoft.graph.windowsUpdates.driverUpdateCatalogEntry",
    "id": "5d6dede684ba5c4a731d62d9c9c2a99db12c5e6015e9f8ad00f3e9387c7f399c",
    "displayName": "Microsoft - Test - 1.0.0.1",
    "deployableUntilDateTime": null,
    "releaseDateTime": "0001-01-21T04:18:32Z",
    "description": "Microsoft test driver update released in January 2021",
    "driverClass": "OtherHardware",
    "provider": "Microsoft",
    "setupInformationFile": null,
    "manufacturer": "Microsoft",
    "version": "1.0.0.1",
    "versionDateTime": "2021-01-11T02:43:14Z"

Approve driver content for deployment

Each driver update is associated with a unique catalog entry. Approve content for drivers and firmware by adding a content approval for the catalog entry to an existing policy. Content approval is a compliance change for the policy.

Important

Any deployment settings configured for the content approval will be combined with the existing update policy's deployment settings. If the content approval and update policy specify the same deployment setting, the setting from the content approval is used.

Add a content approval to an existing policy, Policy ID 9011c330-1234-5678-9abc-def012345678 for the driver update with the Catalog ID 5d6dede684ba5c4a731d62d9c9c2a99db12c5e6015e9f8ad00f3e9387c7f399c. Schedule the start date for February 14, 2023 at 1 AM UTC:

POST https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678/complianceChanges
content-type: application/json

{
    "@odata.type": "#microsoft.graph.windowsUpdates.contentApproval",
    "content": {
        "@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
        "catalogEntry": {
            "@odata.type": "#microsoft.graph.windowsUpdates.driverUpdateCatalogEntry",
            "id": "5d6dede684ba5c4a731d62d9c9c2a99db12c5e6015e9f8ad00f3e9387c7f399c"
        }
    },
    "deploymentSettings": {
        "@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
        "schedule": {
            "startDateTime": "2023-02-14T01:00:00Z"
        }
    }
}

The response for a content approval returns content and deployment settings along with an id, which is the Compliance Change ID. The Compliance Change ID is c03911a7-9876-5432-10ab-cdef98765432 in the following truncated response:

    "@odata.type": "#microsoft.graph.windowsUpdates.contentApproval",
    "id": "c03911a7-9876-5432-10ab-cdef98765432",
    "createdDateTime": "2023-02-02T17:54:39.173292Z",
    "isRevoked": false,
    "revokedDateTime": "0001-01-01T00:00:00Z",
    "content": {
        "@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
        "catalogEntry": {
            "@odata.type": "#microsoft.graph.windowsUpdates.driverUpdateCatalogEntry",
            "id": "5d6dede684ba5c4a731d62d9c9c2a99db12c5e6015e9f8ad00f3e9387c7f399c"
        }
    },
    "deploymentSettings": {
        "schedule": {
            "startDateTime": "2023-02-14T01:00:00Z",

Review all of the compliance changes to a policy with the most recent changes listed in the response first. The following example returns the compliance changes for a policy with the Policy ID 9011c330-1234-5678-9abc-def012345678 and sorts by createdDateTime in descending order:

GET https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678/complianceChanges?orderby=createdDateTime desc

Tip

There should only be one Compliance Change ID per Catalog ID for a policy. If there are multiple Compliance Change IDs for the same Catalog ID then, most likely, there's multiple deployments for the same piece of content targeted to the same audience but with different deployment behaviors. To remove the duplicate, delete the compliance change with the duplicate Catalog ID. Deleting the compliance change will mark any deployments created by the approval as archived.

To retrieve the deployment ID, use the expand parameter to review the deployment information related the content approval. The following example displays the content approval and the deployment information for Compliance Change ID c03911a7-9876-5432-10ab-cdef98765432 in update Policy ID 9011c330-1234-5678-9abc-def012345678:

GET https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678/complianceChanges/c03911a7-9876-5432-10ab-cdef98765432/$/microsoft.graph.windowsUpdates.contentApproval?$expand=deployments

Edit deployment settings for a content approval

Since content approval is a compliance change for the policy, when you update a content approval, you're editing the compliance change for the policy. The following example changes the startDateTime for the Compliance Change ID of c03911a7-9876-5432-10ab-cdef98765432 in the update Policy ID 9011c330-1234-5678-9abc-def012345678 to February 28, 2023 at 5 AM UTC:

PATCH https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678/complianceChanges/c03911a7-9876-5432-10ab-cdef98765432
content-type: application/json

{
    "@odata.type": "#microsoft.graph.windowsUpdates.contentApproval",
    "deploymentSettings": {
        "@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
        "schedule": {
            "startDateTime": "2023-02-28T05:00:00Z"
        }
    }
}

Revoke content approval

Approval for content can be revoked by setting the isRevoked property of the compliance change to true. This setting can be changed while a deployment is in progress. However, revoking will only 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.

PATCH https://graph.microsoft.com/beta/admin/windows/updates/updatePolicies/9011c330-1234-5678-9abc-def012345678/complianceChanges/c03911a7-9876-5432-10ab-cdef98765432
content-type: application/json

{
    "@odata.type": "#microsoft.graph.windowsUpdates.contentApproval",
    "isRevoked": true
}

To display all deployments with the most recently created returned first, order deployments based on the createdDateTime:

GET https://graph.microsoft.com/beta/admin/windows/updates/deployments?orderby=createdDateTime desc

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

Policy considerations for drivers

It's possible for the service to receive content approval but the content doesn't get installed on the device because of a Group Policy, CSP, or registry setting on the device. In some cases, organizations specifically configure these policies to fit their current or future needs. For instance, organizations may want to review applicable driver content, but not allow installation. Configuring this sort of behavior can be useful, especially when transitioning management of driver updates due to changing organizational needs. The following list describes driver related update policies that can affect deployments:

Policies that exclude drivers from Windows Update for a device

The following policies exclude drivers from Windows Update for a device:

  • Locations of policies that exclude drivers:
    • Group Policy: \Windows Components\Windows Update\Do not include drivers with Windows Updates set to enabled
    • CSP: ExcludeWUDriversInQualityUpdate set to 1
    • Registry: HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\ExcludeWUDriversFromQualityUpdates set to 1
    • Intune: Windows Drivers update setting for the update ring set to Block

Behavior: Devices with driver exclusion polices that are enrolled for drivers and added to an audience:

  • Will display the applicable driver content
  • Won't install drivers that are approved
    • If drivers are deployed to a device that's blocking them, Windows Autopatch displays the driver is being offered and reporting displays the install is pending.

Policies that define the source for driver updates

The following policies define the source for driver updates as either Windows Update or Windows Server Update Service (WSUS):

  • Locations of policies that define an update source:
    • Group Policy: \Windows Components\Windows Update\Manage updates offered from Windows Server Update Service\Specify source service for specific classes of Windows Updates set to enabled with the Driver Updates option set to Windows Update
    • CSP: SetPolicyDrivenUpdateSourceForDriverUpdates set to 0 for Windows Update as the source
    • Registry: HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\SetPolicyDrivenUpdateSourceForDriverUpdates set to 0. Under \AU, UseUpdateClassPolicySource also needs to be set to 1
    • Intune: Not applicable. Intune deploys updates using Windows Update for Business. Co-managed clients from Configuration Manager with the workload for Windows Update policies set to Intune will also use Windows Update for Business.

Behavior: Devices with these update source policies that are enrolled for drivers and added to an audience:

  • Will display the applicable driver content
  • Will install drivers that are approved

Note

When the scan source for drivers is set to WSUS, Windows Autopatch doesn't get inventory events from devices. This means that Windows Autopatch won't be able to report the applicability of a driver for the device.