Compartilhar via

Controlos programáticos para atualizações de funcionalidades do Windows

Importante

As informações na secção aplicam-se às licenças Business Premium, A3+, E3+ e F3. Para obter mais informações, veja Funcionalidades e capacidades e Licenças e elegibilidades.

Os controlos programáticos do Windows Autopatch são utilizados para aprovar e agendar atualizações de software através do Microsoft API do Graph. Pode chamar a API diretamente, através de um SDK do Graph, ou integrá-la numa ferramenta de gestão, como Microsoft Intune.

Este artigo utiliza o Graph Explorer para percorrer todo o processo de implementação de uma atualização de funcionalidades nos clientes. Neste artigo, irá:

Neste artigo, irá:

Pré-requisitos

Todos os pré-requisitos do Windows Autopatch têm de ser cumpridos.

Permissões

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

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

Pontos finais necessários

Tem de ter acesso aos seguintes pontos finais:

Windows Update pontos finais

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

API do Graph pontos finais:

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

Abrir o Graph Explorer

Para este artigo, irá utilizar o Graph Explorer para fazer pedidos às APIs do Microsoft Graph para obter, adicionar, eliminar e atualizar dados. O Graph Explorer é uma ferramenta de programador que lhe permite saber mais sobre as APIs do Microsoft Graph. Para obter mais informações sobre como utilizar o Graph Explorer, consulte Introdução ao Graph Explorer.

Aviso

  • Os pedidos listados neste artigo requerem o início de sessão com uma conta do Microsoft 365. Se necessário, está disponível uma avaliação gratuita de um mês para Microsoft 365 Business Premium.
  • Utilizar um inquilino de teste para aprender e verificar se o processo de implementação é altamente recomendado. O Graph Explorer destina-se a ser uma ferramenta de aprendizagem. Certifique-se de que compreende a concessão de consentimento e o tipo de consentimento do Graph Explorer antes de continuar.

  1. Num browser, aceda ao Graph Explorer e inicie sessão com uma conta de utilizador Microsoft Entra.

  2. Poderá ter de ativar a WindowsUpdates.ReadWrite.All permissão para utilizar as consultas neste artigo. Para ativar a permissão:

    1. Selecione o separador Modificar permissões no Graph Explorer.
    2. Na caixa de diálogo permissões, selecione a permissão WindowsUpdates.ReadWrite.All e, em seguida, selecione Consentimento. Poderá ter de iniciar sessão novamente para conceder consentimento. Captura de ecrã do separador Modificar permissões no Graph Explorer

  3. Para fazer pedidos:

    1. Selecione GET, POST, PUT, PATCH ou DELETE na lista pendente do método HTTP.
    2. Introduza o pedido no campo URL. A versão será preenchido automaticamente com base no URL.
    3. Se precisar de modificar o corpo do pedido, edite o separador Corpo do pedido.
    4. Selecione o botão Executar consulta . Os resultados serão apresentados na janela Resposta .

    Dica

    Ao rever a documentação do Microsoft Graph, poderá reparar que os pedidos de exemplo normalmente listam content-type: application/json. Especificar content-type normalmente não é necessário para o Graph Explorer, mas pode adicioná-lo ao pedido selecionando o separador Cabeçalhos e adicionando o content-type ao campo Cabeçalhos de pedido como a Chave e application/json como o Valor.

Executar consultas para identificar dispositivos

Utilize o tipo de recurso do dispositivo para localizar clientes para se inscreverem no Windows Autopatch. Altere os parâmetros de consulta de acordo com as suas necessidades específicas. Para obter mais informações, veja Utilizar parâmetros de consulta.

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

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

  • Apresenta o ID do Dispositivo do AzureAD e o Nome dos dispositivos que têm um nome a começar por Test:

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

Adicionar um cabeçalho de pedido para consultas avançadas

Para os próximos pedidos, defina o cabeçalho ConsistencyLevel como eventual. Para obter mais informações sobre parâmetros de consulta avançados, veja Advanced query capabilities on Microsoft Entra directory objects (Capacidades de consulta avançadas em objetos de diretório Microsoft Entra).

  1. No Graph Explorer, selecione o separador Cabeçalhos do pedido.

  2. Para Tipo de chave em ConsistencyLevel e para Valor, escreva eventual.

  3. Selecione o botão Adicionar . Quando tiver terminado, remova o cabeçalho do pedido ao selecionar o ícone do caixote do lixo.

    Captura de ecrã do separador cabeçalhos de pedido no Graph Explorer

  • Apresentar o Nome e a versão do sistema operativo do dispositivo que tem 01234567-89ab-cdef-0123-456789abcdef como ID de Dispositivo do 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 tenham máquinas virtuais listadas como modelo, mas que tenham um fabricante listado. Apresentar o ID do Dispositivo do AzureAD, o Nome e a versão do sistema operativo 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

Normalmente, os pedidos que utilizam o tipo de recurso do dispositivo têm um id e um deviceid:

  • O deviceid é o Microsoft Entra ID do Dispositivo e será utilizado neste artigo.
    • Mais adiante neste artigo, será deviceid utilizado como um id quando efetuar determinados pedidos, como adicionar um dispositivo a uma audiência de implementação.
  • Normalmenteid, o do tipo de recurso do dispositivo é o Microsoft Entra ID do Objeto, que não será utilizado neste artigo.

Registrar dispositivos

Quando inscreve dispositivos na gestão de atualizações de funcionalidades, o Windows Autopatch torna-se a autoridade para atualizações de funcionalidades provenientes de Windows Update. Desde que um dispositivo permaneça inscrito na gestão de atualizações de funcionalidades através do Windows Autopatch, o dispositivo não recebe quaisquer outras atualizações de funcionalidades de Windows Update a menos que seja explicitamente implementado com o Windows Autopatch. É disponibilizada a atualização de funcionalidades especificada a um dispositivo se ainda não tiver recebido a atualização. Por exemplo, se implementar Windows 11 atualização de funcionalidades versão 22H2 num dispositivo inscrito na gestão de atualizações de funcionalidades e estiver atualmente numa versão mais antiga do Windows 11, o dispositivo é atualizado para a versão 22H2. Se o dispositivo já estiver a executar a versão 22H2 ou posterior, este permanecerá na versão atual.

Dica

Windows Update para Empresas tem um livro que apresenta a versão atual do sistema operativo para dispositivos. No livro, aceda ao separador Atualizações de funcionalidades e, no mosaico Atualização de funcionalidades no Serviço , selecione a ligação Ver detalhes para abrir a lista de opções de detalhes. A versão do SO e Microsoft Entra ID de dispositivos podem ser facilmente exportados para um ficheiro .csv ou abertos nos Registos do Azure Monitor para ajudar na criação de uma audiência de implementação.

Inscreve dispositivos com base nos tipos de atualizações que pretende que recebam. Atualmente, pode inscrever dispositivos para receber atualizações de funcionalidades (feature) ou controladores (driver). Pode inscrever dispositivos para receber atualizações de várias classificações de atualizações.

  1. Para inscrever dispositivos, post to updatableAssets using enrollAssets. O exemplo seguinte inscreve três dispositivos para receber atualizações do controlador:

    1. No Graph Explorer, selecione POST na lista pendente do verbo HTTP.

    2. Introduza o seguinte pedido no campo URL:
      https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/enrollAssets

    3. No separador Corpo do pedido , introduza o seguinte JSON, fornecendo as seguintes informações:

      • Microsoft Entra ID do Dispositivo comoid
      • driver Ou feature para 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 serão apresentados na janela Resposta . Neste caso, o http status código de 202 Accepted.

      Captura de ecrã a mostrar a inscrição com êxito de recursos através do Graph Explorer.

Listar entradas de catálogo para atualizações de funcionalidades

Cada atualização de funcionalidades está associada a uma entrada de catálogo exclusiva. O id devolvido é o ID do Catálogo e é utilizado para criar uma implementação. As atualizações de funcionalidades são implementáveis até atingirem as datas de descontinuação do suporte. Para obter mais informações, veja as datas de ciclo de vida do suporte para as edições Windows 10 e Windows 11 Enterprise e Education. A consulta seguinte lista todas as entradas de catálogo de atualização de funcionalidades implementáveis:

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

A seguinte resposta truncada apresenta um ID de Catálogo de para a atualização de d9049ddb-0ca8-4bc1-bd3c-41a456ef300f funcionalidades Windows 11, 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 implementação

Ao criar uma implementação para uma atualização de funcionalidades, existem várias opções disponíveis para definir o comportamento da implementação. As definições de implementação e monitorização são opcionais. As seguintes definições de implementação são definidas no corpo do pedido de exemplo para implementar a atualização de funcionalidades Windows 11, versão 22H2 (ID do Catálogo de d9049ddb-0ca8-4bc1-bd3c-41a456ef300f):

  • Data de início da implementação de 14 de fevereiro de 2023 às 5:00 UTC
  • Implementação gradual a um ritmo de 100 dispositivos a cada três dias
  • Regra de monitorização que interrompe a implementação se cinco dispositivos reverterem a atualização de funcionalidades
  • Comportamento de suspensão de salvaguarda predefinido da aplicação de todas as salvaguardas aplicáveis aos dispositivos numa implementação
    • Quando as suspensões de salvaguarda não são explicitamente definidas, o comportamento de suspensão de salvaguarda predefinido é 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:

  • O novo ID de Implementação, de910e12-3456-7890-abcd-ef1234567890 no exemplo

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

  • Quaisquer definições definidas no corpo do pedido de implementaçã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 implementação

Para atualizar a implementação, a aplicação PATCH do recurso de implementação através do ID de Implementação fornece as definições atualizadas no corpo do pedido. O exemplo seguinte mantém as definições de implementação gradual existentes que foram definidas ao criar a implementação, mas altera a data de início da implementação para 28 de fevereiro de 2023 às 5:00 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 definições de implementação da implementação com um ID de Implementação do de910e12-3456-7890-abcd-ef1234567890:

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

Adicionar membros à audiência de implementação

O ID da Audiência, d39ad1ce-0123-4567-89ab-cdef01234567, foi criado quando a implementação foi criada. O ID de Audiência é utilizado para adicionar membros à audiência de implementação. Após a atualização da audiência de implementação, Windows Update começa a oferecer a atualização aos dispositivos de acordo com as definições de implementação. Desde que a implementação exista e o dispositivo esteja na audiência, a atualização é disponibilizada.

O exemplo seguinte adiciona três dispositivos à audiência de implementação através do 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 com o 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

Colocar uma implementação em pausa

Para colocar uma implementação em pausa, patch a implementação para ter uma requestedValue de paused para deploymentState. Para retomar a implementação, utilize o valor none e o estado será atualizado para offering ou scheduled se a implementação ainda não atingiu a data de início.

O exemplo seguinte coloca a implementação em pausa com um ID de Implementação do 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"
  }
}

Eliminar uma implementação

Para remover completamente a implementação, elimine a implementação. Eliminar a implementação impede que os conteúdos sejam oferecidos aos dispositivos se ainda não o tiverem recebido. Para retomar a oferta do conteúdo, é necessário criar uma nova aprovação.

O exemplo seguinte elimina a implementação com um ID de Implementação do 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 já não precisar de gestão, anula-o no Windows Autopatch. Tal como a inscrição de um dispositivo, especifique ou driverfeature como o valor do updateCategory. O dispositivo deixará de receber atualizações do Windows Autopatch para a categoria de atualização especificada. Consoante a configuração do dispositivo, poderá começar a receber atualizações de Windows Update. Por exemplo, se um dispositivo ainda estiver inscrito para atualizações de funcionalidades, mas não estiver inscrito nos controladores:

  • As implementações de controladores existentes do serviço não serão oferecidas ao dispositivo
  • O dispositivo continua a receber atualizações de funcionalidades do Windows Autopatch
  • Os controladores podem começar a ser instalados a partir de Windows Update consoante a configuração do dispositivo

Para anular a inscrição de um dispositivo, POST para updatableAssets com unenrollAssets. No corpo do pedido, especifique:

  • Microsoft Entra ID do Dispositivo como id para o dispositivo
  • driver Ou feature para updateCategory

O exemplo seguinte remove a driver inscrição de dois dispositivos 01234567-89ab-cdef-0123-456789abcdef e 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"
    }
  ]
}