アクション出力の入力としての使用

いくつかのオートメーションアクションは、定義済みの出力を返します。{{stepName.outputName}} 形式を使用して、これらの出力をランブックの後のステップに入力として渡すことができます。ランブックでは、さまざまなオートメーションアクションについて、その出力を定義することができます。これにより、スクリプトを実行することや、他の AWS のサービス のために API オペレーションを呼び出すことができ、その出力値は、後のアクションで入力として再利用できます。ランブック内のパラメータのデータ型は静的です。つまり、パラメータのデータ型は定義後に変更することはできません。ステップ出力を定義するには、以下のフィールドを指定します。

出力の値が指定したデータ型と一致しない場合、オートメーションはデータ型を変換しようとします。例えば、返される値が Integer で、指定された Type が String の場合、最終的な出力値は String 値です。次のネットワーク接続タイプがサポートされています。

自動化アクションでパラメータを使用する場合、アクションの入力内でデータ型を動的に変更することはできません。

アクションの出力を定義し、その出力値を後のアクションで入力として参照する方法を示した、ランブックの例を次に示します。このランブックでは、以下を処理します。

---
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 オペレーションによって定義されます。API オペレーション (メソッド) は、以下の「サービスリファレンス」ページの左側のナビゲーションでサービスを選択することで表示できます。呼び出すサービスの [Client (クライアント)] セクションでメソッドを選択します。例えば、Amazon Relational Database Service (Amazon RDS) のすべての API オペレーション (メソッド) は、Amazon RDS メソッドのページに一覧表示されます。

各オートメーションアクションのスキーマは、次の場所で表示できます。

スキーマには、各アクションを使用するための必須フィールドの説明が含まれています。

Selector/PropertySelector フィールドの使用

各オートメーションアクションでは、出力 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 変数に割り当てます。同じ自動化の他のステップでは、ImageId を指定して "{{ getImageId.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 要素内の 1 つ以上のコンポーネントを選択するために使用されます。次のリストには、Systems Manager Automation でサポートされている JSONPath 演算子に関する情報が含まれています。

JSONPath 演算子をよりよく理解するために、ec2 DescribeInstances API オペレーションの次の JSON 応答を確認してください。このレスポンスの下には、DescribeInstances API オペレーションからのレスポンスにさまざまな JSONPath 式を適用してさまざまな結果を示すいくつかの例があります。

{
    "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