Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
La mayoría de los runbooks de Azure Automation tienen alguna forma de salida. Esta salida puede ser un mensaje de error para el usuario o un objeto complejo que se va a usar con otro runbook. Windows PowerShell proporciona múltiples flujos para enviar la salida desde un script o flujo de trabajo. Azure Automation funciona con cada uno de estos flujos de forma diferente. Debe seguir los procedimientos recomendados sobre cómo usar los flujos al crear un runbook.
En la tabla siguiente se describe brevemente cada flujo con su comportamiento en Azure Portal en los runbooks publicados y durante las pruebas de un runbook. El flujo de salida es el flujo principal que se utiliza para la comunicación entre los runbooks. El resto de los flujos se clasifican como flujos de mensajes, pensados para comunicar información al usuario.
| Flujo | Descripción | Publicado | 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. |
| Depurar | Mensajes dirigidos a un usuario interactivo. No debe usarse en runbooks. | No se registra en el historial de trabajos. | No se muestra en el panel de salida de la prueba. |
| Salida | 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. |
| Progreso | Registros generados automáticamente antes y después de cada actividad en el runbook. El runbook no debe intentar crear sus propios registros de progreso, ya que 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. |
| Verbose | Mensajes que proporcionan información general o de depuración. | Solo se escribe en el historial de trabajos si el registro detallado del runbook está activado. | Se muestra en el panel de salida de la prueba solo si la variable VerbosePreference está establecida en Continue en el runbook. |
| Advertencia | Mensaje de advertencia destinado al usuario. | Se escribe en el historial de trabajos. | Se muestra en el panel de salida de la prueba. |
Utilice el flujo de salida
El flujo de salida se usa para la salida de los objetos creados por un script o flujo de trabajo, cuando se ejecuta correctamente. Azure Automation usa este flujo principalmente para objetos destinados a ser consumidos por runbooks primarios que llaman al runbook actual. Cuando un runbook primario llama a un runbook insertado, el runbook secundario devuelve los datos del flujo de salida al primario.
El runbook usa el flujo de salida para comunicar información general al cliente solo si nunca se le llama desde otro runbook. Como procedimiento recomendado, sin embargo, le recomendamos que los runbooks usen la opción de flujo detallado para comunicar información general al usuario.
Para que el runbook escriba datos en el flujo de salida, utilice Write-Output. Como alternativa, puede colocar el objeto en su propia línea en el script.
#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object
Gestión de la salida de una función
Cuando una función de runbook escribe en el flujo de salida, 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. Considere el siguiente ejemplo de runbook del flujo de trabajo de PowerShell.
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"
}
}
El flujo de salida del trabajo del runbook es:
Output inside of function
Output outside of function
El flujo detallado del trabajo del runbook es:
Verbose outside of function
Verbose inside of function
Una vez que haya publicado el runbook y antes de iniciarlo, debe activar también el registro detallado en la configuración del runbook para obtener la salida del flujo detallado.
Declaración del tipo de datos de salida
A continuación se muestran ejemplos de tipos de datos de salida:
System.StringSystem.Int32System.Collections.HashtableMicrosoft.Azure.Commands.Compute.Models.PSVirtualMachine
Declaración del tipo de datos de salida de un flujo de trabajo
Un flujo de trabajo especifica el tipo de datos de su salida mediante el atributo OutputType. Este atributo no tiene ningún efecto en tiempo de ejecución, pero en tiempo de diseño proporciona una indicación de la salida esperada del runbook. A medida que el conjunto de herramientas para los runbooks sigue evolucionando, la importancia de declarar los tipos de datos de salida durante el diseño aumenta. Por tanto, es una buena práctica incluir esta declaración en cualquier libro de operaciones que se 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
}
Declaración del tipo de datos de salida en un runbook gráfico
Para declarar un tipo de salida en un runbook gráfico o en un flujo de trabajo gráfico de PowerShell, seleccione la opción de menú Entrada y salida y especifique el tipo de salida. Se recomienda usar el nombre completo de la clase .NET para que el tipo se pueda identificar fácilmente cuando un runbook principal hace referencia a él. Al usar el nombre completo, se exponen todas las propiedades de la clase al bus de datos del runbook. Además, se aumenta la flexibilidad cuando se usan las propiedades para la lógica condicional, el registro y la referencia como valores para otras actividades de runbooks.
Nota:
Después de escribir un valor en el cuadro Tipo de salida del panel Propiedades de entrada y salida, asegúrese de hacer clic fuera del control para que reconozca la entrada.
En el ejemplo siguiente se utilizan dos runbooks gráficos para mostrar la característica de entrada y salida. Al aplicar el modelo de diseño modular de runbook, tiene un runbook como plantilla de runbook de autenticación que administra la autenticación con Azure mediante Identidades administradas. El segundo runbook, que normalmente realiza la lógica básica para automatizar un determinado escenario, en este caso ejecuta la plantilla de runbook de autenticación. Muestra los resultados en el panel de salida de la prueba. En circunstancias normales, haríamos que este runbook hiciera algo en un recurso que está aprovechando la salida del runbook secundario.
Esta es la lógica básica del runbook AuthenticateTo-Azure.
.
El runbook incluye el tipo de salida Microsoft.Azure.Commands.Profile.Models.PSAzureProfile, que devuelve las propiedades del perfil de autenticación.
Aunque este runbook es sencillo, hay un elemento de configuración que merece destacarse. La última actividad ejecuta el cmdlet Write-Output para escribir datos de perfil en una variable mediante una expresión de PowerShell para el parámetro Inputobject. Este parámetro es obligatorio para Write-Output.
El segundo runbook de este ejemplo, denominado Test-ChildOutputType, simplemente define dos actividades.
La primera actividad llama al runbook AuthenticateTo-Azure. La segunda actividad ejecuta el cmdlet Write-Verbose con la opción Origen de datos establecida en Resultado de la actividad. Además, Ruta de campo se establece en Context.Subscription.Name, la salida de contexto del runbook AuthenticateTo-Azure.
La salida resultante es el nombre de la suscripción.
Uso de flujos de mensajes
A diferencia del flujo de salida, los flujos de mensajes comunican información al usuario. Hay varios flujos de mensajes para diferentes tipos de información y Azure Automation controla cada secuencia de forma diferente.
Escritura de la salida de flujos de error y de advertencia
Los flujos de error y de advertencia registran los problemas que se producen en un runbook. Azure Automation escribe estos flujos en el historial de trabajos cuando se ejecuta un runbook. Cuando se prueba un runbook, Automation incluye los flujos en el panel de salida de la prueba de Azure Portal.
De forma predeterminada, un libro de operaciones continúa ejecutándose después de una advertencia o un error. Puede especificar que el runbook se suspenda en caso de advertencia o error haciendo que el runbook establezca una variable de preferencia antes de crear el mensaje. Por ejemplo, para hacer que el runbook se suspenda en caso de que se produzca un error, al igual que lo hace en caso de una excepción, establezca la variable ErrorActionPreference en Stop.
Cree un mensaje de advertencia o de error mediante los cmdlets Write-Warning o Write-Error. Las actividades también pueden escribir en los flujos de advertencia y de error.
#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."
Escritura de la salida en el flujo de depuración
Azure Automation usa la secuencia de mensajes de depuración para los usuarios interactivos. De manera predeterminada, Azure Automation no captura ningún dato de flujos de depuración, solo se capturan datos de salida, de error y de advertencia, así como datos detallados si el runbook está configurado para capturarlos.
Para capturar datos de flujos de depuración, debe realizar dos acciones en los runbooks:
Establezca la variable
$GLOBAL:DebugPreference="Continue", que indica a PowerShell que continúe siempre que se encuentre un mensaje de depuración. La parte $GLOBAL: indica a PowerShell que lo haga en el ámbito global, en lugar de en el ámbito local en el que se encuentre el script en el momento de ejecución de la instrucción.Redirija el flujo de depuración que no se capture a un flujo que sí se capture, como output. Para lograr esto, configure el redireccionamiento de PowerShell para la instrucción que se debe ejecutar. Para obtener más información sobre el redireccionamiento de PowerShell, consulte Acerca del redireccionamiento.
Ejemplos
En este ejemplo, el runbook se configura mediante los cmdlets Write-Output y Write-Debug con la intención de generar dos flujos diferentes.
Write-Output "This is an output message."
Write-Debug "This is a debug message."
Si este runbook fuera a ejecutarse tal cual, el panel de salida del trabajo del runbook transmitiría el siguiente resultado:
This is an output message.
En este ejemplo, el runbook se ha configurado de forma similar al ejemplo anterior, salvo que la instrucción $GLOBAL:DebugPreference="Continue" se incluye con la adición de 5>&1 al final de la instrucción Write-Debug.
Write-Output "This is an output message."
$GLOBAL:DebugPreference="Continue"
Write-Debug "This is a debug message." 5>&1
Si se ejecutara este runbook, el panel de salida del trabajo del runbook mostraría el siguiente resultado:
This is an output message.
This is a debug message.
Esto se debe a que la instrucción $GLOBAL:DebugPreference="Continue" indica a PowerShell que muestre los mensajes de depuración, y la adición de 5>&1 al final de la instrucción Write-Debug indica a PowerShell que redirija el flujo 5 (debug) al flujo 1 (output).
Escritura de la salida en un flujo detallado
El flujo de mensajes detallados ofrece información general acerca del funcionamiento del runbook. Puesto que el flujo de depuración no está disponible para un runbook, este debe usar los mensajes detallados para la información de depuración.
De forma predeterminada, el historial de trabajos no almacena mensajes detallados de runbooks publicados, por motivos de rendimiento. Para almacenar mensajes detallados, use la pestaña Configurar de Azure Portal con el valor Registrar registros detallados; de este modo establece que los runbooks publicados registren mensajes detallados. Active esta opción solo para solucionar problemas o para depurar un runbook. En la mayoría de los casos, deberá mantener la configuración predeterminada y no escribir los 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. Con esa variable establecida, los mensajes verbosos se muestran en el panel de salida de prueba del portal de Azure.
En el código siguiente se crea un mensaje detallado mediante el cmdlet Write-Verbose.
#The following line creates a verbose message.
Write-Verbose -Message "This is a verbose message."
Manejo de registros de progreso
Puede usar la pestaña Configure del portal de Azure para configurar un runbook para registrar registros de progreso. En la configuración predeterminada no se escriben los registros, con el fin de maximizar el rendimiento. En la mayoría de los casos, debe mantener la configuración predeterminada. Active esta opción solo para solucionar problemas o para depurar un runbook.
Si habilita el registro de progreso, el runbook escribe un registro en el historial de trabajos antes y después de que se ejecute cada actividad. Cuando se prueba un runbook, no se muestran los mensajes de progreso, aunque el runbook esté configurado para registrar estos registros.
Nota:
El cmdlet Write-Progress no es válido en un runbook, ya que está pensado para usarse con un usuario interactivo.
Trabajo con variables de preferencia
Puede establecer determinadas variables de Windows PowerShell preference en los runbooks para controlar la respuesta a los datos enviados a diferentes flujos de salida. En la siguiente tabla se enumeran las variables de preferencia que pueden usarse en runbooks, junto con sus valores predeterminados y válidos. Hay valores adicionales disponibles para las variables de preferencia cuando se usan en Windows PowerShell fuera de Azure Automation.
| Variable | Valor predeterminado | Valores válidos |
|---|---|---|
WarningPreference |
Continuar | Parar Continuar SilentlyContinue |
ErrorActionPreference |
Continuar | Parar Continuar SilentlyContinue |
VerbosePreference |
SilentlyContinue | Parar 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. Este valor hace que se ignore el mensaje. |
| Parar | Registra el mensaje y suspende el runbook. |
Recupera la salida del runbook y los mensajes
Recuperación de salidas de runbook y mensajes en Azure Portal
Puede ver los detalles de un trabajo de runbook en Azure Portal, en la pestaña Trabajos del runbook. El resumen del trabajo muestra 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. El historial de trabajos incluye los mensajes del flujo de salida, así como de los flujos de advertencia y de error. También incluye los mensajes del flujo detallado y los registros de progreso si el runbook está configurado para escribir registros detallados y de progreso.
Nota:
Los flujos de trabajo para los runbooks de Python actualmente son compatibles con la salida en inglés.
Recuperación de salidas de runbook y mensajes en Windows PowerShell
En Windows PowerShell, puede recuperar la salida y los mensajes de un runbook con el cmdlet Get-AzAutomationJobOutput. Este cmdlet requiere la identificación del trabajo y tiene un parámetro denominado Stream en el cual se especifica qué flujo hay que recuperar. Puede especificar un valor de Any para este parámetro, con el fin de recuperar todos los flujos del trabajo.
En el ejemplo siguiente se inicia un runbook y, a continuación, se espera a que finalice. Una vez que el runbook finaliza la ejecución, el script recopila su flujo de salida del trabajo.
$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
Recuperación de salidas de runbook y mensajes en runbooks gráficos
En los runbooks gráficos, hay disponible un registro adicional de salida y mensajes en forma de seguimiento del nivel de actividad. Hay dos niveles de seguimiento: básico y detallado. El seguimiento básico muestra la hora de inicio y de finalización de cada actividad del runbook, así como información relacionada con los reintentos de actividad, como el número de intentos y la hora de inicio de la actividad. El seguimiento detallado incluye las características del seguimiento básico más el registro de los datos de entrada y salida de cada actividad.
Actualmente, el seguimiento en el nivel de actividad escribe registros mediante el flujo detallado. Por lo tanto, debe habilitar el registro detallado cuando habilite el seguimiento. Para los runbooks gráficos con el seguimiento habilitado, no hay ninguna necesidad de escribir registros de progreso. El seguimiento básico tiene la misma finalidad y es más informativo.
En la imagen puede ver que, cuando se habilita el registro detallado y el seguimiento para los runbooks gráficos, hay mucha más información disponible en la vista Transmisiones de trabajo de producción. Esta información adicional puede ser esencial para solucionar problemas de producción con un "runbook" o manual de operaciones.
Sin embargo, a menos que necesite esta información para realizar un seguimiento del progreso de un runbook y solucionar problemas, como procedimiento recomendado le conviene mantener el seguimiento desactivado. Los registros de seguimiento pueden ser particularmente numerosos. Con el seguimiento de runbooks gráficos puede obtener de dos a cuatro registros por actividad, en función de la configuración del seguimiento básico o detallado.
Para habilitar el seguimiento en el nivel de actividad:
En el portal de Azure, abra la cuenta de Automation.
En Automatización de procesos, haga clic en Runbooks para abrir la lista de runbooks.
En la página Runbooks, seleccione un runbook gráfico de la lista.
En Configuración, haga clic en registro y seguimiento.
En la página Registro y seguimiento, en Registrar registros detallados, haga clic en Activar para habilitar el registro detallado.
En Seguimiento a nivel de actividad, cambie el nivel de seguimiento a Básico o Detallado, en función del nivel de seguimiento que necesite.
Recuperación de salida de runbook y mensajes en registros de Microsoft Azure Monitor
Azure Automation puede enviar el estado de un trabajo del runbook y de flujos de trabajos al área de trabajo de Log Analytics. Azure Monitor admite registros que le permiten:
- Obtener información sobre los trabajos de Automation.
- Desencadenar un correo electrónico o una alerta en función del estado del trabajo del runbook (por ejemplo, Error o Suspendido).
- Escribir consultas avanzadas en los flujos de trabajo.
- Correlacionar trabajos entre cuentas de Automation.
- Visualizar el historial de trabajos.
Para obtener más información sobre cómo configurar la integración con registros de Azure Monitor para recopilar, correlacionar y actuar sobre los datos de trabajo, consulte Forward job status and job streams from Automation to Azure Monitor Logs.
Pasos siguientes
- Para ver consultas de ejemplo, consulte Consultas de ejemplo para registros de trabajos y flujos de trabajo
- Para trabajar con runbooks, consulte Administrar runbooks en Azure Automation.
- Si no está familiarizado con el scripting de PowerShell, consulte la documentación de PowerShell.
- Para obtener la referencia del cmdlet de PowerShell de Azure Automation, consulte Az.Automation.
- Para solucionar problemas relacionados con la salida del runbook y los flujos de mensajes, consulte Solución de problemas de runbook.