Tworzenie modułowych elementów runbook w usłudze Automation

  • Artykuł

Dobrym rozwiązaniem w usłudze Azure Automation jest napisanie modułowych elementów Runbook wielokrotnego użytku z dyskretną funkcją wywoływaną przez inne elementy Runbook. Nadrzędny element Runbook często wywołuje co najmniej jeden podrzędny element Runbook w celu wykonania wymaganych funkcji.

Istnieją dwa sposoby wywoływania podrzędnego elementu Runbook: wbudowane lub za pomocą polecenia cmdlet. W poniższej tabeli podsumowano różnice, które pomogą Ci zdecydować, który sposób jest lepszy dla Twoich scenariuszy.

W tekście Polecenia cmdlet
Zadanie Podrzędne elementy Runbook działają w tym samym zadaniu co element nadrzędny. Dla podrzędnego elementu Runbook jest tworzone oddzielne zadanie.
Wykonanie Nadrzędny element Runbook czeka na zakończenie podrzędnego elementu Runbook przed kontynuowaniem. Nadrzędny element Runbook jest kontynuowany natychmiast po uruchomieniu podrzędnego elementu Runbook lub nadrzędny element Runbook czeka na zakończenie zadania podrzędnego.
Wyjście Nadrzędny element Runbook może bezpośrednio pobierać dane wyjściowe z podrzędnego elementu Runbook. Nadrzędny element Runbook musi pobierać dane wyjściowe z podrzędnego zadania elementu Runbook lub nadrzędny element Runbook może bezpośrednio pobierać dane wyjściowe z podrzędnego elementu Runbook.
Parametry Wartości parametrów podrzędnego elementu Runbook są określane oddzielnie i mogą używać dowolnego typu danych. Wartości parametrów podrzędnego elementu Runbook muszą być łączone w jedną tabelę skrótów. Ta tabela skrótu może zawierać tylko proste, tablicowe i obiekty typy danych, które używają serializacji JSON.
Konto usługi Automation Nadrzędny element Runbook może używać tylko podrzędnego elementu Runbook na tym samym koncie usługi Automation. Nadrzędne elementy Runbook mogą używać podrzędnego elementu Runbook z dowolnego konta usługi Automation, z tej samej subskrypcji platformy Azure, a nawet z innej subskrypcji, do której masz połączenie.
Publikowanie Podrzędny element Runbook musi zostać opublikowany przed opublikowaniem nadrzędnego elementu Runbook. Podrzędny element Runbook jest publikowany w dowolnym momencie przed uruchomieniem nadrzędnego elementu Runbook.

Wywoływanie podrzędnego elementu Runbook przy użyciu wykonywania wbudowanego

Aby wywołać element Runbook w tekście z innego elementu Runbook, użyj nazwy elementu Runbook i podaj wartości jego parametrów, podobnie jak w przypadku działania lub polecenia cmdlet. Wszystkie elementy Runbook na tym samym koncie usługi Automation są dostępne dla wszystkich innych, które mają być używane w ten sposób. Nadrzędny element Runbook czeka na zakończenie podrzędnego elementu Runbook przed przejściem do następnego wiersza, a wszystkie dane wyjściowe są zwracane bezpośrednio do elementu nadrzędnego.

Wywołanie elementu Runbook w tekście powoduje uruchomienie go w tym samym zadaniu co nadrzędny element Runbook. W historii zadań podrzędnego elementu Runbook nie ma żadnych wskazówek. Wszelkie wyjątki i wszystkie dane wyjściowe strumienia z podrzędnego elementu Runbook są skojarzone z elementem nadrzędnym. To zachowanie skutkuje mniejszą liczbą zadań i ułatwia ich śledzenie i rozwiązywanie problemów.

Po opublikowaniu elementu Runbook wszystkie podrzędne elementy Runbook, które wywołuje, muszą być już opublikowane. Przyczyną jest to, że usługa Azure Automation tworzy skojarzenie z dowolnymi podrzędnymi elementami Runbook podczas kompilowania elementu Runbook. Jeśli podrzędne elementy Runbook nie zostały jeszcze opublikowane, nadrzędny element Runbook wydaje się prawidłowo publikować, ale generuje wyjątek po uruchomieniu.

Jeśli wystąpi wyjątek, możesz ponownie opublikować nadrzędny element Runbook, aby prawidłowo odwoływać się do podrzędnych elementów Runbook. Nie musisz ponownie publikować nadrzędnego elementu Runbook, jeśli jakikolwiek podrzędny element Runbook został zmieniony, ponieważ skojarzenie zostało już utworzone.

Parametry podrzędnego elementu Runbook nazywanego wbudowanym mogą być dowolnym typem danych, w tym obiektami złożonymi. Nie ma serializacji JSON, tak jak podczas uruchamiania elementu Runbook przy użyciu witryny Azure Portal lub za pomocą polecenia cmdlet Start-AzAutomationRunbook .

Typy elementów Runbook

Obecnie program PowerShell 5.1 jest obsługiwany i tylko niektóre typy elementów Runbook mogą wywoływać siebie nawzajem:

  • Element Runbook programu PowerShell i graficzny element Runbook mogą wywoływać siebie w tekście, ponieważ oba są oparte na programie PowerShell.
  • Element Runbook przepływu pracy programu PowerShell i graficzny element Runbook przepływu pracy programu PowerShell mogą wywoływać siebie w tekście, ponieważ oba są oparte na przepływie pracy programu PowerShell.
  • Typy programu PowerShell i typy przepływów pracy programu PowerShell nie mogą wywoływać siebie w tekście. Muszą używać polecenia Start-AzAutomationRunbook.

Ważne

Wykonywanie skryptów podrzędnych przy użyciu polecenia .\child-runbook.ps1 nie jest obsługiwane w programach PowerShell 7.1 i PowerShell 7.2 Obejście: użyj Start-AutomationRunbook (wewnętrznego polecenia cmdlet) lub Start-AzAutomationRunbook (z modułu Az.Automation ), aby uruchomić inny element Runbook z nadrzędnego elementu Runbook.

Kolejność publikowania elementów Runbook ma znaczenie tylko dla przepływów pracy programu PowerShell i graficznych elementów Runbook przepływu pracy programu PowerShell.

Gdy element Runbook wywołuje element runbook podrzędny przepływu pracy programu PowerShell lub graficzny lub podrzędny element Runbook przy użyciu wykonywania wbudowanego, używa nazwy elementu Runbook. Nazwa musi zaczynać się od .\\ , aby określić, że skrypt znajduje się w katalogu lokalnym.

Przykład

Poniższy przykład uruchamia testowy podrzędny element Runbook, który akceptuje złożony obiekt, wartość całkowitą i wartość logiczną. Dane wyjściowe podrzędnego elementu Runbook są przypisywane do zmiennej. W takim przypadku podrzędny element Runbook jest elementem Runbook przepływu pracy programu PowerShell.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = PSWF-ChildRunbook -VM $vm -RepeatCount 2 -Restart $true

Oto ten sam przykład, ale używanie elementu Runbook programu PowerShell jako elementu podrzędnego.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = .\PS-ChildRunbook.ps1 -VM $vm -RepeatCount 2 -Restart $true

Uruchamianie podrzędnego elementu Runbook przy użyciu polecenia cmdlet

Ważne

Jeśli element Runbook wywołuje podrzędny element Runbook przy użyciu Start-AzAutomationRunbook polecenia cmdlet z parametrem Wait , a podrzędny element Runbook generuje wynik obiektu, operacja może napotkać błąd. Aby obejść ten błąd, zobacz Podrzędne elementy Runbook z danymi wyjściowymi obiektu. W tym artykule pokazano, jak zaimplementować logikę do sondowania wyników przy użyciu polecenia cmdlet Get-AzAutomationJobOutputRecord .

Możesz użyć Start-AzAutomationRunbook polecenia , aby uruchomić element Runbook zgodnie z opisem w temacie Uruchamianie elementu Runbook przy użyciu programu Windows PowerShell. Istnieją dwa tryby użycia dla tego polecenia cmdlet:

  • Polecenie cmdlet zwraca identyfikator zadania podczas tworzenia zadania podrzędnego elementu Runbook.
  • Polecenie cmdlet czeka na zakończenie podrzędnego zadania i zwraca dane wyjściowe z podrzędnego elementu Runbook. Skrypt włącza ten tryb, określając Wait parametr .

Zadanie podrzędnego elementu Runbook uruchomione za pomocą polecenia cmdlet jest uruchamiane oddzielnie od nadrzędnego zadania elementu Runbook. To zachowanie powoduje więcej zadań niż uruchomienie wbudowanego elementu Runbook i utrudnia śledzenie zadań. Element nadrzędny może uruchomić więcej niż jeden podrzędny element Runbook asynchronicznie bez oczekiwania na zakończenie każdego elementu runbook. W przypadku tego równoległego wykonywania wywołującego podrzędne elementy Runbook w tekście nadrzędny element Runbook musi używać słowa kluczowego równoległego.

Podrzędne dane wyjściowe elementu Runbook nie zwracają się niezawodnie do nadrzędnego elementu Runbook z powodu chronometrażu. Ponadto, $VerbosePreference, $WarningPreferencei inne zmienne mogą nie być propagowane do podrzędnych elementów Runbook. Aby uniknąć tych problemów, możesz uruchomić podrzędne elementy Runbook jako oddzielne zadania automatyzacji przy użyciu Start-AzAutomationRunbook parametru Wait . Ta technika blokuje nadrzędny element Runbook do momentu zakończenia podrzędnego elementu Runbook.

Jeśli nie chcesz, aby nadrzędny element Runbook był blokowany podczas oczekiwania, możesz uruchomić podrzędny element Runbook przy użyciu Start-AzAutomationRunbook polecenia bez parametru Wait . W takim przypadku element Runbook musi użyć polecenia Get-AzAutomationJob , aby poczekać na ukończenie zadania. Aby pobrać wyniki, należy również użyć polecenia Get-AzAutomationJobOutput i Get-AzAutomationJobOutputRecord .

Parametry podrzędnego elementu Runbook uruchomionego przy użyciu polecenia cmdlet są dostarczane jako tabela skrótów, zgodnie z opisem w temacie Parametry elementu Runbook. Można używać tylko prostych typów danych. Jeśli element Runbook ma parametr ze złożonym typem danych, musi być wywoływany w tekście.

Kontekst subskrypcji może zostać utracony podczas uruchamiania podrzędnych elementów Runbook jako oddzielnych zadań. Aby podrzędny element Runbook wykonywał polecenia cmdlet modułu Az dla określonej subskrypcji platformy Azure, element podrzędny musi uwierzytelniać się w tej subskrypcji niezależnie od nadrzędnego elementu Runbook.

Jeśli zadania w ramach tego samego konta usługi Automation działają z więcej niż jedną subskrypcją, wybranie subskrypcji w jednym zadaniu może zmienić aktualnie wybrany kontekst subskrypcji dla innych zadań. Aby uniknąć tej sytuacji, należy użyć Disable-AzContextAutosave -Scope Process na początku każdego elementu Runbook. Ta akcja zapisuje tylko kontekst w tym wykonaniu elementu Runbook.

Przykład

Poniższy przykład uruchamia podrzędny element Runbook z parametrami, a następnie czeka na jego zakończenie przy użyciu Start-AzAutomationRunbook polecenia cmdlet z parametrem Wait . Po zakończeniu podrzędnego elementu Runbook przykład zbiera dane wyjściowe polecenia cmdlet z podrzędnego elementu Runbook. Aby użyć Start-AzAutomationRunbookpolecenia , skrypt musi uwierzytelnić się w ramach subskrypcji platformy Azure.

# Ensure that the runbook does not inherit an AzContext
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

$params = @{"VMName"="MyVM";"RepeatCount"=2;"Restart"=$true}

Start-AzAutomationRunbook `
    -AutomationAccountName 'MyAutomationAccount' `
    -Name 'Test-ChildRunbook' `
    -ResourceGroupName 'LabRG' `
    -DefaultProfile $AzureContext `
    -Parameters $params -Wait

Jeśli chcesz, aby element Runbook był wykonywany przy użyciu tożsamości zarządzanej przypisanej przez system, pozostaw kod w stanie rzeczywistym. Jeśli wolisz użyć tożsamości zarządzanej przypisanej przez użytkownika, wykonaj:

  1. Z wiersza 5 usuń $AzureContext = (Connect-AzAccount -Identity).contextelement ,
  2. Zastąp go ciągiem $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, i
  3. Wprowadź identyfikator klienta.

Następne kroki