Implantar atualizações de recursos com o serviço de implantação do Windows Update for Business
O serviço de implantação do Windows Update for Business é usado para aprovar e agendar atualizações de software. O serviço de implantação expõe seus recursos por meio do Microsoft 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 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ê fará:
Neste artigo, você fará:
- Abrir Explorer do Graph
- Executar consultas para identificar dispositivos
- Registrar dispositivos
- Listar entradas de catálogo para atualizações de recursos
- Criar uma implantação
- Adicionar membros ao público de implantação
- Pausar uma implantação
- Excluir uma implantação
- Cancelar registro de dispositivos
Pré-requisitos
Todos os pré-requisitos para o serviço de implantação do Windows Update for Business devem ser atendidos.
Permissões
As seguintes permissões são necessárias para as consultas listadas neste artigo:
- Operações de serviço de implantação do WindowsUpdates.ReadWrite.Allfor Windows Update for Business.
- Pelo menos a permissão Device.Read.All para exibir informações do dispositivo .
Algumas funções, como o administrador de implantação Windows Update, já têm essas permissões.
Abrir Explorer do Graph
Para este artigo, você usará o Graph Explorer para fazer solicitações às APIs do Microsoft Graph para recuperar, adicionar, excluir e atualizar dados. Graph Explorer é uma ferramenta de desenvolvedor que permite que você aprenda sobre 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 entrar com uma conta do Microsoft 365. Se necessário, uma avaliação gratuita de um mês está disponível para Microsoft 365 Business Premium.
- Usar um locatário de teste para saber e verificar se o processo de implantação é altamente recomendado. O Explorer de grafo destina-se a ser uma ferramenta de aprendizado. Verifique se você entende a concessão de consentimento e o tipo de consentimento do Graph Explorer antes de prosseguir.
Em um navegador, acesse Graph Explorer e entre usando uma conta de usuário Microsoft Entra.
Talvez seja necessário habilitar a
WindowsUpdates.ReadWrite.Allpermissão para usar as consultas neste artigo. Para habilitar a permissão:Selecione a guia Modificar permissões no Graph Explorer.
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 o consentimento.
Para fazer solicitações:
- Selecione GET, POST, PUT, PATCH ou DELETE na lista suspensa para o método HTTP.
- Insira a solicitação no campo URL. A versão será preenchida automaticamente com base na URL.
- Se você precisar modificar o corpo da solicitação, edite a guia Solicitar corpo .
- Selecione o botão Executar consulta . Os resultados serão exibidos na janela Resposta .
Dica
Ao revisar a documentação do Microsoft Graph, você pode notar que as solicitações de exemplo geralmente listam
content-type: application/json. Especificarcontent-typenormalmente não é necessário para o Graph Explorer, mas você pode adicioná-lo à solicitação selecionando a guia Cabeçalhos e adicionando ocontent-typeao campo Cabeçalhos de Solicitação como a Chave eapplication/jsoncomo o Valor.
Executar consultas para identificar dispositivos
Use o tipo de recurso do dispositivo para encontrar clientes para se registrar no serviço de implantação. 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,displayNameExibe a ID e o nome do dispositivo do AzureAD 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 avançados de consulta, consulte Recursos avançados de consulta em Microsoft Entra objetos de diretório.
No Graph Explorer, selecione a guia Cabeçalhos de solicitação.
Para tipo de chave dentro
ConsistencyLevele para Valor, digiteeventual.Selecione o botão Adicionar . Quando terminar, remova o cabeçalho da solicitação selecionando o ícone lixeira.
Exiba a versão nome e sistema operacional do dispositivo que tem
01234567-89ab-cdef-0123-456789abcdefcomo ID do dispositivo do AzureAD:GET https://graph.microsoft.com/v1.0/devices?$search="deviceid:01234567-89ab-cdef-0123-456789abcdef"&$select=displayName,operatingSystemVersionPara encontrar dispositivos que provavelmente não são máquinas virtuais, filtre para dispositivos que não têm máquina virtual listada como modelo, mas têm um fabricante listado. Exiba a versão do sistema operacional, nome e ID do dispositivo do AzureAD 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 do dispositivo normalmente têm um id e um deviceid:
- O
deviceidé o Microsoft Entra ID do dispositivo e será usado neste artigo.- Posteriormente neste artigo, isso
deviceidserá usado como umidquando você fizer determinadas solicitações, como adicionar um dispositivo a um público-alvo de implantação.
- Posteriormente neste artigo, isso
- O
iddo tipo de recurso do dispositivo geralmente é a ID do objeto Microsoft Entra, que não será usada neste artigo.
Registrar dispositivos
Quando você registra dispositivos no gerenciamento de atualização de recursos, o serviço de implantação se torna a autoridade para atualizações de recursos provenientes de Windows Update. Enquanto um dispositivo permanecer registrado no gerenciamento de atualização de recursos por meio do serviço de implantação, o dispositivo não recebe nenhuma outra atualização de recurso do Windows Update a menos que seja implantado explicitamente usando o serviço de implantação. Um dispositivo será oferecido a atualização de recurso especificada se ele ainda não tiver recebido a atualização. Por exemplo, se você implantar Windows 11 atualização de recursos versão 22H2 em um dispositivo registrado no gerenciamento de atualização de recursos e estiver 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.
Dica
Windows Update para relatórios empresariais tem uma pasta de trabalho que exibe a versão atual do sistema operacional para dispositivos. Na pasta de trabalho, acesse a guia Atualizações de recursos e, no bloco de atualização de recursos no serviço , selecione o link Exibir detalhes para abrir o flyout de detalhes. A versão do sistema operacional e o Microsoft Entra ID de dispositivos podem ser facilmente exportados para um arquivo .csv ou abertos nos Logs do Azure Monitor para ajudar na criação de um público de implantação.
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.
- Para registrar dispositivos, POST para updatableAssets usando registrAssets. O exemplo a seguir registra três dispositivos para receber atualizações do driver:
No Graph Explorer, selecione POST na lista suspensa para o verbo HTTP.
Insira a seguinte solicitação no campo URL:
https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/enrollAssetsNa guia Corpo da solicitação , insira o seguinte JSON, fornecendo as seguintes informações:
- Microsoft Entra ID do dispositivo como
id - Ou
featuredriverpara a atualizaçãoCategory
{ "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" } ] }- Microsoft Entra ID do dispositivo como
Selecione o botão Executar consulta . Os resultados serão exibidos na janela Resposta . Nesse caso, o código http status de
202 Accepted.
Listar entradas de catálogo para atualizações de recursos
Cada atualização de recurso está associada a uma entrada de catálogo exclusiva. O id retornado é a ID do Catálogo e é usado para criar uma implantação. As atualizações de recursos são implantáveis até atingirem as datas de aposentadoria de suporte. Para obter mais informações, confira as datas do ciclo de vida de suporte para 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 do Catálogo da atualização de d9049ddb-0ca8-4bc1-bd3c-41a456ef300f recursos do 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 implantação
Ao criar uma implantação para uma atualização de recurso, 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 a atualização de recurso Windows 11 versão 22H2 (ID do catálogo de d9049ddb-0ca8-4bc1-bd3c-41a456ef300f):
- Data de início da implantação de 14 de fevereiro de 2023 às 5:00 UTC
- Distribuição gradual a uma taxa de 100 dispositivos a cada três dias
- Regra de monitoramento que pausará a implantação se cinco dispositivos reverterem a atualização do recurso
- Comportamento padrão de retenção de proteção da aplicação de 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 conterá:
A nova ID de Implantação,
de910e12-3456-7890-abcd-ef1234567890no exemploA nova ID de Audiência,
d39ad1ce-0123-4567-89ab-cdef01234567no exemploQuaisquer 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 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 configurações de implantação da 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 de implantação
A ID de Audiência, d39ad1ce-0123-4567-89ab-cdef01234567, foi criada quando a implantação foi criada. A ID de Audiência é usada para adicionar membros ao público de implantação. Depois que o público de implantação é atualizado, 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 ao público 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 ao público-alvo, 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 chegado à 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 a implantação completamente, EXCLUA a implantação. A exclusão da implantação impedirá que o conteúdo seja oferecido aos dispositivos se eles ainda não o receberem. Para retomar a oferta do conteúdo, uma nova aprovação precisará 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 precisar mais de gerenciamento, desmarcam-no do serviço de implantação. Assim como registrar um dispositivo, especifique driver ou feature como o valor para o updateCategory. O dispositivo não receberá mais atualizações do serviço de implantação para a categoria de atualização especificada. Dependendo da configuração do dispositivo, ele pode começar a receber atualizações de Windows Update. Por exemplo, se um dispositivo ainda estiver registrado para atualizações de recursos, mas ele não for registrado de drivers:
- As implantações de driver existentes do serviço não serão oferecidas ao dispositivo
- O dispositivo continua recebendo atualizações de recursos do serviço de implantação
- Os drivers podem começar a ser instalados a partir de Windows Update dependendo da configuração do dispositivo
Para desativar um dispositivo, POST para updatableAssets usando unenrollAssets. No corpo da solicitação, especifique:
- Microsoft Entra ID do dispositivo quanto
idao dispositivo - Ou
featuredriverpara a atualizaçãoCategory
O exemplo a seguir remove o driver registro 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"
}
]
}
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de