UpdateOrchestrator API

UpdateOrchestrator planuje automatyczne aktualizacje oprogramowania z uwzględnieniem wpływu na użytkownika. Ten interfejs API umożliwia określenie akcji, takich jak pobieranie lub instalowanie, wraz z ich wymaganiami, w celu uruchamiania aktualizacji w optymalnym czasie, który minimalizuje wpływ na użytkownika. Funkcje te szczególnie przynoszą korzyści systemom o niższej wydajności z ograniczonymi zasobami obliczeniowymi lub wolniejszymi.

System Windows 20H1 zawiera rozwiązanie pierwszej generacji dla przypadków użycia automatycznych aktualizacji oprogramowania, które zostały zaadaptowane przez aktualizacje systemu operacyjnego i aktualizacje aplikacji ze Sklepu. Uwidacznia początkową wersję interfejsu API „Ograniczony dostęp” dla wybranego zbioru programów aktualizujących aplikacje w trybie użytkownika, jak opisano poniżej.

Funkcje

• Dynamicznie rejestruje aktualizatory oprogramowania

• Wywołuje zarejestrowane aktualizatory oprogramowania w optymalnych czasach, takich jak podczas braku użytkownika, aby zaktualizować "aplikacje w trybie użytkownika".

• Obejmuje możliwość "utrzymania pracy" na zasilaniu prądem AC, aby jeszcze bardziej zmniejszyć wpływ nieobecności użytkownika.

Odbiorcy deweloperów

Ważny

Interfejs API UpdateOrchestrator jest częścią funkcji o ograniczonym dostępie (zobacz klasę LimitedAccessFeatures). Aby uzyskać więcej informacji lub zażądać tokenu odblokowania, użyj formularza żądania tokenu dostępu LAF.

Użyj interfejsu API UpdateOrchestrator, jeśli masz już programy aktualizujące oprogramowanie działające w tle dla aplikacji Win32 w „trybie użytkownika”, takich jak aktualizator Adobe dla programu Acrobat Reader lub Steam firmy Valve. Ten interfejs nie jest wymagany w przypadku aplikacji platformy UWP/Store, ponieważ sklep Microsoft Store korzysta już z tej funkcji w przypadku aktualizacji oprogramowania.

Aby zapewnić najlepsze doświadczenie klienta, to początkowe wydanie interfejsu API jest ograniczone do wybranego zestawu zarejestrowanych aktualizatorów, którzy spełniają następujące kryteria:

• Aktualizacje tylko dla aplikacji w trybie użytkownika
• Nie należy uwzględniać systemu BIOS/oprogramowania układowego/sterowników urządzeń lub oprogramowania.
  • Aktualizacja systemu BIOS, oprogramowania układowego lub sterowników urządzeń/oprogramowania, które nie przeszły wspólnych kryteriów jakości, stanowi znaczne ryzyko, szczególnie gdy użytkownik nie jest obecny.
• Udział w korzystaniu z tego API oznacza, że można zaświadczyć o całej zawartości pobranej i zainstalowanej poprzez automatyczne aktualizacje oprogramowania na systemach użytkowników poprzez audyt.

Początkowa wersja interfejsu API UpdateOrchestrator jako funkcja ograniczonego dostępu dotyczy tylko aktualizacji spełniających powyższe kryteria w tej chwili.

Naszym celem jest ulepszenie funkcjonalności tego interfejsu API i zmniejszenie wpływu wielu automatycznych aktualizacji oprogramowania w systemie Windows. Będziemy wdzięczni za twoje dane wejściowe poprzez tę krótką ankietę, aby pomóc nam zrozumieć, w jaki sposób UpdateOrchestrator API może lepiej spełniać potrzeby twoich deweloperów.

Expediting OEM Apps via Universal Orchestrator framework (Przyspieszanie aplikacji OEM za pomocą platformy Universal Orchestrator)

Ważny

Program Universal Orchestrator udostępnia funkcje maszynom OEM w celu zarejestrowania aplikacji podczas procesu tworzenia obrazu w celu przeprowadzenia jednorazowej przyspieszonej instalacji/aktualizacji. Ta instalacja odbywa się w ciągu 30 minut od zalogowania użytkownika do nowego urządzenia. Należy pamiętać, że przyspieszenie procesu aplikacji może mieć negatywny wpływ na doświadczenie początkowe nowych urządzeń. Ta funkcja jest dostępna tylko w wersjach systemu Windows z aktualizacją zbiorczą niezwiązaną z zabezpieczeniami z listopada 2024 r.

Windows 11 23H2 — KB5046732 (kompilacja systemu operacyjnego 22631.4541)
Windows 11 24H2 — KB5046740 (kompilacja systemu operacyjnego 26100.2454)

Wymagania

Aby podłączyć przyspieszone środowisko aplikacji, aplikacja musi spełniać następujące wymagania:

• Musi to być aplikacja ze sklepu spakowana w formacie MSIX
• Musi mieć prawidłową nazwę rodziny produktów (PFN)

Rejestracja

Pliki rejestracji to pliki JSON ASCII zawierające metadane z informacjami o żądanym przyspieszonym przepływie, a także wszelkie niestandardowe ustawienia docelowe po stronie klienta, które należy wykonać.

Przyspieszone aplikacje obsługują dwa mechanizmy aktualizowania/uzyskiwania aplikacji:

1. Bezpośrednio ze sklepu Microsoft Store, korzystając z identyfikatora produktu (zalecane)
2. Z adresu URL, który zawiera pakiet MSIX lub pakiet zbiorczy. Ten pakiet musi zawierać aplikację spakowaną przez Sklep z prawidłową nazwą rodziny pakietów (PFN). Właściciel aplikacji lub producenta OEM jest odpowiedzialny za utrzymanie tego adresu URL.

Każdy plik rejestracji musi zawierać następujące wymagane właściwości JSON:

Klucz	Typ	Opis
PFN	Struna	Nazwa rodziny pakietów aplikacji (np. Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName	Struna	Ciąg reprezentujący producenta OEM tworzącego tę rejestrację
UpdaterName	Struna	Unikalna nazwa do śledzenia tej przyspieszonej rejestracji
WersjaRejestracji	Liczba	Wersja tej rejestracji aplikacji
Źródło	Struna	Dozwolone wartości: Sklep | CustomURL Store — wyszukuje aplikację bezpośrednio ze sklepu Microsoft Store CustomURL — wyszukuje aplikację z adresu URL określonego w wartości "Punkt końcowy" rejestracji aplikacji
Scenariusz	Struna	Dozwolone wartości: Aktualizacja | Pozyskiwanie | StubAcquisition Update — (nieobsługiwane w przypadku przepływów CustomURL) próbuje zaktualizować istniejącą aplikację do najnowszej dostępnej wersji. Nie wykonano żadnej pracy, jeśli aplikacja nie jest obecna Pozyskiwanie — próbuje uzyskać najnowszą wersję aplikacji. StubAcquisition — próbuje uzyskać "wycinkę" aplikacji (jeśli jest dostępna). Pobiera pełną aplikację, jeśli wersja próbna nie jest dostępna.
IdentyfikatorProduktu	Struna	(Tylko wymagane w przypadku scenariuszy sklepu) Identyfikator ProductId żądanej aplikacji ze Sklepu
Punkt końcowy	Struna	(Tylko wymagane dla scenariuszy CustomURL) Ciąg URI wskazujący na lokalizację hostującą pakiet MSIX. Musi być adresem URL SSL, który zaczyna się od "https".

Ponadto można określić następujące opcjonalne właściwości w celu zmodyfikowania zachowania przyspieszonej instalacji aplikacji lub kierowania przyspieszonego przepływu tylko w określonych warunkach.

Klucz	Typ	Domyślny	Opis
AllowedInOobe	Boolean	Nieprawda	Czy ta przyspieszona aplikacja powinna być uruchamiana podczas OOBE użytkownika. Uwaga: Zachowaj ostrożność podczas ustawiania wartości true, ponieważ może to spowodować utworzenie ograniczeń zasobów na urządzeniu podczas przepływu Out of Box Experience i negatywnie wpłynąć na wydajność postrzeganą przez użytkownika.
MaksymalnaLiczbaPonownychPrób	Liczba	1	Liczba ponownych prób dozwolonych po awarii dla tego aktualizatora. Maksymalna dozwolona wartość to: 5
CzasPrzerwyWMinutach	Liczba	15	Czas oczekiwania w minutach, aż program aktualizujący zakończy pracę. Maksymalna dozwolona wartość to: 30
Architektura	Struna	Brak ograniczeń	Dozwolone wartości: "amd64" | "arm64". Określa, czy przyspieszona praca powinna odbywać się tylko dla określonej architektury.
MinimalnaDozwolonaWersjaKompilacji	Liczba	Brak ograniczeń	Minimalne wersje kompilacji systemu Windows, w których dozwolona jest przyspieszona praca. Ex. Jeśli ustawiono wartość 22631, przyspieszona praca będzie dozwolona dla systemu Windows 11 23H2 (10.0.22631.x), ale zablokowana dla systemu Windows 11 22H2 (10.0.22621.x)
HonorDeprovisioning	Typ logiczny	Fałsz	(Dotyczy tylko scenariuszy pozyskiwania) Jeśli aplikacja została wcześniej odprovisionowana, nie próbuj jej ponownie uzyskać.
PomińJeśliObecny	Boolean	Fałszywy	(Dotyczy tylko scenariuszy pozyskiwania) Nie wykonuj przyspieszonej pracy, jeśli jakakolwiek wersja aplikacji jest już obecna.
Priorytet	Liczba	100	Wartość liczbowa z zakresu od 1 do 100 wskazująca względny priorytet tej aktualizacji aplikacji. Niższe wartości wskazują wyższy względny priorytet dla innych przyspieszonych aplikacji.
Wykluczoneregiony	Tablica (ciąg)	Brak ograniczeń	Tablica ciągów JSON dla regionów, w których ta aplikacja nie powinna być przyspieszona. Każdy wpis w tablicy odpowiada dwuliterowemu kodowi kraju ISO 3166-1 dla wybranego regionu. Na przykład: ["US", "MX"] zapobiegłoby temu przepływowi na urządzeniach, na których region to Stany Zjednoczone lub Meksyk. Uwaga: Tej wartości nie można używać w połączeniu z regionami dołączonymi.
Uwzględnioneregiony	Tablica (ciąg)	Brak ograniczeń	Tablica JSON ciągów wskazująca listę dozwolonych regionów, w których ta aplikacja powinna zostać przyspieszona. Każdy wpis w tablicy odpowiada dwuliterowemu kodowi kraju ISO 3166-1 określonego regionu. Na przykład: ["US", "MX"] zezwala na ten przepływ tylko na urządzeniach, na których region to Stany Zjednoczone lub Meksyk. Uwaga: Tej wartości nie można używać w połączeniu z ExcludedRegions.
Uwzględnione edycje	Tablica (liczba)	Brak ograniczeń	Tablica JSON liczb wskazująca listę dozwolonych wersji, w których ta aplikacja powinna zostać przyspieszona. Każdy wpis w tablicy odpowiada kodowi edycji, który został pobrany za pomocą interfejsu API GetProductInfo. Na przykład: [121, 122] do uwzględnienia tylko wersji Education i EducationN Uwaga: Tej wartości nie można używać w połączeniu z wartością ExcludedEditions.
Wykluczone edycje	Tablica (liczba)	Brak ograniczeń	Tablica liczb JSON dla wersji, w których ta aplikacja nie powinna być przyspieszona. Każdy wpis w tablicy odpowiada kodowi edycji pobranemu przez API GetProductInfo. Na przykład: [121, 122], aby wykluczyć edycje Education i EducationN. Uwaga: Tej wartości nie można używać w połączeniu z UwzględnionymiEdycjami.

Próbki

Pozyskiwanie w oparciu o sklep, tylko w Stanach Zjednoczonych i Meksyku, do wykonania podczas OOBE

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

Pozyskiwanie aplikacji opartych na adresach URL na urządzeniach amd64, z wyłączeniem edycji Education i EducationN, tylko w systemie 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 
    }

Narzędzia

Aby ułatwić proces rejestracji i przekazać praktyczną informację zwrotną na temat metadanych rejestracji, producenci OEM powinni używać skryptów PowerShell AppOrchestration dostępnych pod następującym adresem:
microsoft/ms-update-universalorchestrator: skrypty i narzędzia do integracji z przepływami aktualizacji opartymi na Universal Orchestrator

Skrypty wykonują podstawową walidację i przeprowadzają rejestrację w odpowiedniej lokalizacji na urządzeniu. W przypadku błędów skrypty zgłaszają wyjątek z określonymi szczegółami awarii.

Aby użyć skryptów:

1. Pobierz skrypty na urządzenie. Na stronie repozytorium GitHub możesz wybrać opcję pobrania jako pliku ZIP i wyodrębnienia na urządzenie
2. W oknie programu PowerShell uruchom polecenie "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"

Uwaga: Te skrypty wymagają od użytkownika posiadania uprawnień administracyjnych na urządzeniu i muszą zostać wykonane z poziomu konsoli z podwyższonym poziomem uprawnień.

Istnieją 4 główne cmdlety używane w procesie rejestracji

Test-UpdaterRegistration <PathToRegistrationFile>
Cel: Weryfikowanie zawartości proponowanego pliku rejestracji (bez przeprowadzania rejestracji). Umożliwia firmie OEM wprowadzanie zmian w zawartości pliku rejestracyjnego bez wpływu na urządzenie

Add-UpdaterRegistration <PathToRegistrationFile>
Cel: Weryfikowanie i przygotowywanie zawartości pliku rejestracji do odpowiedniej lokalizacji w celu dołączenia do przyspieszonego przepływu aplikacji

Get-UpdaterRegistration <OEMName><UpdaterName>
Cel: Jeśli podano wartości OEMName i UpdaterName, zwraca podsumowanie istniejącej rejestracji zgodnej z tymi wartościami. Jeśli te dane wejściowe zostaną pominięte, zwraca podsumowanie wszystkich bieżących rejestracji znajdujących się na urządzeniu.

Remove-UpdaterRegistration <OEMName><UpdaterName<
Cel: anuluje rejestrację zgodną z wartościami OEMName i UpdaterName.

Egzekucja

Platforma Universal Orchestrator automatycznie wywołuje każdą z zarejestrowanych aplikacji w sekwencji na podstawie względnego priorytetu w ciągu pierwszych 30 minut od dotarcia użytkownika do pulpitu na nowym urządzeniu (lub podczas OOBE użytkownika, jeśli wartość AllowedInOobe jest ustawiona na wartość true). Każda zarejestrowana aplikacja dodana przez proces rejestracji producenta OEM będzie próbowana do momentu:

• Pomyślnie zainstalowano
• Przekracza maksymalną liczbę błędów określonych w parametrze MaxRetryCount. Po każdym niepowodzeniu aplikacja wprowadzi okres ochładzania 30 minut, zanim zostanie podjęta ponowna próba.

Platforma Universal Orchestrator nie będzie wykonywać przyspieszonych prób, jeśli spełniony jest którykolwiek z następujących warunków:

• Urządzenie nie ma dostępu do Internetu
• Urządzenie znajduje się w sieci taryfowej
• Urządzenie jest zasilane z baterii, a oszczędzanie baterii jest włączone
• Urządzenie jest skonfigurowane z zasadą ograniczonego ruchu sieciowego Windows Update
• Urządzenie jest skonfigurowane przy użyciu zasad CTA, które nie są ustawione dla rozwiązania AutoApprove
  
  W każdym z tych przypadków platforma Universal Orchestrator będzie przechowywać rejestracje, dopóki konfiguracja urządzenia nie umożliwi przyspieszonych prób kontynuowania.
  Jeśli rejestracja aplikacji zawiera opcjonalne wartości, które blokują przyspieszony przepływ (np. ze względu na typ wersji), platforma Universal Orchestrator rozważy spełnienie tego żądania rejestracji i nie podejmie ponownej próby, nawet jeśli te warunki mogą później ulec zmianie na urządzeniu.
  
  

Ważny

Zachowaj ostrożność, decydując się na przyspieszenie aplikacji za pośrednictwem tej platformy, ponieważ operacje aktualizacji występują, gdy urządzenie może być używane i może spowodować negatywny wpływ na wydajność środowiska użytkownika na nowym urządzeniu.