Salida y mensajes de runbooks

Importante

Esta versión de Service Management Automation (SMA) ha llegado al final del soporte técnico. Se recomienda actualizar a SMA 2022.

La mayoría de los runbooks de Automation generan alguna forma de salida, como un mensaje de error al usuario o un objeto complejo que será consumido por otro flujo de trabajo. Windows PowerShell 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 y debe seguir los procedimientos recomendados para usar cada uno de ellos al crear un runbook.

En la tabla siguiente se proporciona una breve descripción de cada uno de los flujos y su comportamiento en el Portal de administración cuando se ejecuta un runbook publicado y cuando se prueba un runbook. En las secciones posteriores se proporcionan más detalles sobre cada secuencia.

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.
Verbose	Proporciona información general o información para solucionar problemas.	Solo se escribe en el historial de trabajos si el registro detallado del runbook está activado.	Se muestran en el panel de resultados de pruebas solo 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 están diseñados para 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á diseñado para la salida de los objetos creados por un flujo de trabajo cuando se ejecuta correctamente. En Automation, este flujo se utiliza principalmente para objetos destinados a ser consumidos por runbooks primarios que llamen al runbook actual. Cuando se llama a un runbook alineado desde un runbook primario, devuelve datos del flujo de salida al flujo principal. 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, 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 varios flujos de mensajes para los diferentes tipos de información y Automation controla cada uno de forma diferente.

Seleccione la pestaña necesaria para obtener más información sobre estos flujos de mensajes:

Flujos de error y de advertencia

Los flujos de error y de advertencia 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 Salida de prueba del Portal de administración cuando se prueba un runbook. De forma predeterminada, el runbook continuará ejecutándose después de un error o advertencia. Puede especificar que el runbook debe suspenderse en una advertencia o error estableciendo una variable de preferencias del runbook antes de crear el mensaje. Por ejemplo, para hacer que un runbook se suspenda en caso de un error como lo haría una excepción, establezca $ErrorActionPreference en Detener.

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 el Stream Depurar no está disponible en un runbook, se deben usar mensajes detallados para la información de 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, configure los runbooks publicados para Escribir 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.

El valor predeterminado de la variable $VerbosePreference es SilentlyContinue. No es necesario cambiar esta variable en un runbook publicado para almacenar mensajes detallados. Sin embargo, 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 los mensajes detallados al probar un runbook, debe establecer la variable $VerbosePreference en Continuar. Cuando esa variable está establecida, los mensajes detallados se muestran en el panel de salida de la 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

La secuencia de depuración está pensada para su uso con un usuario interactivo y no debe usarse en runbooks.

Registros de progreso

Si configura un runbook para escribir 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. Al probar un runbook, los mensajes de progreso no se muestran aunque el runbook esté configurado para registrar los registros de progreso.

El cmdlet Write-Progress no es válido en un runbook, ya que está pensado para su uso 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	Stop Continuar 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.
Stop	Registra el mensaje y suspende el runbook.

Recuperar salidas de runbooks y mensajes

Portal de administración

Puede ver los detalles de un trabajo de runbook en el Portal de administración de la pestaña Trabajos de un runbook. El Resumen del trabajo mostrará los parámetros de entrada y el Output Stream , además de información general sobre el trabajo y las excepciones que se hayan producido. El Historial incluirá mensajes del flujo de salida y los Warning and Error Streams , además del Verbose Stream y el Progress Records si el runbook está configurado para escribir registros detallados y de progreso.

Windows PowerShell

En Windows PowerShell, puede recuperar la salida y los mensajes de un runbook con el cmdlet Get SmaJobOutput . Este cmdlet necesita el identificador del trabajo y tiene un parámetro denominado flujo donde debe especificar qué flujo se devolverá. Puede especificar Any para devolver todos los flujos de 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

Creación de runbooks de automatización.