Partager via

Sortie et messages de runbook

  • Article

La plupart des runbooks Automation ont une forme de sortie telle qu’un message d’erreur à l’utilisateur ou un objet complexe destiné à être consommé par un autre flux de travail. Windows PowerShell fournit plusieurs flux pour envoyer la sortie d'un flux de travail. Service Management Automation fonctionne différemment avec chacun de ces flux, et vous devez suivre les meilleures pratiques pour chaque utilisation lorsque vous créez un runbook.

Le tableau suivant fournit une brève description de chacun des flux et de leur comportement dans le Portail de gestion, aussi bien durant l'exécution d'un Runbook publié que pendant le test d'un Runbook. Des détails supplémentaires sur chaque flux sont fournis dans les sections suivantes.

Flux Description Publiée Test
Sortie Objets destinés à être consommés par d’autres Runbooks. Consignation dans l’historique des tâches. Affichage dans le volet de sortie du test.
Avertissement Message d’avertissement destiné à l’utilisateur. Consignation dans l’historique des tâches. Affichage dans le volet de sortie du test.
Error Message d’erreur destiné à l’utilisateur. Contrairement à une exception, le Runbook se poursuit après un message d’erreur par défaut. Consignation dans l’historique des tâches. Affichage dans le volet de sortie du test.
Commentaires Messages qui fournissent des informations générales ou de résolution des problèmes. Consignation dans l’historique des tâches uniquement si la journalisation documentée est activée pour le Runbook. Affiché dans le volet de résultats des tests uniquement si $VerbosePreference a la valeur Continue dans le Runbook.
Progress Informations générées automatiquement avant et après chaque activité dans le Runbook. Le runbook ne doit pas tenter de créer ses propres enregistrements de progression, car il est destiné à un utilisateur interactif. Consignation dans l’historique des tâches uniquement si l’enregistrement de la progression est activé pour le Runbook. Pas d’affichage dans le volet de sortie du test.
Déboguer Messages destinés à un utilisateur interactif. Utilisation proscrite dans les Runbooks. Pas de consignation dans l’historique des tâches. Pas d’affichage dans le volet de sortie du test.

Flux de sortie

Le flux de sortie est prévu pour la sortie des objets créés par un flux de travail quand il s'exécute correctement. Dans Automation, ce flux est principalement utilisé pour les objets destinés à être consommés par les runbooks parents qui appellent le runbook actuel. Lorsque vous appelez un Runbook en ligne à partir d’un Runbook parent, il retourne les données au parent à partir du flux de sortie. Vous devez utiliser le flux de sortie uniquement pour retourner des informations générales à l’utilisateur si vous savez que le Runbook ne sera jamais appelé par un autre Runbook. Cependant, nous vous recommandons d’utiliser le flux des commentaires pour communiquer des informations générales à l’utilisateur.

Vous pouvez écrire des données dans le flux de sortie à l’aide de Write-Output ou en plaçant l’objet sur sa propre ligne dans le Runbook.

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

Sortie à partir d’une fonction

Lorsque vous écrivez dans le flux de sortie, dans une fonction qui est incluse dans votre Runbook, la sortie est renvoyée au Runbook. Si le runbook affecte cette sortie à une variable, il n’est pas écrit dans le flux de sortie. Toute écriture dans d’autres flux à partir de la fonction se fait dans le flux correspondant du Runbook.

Examinez l’exemple de Runbook suivant.

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

Le flux de sortie pour la tâche du Runbook serait :

Output outside of function

Le flux des commentaires pour la tâche du Runbook serait :

Verbose outside of function
Verbose inside of function

La variable $functionOutput a la valeur :

Output inside of function

Déclarer le type de données de sortie

Un flux de travail peut spécifier le type de données de sa sortie à l’aide de l’ attribut OutputType. Cet attribut n’a aucun effet lors de l’exécution, mais il fournit une indication à l’auteur du Runbook sur la sortie attendue du Runbook au moment de la conception. Alors que l’ensemble d’outils dédiés aux Runbooks continue d’évoluer, la déclaration des types de données de sortie au moment de la conception gagne en importance. Par conséquent, il est recommandé d’inclure cette déclaration dans tous les Runbooks que vous créez.

L’exemple de Runbook suivant génère un objet String et inclut une déclaration de son type de sortie. Si votre Runbook génère un tableau d’un certain type, vous devez toujours spécifier le type, par opposition à un tableau du type.

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

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

Flux de messages

Contrairement au flux de sortie, les flux de messages sont destinés à la communication des informations à l’utilisateur. Il existe plusieurs flux de messages pour différents types d’informations, et chacun d’eux est géré différemment par Automation.

Sélectionnez l’onglet requis pour en savoir plus sur ces flux de messages :

Les flux d’erreurs et d’avertissements sont conçus pour l’enregistrement des problèmes qui se produisent dans un Runbook. Ils sont écrits dans l’historique des travaux lorsqu’un runbook est exécuté et sont inclus dans le volet Sortie de test dans le portail de gestion lorsqu’un runbook est testé. Par défaut, l’exécution du Runbook se poursuit après un avertissement ou une erreur. Vous pouvez spécifier l’interruption du Runbook en cas d’avertissement ou d’erreur en définissant une variable de préférence dans le Runbook avant de créer le message. Par exemple, pour déclencher l’interruption du Runbook en cas d’erreur, comme dans le cas d’une exception, affectez la valeur Stop à $ErrorActionPreference .

Créez un message d’avertissement ou un message d’erreur à l’aide de l’applet de commande Write-Warning ou Write-Error. Les activités peuvent également écrire dans ces flux.

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

Informations de progression

Si vous configurez un Runbook pour journaliser les informations de progression (sous l'onglet Configurer du Runbook dans le Portail de gestion), un enregistrement est écrit dans l'historique des travaux avant et après l'exécution de chaque activité. Afin d’optimiser les performances, il est généralement recommandé de conserver le paramètre par défaut (les informations de progression ne sont pas enregistrées pour le Runbook). Activez cette option uniquement pour résoudre les problèmes liés à un Runbook ou déboguer un Runbook. Lors du test d’un runbook, les messages de progression ne s’affichent pas même si le runbook est configuré pour journaliser les enregistrements de progression.

L’applet de commande Write-Progress n’est pas valide dans un runbook, car elle est destinée à être utilisée avec un utilisateur interactif.

Variables de préférence

Windows PowerShell utilise des variables de préférence pour déterminer comment répondre aux données envoyées aux différents flux de sortie. Vous pouvez définir ces variables dans un Runbook pour contrôler comment il répondra aux données envoyées dans différents flux.

Le tableau suivant répertorie les variables de préférence qui peuvent être utilisées dans des Runbooks, ainsi que leurs valeurs valides et valeurs par défaut.

Remarque

Ce tableau inclut uniquement les valeurs valides dans un Runbook. Des valeurs supplémentaires sont valides pour les variables de préférence lorsqu’elles sont utilisées dans Windows PowerShell en dehors de Service Management Automation.

Variable Valeur par défaut Valeurs valides
WarningPreference Continuer Arrêter
Continuer<\br>
\SilentlyContinue
ErrorActionPreference Continuer Arrêter
Continuer
SilentlyContinue
VerbosePreference SilentlyContinue Arrêter
Continuer
SilentlyContinue

Le tableau suivant indique le comportement associé aux valeurs des variables de préférence valides dans les Runbooks.

Valeur Comportement
Continuer Enregistre le message et poursuit l’exécution du Runbook.
SilentlyContinue Poursuit l’exécution du Runbook sans enregistrer le message. Le message est alors ignoré.
Stop Enregistre le message et interrompt le Runbook.

Récupération de la sortie et des messages de Runbook

Portail de gestion

Vous pouvez afficher les détails d'une tâche de Runbook dans le Portail de gestion, sous l'onglet Travaux d'un Runbook. Le Résumé du travail affiche les paramètres d'entrée et le Output Stream , ainsi que des informations générales sur le travail et les exceptions survenues, le cas échéant. L’historique inclut les messages du flux de sortie et des flux d’avertissements et d’erreurs en plus du flux de commentaires et des informations de progression si le Runbook est configuré pour enregistrer les informations de commentaires et de progression.

Windows PowerShell

Dans Windows PowerShell, vous pouvez récupérer la sortie et les messages d'un Runbook à l'aide de l'applet de commande Get-SmaJobOutput . Cette applet de commande nécessite l'ID du travail. Par ailleurs, elle a un paramètre appelé Stream où vous spécifiez le flux à retourner. Vous pouvez spécifier la valeur Any pour renvoyer tous les flux de la tâche.

Dans l’exemple suivant, un exemple de Runbook est démarré et exécuté. À l’issue de l’exécution du Runbook, son flux de sortie est collecté à partir de la tâche.

$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

Étapes suivantes

Créer des runbooks Automation.