Share via

Dane wyjściowe i komunikaty elementu runbook

  • Artykuł

Ważne

Ta wersja usługi Service Management Automation (SMA) osiągnęła koniec wsparcia technicznego. Zalecamy uaktualnienie do wersji SMA 2022.

Większość elementów Runbook automatyzacji będzie mieć jakąś formę danych wyjściowych, takich jak komunikat o błędzie dla użytkownika lub złożony obiekt przeznaczony do użycia przez inny przepływ pracy. Windows PowerShell udostępnia wiele strumieni do wysyłania danych wyjściowych z przepływu pracy. Usługa Service Management Automation współdziała z poszczególnymi strumieniami w inny sposób i należy postępować zgodnie z najlepszymi rozwiązaniami dotyczącymi używania każdego elementu runbook podczas tworzenia elementu Runbook.

Poniższa tabela zawiera krótki opis każdego strumienia i ich zachowania w portalu zarządzania zarówno podczas uruchamiania opublikowanego elementu Runbook, jak i podczas testowania elementu Runbook. Dalsze szczegółowe informacje na temat każdego strumienia znajdują się w kolejnych sekcjach.

Stream Opis Opublikowany Testowanie
Dane wyjściowe Obiekty, które mają być używane przez inne elementy Runbook. Zapisywany w historii zadań. Wyświetlany w okienku danych wyjściowych testu.
Ostrzeżenie Komunikat ostrzegawczy przeznaczony dla użytkownika. Zapisywany w historii zadań. Wyświetlany w okienku danych wyjściowych testu.
Błąd Komunikat o błędzie przeznaczony dla użytkownika. Inaczej niż w przypadku wyjątku, element Runbook domyślnie kontynuuje pracę po zgłoszeniu komunikatu o błędzie. Zapisywany w historii zadań. Wyświetlany w okienku danych wyjściowych testu.
Pełny Komunikaty z informacjami ogólnymi lub dotyczącymi rozwiązywania problemów. Zapisywany w historii zadań tylko wtedy, gdy dla elementu Runbook jest włączone rejestrowanie pełne. Wyświetlane w okienku Dane wyjściowe testu tylko wtedy, gdy $VerbosePreference jest ustawiona na Pozycję Kontynuuj w elemencie Runbook.
Postęp Rekordy generowane automatycznie przed każdym działaniem w elemencie Runbook i po nim. Element Runbook nie powinien próbować tworzyć własnych rekordów postępu, ponieważ są one przeznaczone dla użytkownika interaktywnego. Zapisywany w historii zadań tylko wtedy, gdy dla elementu Runbook jest włączone rejestrowanie postępu. Nie jest wyświetlany w okienku danych wyjściowych testu.
Debugowanie Komunikaty przeznaczone dla użytkownika interaktywnego. Nie należy używać w elementach Runbook. Nie jest zapisywany w historii zadań. Nie jest zapisywany w okienku danych wyjściowych testu.

Strumień wyjściowy

Strumień wyjściowy jest przeznaczony dla danych wyjściowych obiektów utworzonych przez poprawnie działający przepływ pracy. W usłudze Automation ten strumień jest używany głównie dla obiektów przeznaczonych do użycia przez nadrzędne elementy Runbook wywołujące bieżący element Runbook. Po wywołaniu elementu Runbook wbudowanego z nadrzędnego elementu Runbook zwraca dane ze strumienia wyjściowego do elementu nadrzędnego. Strumienia wyjściowego należy używać tylko do przekazywania ogólnych informacji do użytkownika, jeśli wiadomo, że element Runbook nigdy nie zostanie wywołany przez inny element Runbook. Najlepszym rozwiązaniem jest jednak użycie Stream Verbose w celu przekazania ogólnych informacji użytkownikowi.

Dane można zapisywać w strumieniu wyjściowym przy użyciu funkcji Write-Output lub umieszczając obiekt na własnym wierszu w elemecie Runbook.

#The following lines both write an object to the output stream.
Write-Object -InputObject $object
$object

Dane wyjściowe z funkcji

Podczas zapisywania do strumienia wyjściowego w funkcji, która znajduje się w elemencie Runbook, dane wyjściowe są przekazywane z powrotem do elementu Runbook. Jeśli element Runbook przypisuje te dane wyjściowe do zmiennej, nie jest zapisywany w strumieniu wyjściowym. Zapisanie do wszelkich innych strumieni w funkcji spowoduje zapisanie do odpowiedniego strumienia elementu Runbook.

Zapoznaj się z następującym przykładowym elementem Runbook.

Workflow Test-Runbook
{
   Write-Verbose "Verbose outside of function"
   Write-Output "Output outside of function"
   $functionOutput = Test-Function

   Function Test-Function
   {
      Write-Verbose "Verbose inside of function"
      Write-Output "Output inside of function"
   }
}

Odpowiedni strumień wyjściowy dla zadania elementu Runbook:

Output outside of function

Odpowiedni strumień pełny dla zadania elementu Runbook:

Verbose outside of function
Verbose inside of function

Zmienna $functionOutput będzie mieć wartość:

Output inside of function

Deklarowanie typu danych wyjściowych

Przepływ pracy może określać typ danych wyjściowych przy użyciu atrybutu OutputType. Ten atrybut nie ma znaczenia w czasie wykonywania, ale stanowi wskazówkę dla twórcy elementu Runbook podczas projektowania informującą o oczekiwanym typie danych wyjściowych elementu Runbook. Ponieważ zestaw narzędzi dla elementów Runbook jest w dalszym ciągu rozwijany, deklarowanie typów danych wyjściowych w czasie projektowania będzie zyskiwać na znaczeniu. W rezultacie najlepszym rozwiązaniem jest dołączenie tej deklaracji do wszystkich utworzonych elementów Runbook.

Następujący przykładowy element Runbook generuje obiekt ciągu i zawiera deklarację typu jego danych wyjściowych. Jeśli element Runbook generuje tablicę pewnego typu, należy także określić typ, a nie tablicę typu.

Workflow Test-Runbook
{
   [OutputType([string])]

   $output = "This is some string output."
   Write-Output $output
}

Strumienie komunikatów

W przeciwieństwie do strumienia wyjściowego strumienie komunikatów są przeznaczone do przekazywania informacji do użytkownika. Istnieje wiele strumieni komunikatów dla różnych rodzajów informacji, a każda z nich jest obsługiwana inaczej przez usługę Automation.

Wybierz kartę wymaganą, aby dowiedzieć się więcej o tych strumieniach komunikatów:

Strumienie ostrzeżeń i błędów są przeznaczone do rejestrowania problemów występujących w elemencie Runbook. Są one zapisywane w historii zadań po wykonaniu elementu Runbook i są uwzględniane w okienku Danych wyjściowych testów w portalu zarządzania po przetestowaniu elementu Runbook. Domyślnie element Runbook kontynuuje wykonywanie po ostrzeżeniu lub błędzie. Można określić, że element Runbook powinien zostać zawieszony w ostrzeżeniu lub błędzie, ustawiając zmienną preferencji w elemecie Runbook przed utworzeniem komunikatu. Aby na przykład spowodować wstrzymanie elementu Runbook na błędzie, ponieważ byłby to wyjątek, ustaw $ErrorActionPreference na Zatrzymaj.

Utwórz ostrzeżenie lub komunikat o błędzie przy użyciu polecenia cmdlet Write-Warning lub Write-Error . Działania mogą także zapisywać do tych strumieni.

#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."

Rekordy postępu

Jeśli skonfigurujesz element Runbook do rejestrowania rekordów postępu (na karcie Konfigurowanie elementu Runbook w portalu zarządzania), rekord zostanie zapisany w historii zadań przed uruchomieniem każdego działania i po nim. W większości przypadków należy zachować domyślne ustawienie elementu Runbook (tzn. bez rejestrowania rekordów postępu), aby zwiększyć wydajność. Włącz tę opcję tylko podczas rozwiązywania problemów z elementem Runbook lub jego debugowania. Podczas testowania elementu Runbook komunikaty postępu nie są wyświetlane, nawet jeśli element Runbook jest skonfigurowany do rejestrowania rekordów postępu.

Polecenie cmdlet Write-Progress nie jest prawidłowe w elemecie Runbook, ponieważ jest przeznaczone do użytku z użytkownikiem interaktywnym.

Zmienne preferencji

Windows PowerShell używa zmiennych preferencji do określenia sposobu reagowania na dane wysyłane do różnych strumieni wyjściowych. Te zmienne możesz ustawić w elemencie Runbook, aby kontrolować sposób odpowiadania przez niego na dane przesyłane do różnych strumieni.

W poniższej tabeli przedstawiono zmienne preferencji, których można użyć w elementach Runbook, oraz ich prawidłowe i domyślne wartości.

Uwaga

Ta tabela zawiera tylko wartości, które są prawidłowe w elemecie Runbook. Dodatkowe wartości są prawidłowe dla zmiennych preferencji, gdy są używane w Windows PowerShell poza usługą Service Management Automation.

Zmienna Wartość domyślna Prawidłowe wartości
WarningPreference Kontynuuj Stop
Kontynuuj
SilentlyContinue
ErrorActionPreference Kontynuuj Stop
Kontynuuj
SilentlyContinue
VerbosePreference SilentlyContinue Stop
Kontynuuj
SilentlyContinue

W poniższej tabeli przedstawiono zachowania dla 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. To powoduje zignorowanie komunikatu.
Stop Rejestruje komunikat i zawiesza element Runbook.

Pobieranie danych wyjściowych i komunikatów elementu Runbook

Portal zarządzania

Szczegóły zadania elementu Runbook można wyświetlić w portalu zarządzania na karcie Zadania elementu Runbook. W obszarze Podsumowanie zadania zostaną wyświetlone parametry wejściowe i dane wyjściowe Stream oprócz ogólnych informacji o zadaniu i wszelkich wyjątkach, jeśli wystąpiły. Historia będzie zawierać komunikaty z Stream danych wyjściowych oraz strumienie ostrzeżeń i błędów oprócz pełnychStream i rekordów postępu, jeśli element Runbook jest skonfigurowany do rejestrowania pełnych i postępu rekordów.

Windows PowerShell

W Windows PowerShell można pobrać dane wyjściowe i komunikaty z elementu Runbook przy użyciu polecenia cmdlet Get-SmaJobOutput. To polecenie cmdlet wymaga identyfikatora zadania i ma parametr o nazwie Stream, w którym określasz, który strumień ma być zwracany. Można określić dowolne , aby zwrócić wszystkie strumienie dla zadania.

W poniższym przykładzie jest uruchamiany przykładowy element Runbook, a następnie kod czeka na jego zakończenie. Po zakończeniu jego strumień wyjściowy jest zbierany z zadania.

$webServer = 'https://MyServer'
$port = 9090
$runbookName = "Test-Runbook"
$job = Start-SmaRunbook -WebServiceEndpoint $webServer -Port $port -Name $runbookName

$doLoop = $true
While ($doLoop) {
   $job = Get-SmaJob -WebServiceEndpoint $webServer -Port $port -Id $job.Id
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped")
}

Get-SmaJobOutput -WebServiceEndpoint $webServer -Port $port -Id $job.Id -Stream Output

Następne kroki

Tworzenie elementów Runbook automatyzacji.