使用動作輸出作為輸入 - AWS Systems Manager
在執行手冊中使用 JSONPath

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用動作輸出作為輸入

數個自動化動作會傳回預先定義的輸出。您可以將這些輸出作為輸入傳遞給 {{stepName.outputName}} 格式執行手冊中的後續步驟。您還可以在執行手冊中定義自動化動作的自訂輸出。這可讓您執行指令碼或呼叫其他 API 作業 AWS 服務 一次，以便在稍後的動作中重複使用這些值做為輸入。執行手冊中的參數類型是靜態的。這意味著參數類型在定義後便無法變更。若要定義步驟輸出，請提供下列欄位：

  • 名稱：(必填) 用於在後面的步驟中引用輸出值的輸出名稱。

  • 選取器：(必填) 用於決定輸出值的 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動作呼叫 Amazon EC2 DescribeImages API 作業以取得特定視窗伺服器 2016 年的名稱AMI。這會將映像 ID 輸出為 ImageId。

  • 使用此aws:executeAwsApi動作呼叫 Amazon EC2 RunInstances API 作業，以啟動一個使用上一個步驟的ImageId執行個體。這會將執行個體 ID 輸出為 InstanceId。

  • 使用此 aws:waitForAwsResourceProperty動作輪詢 Amazon EC2 DescribeInstanceStatus API 操作，以等待執行個體到達狀running態。動作在 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 操作定義。您可以檢視 API 操作 (也稱為方法)，方式是在以下服務參考頁面的左側導覽中選擇一項服務。在您想要呼叫之服務的 Client (用戶端) 部分選擇一個方法。例如，Amazon Relational Database Service (Amazon RDS) 的所有 API 操作 (方法) 均列於以下頁面：Amazon RDS 方法。

您可以在以下位置檢視每個自動化動作的結構描述：

結構描述包括使用各動作之必要欄位的描述。

使用選取器/欄位 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 自動化支援的 JSONPath 運算子相關資訊：

  • 以點標記的子代 (.)：與 JSON 物件搭配使用。此運算子會選取特定索引鍵的值。

  • Deep-scan (..)：與 JSON 元素搭配使用。此運算子會在各層級掃描 JSON 元素並選取具有特定索引鍵之值的清單。此運算子的傳回類型一律為 JSON 陣列。在自動化動作輸出類型的內容中，運算子可以是 StringList 或 MapList。

  • Array-Index ([ ])：與 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 響應，然後將所有狀態對象作為一個 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