Controles programáticos para atualizações de qualidade aceleradas do Windows

Neste artigo, você irá:

Pré-requisitos

Todos os pré-requisitos do Windows Autopatch devem ser atendidos , incluindo garantir que as Ferramentas de Integridade de Atualização estejam instaladas nos clientes.

Importante

Esta etapa não é necessária se o seu dispositivo estiver executando o Windows 11 24H2 e posterior.

  • As Ferramentas de Integridade de Atualização são instaladas a partir do KB4023057. Para confirmar a presença das Ferramentas de Integridade de Atualização em um dispositivo, use um dos seguintes métodos:
    • Executar um teste de preparação para atualizações aceleradas
    • Procure a pasta C:\Program Files\Microsoft Update Health Tools ou examine Adicionar Remover programas para as Ferramentas de Integridade do Microsoft Update.
    • Exemplo de script do PowerShell para verificar a instalação de ferramentas: Get-CimInstance -ClassName Win32_Product \| Where-Object {$_.Name -match "Microsoft Update Health Tools"}

Permissões

As seguintes permissões são necessárias para as consultas listadas neste artigo:

Algumas funções, como o administrador de implantação do Windows Update, já têm essas permissões.

Pontos de extremidade necessários

Você deve ter acesso aos seguintes pontos de extremidade:

Pontos de extremidade do Windows Update

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

Pontos de extremidade da API do Graph:

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

Abra o Graph Explorer

Para este artigo, você usará o Graph Explorer para fazer solicitações às APIs do Microsoft Graph para recuperar, adicionar, excluir e atualizar dados. O Graph Explorer é uma ferramenta de desenvolvedor que permite que você saiba mais sobre as APIs do Microsoft Graph. Para obter mais informações sobre como usar o Graph Explorer, consulte Introdução ao Graph Explorer.

Aviso

  • As solicitações listadas neste artigo exigem a entrada com uma conta do Microsoft 365. Se necessário, uma avaliação gratuita de um mês está disponível para o Microsoft 365 Business Premium.
  • É altamente recomendável usar um locatário de teste para aprender e verificar o processo de implantação. O Graph Explorer pretende ser uma ferramenta de aprendizado. Certifique-se de entender a concessão de consentimento e o tipo de consentimento para o Graph Explorer antes de continuar.

  1. Em um navegador, acesse o Graph Explorer e entre usando uma conta de usuário do Microsoft Entra.

  2. Talvez seja necessário habilitar a WindowsUpdates.ReadWrite.All permissão para usar as consultas neste artigo. Para habilitar a permissão:

    1. Selecione a guia Modificar permissões no Graph Explorer.
    2. Na caixa de diálogo permissões, selecione a permissão WindowsUpdates.ReadWrite.All e selecione Consentimento. Talvez seja necessário entrar novamente para conceder consentimento. Captura de tela da guia modificar permissões no Graph Explorer

  3. Para fazer solicitações:

    1. Selecione GET, POST, PUT, PATCH ou DELETE na lista suspensa do método HTTP.
    2. Insira a solicitação no campo URL. A versão será preenchida automaticamente com base na URL.
    3. Se você precisar modificar o corpo da solicitação, edite a guia Corpo da solicitação .
    4. Selecione o botão Executar consulta . Os resultados aparecerão na janela Resposta .

    Dica

    Ao revisar a documentação do Microsoft Graph, você pode observar que as solicitações de exemplo geralmente listam content-type: application/json. A especificação content-type normalmente não é necessária para o Graph Explorer, mas você pode adicioná-lo à solicitação selecionando a guia Cabeçalhos e adicionando-o content-type ao campo Cabeçalhos da solicitação como a Chave e application/json como o Valor.

Executar consultas para identificar dispositivos

Use o tipo de recurso de dispositivo para localizar clientes para registrar no Windows Autopatch. Altere os parâmetros de consulta para atender às suas necessidades específicas. Para obter mais informações, consulte Usar parâmetros de consulta.

  • Exibe a ID do Dispositivo do AzureAD e o Nome de todos os dispositivos:

    GET https://graph.microsoft.com/v1.0/devices?$select=deviceid,displayName

  • Exibe a ID do dispositivo AzureAD e o nome para dispositivos que têm um nome começando com Test:

    GET https://graph.microsoft.com/v1.0/devices?$filter=startswith(displayName,'Test')&$select=deviceid,displayName

Adicionar um cabeçalho de solicitação para consultas avançadas

Para as próximas solicitações, defina o cabeçalho ConsistencyLevel como eventual. Para obter mais informações sobre parâmetros de consulta avançados, consulte Recursos avançados de consulta em objetos de diretório do Microsoft Entra.

  1. No Graph Explorer, selecione a guia Cabeçalhos de solicitação.

  2. Para Chave , digite e ConsistencyLevel para Valor, digite eventual.

  3. Selecione o botão Adicionar . Quando terminar, remova o cabeçalho da solicitação selecionando o ícone de lixeira.

    Captura de tela da guia cabeçalhos de solicitação no Graph Explorer

  • Exiba o Nome e a versão do sistema operacional para o dispositivo que tem 01234567-89ab-cdef-0123-456789abcdef como a ID do Dispositivo AzureAD:

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

  • Para localizar dispositivos que provavelmente não são máquinas virtuais, filtre por dispositivos que não têm a máquina virtual listada como o modelo, mas têm um fabricante listado. Exiba a ID do dispositivo AzureAD, o nome e a versão do sistema operacional para cada dispositivo:

    GET https://graph.microsoft.com/v1.0/devices?$filter=model ne 'virtual machine' and NOT(manufacturer eq null)&$count=true&$select=deviceid,displayName,operatingSystemVersion

Dica

As solicitações que usam o tipo de recurso de dispositivo normalmente têm um id e um deviceid:

  • É deviceid a ID do dispositivo do Microsoft Entra e será usada neste artigo.
    • Adiante neste artigo, isso deviceid será usado como quando id você fizer determinadas solicitações, como adicionar um dispositivo a um público-alvo de implantação.
  • O id tipo de recurso do dispositivo geralmente é a ID do Objeto do Microsoft Entra, que não será usada neste artigo.

Listar entradas do catálogo para atualizações aceleradas

Cada atualização está associada a uma entrada de catálogo exclusiva. Você pode consultar o catálogo para encontrar atualizações que possam ser aceleradas. A id retornada é a ID do Catálogo e é usada para criar uma implantação. A consulta a seguir lista todas as atualizações de qualidade, relacionadas ou não à segurança , que podem ser implantadas como atualizações aceleradas pelo Windows Autopatch. Usar $top=2 e ordenar por ReleaseDateTimeshows exibe as atualizações mais recentes que podem ser implantadas conforme acelerada.

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

A seguinte resposta truncada exibe uma ID de catálogo para a 08/08/2023 - 2023.08 B SecurityUpdate for Windows 10 and later atualização de e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5 segurança:

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

O Windows Autopatch pode exibir mais informações sobre atualizações lançadas em ou após janeiro de 2023. O uso da revisão do produto fornece informações adicionais sobre as atualizações, como os números de KB e o MajorVersion.MinorVersion.BuildNumber.UpdateBuildRevision. O Windows 10 e o 11 compartilham as mesmas versões principais e secundárias, mas têm números de build diferentes.

Use o seguinte para exibir as informações de revisão do produto para a atualização de qualidade mais recente:

GET https://graph.microsoft.com/beta/admin/windows/updates/catalog/entries?$expand=microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/productRevisions&$orderby=releaseDateTime desc&$top=1

A resposta truncada a seguir exibe informações sobre o KB5029244 para Windows 10, versão 22H2, e KB5029263 para Windows 11, versão 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"
                    }
                },

Criar uma implantação

Ao criar uma implantação, há várias opções disponíveis para definir como a implantação se comporta. O exemplo a seguir cria uma implantação para a atualização de segurança com a 08/08/2023 - 2023.08 B SecurityUpdate for Windows 10 and later ID e317aa8a0455ca604de95329b524ec921ca57f2e6ed3ff88aac757a7468998a5de entrada de catálogo e define as opções de implantação no userExperience corpo da expedite solicitação.

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

A solicitação retorna um código de resposta 201 Created e um objeto de implantação no corpo da resposta para a implantação recém-criada, que inclui:

  • A IDde910e12-3456-7890-abcd-ef1234567890 de implantação da implantação recém-criada.
  • A IDd39ad1ce-0123-4567-89ab-cdef01234567 de audiência da audiência de implantação recém-criada.
{
    "@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": []
    }
}

Adicionar membros ao público-alvo de implantação

A ID de Audiência, d39ad1ce-0123-4567-89ab-cdef01234567, foi criada quando a implantação foi criada. A ID da Audiência é usada para adicionar membros à audiência de implantação. Depois que o público-alvo da implantação é atualizado, o Windows Update começa a oferecer a atualização para os dispositivos de acordo com as configurações de implantação. Desde que a implantação exista e o dispositivo esteja na audiência, a atualização será acelerada.

O exemplo a seguir adiciona dois dispositivos ao público-alvo da implantação usando o Microsoft Entra ID para cada dispositivo:

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

Para verificar se os dispositivos foram adicionados à audiência, execute a seguinte consulta usando a ID de audiência de d39ad1ce-0123-4567-89ab-cdef01234567:

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

Excluir uma implantação

Para interromper uma implantação acelerada, EXCLUA a implantação. Excluir a implantação impede que o conteúdo seja oferecido a dispositivos se eles ainda não o tiverem recebido. Para retomar a oferta do conteúdo, uma nova aprovação deve ser criada.

O exemplo a seguir exclui a implantação com uma ID de implantação de de910e12-3456-7890-abcd-ef1234567890:

DELETE https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890

Teste de prontidão para acelerar as atualizações

Você pode verificar a prontidão dos clientes para receber atualizações aceleradas usando isReadinessTest. Crie uma implantação que especifique que é um teste de preparação rápida e adicione membros ao público-alvo da implantação. O serviço verifica se os clientes atendem aos pré-requisitos para acelerar as atualizações. Os resultados do teste são exibidos na pasta de trabalho de relatórios do Windows Update para Empresas. Na guia Atualizações de qualidade, selecione o bloco de status Acelerar, que abre um submenu com uma guia Prontidão com os resultados do teste de preparação.

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

A resposta truncada exibe que isReadinessTest está definido como true e fornece um DeploymentID de de910e12-3456-7890-abcd-ef1234567890. Em seguida, você pode adicionar membros ao público-alvo da implantação para que o serviço marcar se os dispositivos atendem às pré-requisitos e, em seguida, examine os resultados na pasta de trabalho de relatórios do Windows Update para Empresas.

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

Local do log para as Ferramentas de Integridade de Atualização

As Ferramentas de Integridade de Atualização são usadas quando você implanta atualizações aceleradas. Em alguns casos, talvez você queira examinar os logs para as Ferramentas de Integridade de Atualização.

Local do log: %ProgramFiles%\Microsoft Update Health Tools\Logs

Para obter mais informações, consulte Solução de problemas de atualizações aceleradas.

  • Last updated on