UpdateOrchestrator API

UpdateOrchestrator pianifica gli aggiornamenti software automatici tenendo presente l'impatto degli utenti. Questa API consente di specificare azioni, ad esempio il download o l'installazione, insieme ai relativi requisiti per eseguire gli aggiornamenti in un momento ottimale che riduce al minimo l'impatto dell'utente. Queste funzionalità traggono vantaggio in particolare dai sistemi a prestazioni inferiori con risorse di calcolo limitate o più lente.

Windows 20H1 include una soluzione di prima generazione per i casi d'uso degli aggiornamenti software automatici adottati dagli aggiornamenti del sistema operativo e dagli aggiornamenti delle app dello Store ed espone una versione iniziale di "Accesso limitato" di questa API per un set selezionato di aggiornamenti delle app "in modalità utente", come descritto di seguito.

Caratteristiche

• Registra dinamicamente gli aggiornamenti software

• Richiama gli aggiornamenti software registrati durante i momenti ottimali, ad esempio durante l'assenza dell'utente, per aggiornare le "app in modalità utente".

• Include la possibilità di "mantenere sveglio" il dispositivo quando è alimentato a corrente alternata per ridurre ulteriormente l'impatto dell'assenza dell'utente.

Pubblico degli sviluppatori

Usa l'API UpdateOrchestrator se disponi già di aggiornamenti software in background per applicazioni win32 "modalità utente", ad esempio l'updater di Adobe per Acrobat Reader o Valve's Steam. Questa interfaccia non è necessaria per le applicazioni UWP/Store perché Microsoft Store sfrutta già questa funzionalità per gli aggiornamenti software.

Per offrire la migliore esperienza del cliente, questa versione iniziale dell'API ha come ambito un set selezionato di aggiornamenti registrati che soddisfano i criteri seguenti:

• Aggiornamenti solo per le applicazioni in modalità utente
• Non coinvolgere BIOS/Firmware/Dispositivo o driver del software
  • L'aggiornamento di bios, firmware o driver di dispositivo/software che non hanno superato criteri di qualità comuni rappresentano un rischio sostanziale, in particolare quando un utente non è presente.
• Partecipare nell'uso di questa API comporta essere in grado di garantire tutto il contenuto scaricato e installato dai programmi di aggiornamento software in background nei sistemi degli utenti tramite verifiche.

Il rilascio iniziale dell'API UpdateOrchestrator come funzionalità di accesso limitato è attualmente disponibile solo per gli aggiornatori che soddisfano i criteri precedenti.

Il nostro obiettivo è migliorare le funzionalità di questa API e ridurre l'impatto di più aggiornamenti software automatici in Windows. Microsoft apprezzerebbe il tuo contributo attraverso questo breve sondaggio per aiutarci a comprendere come l'API UpdateOrchestrator possa servire meglio le tue esigenze di sviluppo.

Accelerare le app OEM tramite il framework di Universal Orchestrator

Requisiti

Per integrarsi nel framework applicativo accelerato, l'app deve soddisfare i seguenti requisiti:

• Deve essere un'app in pacchetto nello Store in formato MSIX
• Deve avere un nome di famiglia di prodotti valido (PFN)

Registrazione

I file di registrazione sono file JSON ASCII che contengono metadati con informazioni sul flusso accelerato desiderato, nonché qualsiasi destinazione lato client personalizzata che deve essere eseguita.

Le app accelerate supportano due meccanismi per aggiornare/acquisire un'app:

1. Direttamente dal Microsoft Store utilizzando il ProductId (scelta consigliata)
2. Da un URL che contiene un pacchetto MSIX o un bundle. Questo pacchetto deve contenere un'app dello Store in pacchetto con un Nome di Famiglia del Pacchetto (PFN) valido. L'OEM o il proprietario dell'app è responsabile della gestione di questo URL.

Ogni file di registrazione deve contenere le proprietà JSON necessarie seguenti:

Chiave	Digitare	Descrizione
PFN	Stringa	Nome della famiglia di pacchetti dell'app (ad esempio, Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName	Stringa	Stringa per rappresentare l'OEM che crea questa registrazione
UpdaterName	Stringa	Nome univoco per tenere traccia di questa registrazione accelerata
Versione di registrazione	Numero	La versione della registrazione di questa app
Fonte	Stringa	Valori consentiti: Negozio | CustomURL Store: cerca l'app direttamente da Microsoft Store CustomURL: cerca l'app tramite un URL specificato nel campo "Endpoint" della registrazione dell'app.
Scenario	Corda	Valori consentiti: Aggiornare | Acquisizione | StubAcquisition Aggiornamento: (non supportato per i flussi CustomURL) tenta di aggiornare un'app esistente alla versione più recente disponibile. Non viene eseguito alcun lavoro se l'app non è presente Acquisizione: tenta di acquisire la versione più recente di un'app. StubAcquisition: tenta di acquisire uno "stub" dell'app (se disponibile). Acquisisce l'app completa se lo stub non è disponibile.
ProductId	Corda	(Obbligatorio solo per gli scenari dello Store) ProductId dell'app dello Store desiderata
Punto di terminazione	Stringa	(Obbligatorio solo per gli scenari CustomURL) Stringa URI che punta a una posizione che ospita un pacchetto MSIX. Deve essere un URI SSL che inizia con "https".

Inoltre, è possibile specificare le proprietà facoltative seguenti per modificare il comportamento dell'installazione accelerata dell'app o impostare come destinazione il flusso accelerato in modo che si verifichi solo in determinate condizioni.

Chiave	Digitare	Predefinito	Descrizione
AllowedInOobe	Booleano	Falso	Indica se questa app rapida deve essere eseguita durante la configurazione guidata dell'utente. Nota: Prestare attenzione quando si imposta questa opzione su true, poiché ciò può creare vincoli di risorse in un dispositivo durante il flusso Out of Box Experience e influire negativamente sulle prestazioni percepite dall'utente.
MaxRetryCount	Numero	1	Numero di volte in cui questo aggiornamento può riprovare dopo un errore. Il valore massimo consentito è: 5
TimeoutDurationInMinutes	Numero	15	Durata in minuti di attesa del completamento di questo aggiornamento. Il valore massimo consentito è: 30
Architettura	Stringa	Nessuna restrizione	Valori consentiti: "amd64" | "arm64". Specifica se il lavoro accelerato deve essere eseguito solo per un'architettura specifica.
VersioneMinimaConsentitaCompilazione	Numero	Nessuna restrizione	Versioni minime della build di Windows in cui è consentito il lavoro accelerato. Ex. Se è impostato su 22631, il lavoro accelerato sarà consentito per Windows 11 23H2 (10.0.22631.x), ma bloccato per Windows 11 22H2 (10.0.22621.x)
HonorDeprovisioning	Booleano	Falso	(Applicabile solo per gli scenari di acquisizione) Se l'app è stata deprovisionata in precedenza, non tentare di acquisirla di nuovo.
Salta se presente	Booleano	Falso	(Applicabile solo per gli scenari di acquisizione) Non eseguire il lavoro accelerato se una versione dell'app è già presente.
Priorità	Numero	100	Valore numerico compreso tra 1 e 100 per indicare la priorità relativa di questo aggiornamento dell'applicazione. I valori inferiori indicano una priorità relativa più alta per altre app rapide.
Regioni Escluse	Matrice (stringa)	Nessuna restrizione	Matrice JSON di stringhe per le aree in cui questa app non deve essere accelerata. Ogni voce nella matrice corrisponde al codice paese ISO 3166-1 di 2 lettere dell'area desiderata. Ad esempio, ["US", "MX"] impedirebbe questo flusso nei dispositivi in cui l'area è Stati Uniti o Messico. Nota: Questo valore non può essere usato insieme a IncludedRegions.
Aree incluse	Matrice (stringa)	Nessuna restrizione	Matrice JSON di stringhe che indicano un elenco di aree consentite in cui l'app deve essere accelerata. Ogni voce nella matrice corrisponde al codice paese ISO 3166-1 di 2 lettere dell'area desiderata. Ad esempio, ["US", "MX"] consentirebbe questo flusso solo nei dispositivi in cui l'area è Stati Uniti o Messico. Nota: Questo valore non può essere usato insieme a ExcludedRegions.
Edizioni Incluse	Matrice (numero)	Nessuna restrizione	Matrice JSON di numeri che indicano un elenco di edizioni consentite in cui l'app deve essere accelerata. Ogni voce nella matrice corrisponde al codice Edition recuperato dall'API GetProductInfo . Per esempio, [121, 122] per includere solo le edizioni Education e EducationN Nota: Questo valore non può essere usato insieme a ExcludedEditions.
Edizioni Escluse	Matrice (numero)	Nessuna restrizione	Matrice JSON di numeri per le edizioni in cui questa app non deve essere accelerata. Ogni voce nella matrice corrisponde al codice Edition recuperato dall'API GetProductInfo . Ad esempio, [121, 122] esclude le edizioni Education e EducationN. Nota: Questo valore non può essere usato insieme a IncludedEditions.

Campioni

acquisizione di stub basata sul negozio, solo negli Stati Uniti e in Messico, da eseguire durante l'esperienza iniziale

    {  
        "RegistrationVersion":1,  
        "Source": "Store",  
        "Scenario": "StubAcquisition",  
        "PFN": "FakePackageFamilyName",  
        "ProductId": "StoreProductId",  
        "HonorDeprovisioning": true,  
        "AllowedInOobe": true,  
        "IncludedRegions": ["US", "MX"],  
        "Priority": 50  
    }

L'acquisizione di app basate su URL su dispositivi amd64, escluse le edizioni Education e EducationN, è disponibile solo su Windows 11 23H2 (not Windows 11 22H2)

    {  
        "RegistrationVersion":2,  
        "Source": "CustomURL",  
        "Scenario": "Acquisition",  
        "PFN": "FakePackageFamilyName",  
        "Endpoint": "https://<SSL_URI>",   
        "ExcludedEditions": [121, 122],   
        "Architecture": "amd64",   
        "MinimumAllowedBuildVersion": 22631,  
        "Priority": 60 
    }

Strumenti

Per facilitare il processo di registrazione e fornire commenti e suggerimenti interattivi sui metadati di registrazione, gli OEM devono usare l'AppOrchestration script di PowerShell dal percorso seguente:
microsoft/ms-update-universalorchestrator: strumenti e script per integrarsi con flussi di aggiornamento basati su Universal Orchestrator

Gli script eseguono la convalida di base e predispongono la registrazione sulla posizione appropriata sul dispositivo. In caso di errori, gli script generano un'eccezione con i dettagli specifici dell'errore.

Per usare gli script:

1. Scaricare gli script nel dispositivo. Dalla pagina del repository GitHub è possibile scegliere di scaricare come file ZIP ed estrarre nel dispositivo
2. In una finestra di PowerShell eseguire "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"

Nota: Questi script richiedono all'utente di disporre di privilegi amministrativi nel dispositivo e devono essere eseguiti da una console con privilegi elevati.

Esistono 4 cmdlet principali usati per il flusso di registrazione

Test-UpdaterRegistration <PercorsoAlFileDiRegistrazione>
Scopo: convalidare il contenuto di un file di registrazione proposto (senza eseguire la registrazione). Consente all'OEM di scorrere il payload del file di registrazione senza influire sul dispositivo

Add-UpdaterRegistration <PathToRegistrationFile>
Scopo: convalidare e preparare i contenuti di un file di registrazione nella posizione appropriata, per facilitare l'integrazione nel flusso rapido dell'app

Get-UpdaterRegistration <OEMName><UpdaterName>
Scopo: se vengono forniti OEMName e UpdaterName, restituisce un riepilogo di una registrazione esistente corrispondente a tali valori. Se tali input vengono omessi, restituisce un riepilogo di tutte le registrazioni correnti presenti nel dispositivo.

Remove-UpdaterRegistration <OEMName><UpdaterName<
Scopo: annulla le operazioni di registrazione corrispondenti ai valori OEMName e UpdaterName.

Esecuzione

Il framework Universal Orchestrator richiama automaticamente ogni app registrata, in sequenza in base alla priorità relativa, entro i primi 30 minuti da quando un utente raggiunge il desktop su un nuovo dispositivo (o durante l'esperienza guidata iniziale utente se AllowedInOobe è impostato su true). Ogni applicazione registrata aggiunta dal processo di registrazione OEM verrà tentata fino a quando:

• L'installazione è stata completata
• Supera la quantità massima di errori specificati in MaxRetryCount. Dopo ogni errore, l'app immetterà un periodo di raffreddamento di 30 minuti prima di riprovare.

Il framework di Universal Orchestrator non eseguirà tentativi accelerati se si verifica una delle condizioni seguenti:

• Il dispositivo non ha accesso a Internet
• Il dispositivo si trova in una rete a consumo
• Il dispositivo è a batteria e il risparmio batteria è abilitato
• Il dispositivo è configurato con un criterio di restrizione del traffico di rete di Windows Update
• Il dispositivo è configurato con una politica CTA che non è impostata per l'approvazione automatica
  
  In ognuno di questi casi, il framework Universal Orchestrator manterrà le registrazioni invariate fino a quando la configurazione del dispositivo non consente tentativi accelerati di procedere.
  Se la registrazione dell'app contiene valori facoltativi che bloccano il flusso accelerato (ad esempio a causa del tipo di edizione), il framework di Universal Orchestrator considererà questa richiesta di registrazione soddisfatta e non lo tenterà di nuovo, anche se tali condizioni potrebbero cambiare successivamente in un dispositivo.