Programmatic controls for expedited Windows quality updates

Bài viết
09/24/2024
Áp dụng cho:

✅ Windows 11, ✅ Windows 10

In this article, you will:

Open Graph Explorer
Run queries to identify test devices
List catalog entries for expedited updates
Create a deployment
Add members to the deployment audience
Delete a deployment

Prerequisites

All of the Windows Autopatch prerequisites 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 Autopatch operations.
At least Device.Read.All permission to display device information.

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.

From a browser, go to Graph Explorer and sign in using a Microsoft Entra user account.
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.
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.

In Graph Explorer, select the Request headers tab.
For Key type in ConsistencyLevel and for Value, type eventual.
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-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.

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 Windows Autopatch. 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"
                    }
                ]
            }
        }
    ]
}

Windows Autopatch 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-ef1234567890 of the newly created deployment.
The Audience ID d39ad1ce-0123-4567-89ab-cdef01234567 of 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 .etl format.
- Microsoft offers PerfView as a download on GitHub, which displays .etl files.

For more information, see Troubleshooting expedited updates.

Chia sẻ qua