Настройка входных параметров Runbook в службе автоматизации

Статья
08/18/2023

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

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

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

Типы входных данных

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

Тип runbook	Поддерживаемые входные данные параметров
PowerShell	-Строка — Security.SecureString - INT32 -Логических -Datetime -Массива — Collections.Hashtable — Management.Automation.SwitchParameter
Рабочий процесс PowerShell	-Строка — Security.SecureString - INT32 -Логических -Datetime -Массива — Collections.Hashtable — Management.Automation.SwitchParameter
Графический PowerShell	-Строка - INT32 - INT64 -Логических -Десятичных -Datetime -Объекта
Python	-Строка

Настройка входных параметров в модулях Runbook PowerShell

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

Свойство	Description
Тип	Необходимые. Для значения параметра ожидается тип данных. Допускаются любые типы .NET.
Имя.	Обязательно. Имя параметра. Это имя должно быть уникальным для runbook, должно начинаться с буквы, может содержать только буквы, цифры или символы подчеркивания.
Обязательный	Необязательно. Логическое значение указывает, требуется ли параметру значение. Если установлено значение True, при запуске runbook будет необходимо указывать значение. Если установлено значение False, указывать значение необязательно. Если не указать значение для свойства `Mandatory`, PowerShell по умолчанию считает входной параметр необязательным.
Default value	Необязательно. Значение, используемое для параметра, если при запуске runbook не передано входное значение. Последовательность runbook может установить значение по умолчанию для любого параметра.

Наряду с перечисленными выше входными параметрами Windows PowerShell поддерживает дополнительные атрибуты входных параметров, например проверки, псевдонимы и наборы параметров. Однако в настоящее время служба автоматизации Azure поддерживает только перечисленные здесь свойства входных параметров.

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

Param
(
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name1 = <Default value>,

  [Parameter (Mandatory= $true/$false)]
  [Type] $Name2 = <Default value>
)

Теперь настроим входные параметры последовательности runbook рабочего процесса PowerShell, которая выводит сведения об одной или всех виртуальных машинах в группе ресурсов. Как показано на снимке экрана ниже, у такой последовательности runbook будет два параметра: имя виртуальной машины (VMName) и имя группы ресурсов (resourceGroupName).

Automation PowerShell Workflow

В этом определении входные параметры — это простые параметры строкового типа.

Обратите внимание, что последовательности runbook PowerShell и рабочих процессов PowerShell поддерживают для входных параметров все простые и сложные типы, например Object или PSCredential. Чтобы передать значение при наличии в runbook входного параметра object, следует использовать хэш-таблицу PowerShell с парами имя-значение. Предположим, например, что в runbook есть приведенный ниже параметр.

[Parameter (Mandatory = $true)]
[object] $FullName

В этом случае вы можете передать для него следующее значение.

@{"FirstName"="Joe";"MiddleName"="Bob";"LastName"="Smith"}

Для модулей Runbook PowerShell 7.1 укажите входные параметры массива в следующем формате:

Имя	Value
TESTPARAMETER	делает, это, даже, работа

Примечание.

Если не передать значение необязательному строковому параметру со значением по умолчанию NULL, значением параметра будет не NULL, а пустая строка.

Настройка входных параметров в графических модулях Runbook

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

Графический модуль Runbook использует следующие основные действия runbook:

Проверка подлинности с помощью Azure с помощью управляемого удостоверения, настроенного для учетной записи службы автоматизации.
определение командлета Get-AzVM для получения свойств виртуальной машины;
использование действия Write-Output для вывода имен виртуальных машин.

Действие Get-AzVM определяет два входных значения: имя виртуальной машины и имя группы ресурсов. Так как эти имена могут отличаться при каждом запуске последовательности runbook, необходимо добавить входные параметры, чтоб она их принимала. См. статью Графическая разработка в службе автоматизации Azure.

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

На странице "Модули Runbook" выберите графическую последовательность runbook и щелкните Изменить.
В графическом редакторе нажмите кнопку Входные и выходные данные, а затем выберите Добавить входные данные, чтобы открыть область входных параметров runbook.
В элементе управления "Входные и выходные данные" отображается список входных параметров, определенных для runbook. Здесь колонке можно добавить новый входной параметр или изменить конфигурацию имеющегося. Чтобы добавить новый параметр для последовательности runbook, нажмите кнопку Добавить входные данные. Откроется колонка Входной параметр Runbook, где можно настроить параметры с помощью свойств, определенных в статье Графическая разработка в службе автоматизации Azure.
Создайте два параметра со следующими свойствами, которые будут использоваться действием Get-AzVM, а затем нажмите кнопку ОК.
- Параметр 1:
  - Имя -- VMName
  - Тип — строка
  - Обязательный -- Нет
- Параметр 2:
  - Имя -- resourceGroupName
  - Тип — строка
  - Обязательный -- Нет
  - Значение по умолчанию -- особый
  - Настраиваемое значение по умолчанию — имя группы ресурсов, содержащей виртуальные машины
Просмотрите параметры в элементе управления для входных и выходных данных.
Нажмите кнопку ОК снова, а затем нажмите кнопку Сохранить.
Щелкните Опубликовать, чтобы опубликовать runbook.

Настройка входных параметров в модулях Runbook Python

В отличие от последовательностей runbook PowerShell и рабочих процессов PowerShell, а также графических последовательностей runbook, последовательности runbook Python не принимают именованные параметры. Редактор runbook анализирует все входные параметры как массив значений аргументов. Для доступа к массиву можно импортировать модуль sys в свой скрипт Python, а затем используйте массив sys.argv. Обратите внимание, что первый элемент массива (sys.argv[0]) является именем скрипта. Поэтому фактически первым входным параметром является sys.argv[1].

Пример использования входных параметров в модуле Runbook Python см. в статье Мой первый модуль Runbook Python в службе автоматизации Azure.

Примечание.

Аргументы с пробелами в настоящее время не поддерживаются. В качестве обходного решения можно использовать \\t в дополнение к \\n.

Назначение значений входным параметрам в модулях Runbook

В этом разделе описаны несколько способов передачи значений во входные параметры последовательностей runbook. Значения параметров можно назначать при выполнении следующих действий:

Запуск модуля Runbook
Тестирование модуля Runbook
Подключение расписания для последовательности runbook
Создание веб-перехватчика для runbook

Запуск Runbook и назначение параметров

Существует много способов запуска последовательности runbook: с помощью пользовательского интерфейса портала Azure, веб-перехватчика, командлетов PowerShell, REST API или пакета SDK.

Запуск опубликованной последовательности runbook на портале Azure и назначение параметров

При запуске последовательности runbook на портале Azure открывается колонка Запуск Runbook, где можно ввести значения для созданных параметров.

Start using the portal

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

Примечание.

Параметры строкового типа поддерживают пустые строковые значения. Если ввести [EmptyString] в поле входного параметра, ему передастся пустая строка. Кроме того, строковые параметры не поддерживают значение NULL. Если строковому параметру не передать значение, PowerShell интерпретирует отсутствие значения как значение NULL.

Запуск опубликованной последовательности runbook с помощью командлетов PowerShell и назначение параметров

Командлеты Azure Resource Manager. Модуль Runbook службы автоматизации, созданный в группе ресурсов, можно запустить с помощью Start-AzAutomationRunbook.

   $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}

   Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params

Командлеты для классической модели развертывания Azure. Модуль runbook службы автоматизации, созданный в группе ресурсов по умолчанию, можно запустить с помощью командлета Start-AzureAutomationRunbook.
```
   $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}

   Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params
```

Примечание.

При запуске последовательности runbook с помощью командлетов PowerShell создается параметр по умолчанию MicrosoftApplicationManagementStartedBy со значением PowerShell. Этот параметр вы можете просмотреть на странице "Сведения о задании".

Запуск runbook с использованием пакета SDK и назначение параметров

Метод Azure Resource Manager. Модуль Runbook можно запустить с помощью пакета SDK языка программирования. Ниже приведен фрагмент кода C# для запуска модуля Runbook в вашей учетной записи службы автоматизации. Весь код можно просмотреть в нашем репозитории GitHub.
```
public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
{
  var response = AutomationClient.Jobs.Create(resourceGroupName, automationAccount, new JobCreateParameters
  {
    Properties = new JobCreateProperties
    {
      Runbook = new RunbookAssociationProperty
      {
        Name = runbookName
      },
      Parameters = parameters
    }
  });
  return response.Job;
}
```
Метод для классической модели развертывания Azure. Запустить модуль runbook можно с помощью пакета SDK для используемого языка программирования. Ниже приведен фрагмент кода C# для запуска модуля Runbook в вашей учетной записи службы автоматизации. Весь код можно просмотреть в нашем репозитории GitHub.
```
public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
{
  var response = AutomationClient.Jobs.Create(automationAccount, new JobCreateParameters
  {
    Properties = new JobCreateProperties
    {
      Runbook = new RunbookAssociationProperty
      {
        Name = runbookName
      },
      Parameters = parameters
    }
  });
  return response.Job;
}
```
Чтобы запустить этот метод, создайте словарь для хранения параметров VMName runbook и resourceGroupName их значений. Запустите модуль Runbook. Ниже приведен фрагмент кода C# для вызова метода, определенного выше.
```
IDictionary<string, string> RunbookParameters = new Dictionary<string, string>();

// Add parameters to the dictionary.
RunbookParameters.Add("VMName", "WSVMClassic");
RunbookParameters.Add("resourceGroupName", "WSSC1");

//Call the StartRunbook method with parameters
StartRunbook("Get-AzureVMGraphical", RunbookParameters);
```

Запуск runbook с использованием REST API и назначение параметров

Задание runbook можно создать и запустить с помощью REST API службы автоматизации Azure. Для этого необходимо использовать метод PUT и следующий универсальный URI запроса: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

В URI запроса замените следующие параметры:

subscriptionId: идентификатор подписки Azure.
resourceGroupName: имя группы ресурсов для учетной записи службы автоматизации.
automationAccountName: имя учетной записи службы автоматизации, размещенной в указанной облачной службе.
jobName: GUID для задания. Идентификаторы GUID в PowerShell можно создать с помощью [GUID]::NewGuid().ToString()*.

Чтобы передать параметры в задание runbook, используйте текст запроса. Он принимает следующую информацию, представленную в формате JSON:

Runbook Name — обязательный параметр. Имя модуля Runbook для запуска задания.
Runbook Parameters — необязательный параметр. Это словарь со списком параметров (именами и значениями) в формате, где имя должно быть строкового типа, а значение может быть любым допустимым значением JSON.

Если вы хотите запустить последовательность runbook Get-AzureVMTextual, созданную ранее с параметрами VMName и resourceGroupName, используйте следующий формат JSON в тексте запроса.

    {
      "properties":{
        "runbook":{
        "name":"Get-AzureVMTextual"},
      "parameters":{
         "VMName":"WindowsVM",
         "resourceGroupName":"ContosoSales"}
        }
    }

Если задание успешно создано, возвращается код состояния HTTP 201. Дополнительные сведения о заголовках и тексте ответа см. в статье о создании задания runbook с помощью REST API.

Тестирование Runbook и назначение параметров

При тестировании черновой версии runbook с помощью параметра тестирования откроется страница "Тест". Эта страница используется для настройки значений созданных вами параметров.

Test and assign parameters

Связывание Runbook с расписанием и назначение параметров

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

Schedule and assign parameters

Создание объекта Webhook для модуля Runbook и назначение параметров

Для модуля Runbook можно создать объект Webhook и настроить входные параметры. Веб-перехватчик нельзя сохранить, если не указаны значения для всех обязательных параметров.

Create webhook and assign parameters

При выполнении последовательности runbook с помощью веб-перехватчика происходит отправка предопределенного входного параметра [WebhookData](automation-webhooks.md) и определенных вами входных параметров.

WebhookData parameter

Передача объекта JSON в Runbook

Иногда может быть полезным хранить данные, которые необходимо передать в модуль runbook, в файле JSON. Например, можно создать файл JSON, который содержит все параметры, которые необходимо передать в runbook. Чтобы сделать это, необходимо преобразовать код JSON в строку, а затем преобразовать строку в объект PowerShell перед его передачей в последовательность runbook.

В этом разделе используется пример, в котором скрипт PowerShell вызывает Start-AzAutomationRunbook для запуска runbook PowerShell, передавая содержимое файла JSON в runbook. Последовательность runbook PowerShell запускает виртуальную машину Azure, получая параметры для нее из объекта JSON.

Создание файла JSON

Введите следующий код в текстовый файл и сохраните его как test.json в любом месте на своем локальном компьютере.

{
   "VmName" : "TestVM",
   "ResourceGroup" : "AzureAutomationTest"
}

Создание модуля runbook

Создайте новую последовательность runbook PowerShell с именем Test-Json в службе автоматизации Azure.

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

Param(
     [parameter(Mandatory=$true)]
     [object]$json
)

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

# Convert object to actual JSON
$json = $json | ConvertFrom-Json

# Use the values from the JSON object as the parameters for your command
Start-AzVM -Name $json.VMName -ResourceGroupName $json.ResourceGroup -DefaultProfile $AzureContext

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

Из строки 10 удалите $AzureContext = (Connect-AzAccount -Identity).context,
Замените его $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context.
Введите идентификатор клиента.

Сохраните и опубликуйте этот модуль runbook в учетной записи службы автоматизации.

Вызов модуля runbook из PowerShell

Теперь можно вызвать модуль runbook с локального компьютера с помощью Azure PowerShell.

Войдите в Azure, как показано ниже. При этом появится запрос ввести учетные данные Azure.
```
Connect-AzAccount
```
Примечание.

Для модулей runbook PowerShell Add-AzAccount и Add-AzureRMAccount являются псевдонимами для Connect-AzAccount. Обратите внимание, что эти псевдонимы недоступны для графических последовательностей runbook. Графический модуль Runbook может использовать только Connect-AzAccount.
Получите содержимое сохраненного файла JSON и преобразуйте его в строку. JsonPath указывает путь, по которому был сохранен файл JSON.
```
$json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
```
Преобразуйте содержимое строки $json в объект PowerShell.
```
$JsonParams = @{"json"=$json}
```
Создайте хэш-таблицу для параметров Start-AzAutomationRunbook.
```
$RBParams = @{
     AutomationAccountName = 'AATest'
     ResourceGroupName = 'RGTest'
     Name = 'Test-Json'
     Parameters = $JsonParams
}
```
Обратите внимание, что вы задаете значение Parameters объекту PowerShell, который содержит значения из файла JSON.

Запустите runbook.

$job = Start-AzAutomationRunbook @RBParams

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

Сведения о подготовке текстовых последовательностей runbook см. в статье Изменение текстовых последовательностей runbook в службе автоматизации Azure.
Сведения о подготовке графических последовательностей runbook см. в статье о графических runbook в службе автоматизации Azure.

Поделиться через

Настройка входных параметров Runbook в службе автоматизации

Типы входных данных

Настройка входных параметров в модулях Runbook PowerShell

Настройка входных параметров в графических модулях Runbook

Настройка входных параметров в модулях Runbook Python

Назначение значений входным параметрам в модулях Runbook

Запуск Runbook и назначение параметров

Запуск опубликованной последовательности runbook на портале Azure и назначение параметров

Запуск опубликованной последовательности runbook с помощью командлетов PowerShell и назначение параметров

Запуск runbook с использованием пакета SDK и назначение параметров

Запуск runbook с использованием REST API и назначение параметров

Тестирование Runbook и назначение параметров

Связывание Runbook с расписанием и назначение параметров

Создание объекта Webhook для модуля Runbook и назначение параметров

Передача объекта JSON в Runbook

Создание файла JSON

Создание модуля runbook

Вызов модуля runbook из PowerShell

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

Дополнительные ресурсы