작업 출력을 입력으로 사용 - AWS Systems Manager
런북에서 JSONPath 사용

AWS Systems Manager Change Manager는 더 이상 신규 고객에게 공개되지 않습니다. 기존 고객은 정상적으로 서비스를 계속 이용할 수 있습니다. 자세한 내용은 AWS Systems Manager Change Manager 가용성 변경을 참조하세요.

작업 출력을 입력으로 사용

몇 가지 자동화 작업은 사전 정의된 출력을 반환합니다. {{stepName.outputName}} 형식을 사용하여 이러한 출력을 런북의 이후 단계에 입력으로 전달할 수 있습니다. 런북에서 다양한 자동화 작업의 출력을 정의할 수 있습니다. 이를 통해 스크립트를 실행하거나 다른 AWS 서비스를 위한 API 작업을 한 번 호출하여 이후 작업에서 해당 값을 입력으로 재사용할 수 있습니다. 런북의 파라미터 유형은 정적입니다. 즉, 파라미터 유형을 정의한 후에는 변경할 수 없습니다. 단계 출력을 정의하려면 다음 필드를 제공하십시오.

  • 이름: (필수) 이후 단계에서 출력 값을 참조하는 데 사용되는 출력 이름입니다.

  • 선택기: (필수) 출력 값을 결정하는 데 사용되는 JSONPath 표현식입니다.

  • 유형: (선택 사항) 선택기 필드에서 반환되는 값의 데이터 유형입니다. 유효한 유형 값은String, Integer, Boolean, StringList, StringMap, MapList입니다. 기본값은 String입니다.

출력 값이 지정한 데이터 유형과 일치하지 않는 경우 Automation은 데이터 유형을 변환하려고 시도합니다. 예를 들어, 반환된 값이 Integer이지만 지정된 Type은 String인 경우 최종 출력 값은 String 값입니다. 다음과 같은 유형의 반환이 지원됩니다.

  • String 값을 StringList, Integer 및 Boolean로 변환할 수 있습니다.

  • Integer 값을 String, StringList로 변환할 수 있습니다.

  • Boolean 값을 String, StringList로 변환할 수 있습니다.

  • 한 가지 요소가 포함된 StringList, IntegerList 또는 BooleanList 값은 String, Integer 또는 Boolean으로 변환할 수 없습니다.

자동화 작업에 파라미터 또는 출력을 사용하면 데이터 유형을 작업의 입력 내에서 동적으로 변경할 수 없습니다.

다음은 작업 출력을 정의하고 해당 값을 이후 작업의 입력으로 참조하는 방법을 보여주는 예제 런북입니다. 이 런북은 다음 작업을 수행합니다.

  • aws:executeAwsApi 작업을 사용하여 특정 Windows Server 2016 AMI의 이름을 가져오도록 Amazon EC2 DescribeImages API 작업을 호출합니다. 이미지 ID를 ImageId로 출력합니다.

  • aws:executeAwsApi 작업을 사용하여 이전 단계의 ImageId를 사용하는 인스턴스 하나를 시작하도록 Amazon EC2 RunInstances API 작업을 호출합니다. 인스턴스 ID를 InstanceId로 출력합니다.

  • aws:waitForAwsResourceProperty 작업을 사용하여 인스턴스가 running 상태에 도달할 때까지 기다리도록 Amazon EC2 DescribeInstanceStatus API 작업을 폴링합니다. 작업 제한 시간은 60초입니다. 폴링 후 60초가 경과되었지만 인스턴스가 running 상태에 도달하지 못하면 단계가 시간 초과됩니다.

  • aws:assertAwsResourceProperty 작업으로 Amazon EC2 DescribeInstanceStatus API 작업을 호출하여 인스턴스가 running 상태에 있음을 어설션합니다. 인스턴스 상태가 running이 아니면 단계가 실패합니다.

---
description: Sample runbook using AWS API operations
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
  AutomationAssumeRole:
    type: String
    description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf."
    default: ''
  ImageName:
    type: String
    description: "(Optional) Image Name to launch EC2 instance with."
    default: "Windows_Server-2022-English-Full-Base*"
mainSteps:
- name: getImageId
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: DescribeImages
    Filters:  
    - Name: "name"
      Values: 
      - "{{ ImageName }}"
  outputs:
  - Name: ImageId
    Selector: "$.Images[0].ImageId"
    Type: "String"
- name: launchOneInstance
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: RunInstances
    ImageId: "{{ getImageId.ImageId }}"
    MaxCount: 1
    MinCount: 1
  outputs:
  - Name: InstanceId
    Selector: "$.Instances[0].InstanceId"
    Type: "String"
- name: waitUntilInstanceStateRunning
  action: aws:waitForAwsResourceProperty
  timeoutSeconds: 60
  inputs:
    Service: ec2
    Api: DescribeInstanceStatus
    InstanceIds:
    - "{{ launchOneInstance.InstanceId }}"
    PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
    DesiredValues:
    - running
- name: assertInstanceStateRunning
  action: aws:assertAwsResourceProperty
  inputs:
    Service: ec2
    Api: DescribeInstanceStatus
    InstanceIds:
    - "{{ launchOneInstance.InstanceId }}"
    PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
    DesiredValues:
    - running
outputs:
- "launchOneInstance.InstanceId"
...

각각의 이전에 설명된 자동화 작업을 통해 서비스 네임스페이스, API 작업 이름, 입력 파라미터 및 출력 파라미터를 지정하여 특정 API 작업을 호출할 수 있습니다. 입력은 선택하는 API 작업에 의해 정의됩니다. 다음 [서비스 참조(Services Reference)] 페이지의 왼쪽 탐색 영역에서 서비스를 선택하여 API 작업(메서드라고도 함)을 볼 수 있습니다. 호출할 서비스에 대한 클라이언트 섹션에서 메서드를 선택합니다. 예를 들어 Amazon Relational Database Service(Amazon RDS)에 대한 모든 API 작업(메서드)이 Amazon RDS 메서드 페이지에 나열됩니다.

다음 위치에서 각 자동화 작업에 대한 스키마를 볼 수 있습니다.

스키마에는 각 작업을 사용하기 위한 필수 필드에 대한 설명이 포함되어 있습니다.

Selector/PropertySelector 필드 사용

각 Automation 작업에서는 출력 Selector(aws:executeAwsApi의 경우) 또는 PropertySelector(aws:assertAwsResourceProperty 및 aws:waitForAwsResourceProperty의 경우)를 지정해야 합니다. 이러한 필드는 AWS API 작업의 JSON 응답을 처리하는 데 사용됩니다. 이러한 필드는 JSONPath 구문에 사용됩니다.

다음은 aws:executeAwsAPi 작업과 관련하여 이 개념을 설명하는 데 도움이 되는 예제입니다.

---
mainSteps:
- name: getImageId
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: DescribeImages
    Filters:  
      - Name: "name"
        Values: 
          - "{{ ImageName }}"
  outputs:
    - Name: ImageId
      Selector: "$.Images[0].ImageId"
      Type: "String"
...

이 자동화는 aws:executeAwsApi 단계인 getImageId에서 DescribeImages API 작업을 호출하고 ec2의 응답을 수신합니다. 그런 다음 이 자동화는 Selector - "$.Images[0].ImageId"를 API 응답에 적용하고 선택한 값을 ImageId 변수에 할당합니다. 동일한 자동화의 다른 단계에서는 "{{ getImageId.ImageId }}"를 지정하여 ImageId의 값을 사용할 수 있습니다.

다음은 aws:waitForAwsResourceProperty 작업과 관련하여 이 개념을 설명하는 데 도움이 되는 예제입니다.

---
- name: waitUntilInstanceStateRunning
  action: aws:waitForAwsResourceProperty
  # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty
  timeoutSeconds: 60
  inputs:
    Service: ec2
    Api: DescribeInstanceStatus
    InstanceIds:
    - "{{ launchOneInstance.InstanceId }}"
    PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
    DesiredValues:
    - running
...

이 자동화는 aws:waitForAwsResourceProperty 단계인 waitUntilInstanceStateRunning에서 DescribeInstanceStatus API 작업을 간접적으로 호출하고 ec2의 응답을 수신합니다. 그런 다음 이 자동화는 PropertySelector - "$.InstanceStatuses[0].InstanceState.Name"을 응답에 적용하여 지정된 반환 값이 DesiredValues 목록의 값(이 경우 running)과 일치하는지 확인합니다. 이 단계는 응답이 인스턴스 상태 running을 반환할 때까지 이 프로세스를 반복합니다.

런북에서 JSONPath 사용

JSONPath 식은 “$.”로 시작하는 문자열로 JSON 요소 내에서 하나 이상의 구성 요소를 선택하는 데 사용됩니다. 다음 목록에는 Systems Manager Automation에서 지원되는 JSONPath 연산자에 대한 정보가 포함되어 있습니다.

  • 점으로 표기된 하위 객체(.): JSON 객체와 함께 사용합니다. 이 연산자는 특정 키의 값을 선택합니다.

  • 상세 검색(..): JSON 요소와 함께 사용합니다. 이 연산자는 수준별로 JSON 요소 수준을 검색하고 특정 키가 지정된 값의 목록을 선택합니다. 이 연산자의 반환 유형은 항상 JSON 배열입니다. 자동화 작업 출력 유형의 컨텍스트에서 이 연산자는 StringList 또는 MapList일 수 있습니다.

  • 배열-인덱스([ ]): JSON 배열과 함께 사용합니다. 이 연산자는 특정 인덱스의 값을 가져옵니다.

  • 필터([?(expression)]): JSON 배열과 함께 사용합니다. 이 연산자는 필터 표현식에 정의된 기준과 일치하는 JSON 배열 값을 필터링합니다. 필터 표현식에는 이 연산자(==, !=, >, <, >= 또는 <=)만 사용할 수 있습니다. 여러 필터 표현식을 AND(&&) 또는 OR(||)과 결합하는 것은 지원되지 않습니다. 이 연산자의 반환 유형은 항상 JSON 배열입니다.

JSONPath 연산자를 더 명확히 이해하려면 ec2 DescribeInstances API 작업의 다음 JSON 응답을 검토합니다. 이 응답 아래에는 다양한 JSONPath 식을 DescribeInstances API 작업의 응답에 적용하여 다양한 결과를 표시하는 여러 예제가 나와 있습니다.

{
    "NextToken": "abcdefg",
    "Reservations": [
        {
            "OwnerId": "123456789012",
            "ReservationId": "r-abcd12345678910",
            "Instances": [
                {
                    "ImageId": "ami-12345678",
                    "BlockDeviceMappings": [
                        {
                            "Ebs": {
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "vol-000000000000"
                            },
                            "DeviceName": "/dev/xvda"
                        }
                    ],
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    }
                }
            ],
            "Groups": []
        },
        {
            "OwnerId": "123456789012",
            "ReservationId": "r-12345678910abcd",
            "Instances": [
                {
                    "ImageId": "ami-12345678",
                    "BlockDeviceMappings": [
                        {
                            "Ebs": {
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "vol-111111111111"
                            },
                            "DeviceName": "/dev/xvda"
                        }
                    ],
                    "State": {
                        "Code": 80,
                        "Name": "stopped"
                    }
                }
            ],
            "Groups": []
        }
    ]
}

JSONPath 예제 1: JSON 응답에서 특정 문자열 가져오기

JSONPath: 
$.Reservations[0].Instances[0].ImageId 

Returns:
"ami-12345678"

Type: String

JSONPath 예제 2: JSON 응답에서 특정 부울 가져오기

JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination
        
Returns:
true

Type: Boolean

JSONPath 예제 3: JSON 응답에서 특정 정수 가져오기

JSONPath:
$.Reservations[0].Instances[0].State.Code
        
Returns:
16

Type: Integer

JSONPath 예제 4: JSON 응답을 상세 검색한 다음, VolumeId에 대한 모든 값을 StringList로 가져오기 

JSONPath:
$.Reservations..BlockDeviceMappings..VolumeId
        
Returns:
[
   "vol-000000000000",
   "vol-111111111111"
]

Type: StringList

JSONPath 예제 5: 특정 BlockDeviceMappings 객체를 StringMap으로 가져오기

JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0]
        
Returns:
{
   "Ebs" : {
      "DeleteOnTermination" : true,
      "Status" : "attached",
      "VolumeId" : "vol-000000000000"
   },
   "DeviceName" : "/dev/xvda"
}

Type: StringMap

JSONPath 예제 6: JSON 응답을 상세 검색한 후 모든 State 객체를 MapList로 가져오기

JSONPath:
$.Reservations..Instances..State 
    
Returns:
[
   {
      "Code" : 16,
      "Name" : "running"
   },
   {
      "Code" : 80,
      "Name" : "stopped"
   }
]

Type: MapList

JSONPath 예제 7: running 상태에 있는 인스턴스에 대한 필터링

JSONPath:
$.Reservations..Instances[?(@.State.Name == 'running')]

Returns:
[
  {
    "ImageId": "ami-12345678",
    "BlockDeviceMappings": [
      {
        "Ebs": {
          "DeleteOnTermination": true,
          "Status": "attached",
          "VolumeId": "vol-000000000000"
        },
        "DeviceName": "/dev/xvda"
      }
    ],
    "State": {
      "Code": 16,
      "Name": "running"
    }
  }
]

Type: MapList

JSONPath 예제 8: running 상태에 있지 않은 ImageId 인스턴스의 반환

JSONPath:
$.Reservations..Instances[?(@.State.Name != 'running')].ImageId

Returns:
[
  "ami-12345678"
]

Type: StringList | String