Konfigurera runbook-utdata och meddelandeströmmar
De flesta Azure Automation-runbooks har någon form av utdata. Det här utdata kan vara ett felmeddelande till användaren eller ett komplext objekt som är avsett att användas med en annan runbook. Windows PowerShell tillhandahåller flera strömmar för att skicka utdata från ett skript eller arbetsflöde. Azure Automation fungerar med var och en av dessa strömmar på olika sätt. Du bör följa metodtipsen för att använda strömmarna när du skapar en runbook.
I följande tabell beskrivs kortfattat varje ström med dess beteende i Azure Portal för publicerade runbooks och under testning av en runbook. Utdataströmmen är huvudströmmen som används för kommunikation mellan runbooks. De andra strömmarna klassificeras som meddelandeströmmar som är avsedda att förmedla information till användaren.
| Stream | beskrivning | Publicerad | Test |
|---|---|---|---|
| Fel | Felmeddelande avsett för användaren. Till skillnad från ett undantag fortsätter runbooken efter ett felmeddelande som standard. | Skrivet till jobbhistorik | Visas i testutdatafönstret |
| Felsöka | Meddelanden avsedda för en interaktiv användare. Bör inte användas i runbooks. | Skrivs inte till jobbhistorik | Visas inte i testutdatafönstret |
| Output | Objekt som är avsedda att användas av andra runbooks. | Skrivet till jobbhistorik | Visas i testutdatafönstret |
| Förlopp | Poster som genereras automatiskt före och efter varje aktivitet i runbooken. Runbooken bör inte försöka skapa egna förloppsposter eftersom de är avsedda för en interaktiv användare. | Skrivs endast till jobbhistorik om förloppsloggning är aktiverat för runbooken | Visas inte i testutdatafönstret |
| Utförlig | Meddelanden som ger allmän information eller felsökningsinformation. | Skrivs endast till jobbhistorik om utförlig loggning är aktiverad för runbooken | Visas endast i testutdatafönstret om VerbosePreference variabeln är inställd på Fortsätt i runbook |
| Varning | Varningsmeddelande avsett för användaren. | Skrivet till jobbhistorik | Visas i testutdatafönstret |
Använda utdataströmmen
Utdataströmmen används för utdata från objekt som skapats av ett skript eller arbetsflöde när den körs korrekt. Azure Automation använder främst den här strömmen för objekt som ska användas av överordnade runbooks som anropar den aktuella runbooken. När en överordnad anropar en runbook infogad returnerar underordnad data från utdataströmmen till den överordnade.
Din runbook använder utdataströmmen för att kommunicera allmän information till klienten endast om den aldrig anropas av en annan runbook. Som bästa praxis bör dock dina runbooks vanligtvis använda den utförliga strömmen för att kommunicera allmän information till användaren.
Låt runbooken skriva data till utdataströmmen med hjälp av Write-Output. Du kan också placera objektet på en egen rad i skriptet.
#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object
Hantera utdata från en funktion
När en runbook-funktion skriver till utdataströmmen skickas utdata tillbaka till runbooken. Om runbooken tilldelar utdata till en variabel skrivs inte utdata till utdataströmmen. Skriva till andra strömmar inifrån funktionen skriver till motsvarande dataström för runbooken. Överväg följande powershell-arbetsflödeskörningsexempel.
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"
}
}
Utdataströmmen för runbook-jobbet är:
Output inside of function
Output outside of function
Den utförliga strömmen för runbook-jobbet är:
Verbose outside of function
Verbose inside of function
När du har publicerat runbooken och innan du startar den måste du också aktivera utförlig loggning i runbook-inställningarna för att få utförliga strömutdata.
Deklarera utdatatyp
Följande är exempel på utdatatyper:
System.StringSystem.Int32System.Collections.HashtableMicrosoft.Azure.Commands.Compute.Models.PSVirtualMachine
Deklarera datatypen utdata i ett arbetsflöde
Ett arbetsflöde anger datatypen för dess utdata med hjälp av attributet OutputType. Det här attributet har ingen effekt under körningen, men det ger dig en indikation vid designtillfället för de förväntade utdata från runbooken. När verktygsuppsättningen för runbooks fortsätter att utvecklas ökar vikten av att deklarera utdatatyper vid designtillfället. Därför är det bästa praxis att inkludera den här deklarationen i alla runbooks som du skapar.
Följande exempel-runbook matar ut ett strängobjekt och innehåller en deklaration av dess utdatatyp. Om runbooken matar ut en matris av en viss typ bör du fortfarande ange typen i stället för en matris av typen.
Workflow Test-Runbook
{
[OutputType([string])]
$output = "This is some string output."
Write-Output $output
}
Deklarera datatypen utdata i en grafisk runbook
Om du vill deklarera en utdatatyp i en grafisk eller grafisk PowerShell Workflow-runbook kan du välja menyalternativet Indata och utdata och ange utdatatypen. Vi rekommenderar att du använder det fullständiga .NET-klassnamnet för att göra typen lätt identifierbar när en överordnad runbook refererar till den. Med det fullständiga namnet exponeras alla egenskaper för klassen för databussen i runbooken och ökar flexibiliteten när egenskaperna används för villkorsstyrd logik, loggning och refererar till som värden för andra runbook-aktiviteter.
Kommentar
När du har angett ett värde i fältet Utdatatyp i fönstret Egenskaper för indata och utdata måste du klicka utanför kontrollen så att den känner igen posten.
I följande exempel visas två grafiska runbooks för att demonstrera indata- och utdatafunktionen. Om du använder den modulära runbookdesignmodellen har du en runbook som mallen Authenticate Runbook som hanterar autentisering med Azure med hanterade identiteter. Den andra runbooken, som normalt utför kärnlogik för att automatisera ett visst scenario, kör i det här fallet mallen Authenticate Runbook. Resultatet visas i fönstret Testutdata. Under normala omständigheter skulle du låta den här runbooken göra något mot en resurs som utnyttjar utdata från den underordnade runbooken.
Här är den grundläggande logiken i Runbooken AuthenticateTo-Azure .
.
Runbooken innehåller utdatatypen Microsoft.Azure.Commands.Profile.Models.PSAzureProfile, som returnerar egenskaperna för autentiseringsprofilen.
Även om den här runbooken är enkel finns det ett konfigurationsobjekt att anropa här. Den senaste aktiviteten kör cmdleten Write-Output för att skriva profildata till en variabel med hjälp av ett PowerShell-uttryck för parametern Inputobject . Den här parametern krävs för Write-Output.
Den andra runbooken i det här exemplet, med namnet Test-ChildOutputType, definierar helt enkelt två aktiviteter.
Den första aktiviteten anropar Runbooken AuthenticateTo-Azure . Den andra aktiviteten kör cmdleten Write-Verbose med datakällan inställd på Aktivitetsutdata. Fältsökvägen är också inställd på Context.Subscription.Name, kontextutdata från Runbooken AuthenticateTo-Azure.
Resultatet är namnet på prenumerationen.
Arbeta med meddelandeströmmar
Till skillnad från utdataströmmen kommunicerar meddelandeströmmar information till användaren. Det finns flera meddelandeströmmar för olika typer av information, och Azure Automation hanterar varje dataström på olika sätt.
Skriva utdata till varnings- och felströmmar
Varnings- och felströmmar loggproblem som uppstår i en runbook. Azure Automation skriver dessa strömmar till jobbhistoriken när du kör en runbook. Automation innehåller strömmarna i fönstret Testutdata i Azure Portal när en runbook testas.
Som standard fortsätter en runbook att köras efter en varning eller ett fel. Du kan ange att runbooken ska pausas vid en varning eller ett fel genom att låta runbooken ange en inställningsvariabel innan du skapar meddelandet. Om du till exempel vill att runbooken ska pausas vid ett fel som vid ett undantag anger du variabeln ErrorActionPreference till Stoppa.
Skapa en varning eller ett felmeddelande med hjälp av cmdleten Write-Warning eller Write-Error . Aktiviteter kan också skriva till varnings- och felströmmarna.
#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."
Skriva utdata för att felsöka dataström
Azure Automation använder dataströmmen för felsökningsmeddelanden för interaktiva användare. Som standard samlar Azure Automation inte in några felsökningsströmdata, endast utdata, fel och varningsdata samlas in samt utförliga data om runbooken är konfigurerad för att avbilda den.
För att kunna samla in data från felsökningsströmmar måste du utföra två åtgärder i dina runbooks:
Ange variabeln
$GLOBAL:DebugPreference="Continue", som talar om för PowerShell att fortsätta när ett felsökningsmeddelande påträffas. Delen $GLOBAL: uppmanar PowerShell att göra detta i det globala omfånget i stället för det lokala omfång som skriptet finns i när instruktionen körs.Omdirigera felsökningsströmmen som vi inte samlar in till en ström som vi samlar in, till exempel utdata. Detta görs genom att ställa in PowerShell-omdirigering mot instruktionen som ska köras. Mer information om PowerShell-omdirigering finns i Omdirigering.
Exempel
I det här exemplet konfigureras runbooken Write-Output med hjälp av cmdletarna och Write-Debug med avsikten att mata ut två olika strömmar.
Write-Output "This is an output message."
Write-Debug "This is a debug message."
Om den här runbooken skulle köras som den är skulle utdatafönstret för runbook-jobbet strömma följande utdata:
This is an output message.
I det här exemplet konfigureras runbooken ungefär som i föregående exempel, förutom att -instruktionen $GLOBAL:DebugPreference="Continue" ingår i tillägget av 5>&1 i slutet av -instruktionen Write-Debug .
Write-Output "This is an output message."
$GLOBAL:DebugPreference="Continue"
Write-Debug "This is a debug message." 5>&1
Om den här runbooken skulle köras strömmas följande utdata i utdatafönstret för runbook-jobbet:
This is an output message.
This is a debug message.
Detta beror på att instruktionen $GLOBAL:DebugPreference="Continue" instruerar PowerShell att visa felsökningsmeddelanden, och tillägget i slutet av 5>&1 -instruktionen Write-Debug uppmanar PowerShell att omdirigera stream 5 (felsökning) till stream 1 (utdata).
Skriva utdata till utförlig ström
Den utförliga meddelandeströmmen stöder allmän information om runbook-åtgärden. Eftersom felsökningsströmmen inte är tillgänglig för en runbook bör runbooken använda utförliga meddelanden för felsökningsinformation.
Som standard lagrar jobbhistoriken inte utförliga meddelanden från publicerade runbooks av prestandaskäl. Om du vill lagra utförliga meddelanden använder du fliken Azure Portal Konfigurera med inställningen Log Verbose Records för att konfigurera publicerade runbooks för att logga utförliga meddelanden. Aktivera det här alternativet bara för att felsöka eller felsöka en runbook. I de flesta fall bör du behålla standardinställningen att inte logga utförliga poster.
När du testar en runbook visas inte utförliga meddelanden även om runbooken har konfigurerats för att logga utförliga poster. Om du vill visa utförliga meddelanden när du testar en runbook måste du ange variabeln VerbosePreference till Fortsätt. Med den variabeluppsättningen visas utförliga meddelanden i fönstret Testa utdata i Azure Portal.
Följande kod skapar ett utförligt meddelande med cmdleten Write-Verbose .
#The following line creates a verbose message.
Write-Verbose -Message "This is a verbose message."
Hantera förloppsposter
Du kan använda fliken Konfigurera i Azure Portal för att konfigurera en runbook för att logga förloppsposter. Standardinställningen är att inte logga posterna för att maximera prestanda. I de flesta fall bör du behålla standardinställningen. Aktivera det här alternativet bara för att felsöka eller felsöka en runbook.
Om du aktiverar loggning av förloppsposter skriver runbooken en post till jobbhistoriken före och efter att varje aktivitet körs. När du testar en runbook visas inte förloppsmeddelanden även om runbooken har konfigurerats för att logga förloppsposter.
Kommentar
Cmdleten Write-Progress är inte giltig i en runbook eftersom den här cmdleten är avsedd att användas med en interaktiv användare.
Arbeta med inställningsvariabler
Du kan ange vissa Windows PowerShell-inställningsvariabler i dina runbooks för att styra svaret på data som skickas till olika utdataströmmar. I följande tabell visas de inställningsvariabler som kan användas i runbooks, med deras standardvärden och giltiga värden. Ytterligare värden är tillgängliga för inställningsvariablerna när de används i Windows PowerShell utanför Azure Automation.
| Olika | Standardvärde | Giltiga värden |
|---|---|---|
WarningPreference |
Fortsätt | Stoppa Fortsätt TystKontinuera |
ErrorActionPreference |
Fortsätt | Stoppa Fortsätt TystKontinuera |
VerbosePreference |
TystKontinuera | Stoppa Fortsätt TystKontinuera |
I nästa tabell visas beteendet för de inställningsvariabelvärden som är giltiga i runbooks.
| Värde | Funktionssätt |
|---|---|
| Fortsätt | Loggar meddelandet och fortsätter att köra runbooken. |
| TystKontinuera | Fortsätter att köra runbooken utan att logga meddelandet. Det här värdet innebär att meddelandet ignoreras. |
| Stoppa | Loggar meddelandet och pausar runbooken. |
Hämtar runbook-utdata och -meddelanden
Hämta runbook-utdata och meddelanden i Azure Portal
Du kan visa information om ett runbook-jobb i Azure Portal med hjälp av fliken Jobb för runbooken. Jobbsammanfattningen visar indataparametrarna och utdataströmmen, förutom allmän information om jobbet och eventuella undantag som har inträffat. Jobbhistoriken innehåller meddelanden från utdataströmmen och varnings- och felströmmar. Den innehåller också meddelanden från utförliga dataströmmar och förloppsposter om runbooken är konfigurerad för att logga utförliga och förloppsposter.
Kommentar
Jobbströmmar för Python-runbooks stöds för närvarande för utdata på engelska.
Hämta runbook-utdata och meddelanden i Windows PowerShell
I Windows PowerShell kan du hämta utdata och meddelanden från en runbook med hjälp av cmdleten Get-AzAutomationJobOutput . Den här cmdleten kräver jobbets ID och har en parameter med namnet Stream där du kan ange vilken dataström som ska hämtas. Du kan ange värdet Alla för den här parametern för att hämta alla strömmar för jobbet.
I följande exempel startas en exempel-runbook och väntar sedan på att den ska slutföras. När runbooken har slutfört körningen samlar skriptet in runbook-utdataströmmen från jobbet.
$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
Hämta runbook-utdata och meddelanden i grafiska runbooks
För grafiska runbooks är extra loggning av utdata och meddelanden tillgänglig i form av spårning på aktivitetsnivå. Det finns två nivåer av spårning: Basic och Detailed. Grundläggande spårning visar start- och sluttiden för varje aktivitet i runbooken, plus information om eventuella aktivitetsförsök. Några exempel är antalet försök och aktivitetens starttid. Detaljerad spårning innehåller grundläggande spårningsfunktioner samt loggning av indata och utdata för varje aktivitet.
För närvarande skriver spårning på aktivitetsnivå poster med hjälp av den utförliga strömmen. Därför måste du aktivera utförlig loggning när du aktiverar spårning. För grafiska runbooks med spårning aktiverat behöver du inte logga förloppsposter. Grundläggande spårning har samma syfte och är mer informativt.
Du kan se från bilden att aktivering av utförlig loggning och spårning för grafiska runbooks gör mycket mer information tillgänglig i vyn Jobbströmmar för produktion. Den här extra informationen kan vara nödvändig för att felsöka produktionsproblem med en runbook.
Men om du inte behöver den här informationen för att spåra förloppet för en runbook för felsökning, kanske du vill fortsätta spåra inaktiverad som en allmän praxis. Spårningsposterna kan vara särskilt många. Med grafisk runbookspårning kan du få två till fyra poster per aktivitet, beroende på konfigurationen av Grundläggande eller Detaljerad spårning.
Så här aktiverar du spårning på aktivitetsnivå:
Öppna ditt Automation-konto på Azure Portal.
Välj Runbooks under Process Automation för att öppna listan över runbooks.
På sidan Runbooks väljer du en grafisk runbook i din lista över runbooks.
Under Inställningar klickar du på Loggning och spårning.
På sidan Loggning och spårning under Log verbose records (Logga utförliga poster) klickar du på På för att aktivera utförlig loggning.
Under Spårning på aktivitetsnivå ändrar du spårningsnivån till Grundläggande eller Detaljerad, baserat på den spårningsnivå som du behöver.
Hämta runbook-utdata och meddelanden i Microsoft Azure Monitor-loggar
Azure Automation kan skicka runbook-jobbstatus och jobbströmmar till din Log Analytics-arbetsyta. Azure Monitor stöder loggar som gör att du kan:
- Få insikt i dina Automation-jobb.
- Utlös ett e-postmeddelande eller en avisering baserat på din runbook-jobbstatus, till exempel Misslyckad eller Pausad.
- Skriva avancerade frågor mellan jobbströmmar.
- Korrelera jobb för olika Automation-konton.
- Visualisera jobbhistorik.
Mer information om hur du konfigurerar integrering med Azure Monitor-loggar för att samla in, korrelera och agera på jobbdata finns i Vidarebefordra jobbstatus och jobbströmmar från Automation till Azure Monitor-loggar.
Nästa steg
- Exempelfrågor finns i Exempelfrågor för jobbloggar och jobbströmmar
- Information om hur du arbetar med runbooks finns i Hantera runbooks i Azure Automation.
- Om du inte är bekant med PowerShell-skript kan du läsa PowerShell-dokumentationen.
- Referens för Azure Automation PowerShell-cmdlet finns i Az.Automation.