Automation에서 Runbook 입력 매개 변수 구성

아티클
03/06/2024

Runbook 입력 매개 변수는 시작하는 Runbook에 데이터를 전달할 수 있도록 하여 Runbook의 유연성을 늘립니다. 이러한 매개 변수는 Runbook 동작이 특정 시나리오 및 환경에 대한 대상이 되도록 합니다. 이 문서에서는 Runbook에서 입력 매개 변수를 구성하고 사용하는 방법을 설명합니다.

PowerShell, PowerShell 워크플로, 그래픽 및 Python Runbook에 대한 입력 매개 변수를 구성할 수 있습니다. Runbook에는 데이터 형식이 다양한 여러 매개 변수가 있거나 매개 변수가 없을 수 있습니다. 입력 매개 변수는 필수 또는 선택 사항일 수 있으며, 선택적 매개 변수에 기본값을 사용할 수 있습니다.

Runbook을 시작할 때 Runbook의 입력 매개 변수에 값을 할당합니다. Runbook은 Azure Portal, 웹 서비스 또는 PowerShell에서 시작할 수 있습니다. 또한 다른 Runbook에서 인라인으로 호출되는 하위 Runbook으로 시작할 수 있습니다.

입력 유형

Azure Automation은 다양한 Runbook 형식에서 다양한 입력 매개 변수 값을 지원합니다. 다음 표에는 각 Runbook 형식에 지원되는 입력 형식이 나와 있습니다.

Runbook 형식	지원되는 매개 변수 입력
PowerShell	- 문자열 - Security.SecureString - INT32 - 부울 - 날짜/시간 - 배열 - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell 워크플로	- 문자열 - Security.SecureString - INT32 - 부울 - 날짜/시간 - 배열 - Collections.Hashtable - Management.Automation.SwitchParameter
그래픽 PowerShell	- 문자열 - INT32 - INT64 - 부울 - 10진 - 날짜/시간 - 개체
Python	- 문자열

PowerShell Runbook에서 입력 매개 변수 구성

Azure Automation의 PowerShell 및 PowerShell 워크플로 Runbook은 다음과 같은 속성을 통해 정의된 입력 매개 변수를 지원합니다.

속성	설명
Type	필수입니다. 매개 변수 값에 필요한 데이터 형식입니다. 모든 .NET 형식이 유효합니다.
이름	필수입니다. 매개 변수의 이름입니다. 이 이름은 Runbook 내에서 고유해야 하고, 문자로 시작해야 하며, 문자, 숫자 또는 밑줄 문자만 포함할 수 있습니다.
필수	선택 사항. 부울 값은 매개 변수에 값이 필요한지 여부를 지정합니다. 이 값을 True로 설정한 경우 Runbook이 시작될 때 값을 지정해야 합니다. 이 값을 False로 설정한 경우 값은 선택 사항입니다. `Mandatory` 속성에 값을 지정하지 않으면 PowerShell은 기본적으로 입력 매개 변수를 선택 사항으로 간주합니다.
기본값	선택 사항. Runbook이 시작할 때 입력 값이 전달되지 않는 경우 매개 변수에 사용되는 값입니다. Runbook은 모든 매개 변수에 기본값을 설정할 수 있습니다.

Windows PowerShell은 유효성 검사, 별칭, 매개 변수 설정과 같이 위에 나열된 것보다 많은 입력 매개 변수 특성을 지원합니다. 그러나 현재 Azure Automation은 나열된 입력 매개 변수 특성만 지원합니다.

예를 들어 PowerShell 워크플로 Runbook의 매개 변수 정의를 살펴보겠습니다. 이 정의의 일반적인 형식은 다음과 같습니다. 여기서 여러 매개 변수는 쉼표로 구분됩니다.

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

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

이제 가상 머신(단일 VM 또는 리소스 그룹 내의 모든 VM)에 대한 세부 정보를 출력하는 PowerShell 워크플로 Runbook에 대한 입력 매개 변수를 구성해보겠습니다. 다음 스크린샷에 표시된 대로 이 Runbook에는 가상 머신의 이름(VMName) 및 리소스 그룹 이름(resourceGroupName)이라는 두 가지 매개 변수가 있습니다.

Automation PowerShell Workflow

이 매개 변수 정의에서 입력 매개 변수는 문자열 형식의 단순 매개 변수입니다.

PowerShell 및 PowerShell 워크플로 Runbook은 입력 매개 변수에 대해 Object 또는 PSCredential과 같은 단순 형식 및 복합 형식을 모두 지원합니다. Runbook에 개체 형식 입력 매개 변수가 있는 경우 값에 전달하려면 이름-값 쌍이 있는 PowerShell 해시 테이블을 사용해야 합니다. 예를 들어 Runbook에 다음 매개 변수가 있습니다.

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

이 경우 매개 변수에 다음 값을 전달할 수 있습니다.

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

PowerShell 7.1 Runbook의 경우 아래 형식으로 배열 입력 매개 변수를 제공합니다.

이름	값
TESTPARAMETER	does,this,even,work

참고 항목

Null 기본값을 사용하여 선택적 문자열 매개 변수에 값을 전달하지 않는 경우 이 매개 변수의 값은 Null이 아닌 빈 문자열입니다.

그래픽 Runbook에서 입력 매개 변수 구성

그래픽 Runbook에 대한 입력 매개 변수 구성을 설명하기 위해 가상 머신(단일 VM 또는 리소스 그룹 내의 모든 VM)에 대한 세부 정보를 출력하는 그래픽 Runbook을 만들겠습니다. 자세한 내용은 내 첫 번째 그래픽 Runbook을 참조하세요.

그래픽 Runbook은 다음과 같은 주요 Runbook 활동을 사용합니다.

자동화 계정에 대해 구성된 관리 ID를 사용하여 Azure에 인증합니다.
VM 속성을 가져오는 Get-AzVM cmdlet을 정의합니다.
쓰기 출력 활동을 사용하여 VM 이름을 출력합니다.

Get-AzVM 활동은 두 개의 입력인 VM 이름과 리소스 그룹 이름을 정의합니다. Runbook이 시작할 때마다 이러한 이름이 다를 수 있으므로 입력 매개 변수를 Runbook에 추가하여 이러한 입력을 수락해야 합니다. Azure Automation에서 그래픽 작성을 참조하세요.

입력 매개 변수를 구성하려면 다음 단계를 수행합니다.

Runbook 페이지에서 그래픽 Runbook을 선택한 다음 편집을 클릭합니다.
그래픽 편집기에서 입력 및 출력 단추를 클릭한 다음 입력 추가를 선택하여 Runbook 입력 매개 변수 창을 엽니다.
입력 및 출력 컨트롤에는 Runbook에 정의된 입력 매개 변수 목록이 표시됩니다. 여기에서 새 입력 매개 변수를 추가하거나 기존의 입력 매개 변수의 구성을 편집합니다. Runbook에 대한 새 매개 변수를 추가하려면 입력 추가를 클릭하여 Runbook 입력 매개 변수 블레이드를 엽니다. 여기서 Azure Automation에서 그래픽 작성에 정의된 속성을 사용하여 매개 변수를 구성할 수 있습니다.
다음 속성을 사용하여 Get-AzVM 활동에서 사용할 두 매개 변수를 만든 다음 확인을 클릭합니다.
- 매개 변수 1:
  - 이름 -- VMName
  - 형식 -- String
  - 필수 -- 아니요
- 매개 변수 2:
  - 이름 -- resourceGroupName
  - 형식 -- String
  - 필수 -- 아니요
  - 기본값 -- 사용자 지정
  - 사용자 지정 기본값 -- VM을 포함하는 리소스 그룹의 이름
입력 및 출력 컨트롤의 매개 변수를 확인합니다.
확인을 다시 클릭하고 저장을 클릭합니다.
게시를 클릭하여 Runbook을 게시합니다.

Python Runbook에서 입력 매개 변수 구성

PowerShell, PowerShell 워크플로 및 그래픽 Runbook과 달리 Python Runbook에서는 명명된 매개 변수를 사용하지 않습니다. Runbook 편집기는 모든 입력 매개 변수를 인수 값 배열로 구문 분석합니다. sys 모듈을 Python 스크립트에 가져온 다음 sys.argv 배열을 사용하여 배열에 액세스할 수 있습니다. 배열의 첫 번째 요소인 sys.argv[0]는 스크립트의 이름입니다. 따라서 첫 번째 실제 입력 매개 변수는 sys.argv[1]입니다.

Python Runbook에서 입력 매개 변수를 사용하는 방법의 예제를 보려면 Azure Automation의 내 첫 번째 Python Runbook을 참조하세요.

참고 항목

공백이 있는 인수는 현재 지원되지 않습니다. 해결 방법으로 \\n 외에도 \\t를 사용할 수 있습니다.

Runbook의 입력 매개 변수에 값 할당

이 섹션에서는 Runbook의 입력 매개 변수에 값을 전달하는 여러 가지 방법에 대해 설명합니다. 다음 작업을 수행할 때 매개 변수 값을 할당할 수 있습니다.

Runbook 시작
Runbook 테스트
Runbook 일정 연결
Runbook에 대한 웹후크 만들기

Runbook 시작 및 매개 변수 할당

Runbook은 Azure Portal, 웹후크, PowerShell cmdlet, REST API, SDK 등 여러 가지 방법을 통해 시작할 수 있습니다.

Azure Portal을 사용하여 게시된 Runbook 시작 및 매개 변수 할당

Azure Portal에서 Runbook을 시작하면 Runbook 시작 블레이드가 열려 만든 매개 변수의 값을 입력할 수 있습니다.

Start using the portal

입력 상자 아래의 레이블에 매개 변수 특성을 정의하도록 설정된 속성을 볼 수 있습니다(예: 필수 또는 선택, 형식, 기본값). 또한 매개 변수 이름 옆에 있는 도움말 풍선에는 매개 변수 입력 값을 결정하는 데 필요한 모든 핵심 정보가 정의됩니다.

참고 항목

문자열 매개 변수는 문자열 형식의 빈 값을 지원합니다. 입력 매개 변수 상자에 [EmptyString]을 입력하면 빈 문자열을 매개 변수에 전달합니다. 또한 문자열 매개 변수는 Null을 지원하지 않습니다. 문자열 매개 변수에 값을 전달하지 않으면 PowerShell은 이를 Null로 해석합니다.

PowerShell cmdlet을 사용하여 게시된 Runbook 시작 및 매개 변수 할당

Azure Resource Manager cmdlet:Start-AzAutomationRunbook을 사용하여 리소스 그룹에 생성된 자동화 Runbook을 시작할 수 있습니다.

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

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

Azure 클래식 배포 모델 cmdlet: Start-AzureAutomationRunbook을 사용하여 기본 리소스 그룹에 생성된 자동화 Runbook을 시작할 수 있습니다

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

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

참고 항목

PowerShell cmdlet을 사용하여 Runbook을 시작하는 경우 기본 매개 변수 MicrosoftApplicationManagementStartedBy가 PowerShell 값을 사용하여 만들어집니다. 작업 세부 정보 창에서 이 매개 변수를 볼 수 있습니다.

SDK를 사용하여 Runbook 시작 및 매개 변수 할당

Azure Resource Manager 방법: 프로그래밍 언어의 SDK를 사용하여 Runbook을 시작할 수 있습니다. 다음은 Automation 계정의 Runbook을 시작하기 위한 C# 코드 조각입니다. 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 클래식 배포 모델 방법: 프로그래밍 언어의 SDK를 사용하여 Runbook을 시작할 수 있습니다. 다음은 Automation 계정의 Runbook을 시작하기 위한 C# 코드 조각입니다. 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;
}

이 메서드를 시작하려면 Runbook 매개 변수 VMName 및 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);

REST API를 사용하여 Runbook 시작 및 매개 변수 할당

PUT 메서드를 다음 요청 URI와 함께 사용하여 Azure Automation REST API로 Runbook 작업을 만들고 시작할 수 있습니다. https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

요청 URI에서 다음 매개 변수를 바꿉니다.

subscriptionId: Azure 구독 ID입니다.
resourceGroupName: Automation 계정의 리소스 그룹 이름입니다.
automationAccountName: 지정된 클라우드 서비스 내에 호스트되는 Automation 계정의 이름입니다.
jobName: 작업의 GUID입니다. PowerShell의 GUID는 [GUID]::NewGuid().ToString()*을 사용하여 만들 수 있습니다.

Runbook 작업에 매개 변수를 전달하려면 요청 본문을 사용합니다. 요청 본문은 JSON 형식으로 제공되는 다음 정보를 사용합니다.

Runbook 이름: 필수입니다. 시작할 작업 시작에 대한 Runbook의 이름입니다.
Runbook 매개 변수: 선택 사항입니다. 이름이 문자열 형식이고 값은 유효한 JSON 값일 수 있는 (이름, 값) 형식인 매개 변수 목록의 사전입니다.

앞서 VMName 및 resourceGroupName을 사용하여 만든 Get-AzureVMTextual Runbook을 시작하려는 경우 요청 본문에 다음 JSON 형식을 사용합니다.

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

작업이 성공적으로 만들어진 경우 HTTP 상태 코드 201이 반환됩니다. 응답 헤더 및 응답 본문에 대한 자세한 내용은 REST API를 사용하여 Runbook 작업 만들기를 참조하세요.

Runbook 테스트 및 매개 변수 할당

테스트 옵션을 사용하여 Runbook의 초안 버전을 테스트하면 테스트 페이지가 열립니다. 이 페이지를 사용하여 만든 매개 변수의 값을 구성할 수 있습니다.

Test and assign parameters

Runbook에 일정 연결 및 매개 변수 할당

Runbook이 특정 시간에 시작하도록 Runbook에 일정을 연결할 수 있습니다. 일정을 만드는 동안 입력 매개 변수를 할당하고 Runbook이 일정에 따라 시작될 때 이러한 값을 사용합니다. 모든 필수 매개 변수 값이 제공될 때까지 일정을 저장할 수 없습니다.

Schedule and assign parameters

Runbook에 대한 webhook 만들기 및 매개 변수 할당

Runbook에 대한 webhook 을 만들고 Runbook 입력 매개 변수를 구성할 수 있습니다. 모든 필수 매개 변수 값이 제공될 때까지 웹후크를 저장할 수 없습니다.

Create webhook and assign parameters

웹후크를 사용하여 Runbook을 실행할 때 미리 정의된 입력 매개 변수 [WebhookData](automation-webhooks.md)가 사용자가 정의한 입력 매개 변수와 함께 전송됩니다.

WebhookData parameter

JSON 개체를 Runbook에 전달합니다.

JSON 파일에서 Runbook에 전달하려는 데이터를 저장하는 것이 유용할 수 있습니다. 예를 들어 Runbook에 전달하려는 모든 매개 변수가 포함된 JSON 파일을 만들 수 있습니다. 이렇게 하려면 JSON 코드를 문자열로 변환한 다음 해당 문자열을 PowerShell 개체로 변환한 후 해당 개체를 Runbook에 전달해야 합니다.

이 섹션에서는 PowerShell 스크립트가 Start-AzAutomationRunbook를 호출하여 PowerShell Runbook을 시작하고 JSON 파일의 내용을 Runbook에 전달하는 예제를 사용합니다. PowerShell Runbook은 JSON 개체에서 VM에 대한 매개 변수를 검색하여 Azure VM을 시작합니다.

JSON 파일 만들기

텍스트 파일에 다음 코드를 입력하고 로컬 컴퓨터의 어딘가에 test.json으로 저장합니다.

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

Runbook 만들기

Azure Automation에서 Test-Json이라는 새 PowerShell Runbook을 만듭니다.

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

시스템이 할당한 관리 ID를 사용하여 Runbook을 실행하려면 코드를 그대로 둡니다. 사용자가 할당한 관리 ID를 사용하려면 다음을 수행합니다.

10번째 줄에서 $AzureContext = (Connect-AzAccount -Identity).context를 제거합니다.
$AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context로 바꿉니다.
클라이언트 ID를 입력합니다.

이 Runbook을 Automation 계정에 저장하고 게시합니다.

PowerShell에서 Runbook 호출

이제 로컬 컴퓨터에서 Azure PowerShell을 사용하여 Runbook을 호출할 수 있습니다.

표시된 대로 Azure에 로그인합니다. 그러면 Azure 자격 증명을 입력하라는 메시지가 표시됩니다.
```
Connect-AzAccount
```
참고 항목

PowerShell Runbook의 경우 Add-AzAccount 및 Add-AzureRMAccount는 Connect-AzAccount에 대한 별칭입니다. 이러한 별칭은 그래픽 Runbook에서 사용할 수 없습니다. Connect-AzAccount 자체만 그래픽 Runbook에서 사용할 수 있습니다.
저장된 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의 값을 JSON 파일의 값이 포함된 PowerShell 개체로 설정하고 있는 것입니다.

Runbook을 시작합니다.

$job = Start-AzAutomationRunbook @RBParams

다음 단계

텍스트 Runbook을 준비하려면 Azure Automation에서 텍스트 Runbook 편집을 참조하세요.
그래픽 Runbook을 준비하려면 Azure Automation에서 그래픽 Runbook 작성을 참조하세요.

다음을 통해 공유

Automation에서 Runbook 입력 매개 변수 구성

입력 유형

PowerShell Runbook에서 입력 매개 변수 구성

그래픽 Runbook에서 입력 매개 변수 구성

Python Runbook에서 입력 매개 변수 구성

Runbook의 입력 매개 변수에 값 할당

Runbook 시작 및 매개 변수 할당

Azure Portal을 사용하여 게시된 Runbook 시작 및 매개 변수 할당

PowerShell cmdlet을 사용하여 게시된 Runbook 시작 및 매개 변수 할당

SDK를 사용하여 Runbook 시작 및 매개 변수 할당

REST API를 사용하여 Runbook 시작 및 매개 변수 할당

Runbook 테스트 및 매개 변수 할당

Runbook에 일정 연결 및 매개 변수 할당

Runbook에 대한 webhook 만들기 및 매개 변수 할당

JSON 개체를 Runbook에 전달합니다.

JSON 파일 만들기

Runbook 만들기

PowerShell에서 Runbook 호출

다음 단계

피드백

피드백

추가 리소스