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

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

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

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

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

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

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

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

Наряду с перечисленными выше входными параметрами 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).

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

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

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

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

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

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

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

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

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

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

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

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

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

2. В графическом редакторе нажмите кнопку Входные и выходные данные, а затем выберите Добавить входные данные, чтобы открыть область входных параметров runbook.

   

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

   

4. Создайте два параметра со следующими свойствами, которые будут использоваться действием Get-AzVM, а затем нажмите кнопку ОК.

   • Параметр 1:

     • Имя -- VMName
     • Тип — строка
     • Обязательный -- Нет

   • Параметр 2:

     • Имя -- resourceGroupName
     • Тип — строка
     • Обязательный -- Нет
     • Значение по умолчанию -- особый
     • Настраиваемое значение по умолчанию — имя группы ресурсов, содержащей виртуальные машины

5. Просмотрите параметры в элементе управления для входных и выходных данных.

6. Нажмите кнопку ОК снова, а затем нажмите кнопку Сохранить.

7. Щелкните Опубликовать, чтобы опубликовать 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.

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

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

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

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

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

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

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

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

Запуск опубликованной последовательности 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 с использованием пакета 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 с помощью параметра тестирования откроется страница "Тест". Эта страница используется для настройки значений созданных вами параметров.

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

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

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

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

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

Передача объекта 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 выполнялся с управляемым удостоверением, назначаемым системой, оставьте код как есть. Если вы предпочитаете использовать управляемое удостоверение, назначаемое пользователем, сделайте следующее:

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

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

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

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

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

   Connect-AzAccount
   

   Примечание.

   Для модулей runbook PowerShell Add-AzAccount и Add-AzureRMAccount являются псевдонимами для Connect-AzAccount. Обратите внимание, что эти псевдонимы недоступны для графических последовательностей runbook. Графический модуль Runbook может использовать только Connect-AzAccount.

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

   $json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
   

3. Преобразуйте содержимое строки $json в объект PowerShell.

   $JsonParams = @{"json"=$json}
   

4. Создайте хэш-таблицу для параметров Start-AzAutomationRunbook.

   $RBParams = @{
        AutomationAccountName = 'AATest'
        ResourceGroupName = 'RGTest'
        Name = 'Test-Json'
        Parameters = $JsonParams
   }
   

   Обратите внимание, что вы задаете значение Parameters объекту PowerShell, который содержит значения из файла JSON.

5. Запустите runbook.

   $job = Start-AzAutomationRunbook @RBParams
   

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

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