Salida y mensajes de runbooks

La mayoría de los runbooks de Automation generan alguna forma de salida, como el mensaje de error dirigido al usuario o un objeto complejo previsto para el consumo de otro flujo de trabajo. Windows PowerShell te ofrece varios flujos para enviar la salida desde un flujo de trabajo. Service Management Automation funciona con cada uno de estos flujos de forma diferente, por lo que es aconsejable que sigas los procedimientos recomendados sobre cómo usar cada uno de ellos cuando crees un runbook.

En la siguiente tabla, se proporciona una breve descripción de cada uno de los flujos y su comportamiento en el Portal de administración, tanto cuando se ejecuta un runbook publicado como cuando se prueba un runbook. En las siguientes secciones, se proporciona más información sobre cada flujo.

Stream	Descripción	Publicado	Prueba
Output	Objetos destinados a ser consumidos por otros runbooks.	Se escribe en el historial de trabajos.	Se muestra en el panel de salida de la prueba.
Advertencia	Mensaje de advertencia destinado al usuario.	Se escribe en el historial de trabajos.	Se muestra en el panel de salida de la prueba.
Error	Mensaje de error destinado al usuario. A diferencia de lo que sucede con las excepciones, el runbook continúa después de un mensaje de error de forma predeterminada.	Se escribe en el historial de trabajos.	Se muestra en el panel de salida de la prueba.
Detallado	Mensajes que proporcionan información general o sobre la solución de problemas.	Solo se escribe en el historial de trabajos si el registro detallado del runbook está activado.	Solo se muestra en el panel de salida prueba si $VerbosePreference está establecido en Continuar en el runbook.
Progreso	Registros que se generan automáticamente antes y después de cada actividad del runbook. El runbook no debe intentar crear sus propios registros de progreso, ya que estos están dirigidos a un usuario interactivo.	Solo se escribe en el historial de trabajos si el registro del progreso del runbook está activado.	No se muestra en el panel de salida de la prueba.
Depurar	Mensajes dirigidos a un usuario interactivo. No debe usarse en runbooks.	No se escribe en el historial de trabajos.	No se escribe en el panel de salida de la prueba.

Flujo de salida

El flujo de salida está previsto para la salida de los objetos creados por un flujo de trabajo cuando se ejecuta correctamente. En Automation, este flujo se usa principalmente para los objetos destinados a ser consumidos por los runbooks primarios que llaman al runbook actual. Cuando llama a un runbook en línea desde un runbook primario, este devuelve los datos del flujo de salida al runbook primario. Solo debe usar el flujo de salida para comunicar información general al usuario si sabe que ningún otro runbook nunca llamará a ese runbook. Le aconsejamos, como procedimiento recomendado, que use la opción de Flujo detallado para comunicar información general al usuario.

Puede escribir datos en el flujo de salida mediante Write-Output o colocando el objeto en su propia línea en el runbook.

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

Salida de una función

Cuando escribe en el flujo de salida de una función que está incluida en su runbook, la salida se devuelve al runbook. Si el runbook asigna esa salida a una variable, ya no se escribe en el flujo de salida. Asimismo, si se escribe en cualquier otro flujo desde la función, se escribirá en el flujo correspondiente del runbook.

Échele un vistazo al siguiente runbook de ejemplo.

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

El flujo de salida del trabajo del runbook sería:

Output outside of function

El flujo detallado del trabajo del runbook sería:

Verbose outside of function
Verbose inside of function

La variable $functionOutput tendría el valor:

Output inside of function

Declaración del tipo de datos de salida

Un flujo de trabajo puede especificar el tipo de datos de su salida mediante el atributo OutputType. Este atributo no tiene ningún efecto durante el tiempo de ejecución, pero proporciona al autor del runbook una indicación de la salida esperada en tiempo de diseño. A medida que el conjunto de herramientas de los runbooks evoluciona, aumenta la importancia de la declaración de tipos de datos de salida en tiempo de diseño. Como resultado, es recomendable incluir esta declaración en cualquier runbook que cree.

El siguiente runbook de ejemplo genera un objeto de cadena e incluye una declaración de su tipo de salida. Si su runbook genera una matriz de un tipo determinado, deberá especificar el tipo en lugar de una matriz de ese tipo.

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

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

Flujos de mensajes

A diferencia del flujo de salida, los flujos de mensajes están diseñados para comunicar información al usuario. Hay varias secuencias de mensajes para diferentes tipos de información, y Automation gestiona cada una de ellas de forma diferente.

Selecciona la pestaña necesaria para obtener más información sobre estas secuencias de mensajes:

Flujos de advertencia y error

Los flujos de advertencia y error están diseñados para registrar los problemas que se producen en un runbook. Se escriben en el historial de trabajos cuando se ejecuta un runbook y se incluyen en el panel de salida de prueba del Portal de administración de Azure cuando se prueba un runbook. De forma predeterminada, el runbook continuará ejecutándose después de un error o advertencia. Para especificar que el runbook debe suspenderse en caso de advertencia o error, puede establecer una variable de preferencia en el runbook antes de crear el mensaje. Por ejemplo, para hacer que un runbook se suspenda en caso de error, tal y como haría una excepción, establezca $ErrorActionPreference en Stop.

Cree un mensaje de advertencia o de error mediante los cmdlets Write-Warning o Write-Error. También se pueden escribir actividades en estos flujos.

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

Flujo detallado

El flujo de mensajes detallados se usa para proporcionar información general acerca del funcionamiento del runbook. Dado que los runbooks no tienen disponible el flujo de depuración, debes usar mensajes detallados para proporcionar información para la solución de problemas. De forma predeterminada, los mensajes detallados de los runbooks publicados no se almacenarán en el historial de trabajos. Para almacenar mensajes detallados, configura los runbooks publicados en Registrar registros detallados en la pestaña Configurar del runbook en el Portal de administración. En la mayoría de los casos, deberá mantener la configuración predeterminada y no escribir los registros detallados de un runbook por motivos de rendimiento. Active esta opción solo para solucionar problemas o para depurar un runbook.

La variable $VerbosePreference toma como valor predeterminado un valor de SilentlyContinue. No es necesario que cambies esta variable en un runbook publicado para que se almacenen los mensajes detallados. Si este valor se establece explícitamente en SilentlyContinue en un runbook publicado, los mensajes detallados no se almacenarán aunque el runbook esté configurado para registrar registros detallados.

Cuando se prueba un runbook, los mensajes detallados no se muestran aunque el runbook esté configurado para escribir registros detallados. Para mostrar mensajes detallados al probar un runbook, debe establecer la variable $VerbosePreference en “Continue”. Cuando esa variable está establecida, los mensajes detallados se muestran en el panel de salida de prueba del Portal de administración.

Cree un mensaje detallado mediante el cmdlet Write-Verbose .

#The following line creates a verbose message.

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

Flujo de depuración

El flujo de depuración está pensado para usarse con un usuario interactivo y no debe usarse en los runbooks.

Registros de progreso

Si configuras un runbook para registrar registros de progreso (en la pestaña Configurar del runbook en el Portal de administración), se escribirá un registro en el historial de trabajos antes y después de la ejecución de cada actividad. En la mayoría de los casos, deberá mantener la configuración predeterminada y no escribir los registros de progreso de un runbook para así maximizar el rendimiento. Active esta opción solo para solucionar problemas o para depurar un runbook. Cuando se prueba un runbook, los mensajes de progreso no se muestran aunque el runbook esté configurado para registrar registros de progreso.

El cmdlet Write-Progress no es válido en un runbook ya que está pensado para usarse con un usuario interactivo.

Variables de preferencia

Windows PowerShell usa variables de preferencia para determinar cómo responder a los datos que se hayan enviado a diferentes flujos de salida. Puede establecer estas variables en un runbook para controlar cómo responderá a los datos que se hayan enviado a diferentes flujos.

En la siguiente tabla se enumeran las variables de preferencia que pueden usarse en runbooks, junto con sus valores válidos y predeterminados.

Nota:

Esta tabla solo incluye los valores que son válidos en un runbook. Hay otros valores adicionales que son válidos para las variables de preferencia cuando se usan en Windows PowerShell fuera de Service Management Automation.

Variable	Valor predeterminado	Valores válidos
WarningPreference	Continuar	Detención Continue<\br> \SilentlyContinue
ErrorActionPreference	Continuar	Stop Continuar SilentlyContinue
VerbosePreference	SilentlyContinue	Stop Continuar SilentlyContinue

En la siguiente tabla se muestra el comportamiento de los valores de las variables de preferencia que son válidos en los runbooks.

Valor	Comportamiento
Continuar	Registra el mensaje y continúa ejecutando el runbook.
SilentlyContinue	Continúa la ejecución del runbook sin registrar el mensaje. Hace que el mensaje se pase por alto.
Detención	Registra el mensaje y suspende el runbook.

Recuperar salidas y mensajes de runbooks

Portal de administración

Puedes ver los detalles de un trabajo de runbook en el Portal de administración de la pestaña llamada Trabajos de un runbook. La opción Resumen del trabajo te mostrará los parámetros de entrada y el Flujo de salida, además de información general sobre el trabajo y las excepciones que se hayan producido. En la opción Historial se incluirán los mensajes del Flujo de salida y los Flujos de error y de advertencia, además del Flujo detallado y los Registros de progreso, si el runbook está configurado para escribir registros detallados y de progreso.

Windows PowerShell

En Windows PowerShell, puedes recuperar la salida y los mensajes de un runbook con el cmdlet Get-SmaJobOutput. Este cmdlet requiere la identificación del trabajo y tiene un parámetro denominado Secuencia en el que se especifica qué secuencia hay que devolver. Puede elegir la opción Cualquiera para devolver todos los flujos del trabajo.

En el ejemplo siguiente se inicia un runbook y, a continuación, se espera a que finalice. Una vez completado, el flujo de salida se recopila del trabajo.

$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

Pasos siguientes

Crea un runbook de Automation.