Настройка выходных данных и потоков сообщений в runbook.

Большинство модулей Runbook Cлужба автоматизации Azure имеют некоторую форму выходных данных. Этот вывод может быть сообщением об ошибке для пользователя или сложным объектом, предназначенным для использования с другим runbook. Windows PowerShell предоставляет несколько потоков для отправки выходных данных из скрипта или рабочего процесса. Cлужба автоматизации Azure работает с каждым из этих потоков по-разному. При создании рабочего процесса необходимо следовать лучшим практикам по использованию потоков.

В следующей таблице кратко описывается каждый поток данных с его поведением на портале Azure для опубликованных runbook'ов и во время тестирования runbook. Поток вывода — это основной поток, используемый для обмена данными между runbooks. Остальные потоки классифицируются как потоки сообщений, предназначенные для передачи информации пользователю.

Используйте поток вывода

Поток вывода предназначен для вывода объектов, созданных скриптом или рабочим процессом, когда он работает правильно. Cлужба автоматизации Azure в основном использует этот поток для объектов, используемых родительскими модулями, которые вызывают текущий модуль Runbook. Когда родительский runbook вызывает другой runbook встроенным способом (inline), дочерний runbook возвращает данные из потока вывода родительскому runbook.

Модуль Runbook использует выходной поток для передачи общих сведений клиенту только в том случае, если он никогда не вызывается другим модульом Runbook. Однако в качестве наилучшей практики рекомендуется, чтобы ваши runbooks обычно использовали подробный поток для передачи общей информации пользователю.

Настройте runbook на запись данных в поток вывода с помощью Write-Output. Кроме того, можно поместить объект в отдельную строку скрипта.

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

Обработка выходных данных функции

Когда функция "runbook" записывает в поток вывода, эти данные передаются обратно в "runbook". Если модуль Runbook назначает выходные данные переменной, выходные данные не записываются в выходной поток. Запись в любые другие потоки из функции сопровождается записью в соответствующий поток для runbook. Рассмотрим следующий пример плана рабочего процесса 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"
  }
}

Поток вывода для задания runbook будет следующим:

Output inside of function
Output outside of function

Подробный поток для задания Runbook следующий:

Verbose outside of function
Verbose inside of function

После публикации runbook и перед его запуском необходимо включить подробное ведение журнала в параметрах runbook, чтобы получить вывод подробного потока.

Объявление типа выходных данных

Ниже приведены примеры типов выходных данных.

• System.String
• System.Int32
• System.Collections.Hashtable
• Microsoft.Azure.Commands.Compute.Models.PSVirtualMachine

Объявление типа выходных данных в рабочем процессе

Рабочий процесс указывает тип выходных данных с помощью атрибута OutputType. Этот атрибут не влияет на выполнение, но он предоставляет представление во время разработки о предполагаемых выходных данных рабочей книги. Как инструментарий для runbook продолжает развиваться, возрастает важность объявления типов выходных данных на этапе проектирования. Поэтому рекомендуется включать это объявление во все создаваемые runbook.

Следующий пример рабочей книги выводит строковый объект и включает в себя объявление типа выходных данных. Если Runbook выводит массив определенного типа, все равно следует указать его тип, а не массив типа.

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

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

Объявить тип выходных данных в графическом руководстве

Чтобы объявить тип выходных данных в графическом runbook или в runbook рабочего процесса PowerShell, выберите параметр Входные и выходные данные и укажите тип выходных данных. Рекомендуется использовать полное имя класса .NET, чтобы легко определить тип, когда родительский модуль Runbook ссылается на него. При использовании полного имени все свойства этого класса предоставляются шине данных в runbook. Это повышает гибкость при использовании свойств для условной логики, ведения журнала и ссылки на них как на значение для других действий в последовательности runbook.

Ниже приведен пример с использованием двух графических runbook, демонстрирующих работу функции "входные и выходные данные". При применении модульной модели проектирования Runbook у вас есть один runbook в качестве шаблона Authenticate Runbook, который управляет аутентификацией в Azure с использованием Managed identities. Второе руководство, которое обычно выполняет основную логику для автоматизации данного сценария, в этом случае выполняет шаблон «Проверка подлинности» в сценарии автоматизации. Результаты отображаются в области выходных данных теста. В обычных условиях этот модуль runbook выполнял бы определенные действия в отношении ресурса, используя выходные данные дочернего модуля runbook.

Ниже приведена базовая логика модуля Runbook AuthenticateTo-Azure.
.

Модуль Runbook включает тип вывода Microsoft.Azure.Commands.Profile.Models.PSAzureProfile, который возвращает свойства профиля аутентификации.

Хотя это руководство простое, здесь есть один элемент конфигурации, который стоит отметить. Последнее действие выполняет командлет Write-Output, который записывает данные профиля в переменную через выражение PowerShell для параметра Inputobject. Этот параметр является обязательным для Write-Output.

Вторая последовательность runbook с именем Test-ChildOutputType в нашем примере просто определяет два действия.

Первое действие вызывает runbook AuthenticateTo-Azure. Второе действие запускает командлет Write-Verbose, у которого в качестве источника данных указаны выходные данные действия. Кроме того, путь Field задан как Context.Subscription.Name, что является контекстным результатом из выполнения рабочей книги AuthenticateTo-Azure.

Результат — имя подписки.

Работа с потоками сообщений

В отличие от потока вывода потоки сообщений передают информацию пользователю. Существует несколько потоков сообщений для различных типов информации, и Cлужба автоматизации Azure обрабатывает каждый поток по-разному.

Запись выходных данных в потоки предупреждений и ошибок

Потоки предупреждений и ошибок используются для ведения журнала проблем, возникающих в runbook. Cлужба автоматизации Azure записывает эти потоки в журнал заданий при выполнении модуля Runbook. Автоматизация включает потоки данных в панели результатов теста на портале Azure при тестировании рабочего процесса.

По умолчанию выполнение runbook продолжается после предупреждения или ошибки. Можно указать, что runbook следует приостанавливать при предупреждении или ошибке. Для этого в runbook перед созданием сообщения должна быть задана привилегированная переменная. Например, чтобы runbook приостанавливался при ошибке так же, как при возникновении исключения, задайте переменной ErrorActionPreference значение Stop.

Создайте предупреждение или сообщение об ошибке с помощью командлета Write-Warning или Write-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."

Запись выходных данных в поток отладки

Cлужба автоматизации Azure использует поток сообщений отладки для интерактивных пользователей. По умолчанию Cлужба автоматизации Azure не фиксирует данные потока отладки, только выходные данные, ошибки и предупреждения, а также подробные данные, если модуль Runbook настроен для его записи.

Чтобы записать данные потока отладки, необходимо выполнить два действия в runbook:

1. Задать переменную $GLOBAL:DebugPreference="Continue", которая указывает PowerShell продолжать работу при обнаружении сообщения отладки. Часть $GLOBAL: указывает PowerShell сделать это в глобальной области, а не локальной, где находится скрипт во время выполнения инструкции.

2. Перенаправить поток отладки, который мы не записываем, в поток, который мы записываем, например выходные данные. Это делается путем установки перенаправления PowerShell для инструкции, которую необходимо выполнить. Дополнительные сведения о перенаправлении PowerShell см. в статье О перенаправлении.

Примеры

В этом примере рабочий процесс настраивается с помощью командлетов Write-Output и Write-Debug с целью вывода двух разных потоков.

Write-Output "This is an output message." 
Write-Debug "This is a debug message."

Если бы этот runbook выполнялся как есть, то в выводной области задания runbook отображался бы поток следующих данных:

This is an output message.

В этом примере runbook настраивается аналогично предыдущему примеру, за исключением того, что инструкция $GLOBAL:DebugPreference="Continue" включается вместе с добавлением 5>&1 в конце инструкции Write-Debug.

Write-Output "This is an output message." 
$GLOBAL:DebugPreference="Continue" 
Write-Debug "This is a debug message." 5>&1

Если бы этот runbook был выполнен, в области вывода задания runbook отображался бы следующий поток данных:

This is an output message.
This is a debug message.

Это обусловлено тем, что инструкция $GLOBAL:DebugPreference="Continue" сообщает PowerShell о необходимости вывода сообщений об отладке, а добавление 5>&1 в конец инструкции Write-Debug указывает PowerShell перенаправлять поток 5 (отладка) в поток 1 (выходные данные).

Запись выходных данных в отладочный поток

Поток подробных сообщений поддерживает передачу общих сведений о работе runbook. Так как поток отладки недоступен для модуля Runbook, модуль Runbook должен использовать подробные сообщения для отладочной информации.

По умолчанию журнал заданий не сохраняет подробные сообщения из опубликованных рабочих книг из-за соображений производительности. Чтобы сохранить подробные сообщения, используйте портал Azure, вкладку Configure с параметром Log Verbose Records для настройки ваших опубликованных рабочих книг на запись подробных сообщений. Включайте этот параметр только для устранения неполадок и отладки Runbook. В большинстве случаев вам следует оставить значение по умолчанию, при котором не ведется подробный журнал.

При тестировании модуля runbook подробные сообщения не отображаются, даже если для runbook настроено добавление подробных записей в журнал. Для отображения подробных сообщений при тестировании инструкции выполнения необходимо присвоить переменной VerbosePreference значение Continue. С помощью этого набора переменных подробные сообщения отображаются в области выходных данных теста на портале Azure.

Приведенный ниже код создает подробное сообщение, используя командлет Write-Verbose.

#The following line creates a verbose message.

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

Обработка записей прогресса

Вкладку Configure на портале Azure можно использовать для настройки рабочей книги для записи записей о ходе выполнения. Чтобы обеспечить максимальную производительность, такие записи в журнал по умолчанию не добавляются. В большинстве случаев следует использовать параметр по умолчанию. Включайте этот параметр только для устранения неполадок и отладки Runbook.

Если включить ведение журнала записей о ходе выполнения, runbook будет добавлять в журнал заданий запись до и после выполнения каждого действия. Тестирование Runbook не отображает сообщения о ходе выполнения, даже если Runbook настроен для ведения записей хода выполнения.

Использование привилегированных переменных

Вы можете задать определенные переменные Windows PowerShell preference в модулях Runbook, чтобы управлять ответом на данные, отправленные в разные выходные потоки. В следующей таблице перечислены переменные предпочтений, которые могут использоваться в runbook, а также их значения по умолчанию и допустимые значения. Дополнительные значения доступны для переменных предпочтения при использовании в Windows PowerShell за пределами Cлужба автоматизации Azure.

В следующей таблице представлено поведение для соответствующих значений привилегированных переменных, допустимых в runbook.

Извлечение данных и сообщений из runbook.

Получение выходных данных и сообщений Runbook на портале Azure

Вы можете просмотреть сведения о задании Runbook на портале Azure, используя вкладку Jobs для задания Runbook. Помимо общей информации о задании, в сводке будут перечислены входные параметры, поток вывода, а также все возникшие исключения. Журнал заданий содержит сообщения из потока вывода и потоков предупреждений и ошибок. Он также содержит сообщения из подробного потока и записей о ходе выполнения, если для планировщика задач настроено ведение журнала подробных данных и записей о ходе выполнения.

Получение выходных данных и сообщений сценария runbook в Windows PowerShell

В powerShell Windows можно получить выходные данные и сообщения из модуля Runbook с помощью командлета Get-AzAutomationJobOutput. Для этого командлета требуется идентификатор задания. У него также есть параметр Stream, с помощью которого можно указать извлекаемый поток. Указав значение Any для этого параметра, можно получить все потоки для задания.

В этом примере запускается тестовый Runbook и ожидается его завершение. После завершения выполнения ранбука, скрипт собирает данные потока вывода ранбука из задания.

$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

Извлечение выходных данных и сообщений runbook в графических последовательностях runbook

Для графических последовательностей runbook дополнительное ведение журнала выходных данных и сообщений доступно в виде трассировки на уровне действий. Существует два уровня трассировки: базовая и подробная. При базовой трассировке отображается время начала и окончания каждого действия в runbook, а также сведения обо всех повторных действиях. Например, число попыток и время начала действия. Подробная трассировка включает основные функции, а также журналирование входных и выходных данных для каждой операции.

В настоящее время при трассировке на уровне активности записи ведутся с помощью подробного потока. Поэтому необходимо включить подробное ведение журнала при активации трассировки. Для графических runbooks с включенной трассировкой нет необходимости вести записи о прогрессе. Базовая трассировка служит той же цели и более информативна.

На приведенном выше изображении видно, что при включении подробного ведения журнала и трассировки графические последовательности runbook предоставляют гораздо больше данных в представлении Потоки заданий в рабочей среде. Эти дополнительные сведения могут быть необходимы для устранения неполадок в производственной среде с помощью плана действий.

Однако, если эти данные не требуются для отслеживания выполнения рабочего сценария в целях устранения неполадок, в общем, рекомендуется отключать трассировку. Записи трассировки могут быть очень многочисленными. В зависимости от того, какая конфигурация трассировки выбрана (базовая или подробная), при трассировке графических последовательностей runbook создается от двух до четырех записей по каждому действию.

Чтобы включить трассировку на уровне активности, выполните следующие действия.

1. На портале Azure откройте учетную запись службы автоматизации.

2. Выберите Runbooks в разделе Автоматизация процессов для открытия списка runbooks.

3. На странице "Runbooks" выберите графический runbook из вашего списка runbooks.

4. В разделе Параметры щелкните Ведение журналов и трассировка.

5. На странице "Ведение журнала и трассировка" в разделе Подробные записи в журнале щелкните Включить, чтобы активировать запись подробных сведений в журнал.

6. В разделе Трассировка уровня действия измените уровень трассировки на Базовый или Подробный в зависимости от того, какой из них требуется.
   

   

Получение выходных данных и сообщений из Runbook в журналах Microsoft Azure Monitor

Cлужба автоматизации Azure может отправлять состояние и потоки заданий Runbook в рабочую область Log Analytics. Azure Monitor поддерживает журналы, которые позволяют:

• узнать полезные сведения о заданиях автоматизации;
• Активировать отправку электронного сообщения или оповещения в зависимости от статуса задания в регламенте, например, если оно не выполнено или приостановлено.
• создавать сложные запросы для потоков заданий;
• Сопоставьте задания между учетными записями автоматизации.
• Отобразить журнал заданий.

Дополнительные сведения о настройке интеграции с журналами Azure Monitor для сбора, корреляции и работы с данными заданий см. в статье Forward job status and job streams from Automation to Azure Monitor Logs.

Следующие шаги

• Примеры запросов см. в разделе "Примеры запросов" для журналов заданий и потоков заданий
• Сведения о работе с руководствами по сценариям см. в разделе Управление руководствами по сценариям в Cлужба автоматизации Azure.
• Если вы не знакомы со сценариями PowerShell, ознакомьтесь с документацией по PowerShell .
• Справочник по командлету PowerShell Cлужба автоматизации Azure см. в разделе Az.Automation.
• Сведения об устранении неполадок, связанных с выходными данными runbook и потоками сообщений, см. в разделе "Устранение неполадок с модулями Runbook".