Controlli a livello di codice per gli aggiornamenti delle funzionalità di Windows

Articolo
09/25/2024
Si applica a:

✅ Windows 11, ✅ Windows 10

Importante

Le informazioni nella sezione si applicano alle licenze Business Premium, A3+, E3+ e F3. Per altre informazioni, vedere Funzionalità e funzionalità e Licenze e diritti.

I controlli programmatici di Windows Autopatch vengono usati per approvare e pianificare gli aggiornamenti software tramite Microsoft API Graph. È possibile chiamare direttamente l'API tramite Graph SDK o integrarli con uno strumento di gestione come Microsoft Intune.

Questo articolo usa Graph Explorer per esaminare l'intero processo di distribuzione di un aggiornamento delle funzionalità ai client. In questo articolo si vedrà come:

In questo articolo si vedrà come:

Aprire Graph Explorer
Eseguire query per identificare i dispositivi
Registrare i dispositivi
Elencare le voci del catalogo per gli aggiornamenti delle funzionalità
Creare una distribuzione
Aggiungere membri al gruppo di destinatari della distribuzione
Sospendere una distribuzione
Eliminare una distribuzione
Annulla la registrazione dei dispositivi

Prerequisiti

Tutti i prerequisiti di Windows Autopatch devono essere soddisfatti.

Autorizzazioni

Per le query elencate in questo articolo sono necessarie le autorizzazioni seguenti:

WindowsUpdates.ReadWrite.All per le operazioni di creazione automatica di pacchetti di Windows.
Almeno l'autorizzazione Device.Read.All per visualizzare le informazioni sul dispositivo .

Alcuni ruoli, ad esempio l'amministratore della distribuzione Windows Update, dispongono già di queste autorizzazioni.

Endpoint necessari

È necessario avere accesso agli endpoint seguenti:

endpoint 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

API Graph endpoint:

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

Aprire Graph Explorer

Per questo articolo si userà Graph Explorer per inviare richieste alle API Microsoft Graph per recuperare, aggiungere, eliminare e aggiornare i dati. Graph Explorer è uno strumento per sviluppatori che consente di ottenere informazioni sulle API Microsoft Graph. Per altre informazioni sull'uso di Graph Explorer, vedere Introduzione a Graph Explorer.

Warning

Le richieste elencate in questo articolo richiedono l'accesso con un account Microsoft 365. Se necessario, è disponibile una versione di valutazione gratuita di un mese per Microsoft 365 Business Premium.
È consigliabile usare un tenant di test per apprendere e verificare il processo di distribuzione. Graph Explorer è progettato per essere uno strumento di apprendimento. Assicurarsi di comprendere la concessione del consenso e il tipo di consenso per Graph Explorer prima di procedere.

Da un browser passare a Graph Explorer e accedere usando un account utente Microsoft Entra.
Potrebbe essere necessario abilitare l'autorizzazione per l'uso WindowsUpdates.ReadWrite.All delle query in questo articolo. Per abilitare l'autorizzazione:
1. Selezionare la scheda Modifica autorizzazioni in Esplora grafici.
2. Nella finestra di dialogo autorizzazioni selezionare l'autorizzazione WindowsUpdates.ReadWrite.All e quindi selezionare Consenso. Potrebbe essere necessario accedere di nuovo per concedere il consenso.
Per effettuare richieste:
1. Selezionare GET, POST, PUT, PATCH o DELETE dall'elenco a discesa per il metodo HTTP.
2. Immettere la richiesta nel campo URL. La versione verrà popolata automaticamente in base all'URL.
3. Se è necessario modificare il corpo della richiesta, modificare la scheda Corpo della richiesta .
4. Selezionare il pulsante Esegui query . I risultati verranno visualizzati nella finestra Risposta .
Suggerimento

Quando si esamina la documentazione di Microsoft Graph, è possibile notare che le richieste di esempio in genere elencano content-type: application/json. La specifica content-type in genere non è necessaria per Graph Explorer, ma è possibile aggiungerla alla richiesta selezionando la scheda Intestazioni e aggiungendo al content-type campo Intestazioni richiesta come chiave e application/json come valore.

Eseguire query per identificare i dispositivi

Usare il tipo di risorsa del dispositivo per trovare i client da registrare in Windows Autopatch. Modificare i parametri di query in base alle esigenze specifiche. Per altre informazioni, vedere Usare i parametri di query.

Visualizza l'ID dispositivo di AzureAD e il nome di tutti i dispositivi:

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

Visualizza l'ID dispositivo e il nome di AzureAD per i dispositivi con un nome che inizia con Test:

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

Aggiungere un'intestazione della richiesta per le query avanzate

Per le richieste successive, impostare l'intestazione ConsistencyLevel su eventual. Per altre informazioni sui parametri di query avanzati, vedere Funzionalità di query avanzate sugli oggetti directory Microsoft Entra.

In Esplora grafici selezionare la scheda Intestazioni richiesta .
Per Tipo di chiave in ConsistencyLevel e per Valore, digitare eventual.
Selezionare il pulsante Aggiungi . Al termine, rimuovere l'intestazione della richiesta selezionando l'icona del cestino.

Visualizzare il nome e la versione del sistema operativo per il dispositivo che ha 01234567-89ab-cdef-0123-456789abcdef come ID dispositivo AzureAD:

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

Per trovare i dispositivi che probabilmente non sono macchine virtuali, filtrare per i dispositivi che non hanno una macchina virtuale elencata come modello ma che hanno un produttore elencato. Visualizzare l'ID dispositivo, il nome e la versione del sistema operativodi AzureAD per ogni 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
```

Suggerimento

Le richieste che usano il tipo di risorsa del dispositivo includono in genere sia un oggetto id che un deviceidoggetto :

è deviceidl'ID dispositivo Microsoft Entra e verrà usato in questo articolo.
- Più avanti in questo articolo, questo deviceid verrà usato come un id quando si effettuano determinate richieste, ad esempio l'aggiunta di un dispositivo a un gruppo di destinatari della distribuzione.
L'oggetto id del tipo di risorsa del dispositivo è in genere l'ID oggetto Microsoft Entra, che non verrà usato in questo articolo.

Registrare i dispositivi

Quando si registrano i dispositivi nella gestione degli aggiornamenti delle funzionalità, Windows Autopatch diventa l'autorità per gli aggiornamenti delle funzionalità provenienti da Windows Update. Fino a quando un dispositivo rimane registrato nella gestione degli aggiornamenti delle funzionalità tramite Windows Autopatch, il dispositivo non riceve altri aggiornamenti delle funzionalità da Windows Update a meno che non venga distribuito in modo esplicito con Windows Autopatch.As a device remains enrolled in feature update management through Windows Autopatch, the device doesn't receive any other feature updates from Windows Update unless explicitly deployed using Windows Autopatch. A un dispositivo viene offerto l'aggiornamento delle funzionalità specificato se non ha già ricevuto l'aggiornamento. Ad esempio, se si distribuisce Windows 11 versione 22H2 dell'aggiornamento delle funzionalità in un dispositivo registrato nella gestione degli aggiornamenti delle funzionalità e attualmente in una versione precedente di Windows 11, il dispositivo viene aggiornato alla versione 22H2. Se il dispositivo è già in esecuzione versione 22H2 o successiva, rimane nella versione corrente.

Suggerimento

Windows Update report per le aziende include una cartella di lavoro che visualizza la versione corrente del sistema operativo per i dispositivi. Nella cartella di lavoro passare alla scheda Aggiornamenti funzionalità e nel riquadro In Service feature update selezionare il collegamento Visualizza dettagli per aprire il riquadro a comparsa Dettagli. La versione del sistema operativo e Microsoft Entra ID dei dispositivi possono essere facilmente esportati in un file .csv o aperti nei log di Monitoraggio di Azure per facilitare la creazione di un gruppo di destinatari della distribuzione.

I dispositivi vengono registrati in base ai tipi di aggiornamenti che si desidera ricevere. Attualmente, è possibile registrare i dispositivi per ricevere gli aggiornamenti delle funzionalità (feature) o i driver (driver). È possibile registrare i dispositivi per ricevere gli aggiornamenti da più classificazioni degli aggiornamenti.

Per registrare i dispositivi, POST per l'updatableAssets usando enrollAssets. L'esempio seguente registra tre dispositivi per ricevere gli aggiornamenti dei driver:
1. In Graph Explorer selezionare POST dall'elenco a discesa per il verbo HTTP.
2. Immettere la richiesta seguente nel campo URL:
  https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/enrollAssets
3. Nella scheda Corpo della richiesta immettere il codice JSON seguente, fornendo le informazioni seguenti:
  - Microsoft Entra ID dispositivo comeid
  - driver O feature per 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. Selezionare il pulsante Esegui query . I risultati verranno visualizzati nella finestra Risposta . In questo caso, il codice di stato HTTP di 202 Accepted.

Elencare le voci del catalogo per gli aggiornamenti delle funzionalità

Ogni aggiornamento delle funzionalità è associato a una voce del catalogo univoca. L'oggetto id restituito è l'ID catalogo e viene usato per creare una distribuzione. Gli aggiornamenti delle funzionalità sono distribuibili fino a quando non raggiungono le date di ritiro del supporto. Per altre informazioni, vedere le date del ciclo di vita del supporto per le edizioni Windows 10 e Windows 11 Enterprise ed Education. La query seguente elenca tutte le voci del catalogo degli aggiornamenti delle funzionalità distribuibili:

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

La risposta troncata seguente visualizza un ID catalogo di per l'aggiornamento delle d9049ddb-0ca8-4bc1-bd3c-41a456ef300f funzionalità di Windows 11 versione 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"
        }
    ]
}

Creare una distribuzione

Quando si crea una distribuzione per un aggiornamento delle funzionalità, sono disponibili più opzioni per definire il comportamento della distribuzione. Le impostazioni di distribuzione e monitoraggio sono facoltative. Le impostazioni di distribuzione seguenti sono definite nel corpo della richiesta di esempio per la distribuzione dell'aggiornamento della funzionalità Windows 11 versione 22H2 (ID catalogo di d9049ddb-0ca8-4bc1-bd3c-41a456ef300f):

Data di inizio della distribuzione del 14 febbraio 2023 alle 5:00 UTC
Implementazione graduale a una velocità di 100 dispositivi ogni tre giorni
Regola di monitoraggio che sospende la distribuzione se cinque dispositivi rimontano l'aggiornamento delle funzionalità
Comportamento predefinito del blocco di protezione dell'applicazione di tutte le misure di sicurezza applicabili ai dispositivi in una distribuzione
- Quando i blocchi di protezione non sono definiti in modo esplicito, il comportamento predefinito del blocco di protezione viene applicato 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"
                }
            ]
        }
    }
}

Il corpo della risposta contiene:

Il nuovo ID di distribuzione, de910e12-3456-7890-abcd-ef1234567890 nell'esempio
Il nuovo ID gruppo di destinatari, d39ad1ce-0123-4567-89ab-cdef01234567 nell'esempio

Tutte le impostazioni definite nel corpo della richiesta di distribuzione

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

Modificare una distribuzione

Per aggiornare la distribuzione, APPLICARE PATCH alla risorsa di distribuzione in base all'ID di distribuzione e specificare le impostazioni aggiornate nel corpo della richiesta. L'esempio seguente mantiene le impostazioni di implementazione graduale esistenti definite durante la creazione della distribuzione, ma modifica la data di inizio della distribuzione in 28 febbraio 2023 alle 5 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"
            }
        }
    }
}

Verificare le impostazioni di distribuzione per la distribuzione con un ID di distribuzione di de910e12-3456-7890-abcd-ef1234567890:

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

Aggiungere membri al gruppo di destinatari della distribuzione

L'ID gruppo di destinatari, d39ad1ce-0123-4567-89ab-cdef01234567, è stato creato al momento della creazione della distribuzione. L'ID gruppo di destinatari viene usato per aggiungere membri al gruppo di destinatari della distribuzione. Dopo l'aggiornamento del gruppo di destinatari della distribuzione, Windows Update inizia a offrire l'aggiornamento ai dispositivi in base alle impostazioni di distribuzione. Finché la distribuzione esiste e il dispositivo è tra i destinatari, viene offerto l'aggiornamento.

L'esempio seguente aggiunge tre dispositivi al gruppo di destinatari della distribuzione usando il Microsoft Entra ID per ogni 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"
    }
  ]
}

Per verificare che i dispositivi siano stati aggiunti al gruppo di destinatari, eseguire la query seguente usando l'ID gruppo di destinatari di d39ad1ce-0123-4567-89ab-cdef01234567:

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

Sospendere una distribuzione

Per sospendere una distribuzione, APPLICARE PATCH alla distribuzione in modo che abbia un requestedValue oggetto per pauseddeploymentState. Per riprendere la distribuzione, usare il valore none e lo stato verrà aggiornato a offering o scheduled se la distribuzione non ha ancora raggiunto la data di inizio.

Nell'esempio seguente la distribuzione viene sospesa con un ID di distribuzione di 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"
  }
}

Eliminare una distribuzione

Per rimuovere completamente la distribuzione, ELIMINARE la distribuzione. L'eliminazione della distribuzione impedisce che il contenuto venga offerto ai dispositivi se non lo hanno già ricevuto. Per riprendere l'offerta del contenuto, è necessario creare una nuova approvazione.

Nell'esempio seguente la distribuzione viene eliminata con un ID di distribuzione di de910e12-3456-7890-abcd-ef1234567890:

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

Annulla la registrazione dei dispositivi

Quando un dispositivo non richiede più la gestione, annulla la registrazione da Windows Autopatch. Analogamente alla registrazione di un dispositivo, specificare driver o feature come valore per updateCategory. Il dispositivo non riceverà più gli aggiornamenti da Windows Autopatch per la categoria di aggiornamento specificata. A seconda della configurazione del dispositivo, potrebbe iniziare a ricevere aggiornamenti da Windows Update. Ad esempio, se un dispositivo è ancora registrato per gli aggiornamenti delle funzionalità, ma viene annullato dai driver:

Le distribuzioni di driver esistenti dal servizio non verranno offerte al dispositivo
Il dispositivo continua a ricevere gli aggiornamenti delle funzionalità da Windows Autopatch
I driver possono iniziare a essere installati da Windows Update a seconda della configurazione del dispositivo

Per annullare la registrazione di un dispositivo, post per l'updatableAssets usando unenrollAssets. Nel corpo della richiesta specificare:

Microsoft Entra ID dispositivo come id per il dispositivo
driver O feature per updateCategory

Nell'esempio seguente viene rimossa driver la registrazione per due dispositivi 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"
    }
  ]
}

Condividi tramite