Konfigurowanie strumieni komunikatów i danych wyjściowych elementu Runbook
Większość elementów Runbook usługi Azure Automation ma jakąś formę danych wyjściowych. Te dane wyjściowe mogą być komunikatem o błędzie dla użytkownika lub obiektu złożonego przeznaczonego do użycia z innym elementem Runbook. Program Windows PowerShell udostępnia wiele strumieni do wysyłania danych wyjściowych ze skryptu lub przepływu pracy. Usługa Azure Automation współdziała z każdym z tych strumieni inaczej. Podczas tworzenia elementu Runbook należy postępować zgodnie z najlepszymi rozwiązaniami dotyczącymi używania strumieni.
W poniższej tabeli krótko opisano każdy strumień ze swoim zachowaniem w witrynie Azure Portal dla opublikowanych elementów Runbook i podczas testowania elementu Runbook. Strumień wyjściowy jest głównym strumieniem używanym do komunikacji między elementami Runbook. Pozostałe strumienie są klasyfikowane jako strumienie komunikatów, przeznaczone do przekazywania informacji użytkownikowi.
| Stream | opis | Opublikowany | Test |
|---|---|---|---|
| Błąd | Komunikat o błędzie przeznaczony dla użytkownika. W przeciwieństwie do wyjątku element Runbook jest domyślnie kontynuowany po komunikacie o błędzie. | Zapisano w historii zadań | Wyświetlane w okienku Danych wyjściowych testu |
| Debugowanie | Komunikaty przeznaczone dla użytkownika interakcyjnego. Nie należy używać w elementach Runbook. | Nie zapisano w historii zadań | Nie są wyświetlane w okienku Danych wyjściowych testu |
| Wyjście | Obiekty przeznaczone do korzystania z innych elementów Runbook. | Zapisano w historii zadań | Wyświetlane w okienku Danych wyjściowych testu |
| Postęp | Rekordy generowane automatycznie przed i po każdym działaniu w elemecie Runbook. Element Runbook nie powinien próbować tworzyć własnych rekordów postępu, ponieważ są one przeznaczone dla użytkownika interaktywnego. | Zapisywanie w historii zadań tylko wtedy, gdy rejestrowanie postępu jest włączone dla elementu Runbook | Nie są wyświetlane w okienku Danych wyjściowych testu |
| Pełne informacje | Komunikaty, które dają ogólne lub debugujące informacje. | Zapisywanie w historii zadań tylko wtedy, gdy pełne rejestrowanie jest włączone dla elementu Runbook | Wyświetlane w okienku Danych wyjściowych testu tylko wtedy, gdy VerbosePreference zmienna jest ustawiona na Kontynuuj w elemencie Runbook |
| Ostrzeżenie | Komunikat ostrzegawczy przeznaczony dla użytkownika. | Zapisano w historii zadań | Wyświetlane w okienku Danych wyjściowych testu |
Używanie strumienia wyjściowego
Strumień wyjściowy jest używany dla danych wyjściowych obiektów utworzonych przez skrypt lub przepływ pracy, gdy działa prawidłowo. Usługa Azure Automation używa głównie tego strumienia, aby obiekty używane przez nadrzędne elementy Runbook wywołujące bieżący element Runbook. Gdy element nadrzędny wywołuje element Runbook w tekście, element podrzędny zwraca dane ze strumienia wyjściowego do elementu nadrzędnego.
Element Runbook używa strumienia wyjściowego do przekazywania informacji ogólnych do klienta tylko wtedy, gdy nigdy nie jest wywoływany przez inny element Runbook. Najlepszym rozwiązaniem jest jednak użycie pełnego strumienia elementów Runbook do przekazywania ogólnych informacji użytkownikowi.
Za pomocą funkcji Write-Output element Runbook zapisz dane w strumieniu wyjściowym. Alternatywnie można umieścić obiekt we własnym wierszu w skrycie.
#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object
Obsługa danych wyjściowych z funkcji
Gdy funkcja runbook zapisuje w strumieniu wyjściowym, dane wyjściowe są przekazywane z powrotem do elementu Runbook. Jeśli element Runbook przypisze te dane wyjściowe do zmiennej, dane wyjściowe nie są zapisywane w strumieniu wyjściowym. Zapisywanie w innych strumieniach z poziomu funkcji zapisuje odpowiedni strumień dla elementu Runbook. Rozważmy następujący przykładowy element Runbook przepływu pracy programu PowerShell.
Workflow Test-Runbook
{
Write-Verbose "Verbose outside of function" -Verbose
Write-Output "Output outside of function"
$functionOutput = Test-Function
$functionOutput
Function Test-Function
{
Write-Verbose "Verbose inside of function" -Verbose
Write-Output "Output inside of function"
}
}
Strumień wyjściowy zadania elementu Runbook to:
Output inside of function
Output outside of function
Pełny strumień zadania elementu Runbook to:
Verbose outside of function
Verbose inside of function
Po opublikowaniu elementu Runbook i przed jego uruchomieniem należy również włączyć pełne rejestrowanie w ustawieniach elementu Runbook, aby uzyskać pełne dane wyjściowe strumienia.
Deklarowanie typu danych wyjściowych
Poniżej przedstawiono przykłady typów danych wyjściowych:
System.StringSystem.Int32System.Collections.HashtableMicrosoft.Azure.Commands.Compute.Models.PSVirtualMachine
Deklarowanie typu danych wyjściowych w przepływie pracy
Przepływ pracy określa typ danych wyjściowych przy użyciu atrybutu OutputType. Ten atrybut nie ma wpływu w czasie wykonywania, ale zapewnia wskazanie w czasie projektowania oczekiwanych danych wyjściowych elementu Runbook. W miarę rozwoju zestawu narzędzi dla elementów Runbook znaczenie deklarowania typów danych wyjściowych w czasie projektowania wzrasta. W związku z tym najlepszym rozwiązaniem jest uwzględnienie tej deklaracji we wszystkich utworzonych elementach Runbook.
Poniższy przykładowy element Runbook generuje obiekt ciągu i zawiera deklarację typu danych wyjściowych. Jeśli element Runbook generuje tablicę określonego typu, nadal należy określić typ, w przeciwieństwie do tablicy typu.
Workflow Test-Runbook
{
[OutputType([string])]
$output = "This is some string output."
Write-Output $output
}
Deklarowanie typu danych wyjściowych w graficznym elemecie Runbook
Aby zadeklarować typ danych wyjściowych w graficznych lub graficznych elementach Runbook przepływu pracy programu PowerShell, możesz wybrać opcję menu Dane wejściowe i wyjściowe i wprowadzić typ danych wyjściowych. Zaleca się użycie pełnej nazwy klasy platformy .NET w celu łatwego zidentyfikowania typu, gdy nadrzędny element Runbook odwołuje się do niego. Użycie pełnej nazwy uwidacznia wszystkie właściwości klasy do magistrali danych w elemencie Runbook i zwiększa elastyczność, gdy właściwości są używane do logiki warunkowej, rejestrowania i odwoływania się jako wartości dla innych działań elementu Runbook.
Uwaga
Po wprowadzeniu wartości w polu Typ danych wyjściowych w okienku Właściwości wejściowe i wyjściowe należy kliknąć poza kontrolką, aby rozpoznać wpis.
W poniższym przykładzie przedstawiono dwa graficzne elementy Runbook, aby zademonstrować funkcję Input (Dane wejściowe) i Output (Dane wyjściowe). Zastosowanie modułowego modelu projektowego elementu Runbook umożliwia użycie jednego elementu Runbook jako szablonu uwierzytelniania elementu Runbook do zarządzania uwierzytelnianiem za pomocą platformy Azure przy użyciu tożsamości zarządzanych. Drugi element Runbook, który zwykle wykonuje podstawową logikę w celu zautomatyzowania danego scenariusza, w tym przypadku wykonuje szablon Uwierzytelnij element Runbook. Spowoduje to wyświetlenie wyników w okienku Danych wyjściowych testu. W normalnych okolicznościach ten element Runbook wykonuje coś w stosunku do zasobu wykorzystującego dane wyjściowe z podrzędnego elementu Runbook.
Oto podstawowa logika elementu Runbook AuthenticateTo-Azure .
.
Element Runbook zawiera typ Microsoft.Azure.Commands.Profile.Models.PSAzureProfiledanych wyjściowych, który zwraca właściwości profilu uwierzytelniania.
Chociaż ten element Runbook jest prosty, istnieje jeden element konfiguracji do wywołania tutaj. Ostatnie działanie wykonuje polecenie cmdlet, Write-Output aby zapisywać dane profilu w zmiennej przy użyciu wyrażenia programu PowerShell dla parametru Inputobject . Ten parametr jest wymagany dla elementu Write-Output.
Drugi element Runbook w tym przykładzie o nazwie Test-ChildOutputType po prostu definiuje dwa działania.
Pierwsze działanie wywołuje element Runbook AuthenticateTo-Azure . Drugie działanie uruchamia Write-Verbose polecenie cmdlet z ustawieniem Źródło danych na dane wyjściowe działania. Ponadto ścieżka pola jest ustawiona na Context.Subscription.Name, czyli dane wyjściowe kontekstu z elementu Runbook AuthenticateTo-Azure.
Wynikowe dane wyjściowe to nazwa subskrypcji.
Praca ze strumieniami komunikatów
W przeciwieństwie do strumienia wyjściowego strumienie komunikatów komunikują się z użytkownikiem. Istnieje wiele strumieni komunikatów dla różnych rodzajów informacji, a usługa Azure Automation obsługuje każdy strumień inaczej.
Zapisywanie danych wyjściowych w strumieniach ostrzeżeń i błędów
Ostrzeżenia i błędy przesyłają strumienie problemów dzienników występujących w elemecie Runbook. Usługa Azure Automation zapisuje te strumienie w historii zadań podczas wykonywania elementu Runbook. Automatyzacja obejmuje strumienie w okienku Dane wyjściowe testu w witrynie Azure Portal po przetestowaniu elementu Runbook.
Domyślnie element Runbook będzie nadal wykonywany po ostrzeżeniu lub błędzie. Można określić, że element Runbook powinien zostać zawieszony na ostrzeżenie lub błąd, ustawiając zmienną preferencji przed utworzeniem komunikatu. Aby na przykład spowodować wstrzymanie elementu Runbook w przypadku błędu, tak jak w przypadku wyjątku, ustaw zmienną ErrorActionPreference na Zatrzymaj.
Utwórz komunikat ostrzegawczy lub komunikat o błędzie przy użyciu polecenia cmdlet Write-Warning lub Write-Error . Działania mogą również zapisywać dane w strumieniach ostrzeżeń i błędów.
#The following lines create a warning message and then an error message that will suspend the runbook.
$ErrorActionPreference = "Stop"
Write-Warning -Message "This is a warning message."
Write-Error -Message "This is an error message that will stop the runbook because of the preference variable."
Zapisywanie danych wyjściowych w strumieniu debugowania
Usługa Azure Automation używa strumienia komunikatów debugowania dla użytkowników interakcyjnych. Domyślnie usługa Azure Automation nie przechwytuje żadnych danych strumienia debugowania, przechwytywane są tylko dane wyjściowe, błędy i ostrzeżenia, a także pełne dane, jeśli element Runbook jest skonfigurowany do przechwytywania.
Aby przechwycić dane strumienia debugowania, należy wykonać dwie akcje w elementach Runbook:
Ustaw zmienną
$GLOBAL:DebugPreference="Continue", która informuje program PowerShell o kontynuowaniu przy każdym napotkaniu komunikatu debugowania. $GLOBAL : część nakazuje programowi PowerShell wykonanie tej czynności w zakresie globalnym, a nie w zakresie lokalnym, w którym skrypt znajduje się w czasie wykonywania instrukcji.Przekieruj strumień debugowania, który nie przechwycimy do strumienia przechwyconego, takiego jak dane wyjściowe. Odbywa się to przez ustawienie przekierowania programu PowerShell względem instrukcji do wykonania. Aby uzyskać więcej informacji na temat przekierowania programu PowerShell, zobacz About Redirection (Informacje o przekierowaniu).
Przykłady
W tym przykładzie element Runbook jest skonfigurowany przy użyciu Write-Output poleceń cmdlet i Write-Debug z zamiarem wyprowadzenia dwóch różnych strumieni.
Write-Output "This is an output message."
Write-Debug "This is a debug message."
Jeśli ten element Runbook miał zostać wykonany w taki sposób, jak to jest, okienko danych wyjściowych zadania elementu Runbook będzie przesyłać strumieniowo następujące dane wyjściowe:
This is an output message.
W tym przykładzie element Runbook jest skonfigurowany podobnie do poprzedniego przykładu, z wyjątkiem instrukcji $GLOBAL:DebugPreference="Continue" dołączonej do dodawania 5>&1 na końcu instrukcji Write-Debug .
Write-Output "This is an output message."
$GLOBAL:DebugPreference="Continue"
Write-Debug "This is a debug message." 5>&1
Jeśli ten element Runbook ma zostać wykonany, okienko danych wyjściowych zadania elementu Runbook będzie przesyłać strumieniowo następujące dane wyjściowe:
This is an output message.
This is a debug message.
Dzieje się tak, ponieważ instrukcja $GLOBAL:DebugPreference="Continue" informuje program PowerShell o wyświetlaniu komunikatów debugowania, a dodanie 5>&1 do końca Write-Debug instrukcji informuje program PowerShell o przekierowaniu strumienia 5 (debugowanie) do strumienia 1 (dane wyjściowe).
Zapisywanie danych wyjściowych w strumieniu pełnym
Pełny strumień komunikatów obsługuje ogólne informacje o operacji elementu Runbook. Ponieważ strumień debugowania nie jest dostępny dla elementu Runbook, element Runbook powinien używać pełnych komunikatów na potrzeby informacji o debugowaniu.
Domyślnie historia zadań nie przechowuje pełnych komunikatów z opublikowanych elementów Runbook ze względów wydajności. Aby przechowywać pełne komunikaty, użyj karty Konfigurowanie witryny Azure Portal z ustawieniem Rejestrowanie pełnych rekordów w celu skonfigurowania opublikowanych elementów Runbook w celu rejestrowania pełnych komunikatów. Włącz tę opcję tylko w celu rozwiązywania problemów lub debugowania elementu Runbook. W większości przypadków należy zachować domyślne ustawienie nie rejestrując pełnych rekordów.
Podczas testowania elementu Runbook pełne komunikaty nie są wyświetlane, nawet jeśli element Runbook jest skonfigurowany do rejestrowania pełnych rekordów. Aby wyświetlić pełne komunikaty podczas testowania elementu Runbook, musisz ustawić zmienną na VerbosePreference Kontynuuj. Po ustawieniu tej zmiennej pełne komunikaty są wyświetlane w okienku Dane wyjściowe testu w witrynie Azure Portal.
Poniższy kod tworzy pełny komunikat przy użyciu polecenia cmdlet Write-Verbose .
#The following line creates a verbose message.
Write-Verbose -Message "This is a verbose message."
Obsługa rekordów postępu
Możesz użyć karty Konfigurowanie witryny Azure Portal, aby skonfigurować element Runbook do rejestrowania rekordów postępu. Ustawieniem domyślnym jest to, aby nie rejestrować rekordów, aby zmaksymalizować wydajność. W większości przypadków należy zachować ustawienie domyślne. Włącz tę opcję tylko w celu rozwiązywania problemów lub debugowania elementu Runbook.
Jeśli włączysz rejestrowanie rekordów postępu, element Runbook zapisuje rekord w historii zadań przed i po każdym uruchomieniu działania. Testowanie elementu Runbook nie wyświetla komunikatów postępu, nawet jeśli element Runbook jest skonfigurowany do rejestrowania rekordów postępu.
Uwaga
Polecenie cmdlet Write-Progress nie jest prawidłowe w elemecie Runbook, ponieważ to polecenie cmdlet jest przeznaczone do użycia z użytkownikiem interaktywnym.
Praca ze zmiennymi preferencji
W elementach Runbook można ustawić pewne zmienne preferencji programu Windows PowerShell, aby kontrolować odpowiedź na dane wysyłane do różnych strumieni wyjściowych. W poniższej tabeli wymieniono zmienne preferencji, które mogą być używane w elementach Runbook z ich domyślnymi i prawidłowymi wartościami. Dodatkowe wartości są dostępne dla zmiennych preferencji w przypadku użycia w programie Windows PowerShell poza usługą Azure Automation.
| Zmienna | Wartość domyślna | Prawidłowe wartości |
|---|---|---|
WarningPreference |
Kontynuuj | Zatrzymaj Kontynuuj SilentlyContinue |
ErrorActionPreference |
Kontynuuj | Zatrzymaj Kontynuuj SilentlyContinue |
VerbosePreference |
SilentlyContinue | Zatrzymaj Kontynuuj SilentlyContinue |
W następnej tabeli wymieniono zachowanie wartości zmiennych preferencji, które są prawidłowe w elementach Runbook.
| Wartość | Zachowanie |
|---|---|
| Kontynuuj | Rejestruje komunikat i kontynuuje wykonywanie elementu Runbook. |
| SilentlyContinue | Kontynuuje wykonywanie elementu Runbook bez rejestrowania komunikatu. Ta wartość ma wpływ na ignorowanie komunikatu. |
| Zatrzymaj | Rejestruje komunikat i zawiesza element Runbook. |
Pobieranie danych wyjściowych i komunikatów elementu runbook
Pobieranie danych wyjściowych i komunikatów elementu Runbook w witrynie Azure Portal
Szczegóły zadania elementu Runbook można wyświetlić w witrynie Azure Portal przy użyciu karty Zadania elementu Runbook. Podsumowanie zadania zawiera parametry wejściowe i strumień wyjściowy oprócz ogólnych informacji o zadaniu i wszelkich wyjątkach, które wystąpiły. Historia zadań zawiera komunikaty ze strumienia wyjściowego oraz strumienie ostrzeżeń i błędów. Zawiera również komunikaty ze strumienia pełnego i rekordów postępu, jeśli element Runbook jest skonfigurowany do rejestrowania pełnych i postępów rekordów.
Uwaga
Strumienie zadań dla elementów Runbook języka Python są obecnie obsługiwane dla danych wyjściowych w języku angielskim.
Pobieranie danych wyjściowych i komunikatów elementu Runbook w programie Windows PowerShell
W programie Windows PowerShell można pobierać dane wyjściowe i komunikaty z elementu Runbook przy użyciu polecenia cmdlet Get-AzAutomationJobOutput . To polecenie cmdlet wymaga identyfikatora zadania i ma parametr o nazwie Stream , w którym należy określić strumień do pobrania. Możesz określić wartość Dowolna dla tego parametru, aby pobrać wszystkie strumienie dla zadania.
Poniższy przykład uruchamia przykładowy element Runbook, a następnie czeka na jego ukończenie. Po zakończeniu wykonywania elementu Runbook skrypt zbiera strumień wyjściowy elementu Runbook z zadania.
$job = Start-AzAutomationRunbook -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook"
$doLoop = $true
While ($doLoop) {
$job = Get-AzAutomationJob -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Id $job.JobId
$status = $job.Status
$doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}
Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Output
# For more detailed job output, pipe the output of Get-AzAutomationJobOutput to Get-AzAutomationJobOutputRecord
Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Any | Get-AzAutomationJobOutputRecord
Pobieranie danych wyjściowych i komunikatów elementu Runbook w graficznych elementach Runbook
W przypadku graficznych elementów Runbook dodatkowe rejestrowanie danych wyjściowych i komunikatów jest dostępne w postaci śledzenia na poziomie działania. Istnieją dwa poziomy śledzenia: Podstawowy i Szczegółowy. Śledzenie podstawowe wyświetla czas rozpoczęcia i zakończenia dla każdego działania w elemercie Runbook oraz informacje związane z wszelkimi ponowną próbą działania. Niektóre przykłady to liczba prób i godzina rozpoczęcia działania. Szczegółowe śledzenie obejmuje podstawowe funkcje śledzenia oraz rejestrowanie danych wejściowych i wyjściowych dla każdego działania.
Obecnie śledzenie na poziomie działania zapisuje rekordy przy użyciu pełnego strumienia. W związku z tym należy włączyć pełne rejestrowanie podczas włączania śledzenia. W przypadku graficznych elementów Runbook z włączonym śledzeniem nie ma potrzeby rejestrowania rekordów postępu. Śledzenie podstawowe służy do tego samego celu i jest bardziej informacyjne.
Na obrazie można zobaczyć, że włączenie pełnego rejestrowania i śledzenia dla graficznych elementów Runbook znacznie więcej informacji jest dostępnych w widoku strumieni zadań produkcyjnych. Te dodatkowe informacje mogą być niezbędne do rozwiązywania problemów produkcyjnych z elementem Runbook.
Jednak jeśli te informacje nie są wymagane do śledzenia postępu elementu Runbook na potrzeby rozwiązywania problemów, warto zachować wyłączenie śledzenia jako ogólne rozwiązanie. Rekordy śledzenia mogą być szczególnie liczne. Dzięki graficznemu śledzeniu elementu Runbook można uzyskać od dwóch do czterech rekordów na działanie, w zależności od konfiguracji śledzenia podstawowego lub szczegółowego.
Aby włączyć śledzenie na poziomie działania:
W witrynie Azure Portal otwórz konto usługi Automation.
Wybierz pozycję Elementy Runbook w obszarze Automatyzacja procesów, aby otworzyć listę elementów Runbook.
Na stronie Elementy Runbook wybierz graficzny element Runbook z listy elementów Runbook.
W obszarze Ustawienia kliknij pozycję Rejestrowanie i śledzenie.
Na stronie Rejestrowanie i śledzenie w obszarze Pełne rekordy dziennika kliknij pozycję Włączone , aby włączyć pełne rejestrowanie.
W obszarze Śledzenie na poziomie działania zmień poziom śledzenia na Podstawowy lub Szczegółowy na podstawie wymaganego poziomu śledzenia.
Pobieranie danych wyjściowych i komunikatów elementu Runbook w dziennikach usługi Microsoft Azure Monitor
Usługa Azure Automation może wysyłać stan zadania elementu Runbook i strumienie zadań do obszaru roboczego usługi Log Analytics. Usługa Azure Monitor obsługuje dzienniki, które umożliwiają:
- Uzyskiwanie szczegółowych informacji na temat zadań usługi Automation.
- Wyzwalanie wiadomości e-mail lub alertu na podstawie stanu zadania elementu Runbook, na przykład Niepowodzenie lub Wstrzymanie.
- Pisanie zaawansowanych zapytań w strumieniach zadań.
- Korelowanie zadań z wielu kont usługi Automation.
- Wizualizowanie historii zadań.
Aby uzyskać więcej informacji na temat konfigurowania integracji z dziennikami usługi Azure Monitor w celu zbierania, korelowania i działania na danych zadań, zobacz Przekazywanie stanu zadania i strumieni zadań z usługi Automation do dzienników usługi Azure Monitor.
Następne kroki
- Aby uzyskać przykładowe zapytania, zobacz Przykładowe zapytania dotyczące dzienników zadań i strumieni zadań
- Aby pracować z elementami Runbook, zobacz Zarządzanie elementami Runbook w usłudze Azure Automation.
- Jeśli nie znasz skryptów programu PowerShell, zobacz dokumentację programu PowerShell .
- Aby zapoznać się z dokumentacją poleceń cmdlet programu PowerShell usługi Azure Automation, zobacz Az.Automation.