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

Os controles programáticos do Windows Autopatch são usados para aprovar e agendar atualizações de software por meio da API do Graph. Você pode chamar a API diretamente, por meio de um SDK do Graph, ou integrá-la a uma ferramenta de gerenciamento, como o Microsoft Intune.

Este artigo usa o Graph Explorer para percorrer todo o processo de implantação de uma atualização de recurso para clientes. Neste artigo, você irá:

Neste artigo, você irá:

Pré-requisitos

Todos os pré-requisitos do Windows Autopatch devem ser atendidos .

Permissões

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

• WindowsUpdates.ReadWrite.All para operações do Windows Autopatch .
• Pelo menos a permissão Device.Read.All para exibir informações do dispositivo .

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.

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.

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.

   

• 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
  

Registrar dispositivos

Quando você registra dispositivos no gerenciamento de atualizações de recursos, o Windows Autopatch se torna a autoridade para atualizações de recursos provenientes do Windows Windows Update. Desde que um dispositivo permaneça registrado no gerenciamento de atualizações de recursos por meio do Windows Autopatch, o dispositivo não receberá nenhuma outra atualização de recursos do Windows Update, a menos que seja implantado explicitamente usando o Windows Autopatch. Um dispositivo recebe a atualização de recursos especificada se ainda não tiver recebido a atualização. Por exemplo, se você implantar a versão de atualização de recursos do Windows 11 22H2 em um dispositivo registrado no gerenciamento de atualizações de recursos e que esteja atualmente em uma versão mais antiga do Windows 11, o dispositivo será atualizado para a versão 22H2. Se o dispositivo já estiver executando a versão 22H2 ou uma versão posterior, ele permanecerá em sua versão atual.

Você registra dispositivos com base nos tipos de atualizações que deseja que eles recebam. Atualmente, você pode registrar dispositivos para receber atualizações de recursos (feature) ou drivers (driver). Você pode registrar dispositivos para receber atualizações de várias classificações de atualização.

1. Para registrar dispositivos, faça POST em updatableAssets usando enrollAssets. O exemplo a seguir registra três dispositivos para receber atualizações de driver:

   1. No Graph Explorer, selecione POST na lista suspensa para o verbo HTTP.

   2. Insira a seguinte solicitação no campo URL:
      https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/enrollAssets

   3. Na guia Corpo da solicitação , insira o seguinte JSON, fornecendo as seguintes informações:

      • ID do dispositivo do Microsoft Entra comoid
      • Um feature ou driver para o 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. Selecione o botão Executar consulta . Os resultados aparecerão na janela Resposta . Nesse caso, o código de status HTTP de 202 Accepted.

      

Listar entradas do catálogo para atualizações de recursos

Cada atualização de recurso está associada a uma entrada de catálogo exclusiva. A id retornada é a ID do Catálogo e é usada para criar uma implantação. As atualizações de recursos podem ser implantadas até atingirem as datas de desativação do suporte. Para obter mais informações, consulte as datas de ciclo de vida de suporte para as edições Windows 10 e Windows 11 Enterprise e Education. A consulta a seguir lista todas as entradas do catálogo de atualizações de recursos implantáveis:

GET https://graph.microsoft.com/beta/admin/windows/updates/catalog/entries?$filter=isof('microsoft.graph.windowsUpdates.featureUpdateCatalogEntry')

A resposta truncada a seguir exibe uma ID de catálogo para o Windows 11, atualização de d9049ddb-0ca8-4bc1-bd3c-41a456ef300f recursos versão 22H2:

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

Criar uma implantação

Ao criar uma implantação para uma atualização de recursos, há várias opções disponíveis para definir como a implantação se comporta. As configurações de implantação e monitoramento são opcionais. As seguintes configurações de implantação são definidas no corpo da solicitação de exemplo para implantar o Windows 11, atualização de recursos versão 22H2 (ID do catálogo ded9049ddb-0ca8-4bc1-bd3c-41a456ef300f):

• Data de início da implantação de 14 de fevereiro de 2023 às 5h UTC
• Distribuição gradual a uma taxa de 100 dispositivos a cada três dias
• Regra de monitoramento que pausa a implantação se cinco dispositivos reverterem a atualização do recurso
• Comportamento de retenção de proteção padrão de aplicar todas as proteções aplicáveis a dispositivos em uma implantação
  • Quando as retenções de proteção não são definidas explicitamente, o comportamento padrão de retenção de proteção é aplicado automaticamente

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

O corpo da resposta contém:

• A nova ID de Implantação, de910e12-3456-7890-abcd-ef1234567890 no exemplo

• A nova ID de Audiência, d39ad1ce-0123-4567-89ab-cdef01234567 no exemplo

• Todas as configurações definidas no corpo da solicitação de implantação

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

Editar uma implantação

Para atualizar a implantação, PATCH o recurso de implantação por sua ID de implantação e forneça as configurações atualizadas no corpo da solicitação. O exemplo a seguir mantém as configurações de distribuição gradual existentes que foram definidas ao criar a implantação, mas altera a data de início da implantação para 28 de fevereiro de 2023 às 5h 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"
            }
        }
    }
}

Verifique as configurações de implantação para a implantação com uma ID de implantação de de910e12-3456-7890-abcd-ef1234567890:

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

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. Enquanto a implantação existir e o dispositivo estiver na audiência, a atualização será oferecida.

O exemplo a seguir adiciona três dispositivos à audiência de 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"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
     "id": "01234567-89ab-cdef-0123-456789abcde1"
    }
  ]
}

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

Pausar uma implantação

Para pausar uma implantação, PATCH a implantação para ter um requestedValue de paused para o deploymentState. Para retomar a implantação, use o valor none e o estado será atualizado para offering ou scheduled se a implantação ainda não tiver atingido a data de início.

O exemplo a seguir pausa a implantação com uma ID de implantação de 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"
  }
}

Excluir uma implantação

Para remover completamente a implantação, EXCLUA-a. 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 precisa 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

Cancelar registro de dispositivos

Quando um dispositivo não exigir mais gerenciamento, cancele o registro no Windows Autopatch. Assim como registra um dispositivo, especifique um ou driverfeature como o valor para o updateCategory. O dispositivo não receberá mais atualizações do Windows Autopatch para a categoria de atualização especificada. Dependendo da configuração do dispositivo, ele pode começar a receber atualizações do Windows Update. Por exemplo, se um dispositivo ainda estiver registrado para atualizações de recursos, mas tiver sido cancelado dos drivers:

• As implantações de driver existentes do serviço não serão oferecidas ao dispositivo
• O dispositivo continua a receber atualizações de recursos do Windows Autopatch
• Os drivers podem começar a ser instalados a partir do Windows Update dependendo da configuração do dispositivo

Para cancelar o registro de um dispositivo, faça um POST em updatableAssets usando unenrollAssets. No corpo da solicitação, especifique:

• ID do dispositivo do Microsoft Entra como id para o dispositivo
• Um feature ou driver para o updateCategory

O exemplo a seguir remove o driver registro de dois dispositivos e01234567-89ab-cdef-0123-456789abcde0: 01234567-89ab-cdef-0123-456789abcdef

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