Partager via

Sortie et messages de runbook

  • Article

Important

Cette version de Service Management Automation (SMA) a atteint la fin du support. Nous vous recommandons de mettre à niveau vers SMA 2022.

La plupart des runbooks Automation ont une forme de sortie semblable à un message d'erreur pour l'utilisateur ou un objet complexe destiné à être consommé par un autre workflow. 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 l’utiliser 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.

STREAM Description Publié Test
Output 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 Sortie de test si l'option $VerbosePreference est définie sur 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 ils sont destinés à 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ébogage 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 des objets destinés à être consommés par des runbooks parents qui appellent le runbook en cours. Lorsque vous appelez un runbook incorporé à partir d'un runbook parent, le runbook incorporé renvoie des données du flux de sortie au runbook parent. 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, elle n’est pas écrite 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 les différents types d'informations et chacun d'eux est traité de manière distincte 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 du 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 que le runbook doit être suspendu 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 suspendre un runbook en cas d'erreur comme le ferait une exception, définissez la valeur $ErrorActionPreference sur Stop.

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 enregistrer 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.

Notes

Ce tableau inclut uniquement les valeurs valides dans un Runbook. D’autres valeurs 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 Continue Arrêter
Continue
SilentlyContinue
ErrorActionPreference Continue Arrêter
Continue
SilentlyContinue
VerbosePreference SilentlyContinue Arrêter
Continue
SilentlyContinue

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

Valeur Comportement
Continue 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é.
Arrêter 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 les Warning and Error Streams . Il inclut également le Verbose Stream et les Progress Records si le Runbook est configuré pour journaliser les enregistrements détaillés et les informations 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 requiert l'ID du travail et utilise un paramètre appelé Stream dans lequel vous pouvez spécifier le flux à renvoyer. Vous pouvez spécifier Any pour renvoyer tous les flux du travail.

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.