Runbookuitvoer- en berichtstromen configureren

  • Artikel

De meeste Azure Automation-runbooks hebben een vorm van uitvoer. Deze uitvoer kan een foutbericht zijn voor de gebruiker of een complex object dat is bedoeld voor gebruik met een ander runbook. Windows PowerShell biedt meerdere streams voor het verzenden van uitvoer van een script of werkstroom. Azure Automation werkt met elk van deze stromen anders. Volg de aanbevolen procedures voor het gebruik van de streams wanneer u een runbook maakt.

In de volgende tabel wordt elke stream kort beschreven met het gedrag ervan in Azure Portal voor gepubliceerde runbooks en tijdens het testen van een runbook. De uitvoerstroom is de hoofdstroom die wordt gebruikt voor communicatie tussen runbooks. De andere streams worden geclassificeerd als berichtstromen, bedoeld om informatie aan de gebruiker te communiceren.

Stream Omschrijving Published Testen
Fout Foutbericht dat is bedoeld voor de gebruiker. In tegenstelling tot een uitzondering wordt het runbook standaard voortgezet na een foutbericht. Geschreven naar taakgeschiedenis Weergegeven in het deelvenster Testuitvoer
Fouten opsporen Berichten die zijn bedoeld voor een interactieve gebruiker. Mag niet worden gebruikt in runbooks. Niet geschreven naar taakgeschiedenis Niet weergegeven in het deelvenster Testuitvoer
Uitvoer Objecten die zijn bedoeld om te worden gebruikt door andere runbooks. Geschreven naar taakgeschiedenis Weergegeven in het deelvenster Testuitvoer
Voortgang Registreert automatisch gegenereerd voor en na elke activiteit in het runbook. Het runbook mag geen eigen voortgangsrecords maken, omdat ze zijn bedoeld voor een interactieve gebruiker. Alleen geschreven naar taakgeschiedenis als voortgangslogboekregistratie is ingeschakeld voor het runbook Niet weergegeven in het deelvenster Testuitvoer
Uitgebreid Berichten die algemene informatie of foutopsporing geven. Alleen geschreven naar taakgeschiedenis als uitgebreide logboekregistratie is ingeschakeld voor het runbook Alleen weergegeven in het deelvenster Testuitvoer als VerbosePreference de variabele is ingesteld op Doorgaan in runbook
Waarschuwing Waarschuwingsbericht bedoeld voor de gebruiker. Geschreven naar taakgeschiedenis Weergegeven in het deelvenster Testuitvoer

De uitvoerstroom gebruiken

De uitvoerstroom wordt gebruikt voor de uitvoer van objecten die zijn gemaakt door een script of werkstroom wanneer deze correct wordt uitgevoerd. Azure Automation maakt voornamelijk gebruik van deze stroom voor objecten die worden gebruikt door bovenliggende runbooks die het huidige runbook aanroepen. Wanneer een bovenliggend item een runbook inline aanroept, retourneert het onderliggende element gegevens van de uitvoerstroom naar het bovenliggende item.

Uw runbook gebruikt de uitvoerstroom om algemene informatie alleen aan de client te communiceren als het nooit wordt aangeroepen door een ander runbook. Als best practice moeten uw runbooks echter doorgaans de uitgebreide stream gebruiken om algemene informatie aan de gebruiker te communiceren.

Laat uw runbook gegevens naar de uitvoerstroom schrijven met behulp van Write-Output. U kunt het object ook op een eigen regel in het script plaatsen.

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

Uitvoer van een functie verwerken

Wanneer een runbookfunctie naar de uitvoerstroom schrijft, wordt de uitvoer teruggegeven aan het runbook. Als het runbook die uitvoer toewijst aan een variabele, wordt de uitvoer niet naar de uitvoerstroom geschreven. Schrijven naar andere streams vanuit de functie schrijft naar de bijbehorende stream voor het runbook. Bekijk het volgende PowerShell Workflow-runbook.

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"
  }
}

De uitvoerstroom voor de runbooktaak is:

Output inside of function
Output outside of function

De uitgebreide stream voor de runbooktaak is:

Verbose outside of function
Verbose inside of function

Zodra u het runbook hebt gepubliceerd en voordat u het start, moet u ook uitgebreide logboekregistratie inschakelen in de runbookinstellingen om de uitgebreide stroomuitvoer op te halen.

Uitvoergegevenstype declareren

Hieronder ziet u voorbeelden van uitvoergegevenstypen:

  • System.String
  • System.Int32
  • System.Collections.Hashtable
  • Microsoft.Azure.Commands.Compute.Models.PSVirtualMachine

Uitvoergegevenstype declareren in een werkstroom

Een werkstroom geeft het gegevenstype van de uitvoer aan met behulp van het kenmerk OutputType. Dit kenmerk heeft geen effect tijdens runtime, maar geeft u een indicatie op het ontwerptijd van de verwachte uitvoer van het runbook. Naarmate de set hulpprogramma's voor runbooks zich blijft ontwikkelen, neemt het belang van het declareren van uitvoergegevenstypen tijdens de ontwerptijd toe. Daarom is het een best practice om deze declaratie op te nemen in runbooks die u maakt.

Het volgende voorbeeldrunbook voert een tekenreeksobject uit en bevat een declaratie van het uitvoertype. Als uw runbook een matrix van een bepaald type uitvoert, moet u nog steeds het type opgeven in plaats van een matrix van het type.

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

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

Uitvoergegevenstype declareren in een grafisch runbook

Als u een uitvoertype wilt declareren in een grafisch of grafisch PowerShell Workflow-runbook, kunt u de menuoptie Invoer en Uitvoer selecteren en het uitvoertype invoeren. Het is raadzaam om de volledige .NET-klassenaam te gebruiken om het type gemakkelijk identificeerbaar te maken wanneer een bovenliggend runbook ernaar verwijst. Als u de volledige naam gebruikt, worden alle eigenschappen van de klasse blootgesteld aan de databus in het runbook en wordt de flexibiliteit vergroot wanneer de eigenschappen worden gebruikt voor voorwaardelijke logica, logboekregistratie en verwijzingen naar waarden voor andere runbookactiviteiten.
Runbook Input and Output option

Notitie

Nadat u een waarde hebt ingevoerd in het veld Uitvoertype in het deelvenster Invoer- en uitvoereigenschappen, moet u buiten het besturingselement klikken, zodat uw invoer wordt herkend.

In het volgende voorbeeld ziet u twee grafische runbooks om de functie Invoer en Uitvoer te demonstreren. Door het modulaire runbookontwerpmodel toe te passen, hebt u één runbook als verificatiesjabloon verifiëren bij Azure met behulp van beheerde identiteiten. Het tweede runbook, dat normaal gesproken kernlogica uitvoert om een bepaald scenario te automatiseren, voert in dit geval de sjabloon Authenticate Runbook uit. De resultaten worden weergegeven in het uitvoervenster Test. Onder normale omstandigheden zou dit runbook iets doen tegen een resource die gebruikmaakt van de uitvoer van het onderliggende runbook.

Hier volgt de basislogica van het Runbook AuthenticateTo-Azure .
Authenticate Runbook Template Example.

Het runbook bevat het uitvoertype Microsoft.Azure.Commands.Profile.Models.PSAzureProfile, dat de eigenschappen van het verificatieprofiel retourneert.
Runbook Output Type Example

Hoewel dit runbook eenvoudig is, is er één configuratie-item dat u hier kunt aanroepen. Met de laatste activiteit wordt de Write-Output cmdlet uitgevoerd om profielgegevens naar een variabele te schrijven met behulp van een PowerShell-expressie voor de Inputobject parameter. Deze parameter is vereist voor Write-Output.

Het tweede runbook in dit voorbeeld met de naam Test-ChildOutputType definieert gewoon twee activiteiten.
Example Child Output Type Runbook

Met de eerste activiteit wordt het Runbook AuthenticateTo-Azure aanroepen. Met de tweede activiteit wordt de Write-Verbose cmdlet uitgevoerd met gegevensbron ingesteld op uitvoer van activiteit. Het veldpad is ook ingesteld op Context.Subscription.Name, de contextuitvoer van het Runbook AuthenticateTo-Azure.

Screenshot of write-verbose cmdlet parameter data source.

De resulterende uitvoer is de naam van het abonnement.
Test-ChildOutputType Runbook Results

Werken met berichtstromen

In tegenstelling tot de uitvoerstroom communiceren berichtstromen informatie aan de gebruiker. Er zijn meerdere berichtstromen voor verschillende soorten informatie en Azure Automation verwerkt elke stroom verschillend.

Uitvoer schrijven naar waarschuwings- en foutstromen

De waarschuwings- en foutstromen logboekproblemen die optreden in een runbook. Azure Automation schrijft deze streams naar de taakgeschiedenis bij het uitvoeren van een runbook. Automation bevat de streams in het deelvenster Testuitvoer in Azure Portal wanneer een runbook wordt getest.

Een runbook wordt standaard uitgevoerd na een waarschuwing of fout. U kunt opgeven dat uw runbook moet worden onderbroken bij een waarschuwing of fout door het runbook een voorkeursvariabele in te stellen voordat u het bericht maakt. Als u bijvoorbeeld wilt dat het runbook wordt onderbroken op een fout zoals bij een uitzondering, stelt u de ErrorActionPreference variabele in op Stoppen.

Maak een waarschuwing of foutbericht met behulp van de cmdlet Write-Warning of Write-Error . Activiteiten kunnen ook naar de waarschuwings- en foutstromen schrijven.

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

Uitvoer schrijven naar foutopsporingsstroom

Azure Automation maakt gebruik van de foutopsporingsberichtstroom voor interactieve gebruikers. Azure Automation legt standaard geen foutopsporingsgegevens vast, alleen uitvoer-, fout- en waarschuwingsgegevens worden vastgelegd, evenals uitgebreide gegevens als het runbook is geconfigureerd om deze vast te leggen.

Als u foutopsporingsgegevens wilt vastleggen, moet u twee acties uitvoeren in uw runbooks:

  1. Stel de variabele $GLOBAL:DebugPreference="Continue"in, waarmee PowerShell doorgaat wanneer er een foutopsporingsbericht wordt aangetroffen. Het $GLOBAL: in het gedeelte wordt PowerShell verteld dit te doen in het globale bereik in plaats van het lokale bereik waarin het script zich bevindt op het moment dat de instructie wordt uitgevoerd.

  2. De foutopsporingsstroom die we niet vastleggen omleiden naar een stroom die we wel vastleggen, zoals uitvoer. Dit wordt gedaan door PowerShell-omleiding in te stellen op basis van de instructie die moet worden uitgevoerd. Zie Over omleiding van PowerShell voor meer informatie over Omleiding.

Voorbeelden

In dit voorbeeld wordt het runbook geconfigureerd met behulp van de Write-Output en Write-Debug cmdlets met de bedoeling om twee verschillende streams uit te voeren.

Write-Output "This is an output message." 
Write-Debug "This is a debug message."

Als dit runbook als zodanig zou worden uitgevoerd, zou het uitvoervenster voor de runbooktaak de volgende uitvoer streamen:

This is an output message.

In dit voorbeeld is het runbook geconfigureerd zoals in het vorige voorbeeld, behalve dat de instructie $GLOBAL:DebugPreference="Continue" is opgenomen in de toevoeging aan 5>&1 het einde van de Write-Debug instructie.

Write-Output "This is an output message." 
$GLOBAL:DebugPreference="Continue" 
Write-Debug "This is a debug message." 5>&1

Als dit runbook zou worden uitgevoerd, zou het uitvoervenster voor de runbooktaak de volgende uitvoer streamen:

This is an output message.
This is a debug message.

Dit gebeurt omdat de $GLOBAL:DebugPreference="Continue" instructie Aan PowerShell vertelt dat foutopsporingsberichten moeten worden weergegeven. De toevoeging aan 5>&1 het einde van de Write-Debug instructie vertelt PowerShell dat stream 5 (foutopsporing) moet worden omgeleid naar stream 1 (uitvoer).

Uitvoer naar uitgebreide stream schrijven

De uitgebreide berichtenstroom ondersteunt algemene informatie over runbookbewerkingen. Omdat de foutopsporingsstroom niet beschikbaar is voor een runbook, moet uw runbook uitgebreide berichten gebruiken voor foutopsporingsinformatie.

Standaard worden in de taakgeschiedenis geen uitgebreide berichten uit gepubliceerde runbooks opgeslagen om prestatieredenen. Als u uitgebreide berichten wilt opslaan, gebruikt u het tabblad Configureren in Azure Portal met de instelling Uitgebreide logboekrecords om uw gepubliceerde runbooks te configureren voor het vastleggen van uitgebreide berichten. Schakel deze optie alleen in om problemen met een runbook op te lossen of fouten op te sporen. In de meeste gevallen moet u de standaardinstelling voor het niet vastleggen van uitgebreide records behouden.

Bij het testen van een runbook worden uitgebreide berichten niet weergegeven, zelfs niet als het runbook is geconfigureerd voor het vastleggen van uitgebreide records. Als u uitgebreide berichten wilt weergeven tijdens het testen van een runbook, moet u de VerbosePreference variabele instellen op Doorgaan. Met deze variabelenset worden uitgebreide berichten weergegeven in het deelvenster Testuitvoer van Azure Portal.

Met de volgende code wordt een uitgebreid bericht gemaakt met behulp van de cmdlet Write-Verbose .

#The following line creates a verbose message.

Write-Verbose -Message "This is a verbose message."

Voortgangsrecords verwerken

U kunt het tabblad Configureren van Azure Portal gebruiken om een runbook te configureren om voortgangsrecords te registreren. De standaardinstelling is om de records niet te registreren om de prestaties te maximaliseren. In de meeste gevallen moet u de standaardinstelling behouden. Schakel deze optie alleen in om problemen met een runbook op te lossen of fouten op te sporen.

Als u logboekregistratie van voortgangsrecords inschakelt, schrijft uw runbook een record naar de taakgeschiedenis voor en na elke uitvoering van de activiteit. Bij het testen van een runbook worden geen voortgangsberichten weergegeven, zelfs niet als het runbook is geconfigureerd om voortgangsrecords te registreren.

Notitie

De cmdlet Write-Progress is niet geldig in een runbook, omdat deze cmdlet is bedoeld voor gebruik met een interactieve gebruiker.

Werken met voorkeursvariabelen

U kunt bepaalde Windows PowerShell-voorkeursvariabelen instellen in uw runbooks om het antwoord op gegevens te beheren die naar verschillende uitvoerstromen worden verzonden. De volgende tabel bevat de voorkeursvariabelen die kunnen worden gebruikt in runbooks, met hun standaard- en geldige waarden. Er zijn extra waarden beschikbaar voor de voorkeursvariabelen wanneer deze worden gebruikt in Windows PowerShell buiten Azure Automation.

Variabel Standaardwaarde Geldige waarden
WarningPreference Doorgaan Stoppen
Doorgaan
SilentlyContinue
ErrorActionPreference Doorgaan Stoppen
Doorgaan
SilentlyContinue
VerbosePreference SilentlyContinue Stoppen
Doorgaan
SilentlyContinue

De volgende tabel bevat het gedrag voor de waarden van de voorkeursvariabele die geldig zijn in runbooks.

Waarde Gedrag
Doorgaan Registreert het bericht en gaat door met het uitvoeren van het runbook.
SilentlyContinue Blijft het runbook uitvoeren zonder het bericht te registreren. Deze waarde heeft het effect dat het bericht wordt genegeerd.
Stoppen Registreert het bericht en onderbreekt het runbook.

Runbookuitvoer en -berichten ophalen

Runbookuitvoer en -berichten ophalen in Azure Portal

U kunt de details van een runbooktaak bekijken in Azure Portal met behulp van het tabblad Taken voor het runbook. In het taakoverzicht worden de invoerparameters en de uitvoerstroom weergegeven, naast algemene informatie over de taak en eventuele uitzonderingen die zijn opgetreden. De taakgeschiedenis bevat berichten uit de uitvoerstroom en waarschuwings- en foutstromen. Het bevat ook berichten van de uitgebreide stroom en voortgangsrecords als het runbook is geconfigureerd voor het vastleggen van uitgebreide en voortgangsrecords.

Notitie

Taakstromen voor Python-runbooks worden momenteel ondersteund voor uitvoer in de Engelse taal.

Runbookuitvoer en -berichten ophalen in Windows PowerShell

In Windows PowerShell kunt u uitvoer en berichten ophalen uit een runbook met behulp van de cmdlet Get-AzAutomationJobOutput . Deze cmdlet vereist de id van de taak en heeft een parameter die wordt aangeroepen Stream om de stream op te geven die moet worden opgehaald. U kunt een waarde opgeven van Any voor deze parameter om alle streams voor de taak op te halen.

In het volgende voorbeeld wordt een voorbeeldrunbook gestart en wordt gewacht totdat het is voltooid. Zodra het runbook is uitgevoerd, verzamelt het script de uitvoerstroom van het runbook van de taak.

$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

Runbookuitvoer en -berichten ophalen in grafische runbooks

Voor grafische runbooks is extra logboekregistratie van uitvoer en berichten beschikbaar in de vorm van tracering op activiteitsniveau. Er zijn twee traceringsniveaus: Basis en Gedetailleerd. Met basistracering worden de begin- en eindtijd voor elke activiteit in het runbook weergegeven, plus informatie met betrekking tot nieuwe pogingen. Enkele voorbeelden zijn het aantal pogingen en de begintijd van de activiteit. Gedetailleerde tracering omvat basistraceringsfuncties plus logboekregistratie van invoer- en uitvoergegevens voor elke activiteit.

Op dit moment schrijft tracering op activiteitsniveau records met behulp van de uitgebreide stream. Daarom moet u uitgebreide logboekregistratie inschakelen wanneer u tracering inschakelt. Voor grafische runbooks waarvoor tracering is ingeschakeld, hoeft u geen voortgangsrecords te registreren. Basistracering dient hetzelfde doel en is informatiever.

Graphical authoring job streams view

U kunt in de afbeelding zien dat uitgebreide logboekregistratie en tracering voor grafische runbooks veel meer informatie beschikbaar maakt in de weergave Productietaakstromen . Deze extra informatie kan essentieel zijn voor het oplossen van productieproblemen met een runbook.

Tenzij u deze informatie echter nodig hebt om de voortgang van een runbook bij te houden voor het oplossen van problemen, wilt u tracering mogelijk uitgeschakeld houden als een algemene praktijk. De traceringsrecords kunnen bijzonder talrijk zijn. Met grafische runbooktracering kunt u twee tot vier records per activiteit ophalen, afhankelijk van uw configuratie van Basic of Gedetailleerde tracering.

Tracering op activiteitsniveau inschakelen:

  1. Open uw Automation-account in Azure Portal.

  2. Selecteer Runbooks onder Procesautomatisering om de lijst van runbooks te openen.

  3. Selecteer op de pagina Runbooks een grafisch runbook in uw lijst met runbooks.

  4. Klik onder Instellingen op Logboekregistratie en tracering.

  5. Klik op de pagina Logboekregistratie en tracering onder Uitgebreide logboekrecords op Aan om uitgebreide logboekregistratie in te schakelen.

  6. Wijzig onder Tracering op activiteitsniveau het traceringsniveau in Basis of Gedetailleerd, op basis van het traceringsniveau dat u nodig hebt.

    Graphical Authoring Logging and Tracing page

Runbookuitvoer en -berichten ophalen in Microsoft Azure Monitor-logboeken

Azure Automation kan de status van runbooktaak en taakstromen verzenden naar uw Log Analytics-werkruimte. Azure Monitor ondersteunt logboeken waarmee u het volgende kunt doen:

  • Inzicht verwerven in uw Automation-taken.
  • Activeer een e-mail of waarschuwing op basis van de status van uw runbooktaak, bijvoorbeeld Mislukt of Onderbroken.
  • Schrijf geavanceerde query's over taakstromen.
  • Taken voor verschillende Automation-accounts aan elkaar te relateren.
  • Taakgeschiedenis visualiseren.

Zie Taakstatus en taakstromen doorsturen van Automation naar Azure Monitor-logboeken voor meer informatie over het configureren van integratie met Azure Monitor-logboeken voor het verzamelen, correleren en uitvoeren van taakgegevens.

Volgende stappen