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

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

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

Использование потока вывода

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

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

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

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

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

Когда функция runbook выполняет запись в поток вывода, выходные данные возвращаются 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

По умолчанию выполнение 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."

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

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

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

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

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

Примеры

В этом примере runbook настраивается с помощью командлетов 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 перейдите на вкладку Настройка и выберите параметр Вести подробный журнал, чтобы опубликованные последовательности runbook записывали в журнал подробные сообщения. Включайте этот параметр только для устранения неполадок и отладки Runbook. В большинстве случаев для runbook следует оставить значение по умолчанию, при котором подробные записи в журнал не добавляются.

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

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

#The following line creates a verbose message.

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

Обработка записей ведения журнала

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

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

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

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

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

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

Извлечение выходных данных и сообщений runbook на портале Azure

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

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

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

В следующем примере запускается пример Runbook и ожидается его завершение. После завершения выполнения runbook скрипт собирает данные потока вывода 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, а также сведения обо всех повторных действиях. Например, число попыток и время начала действия. Подробная трассировка предоставляет базовые возможности, а также запись в журнал входных и выходных данных каждого действия.

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

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

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

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

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

2. Щелкните Модули Runbook в разделе Автоматизация процессов, чтобы открыть список модулей runbook.

3. На странице "Модули Runbook" выберите графическую последовательность runbook.

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

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

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

   

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

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

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

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

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

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