Konfigurace výstupu runbooku a datových proudů zpráv
Většina runbooků Azure Automation má určitou formu výstupu. Tento výstup může být chybovou zprávou pro uživatele nebo komplexní objekt určený k použití s jiným runbookem. Windows PowerShell poskytuje více datových proudů pro odesílání výstupu ze skriptu nebo pracovního postupu. Azure Automation pracuje s každým z těchto datových proudů odlišně. Při vytváření runbooku byste měli dodržovat osvědčené postupy pro používání datových proudů.
Následující tabulka stručně popisuje každý datový proud s jeho chováním na webu Azure Portal pro publikované runbooky a během testování runbooku. Výstupní datový proud je hlavní datový proud používaný ke komunikaci mezi runbooky. Ostatní datové proudy jsou klasifikovány jako datové proudy zpráv, jejichž účelem je sdělit informace uživateli.
| Stream | Popis | Publikováno | Test |
|---|---|---|---|
| Chyba | Chybová zpráva určená pro uživatele Na rozdíl od výjimky runbook ve výchozím nastavení pokračuje za chybovou zprávou. | Zápis do historie úloh | Zobrazeno v podokně výstupu testu |
| Ladění | Zprávy určené pro interaktivního uživatele V runboocích by se nemělo používat. | Nezapisuje se do historie úloh. | Nezobrazuje se v podokně výstupu testu |
| Výstup | Objekty, které mají být spotřebovány jinými runbooky. | Zápis do historie úloh | Zobrazeno v podokně výstupu testu |
| Průběh | Záznamy se automaticky generují před a po každé aktivitě v runbooku. Runbook by se neměl pokoušet vytvářet vlastní záznamy o průběhu, protože jsou určené pro interaktivního uživatele. | Zapsáno do historie úloh pouze v případě, že je protokolování průběhu pro runbook zapnuté | Nezobrazuje se v podokně výstupu testu |
| Podrobnosti | Zprávy, které poskytují obecné nebo ladicí informace. | Zápis do historie úloh pouze v případě, že je pro runbook zapnuté podrobné protokolování | Zobrazí se v podokně výstupu testu pouze v případě, že VerbosePreference je proměnná nastavená na Pokračovat v runbooku. |
| Upozorňující | Zpráva s upozorněním určená pro uživatele | Zápis do historie úloh | Zobrazeno v podokně výstupu testu |
Použití výstupního streamu
Výstupní datový proud se používá pro výstup objektů vytvořených skriptem nebo pracovním postupem při správném spuštění. Azure Automation primárně používá tento datový proud pro objekty, které budou využívat nadřazené runbooky, které volají aktuální runbook. Když nadřazený objekt volá vložený runbook, vrátí podřízená data z výstupního datového proudu do nadřazeného objektu.
Runbook používá výstupní datový proud ke komunikaci obecných informací klientovi pouze v případě, že ho nikdy nevolá jiný runbook. Osvědčeným postupem je ale, že runbooky by obvykle měly používat podrobný datový proud ke sdělení obecných informací uživateli.
Dejte runbooku zapisovat data do výstupního datového proudu pomocí write-output. Případně můžete objekt umístit na vlastní řádek ve skriptu.
#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object
Zpracování výstupu z funkce
Když funkce runbooku zapíše výstupní datový proud, předá se výstup zpět do runbooku. Pokud runbook tento výstup přiřadí proměnné, výstup se do výstupního datového proudu nezapíše. Zápis do všech ostatních datových proudů z funkce zapisuje do odpovídajícího datového proudu runbooku. Představte si následující ukázkový runbook pracovního postupu PowerShellu.
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"
}
}
Výstupní datový proud úlohy runbooku je:
Output inside of function
Output outside of function
Podrobný datový proud pro úlohu runbooku je:
Verbose outside of function
Verbose inside of function
Jakmile runbook publikujete a než ho spustíte, musíte také zapnout podrobné protokolování v nastavení runbooku, abyste získali podrobný výstup datového proudu.
Deklarace výstupního datového typu
Tady jsou příklady výstupních datových typů:
System.StringSystem.Int32System.Collections.HashtableMicrosoft.Azure.Commands.Compute.Models.PSVirtualMachine
Deklarace výstupního datového typu v pracovním postupu
Pracovní postup určuje datový typ výstupu pomocí atributu OutputType. Tento atribut nemá žádný vliv během běhu, ale poskytuje indikaci v době návrhu očekávaného výstupu runbooku. Vzhledem k tomu, že sada nástrojů pro runbooky se stále vyvíjí, zvyšuje se důležitost deklarování výstupních datových typů v době návrhu. Proto je osvědčeným postupem zahrnout tuto deklaraci do všech runbooků, které vytvoříte.
Následující ukázkový runbook zobrazí výstup řetězcového objektu a obsahuje deklaraci jeho výstupního typu. Pokud runbook vypíše pole určitého typu, měli byste typ zadat na rozdíl od pole typu.
Workflow Test-Runbook
{
[OutputType([string])]
$output = "This is some string output."
Write-Output $output
}
Deklarace výstupního datového typu v grafickém runbooku
Pokud chcete deklarovat typ výstupu v grafickém nebo grafickém runbooku pracovního postupu PowerShellu, můžete vybrat možnost nabídky Vstup a výstup a zadat typ výstupu. Doporučuje se použít úplný název třídy .NET, aby byl typ snadno identifikovatelný, když na něj odkazuje nadřazený runbook. Použití úplného názvu zpřístupňuje všechny vlastnosti třídy datovému sběrnici v runbooku a zvyšuje flexibilitu při použití vlastností pro podmíněnou logiku, protokolování a odkazování jako hodnoty pro jiné aktivity runbooku.
Poznámka:
Po zadání hodnoty do pole Typ výstupu v podokně vlastností Vstup a Výstup nezapomeňte kliknout mimo ovládací prvek, aby rozpoznal vaši položku.
Následující příklad ukazuje dva grafické runbooky, které demonstrují funkci Vstup a výstup. Při použití modelu návrhu modulárního runbooku máte jeden runbook jako šablonu ověřování runbooku, která spravuje ověřování pomocí Azure pomocí spravovaných identit. Druhý runbook, který obvykle provádí základní logiku pro automatizaci daného scénáře, v tomto případě spustí šablonu authenticate Runbook. Zobrazí výsledky v podokně výstupu testu. Za normálních okolností byste měli mít tento runbook něco proti prostředku, který využívá výstup z podřízeného runbooku.
Tady je základní logika runbooku AuthenticateTo-Azure .
.
Runbook obsahuje výstupní typ Microsoft.Azure.Commands.Profile.Models.PSAzureProfile, který vrací vlastnosti profilu ověřování.
I když je tento runbook jednoduchý, tady je jedna položka konfigurace, kterou je potřeba volat. Poslední aktivita spustí rutinu Write-Output pro zápis dat profilu do proměnné pomocí výrazu PowerShellu Inputobject pro parametr. Tento parametr je vyžadován pro Write-Output.
Druhý runbook v tomto příkladu s názvem Test-ChildOutputType jednoduše definuje dvě aktivity.
První aktivita volá runbook AuthenticateTo-Azure . Druhá aktivita spustí rutinu Write-Verbose se zdrojem dat nastaveným na výstup aktivity. Cesta pole je také nastavena na Context.Subscription.Name, kontextový výstup z runbooku AuthenticateTo-Azure.
Výsledný výstup je název předplatného.
Práce se streamy zpráv
Na rozdíl od výstupního datového proudu streamy zpráv komunikují s uživatelem informace. Existuje několik datových proudů zpráv pro různé druhy informací a Azure Automation zpracovává každý datový proud jinak.
Zápis výstupu do upozornění a chybových datových proudů
Upozornění a chybové streamy protokolují problémy, ke kterým dochází v runbooku. Azure Automation tyto streamy zapisuje do historie úloh při spouštění runbooku. Automatizace zahrnuje datové proudy v podokně Výstup testu na webu Azure Portal při testování runbooku.
Runbook se ve výchozím nastavení bude spouštět i po upozornění nebo chybě. Pokud chcete před vytvořením zprávy nastavit proměnnou předvoleb, můžete určit, že by se sada Runbook měla pozastavit u upozornění nebo chyby. Pokud například chcete, aby se runbook pozastavil při chybě, protože se jedná o výjimku, nastavte ErrorActionPreference proměnnou na Zastavit.
Vytvořte upozornění nebo chybovou zprávu pomocí rutiny Write-Warning nebo Write-Error . Aktivity můžou také zapisovat do datových proudů upozornění a chyb.
#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."
Zápis výstupu do streamu ladění
Azure Automation používá stream zpráv ladění pro interaktivní uživatele. Azure Automation ve výchozím nastavení nezachytí žádná data streamu ladění, zachytí se pouze výstupní data, chyba a upozornění a také podrobná data, pokud je runbook nakonfigurovaný tak, aby je zachytil.
Abyste mohli zachytit data streamu ladění, musíte v runboocích provádět dvě akce:
Nastavte proměnnou
$GLOBAL:DebugPreference="Continue", která říká PowerShellu, aby pokračoval při každém zjištění ladicí zprávy. Část $GLOBAL: říká PowerShellu, aby to udělal v globálním oboru, nikoli v místním oboru, ve které je skript v době spuštění příkazu.Přesměrujte ladicí stream, který nezachytáváme, na stream, který zachytáváme, jako je výstup. To se provádí nastavením přesměrování PowerShellu na příkaz, který se má provést. Další informace o přesměrování PowerShellu najdete v tématu o přesměrování.
Příklady
V tomto příkladu je runbook nakonfigurovaný pomocí Write-Output rutin a Write-Debug rutin se záměrem výstupu dvou různých datových proudů.
Write-Output "This is an output message."
Write-Debug "This is a debug message."
Pokud by se tento runbook spustil tak, jak je, v podokně výstupu úlohy runbooku by se streamoval následující výstup:
This is an output message.
V tomto příkladu je runbook nakonfigurovaný podobně jako v předchozím příkladu, s výjimkou příkazu $GLOBAL:DebugPreference="Continue" je součástí přidání 5>&1 na konec Write-Debug příkazu.
Write-Output "This is an output message."
$GLOBAL:DebugPreference="Continue"
Write-Debug "This is a debug message." 5>&1
Pokud by se tento runbook spustil, v podokně výstupu úlohy runbooku se streamuje následující výstup:
This is an output message.
This is a debug message.
K tomu dochází, protože příkaz říká PowerShellu $GLOBAL:DebugPreference="Continue" , aby zobrazil ladicí zprávy, a přidání 5>&1 na konec Write-Debug příkazu říká PowerShellu, aby přesměrovává stream 5 (ladění) na stream 1 (výstup).
Zápis výstupu do podrobného datového proudu
Podrobný datový proud zpráv podporuje obecné informace o operaci runbooku. Vzhledem k tomu, že ladicí stream není pro runbook k dispozici, měl by runbook pro ladicí informace používat podrobné zprávy.
Ve výchozím nastavení historie úloh neukládá podrobné zprávy z publikovaných runbooků z důvodů výkonu. Pokud chcete ukládat podrobné zprávy, použijte kartu Konfigurace webu Azure Portal s nastavením Log Verbose Records (Podrobné záznamy protokolu) ke konfiguraci publikovaných runbooků pro protokolování podrobných zpráv. Tuto možnost zapněte pouze pro řešení potíží nebo ladění runbooku. Ve většiněpřípadůch
Při testování runbooku se podrobné zprávy nezobrazí ani v případě, že je runbook nakonfigurovaný tak, aby protokoloval podrobné záznamy. Pokud chcete při testování runbooku zobrazit podrobné zprávy, musíte proměnnou VerbosePreference nastavit na Continue (Pokračovat). V této sadě proměnných se podrobné zprávy zobrazí v podokně výstupu testu na webu Azure Portal.
Následující kód vytvoří podrobnou zprávu pomocí rutiny Write-Verbose .
#The following line creates a verbose message.
Write-Verbose -Message "This is a verbose message."
Zpracování záznamů průběhu
Ke konfiguraci runbooku pro protokolování záznamů průběhu můžete použít kartu Konfigurovat na webu Azure Portal. Výchozí nastavení není protokolovat záznamy, aby se maximalizoval výkon. Ve většiněpřípadůch Tuto možnost zapněte pouze pro řešení potíží nebo ladění runbooku.
Pokud povolíte protokolování záznamu průběhu, runbook zapíše záznam do historie úloh před a po každém spuštění aktivity. Testování runbooku nezobrazuje zprávy o průběhu ani v případě, že je runbook nakonfigurovaný tak, aby protokoloval záznamy průběhu.
Poznámka:
Rutina Write-Progress není v runbooku platná, protože tato rutina je určená pro interaktivního uživatele.
Práce s proměnnými předvoleb
V runboocích můžete nastavit určité proměnné předvoleb Windows PowerShellu, které řídí odpověď na data odesílaná do různých výstupních datových proudů. V následující tabulce jsou uvedeny proměnné předvoleb, které lze použít v runboocích s jejich výchozími a platnými hodnotami. Další hodnoty jsou k dispozici pro proměnné předvoleb, pokud se používají ve Windows PowerShellu mimo Azure Automation.
| Proměnná | Výchozí hodnota | Platné hodnoty |
|---|---|---|
WarningPreference |
Pokračovat | Zastavit Pokračovat SilentlyContinue |
ErrorActionPreference |
Pokračovat | Zastavit Pokračovat SilentlyContinue |
VerbosePreference |
SilentlyContinue | Zastavit Pokračovat SilentlyContinue |
Další tabulka uvádí chování hodnot proměnných předvoleb, které jsou platné v runboocích.
| Hodnota | Chování |
|---|---|
| Pokračovat | Zaprokoluje zprávu a pokračuje v provádění runbooku. |
| SilentlyContinue | Pokračuje v provádění runbooku bez protokolování zprávy. Tato hodnota má vliv na ignorování zprávy. |
| Zastavit | Zaznamená zprávu a pozastaví runbook. |
Načítání výstupu a zpráv Runbooku
Načtení výstupu a zpráv runbooku na webu Azure Portal
Podrobnosti úlohy runbooku můžete zobrazit na webu Azure Portal pomocí karty Úlohy runbooku. Souhrn úlohy zobrazuje vstupní parametry a výstupní datový proud, kromě obecných informací o úloze a všech výjimkách, ke kterým došlo. Historie úloh zahrnuje zprávy z výstupního datového proudu a upozornění a chybových proudů. Obsahuje také zprávy z podrobného datového proudu a záznamů průběhu , pokud je runbook nakonfigurovaný tak, aby protokoloval podrobné záznamy a záznamy průběhu.
Poznámka:
Streamy úloh pro runbooky Pythonu se v současné době podporují pro výstup v anglickém jazyce.
Načtení výstupu a zpráv runbooku ve Windows PowerShellu
Ve Windows PowerShellu můžete načíst výstup a zprávy z runbooku pomocí rutiny Get-AzAutomationJobOutput . Tato rutina vyžaduje ID úlohy a má parametr volaný Stream k určení datového proudu, který se má načíst. Můžete zadat hodnotu Any pro tento parametr pro načtení všech datových proudů pro úlohu.
Následující příklad spustí ukázkový runbook a pak počká, až se dokončí. Jakmile runbook dokončí provádění, skript shromáždí výstupní datový proud runbooku z úlohy.
$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
Načtení výstupu runbooku a zpráv v grafických runboocích
Pro grafické runbooky je k dispozici dodatečné protokolování výstupu a zpráv ve formě trasování na úrovni aktivity. Existují dvě úrovně trasování: Základní a Podrobné. Základní trasování zobrazuje počáteční a koncový čas pro každou aktivitu v runbooku a informace související s opakovanými pokusy o aktivity. Mezi příklady patří počet pokusů a čas zahájení aktivity. Podrobné trasování zahrnuje základní funkce trasování a protokolování vstupních a výstupních dat pro každou aktivitu.
Trasování na úrovni aktivity v současné době zapisuje záznamy pomocí podrobného datového proudu. Proto je nutné povolit podrobné protokolování při povolení trasování. U grafických runbooků s povoleným trasováním není nutné protokolovat záznamy o průběhu. Základní trasování slouží ke stejnému účelu a je informativní.
Na obrázku vidíte, že povolení podrobného protokolování a trasování pro grafické runbooky zpřístupňuje mnohem více informací v zobrazení streamů produkčních úloh. Tyto dodatečné informace můžou být nezbytné pro řešení problémů s produkčním prostředím runbooku.
Pokud ale tyto informace nepotřebujete ke sledování průběhu runbooku pro účely řešení potíží, možná budete chtít trasování vypnout jako obecný postup. Záznamy trasování můžou být zvlášť četné. Pomocí grafického trasování runbooků můžete získat dva až čtyři záznamy na aktivitu v závislosti na konfiguraci základního nebo podrobného trasování.
Povolení trasování na úrovni aktivity:
Na webu Azure Portal otevřete účet Automation.
Výběrem runbooků v části Automatizace procesů otevřete seznam runbooků.
Na stránce Runbooky vyberte ze seznamu runbooků grafický runbook.
V části Nastavení klikněte na Protokolování a trasování.
Na stránce Protokolování a trasování klikněte v části Protokol podrobné záznamy na tlačítko Zapnuto a povolte podrobné protokolování.
V části Trasování na úrovni aktivity změňte úroveň trasování na Úroveň Základní nebo Podrobná na základě požadované úrovně trasování.
Načtení výstupu a zpráv runbooku v protokolech služby Microsoft Azure Monitor
Azure Automation může odesílat stav úlohy runbooku a streamy úloh do pracovního prostoru služby Log Analytics. Azure Monitor podporuje protokoly, které umožňují:
- Získání přehledu o vašich úlohách Automation
- Aktivujte e-mail nebo upozornění na základě stavu úlohy runbooku, například Selhání nebo Pozastavení.
- Psaní pokročilých dotazů napříč datovými proudy úloh
- Korelace úloh napříč účty Automation
- Vizualizujte historii úloh.
Další informace o konfiguraci integrace s protokoly služby Azure Monitor ke shromažďování, korelaci a práci s daty úloh najdete v tématu Předávání stavu úloh a datových proudů úloh z Automation do protokolů služby Azure Monitor.
Další kroky
- Ukázkové dotazy najdete v tématu Ukázkové dotazy pro protokoly úloh a datové proudy úloh.
- Pokud chcete pracovat s runbooky, přečtěte si téma Správa runbooků ve službě Azure Automation.
- Pokud skriptování PowerShellu neznáte, prohlédni si dokumentace k PowerShellu .
- Referenční informace k rutinám Azure Automation PowerShellu najdete v tématu Az.Automation.