mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-11 04:47:23 +00:00

tiaraquan 2d10e02480 Autopatch NFA release

2025-03-26 15:13:51 -07:00

17 KiB

Raw Blame History

title, titleSuffix, description, ms.service, ms.subservice, ms.topic, author, ms.author, manager, ms.collection, ms.localizationpriority, appliesto, ms.date

title

titleSuffix

description

ms.service

ms.subservice

ms.topic

author

ms.author

manager

ms.collection

ms.localizationpriority

appliesto

ms.date

Programmatic controls for drivers and firmware

Windows Autopatch

Use programmatic controls to deploy driver and firmware updates to devices.

windows-client

autopatch

how-to

tiaraquan

aaroncz

tier1

medium

✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 11</a>

✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Windows 10</a>

03/31/2025

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:

[!div class="checklist"]

Open Graph Explorer

Run queries to identify devices

Enroll devices

Create a deployment audience and add audience members

Create an update policy

Review applicable driver content

Approve driver content for deployment

Revoke content approval

Unenroll devices

Prerequisites

All of the Windows Autopatch prerequisites must be met.

Permissions

[!INCLUDE Windows Autopath permissions using Graph Explorer]

Required endpoints

[!INCLUDE windows-autopatch-required-graph-api-endpoints]

Open Graph Explorer

[!INCLUDE Graph Explorer sign in]

Run queries to identify devices

[!INCLUDE Graph Explorer device queries]

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.

[!INCLUDE Graph Explorer enroll devices]

Create a deployment audience and add audience members

[!INCLUDE Graph Explorer enroll devices]

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:

Specify the Audience ID as id
Define any deployment settings.
Add the content-length header to the request if a status code of 411 occurs. The value should be the length of the request body in bytes. For information on error codes, see Microsoft Graph error responses and resource types.

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

[!INCLUDE Graph Explorer unenroll devices]

Policy considerations for drivers

[!INCLUDE Windows Autopatch driver policy considerations]

17 KiB Raw Blame History