アクション出力の入力としての使用
いくつかのオートメーションアクションは、定義済みの出力を返します。{{ 形式を使用して、これらの出力をランブックの後のステップに入力として渡すことができます。ランブックでは、さまざまなオートメーションアクションについて、その出力を定義することができます。これにより、スクリプトを実行することや、他の AWS のサービス のために API オペレーションを呼び出すことができ、その出力値は、後のアクションで入力として再利用できます。ランブック内のパラメータのデータ型は静的です。つまり、パラメータのデータ型は定義後に変更することはできません。ステップ出力を定義するには、以下のフィールドを指定します。stepName.outputName}}
-
名前: (必須) 後のステップで出力値を参照するために使用する出力名。
-
セレクター: (必須) 出力値を決定するために使用される JSONPath 式。
-
タイプ: (オプション) セレクターフィールドによって返されます。有効なタイプ値は
String、Integer、Boolean、StringList、StringMap、MapListです。デフォルト値はStringです。
出力の値が指定したデータ型と一致しない場合、オートメーションはデータ型を変換しようとします。例えば、返される値が Integer で、指定された Type が String の場合、最終的な出力値は String 値です。次のネットワーク接続タイプがサポートされています。
-
String値はStringList、Integer、およびBooleanに変換できます。 -
Integer値はStringおよびStringListに変換できます。 -
Boolean値はStringおよびStringListに変換できます。 -
1 つの要素を含む
StringList、IntegerList、またはBooleanList値は、String、IntegerまたはBooleanに変換できます。
自動化アクションでパラメータを使用する場合、アクションの入力内でデータ型を動的に変更することはできません。
アクションの出力を定義し、その出力値を後のアクションで入力として参照する方法を示した、ランブックの例を次に示します。このランブックでは、以下を処理します。
-
aws:executeAwsApiアクションを使用して Amazon EC2 DescribeImages API オペレーションを呼び出し、特定の Windows Server 2016 AMI の名前を取得します。イメージ ID をImageIdとして出力します。 -
aws:executeAwsApiアクションを使用して、Amazon EC2 RunInstances API オペレーションを呼び出し、前の手順のImageIdを使用するインスタンスを 1 つ起動します。インスタンス ID をInstanceIdとして出力します。 -
aws:waitForAwsResourcePropertyアクションを使用して Amazon EC2 DescribeInstanceStatus API オペレーションをポーリングし、インスタンスがrunning状態になるまで待機します。アクションは 60 秒でタイムアウトします。60 秒間のポーリング後にインスタンス状態がrunningにならなかった場合、このステップはタイムアウトします。 -
aws:assertAwsResourcePropertyアクションを使用して Amazon EC2DescribeInstanceStatusAPI オペレーションを呼び出し、インスタンスが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 オペレーションによって定義されます。API オペレーション (メソッド) は、以下の「サービスリファレンス
各オートメーションアクションのスキーマは、次の場所で表示できます。
スキーマには、各アクションを使用するための必須フィールドの説明が含まれています。
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 演算子に関する情報が含まれています。
-
Dot-notated child (.): JSON オブジェクトで使用します。この演算子は、特定のキーの値を選択します。
-
Deep-scan (..): JSON 要素で使用します。この演算子は、レベル別に JSON 要素レベルをスキャンし、特定のキーで値のリストを選択します。この演算子の戻り型は、常に JSON 配列です。オートメーションアクションの出力タイプのコンテキストでは、演算子は StringList または MapList のいずれかになります。
-
Array-Index([ ]): JSON 配列で使用します。この演算子は、特定のインデックスの値を取得します。
-
Filter ([?(
expression)]): JSON 配列と一緒に使用します。このオペレータは、フィルター式で定義された条件と一致する JSON 配列値をフィルタリングします。フィルター式では、以下の演算子のみを使用できます。==、!=、>、<、>=、<= 複数のフィルター式を AND (&&) または OR (||) と組み合わせることはサポートされていません。この演算子の戻り型は、常に JSON 配列です。
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
