自動化系統變數 - AWS Systems Manager
術語支援的案例不支援的案例

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

自動化系統變數

AWS Systems Manager Automation Runbook 使用以下變數。如需這些變數的使用範例，請檢視 AWS-UpdateWindowsAmi Runbook 的 JSON 來源。

檢視 AWS-UpdateWindowsAmi Runbook 的 JSON 來源

  1. 開啟位於 https://console.aws.amazon.com/systems-manager/ 的 AWS Systems Manager 主控台。

  2. 在導覽窗格中，選擇 Documents (文件)。

  3. 在文件清單中，使用搜尋列或搜尋列右側的號碼選擇 Runbook AWS-UpdateWindowsAmi。

  4. 選擇 Content (內容) 索引標籤。

系統變數

Automation Runbook 目前支援以下系統變數。

變數 詳細資訊

global:ACCOUNT_ID

執行 Automation 的使用者或角色之 AWS 帳戶 ID。

global:DATE

(在執行時間的) 日期格式為 yyyy-MM-dd。

global:DATE_TIME

(在執行時間的) 日期和時間格式為 yyyy-MM-dd_HH.mm.ss。

global:AWS_PARTITION

資源所在的分割區。對於標準 AWS 區域，分割區為 aws。如果資源處於其他分割區，則會傳回 aws-partitionname 分割區。例如，AWS GovCloud (US-West) 區域的資源分割區為 aws-us-gov。

global:REGION

Runbook 執行的區域。例如 us-east-2。
自動化變數

Runbook 支援以下自動化變數。

變數 詳細資訊

automation:EXECUTION_ID

指派給目前自動化的唯一識別符。例如 1a2b3c-1a2b3c-1a2b3c-1a2b3c1a2b3c1a2b3c。

術語

以下術語說明如何解決變數和參數。

術語 定義 範例

Constant ARN (常數 ARN)

不含變數的有效 Amazon Resource Name (ARN)。

arn:aws:iam::123456789012:role/roleName

Runbook 參數

在 Runbook 層級定義的參數 (例如，instanceId)。此參數用於基本的字串替換。此值會在 Start Execution (開始執行) 時間提供。

 
{ 
   "description": "Create Image Demo",
   "version": "0.3",
   "assumeRole": "Your_Automation_Assume_Role_ARN",
   "parameters":{ 
      "instanceId": { 
         "type": "String",
         "description": "Instance to create image from"
   }
}

System variable (系統變數)

在 Runbook 任何部分評估時替換到 Runbook 的一般變數。

 
"activities": [ 
   { 
      "id": "copyImage",
      "activityType": "AWS-CopyImage",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": { 
         "ImageName": "{{imageName}}",
         "SourceImageId": "{{sourceImageId}}",
         "SourceRegion": "{{sourceRegion}}",
         "Encrypted": true,
         "ImageDescription": "Test CopyImage Description created on {{global:DATE}}"
      }
   }
]

Automation variable (自動化變數)

在文件任何部分評估時替換到 Runbook 且與自動化相關的變數。

 
{ 
   "name": "runFixedCmds",
   "action": "aws:runCommand",
   "maxAttempts": 1,
   "onFailure": "Continue",
   "inputs": { 
      "DocumentName": "AWS-RunPowerShellScript",
      "InstanceIds": [ 
         "{{LaunchInstance.InstanceIds}}"
      ],
      "Parameters": { 
         "commands": [ 
            "dir",
            "date",
            "“{{outputFormat}}” -f “left”,”right”,”{{global:DATE}}”,”{{automation:EXECUTION_ID}}”
         ]
      }
   }
}

Systems Manager 參數

AWS Systems Manager Parameter Store 內定義的變數。無法在步驟輸入中直接參考它。存取參數可能需要許可。

 

description: Launch new Windows test instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
  AutomationAssumeRole:
    type: String
    default: ''
    description: >-
      (Required) The ARN of the role that allows Automation to perform the
      actions on your behalf. If no role is specified, Systems Manager
      Automation uses your IAM permissions to run this runbook.
  LatestAmi:
    type: String
    default: >-
      {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}
    description: The latest Windows Server 2016 AMI queried from the public parameter.
mainSteps:
  - name: launchInstance
    action: 'aws:runInstances'
    maxAttempts: 3
    timeoutSeconds: 1200
    onFailure: Abort
    inputs:
      ImageId: '{{LatestAmi}}'
...

支援的案例

案例 說明 範例

建立時的常數 ARN assumeRole。

將會執行授權檢查，以確認呼叫的使用者許可傳遞指定的assumeRole。

 
{
  "description": "Test all Automation resolvable parameters",
  "schemaVersion": "0.3",
  "assumeRole": "arn:aws:iam::123456789012:role/roleName",
  "parameters": { 
  ...

自動化啟動時，為 AssumeRole 提供的 Runbook 參數。

必須在 Runbook 的參數清單中定義。

 
{
  "description": "Test all Automation resolvable parameters",
  "schemaVersion": "0.3",
  "assumeRole": "{{dynamicARN}}",
  "parameters": {
 ...

在開始時提供給 Runbook 參數的值。

客戶提供用於參數的值。在開始時間提供的任何輸入都必須在 Runbook 的參數清單中定義。

 
...
"parameters": {
    "amiId": {
      "type": "String",
      "default": "ami-12345678",
      "description": "list of commands to run as part of first step"
    },
...

啟動自動執行的輸入包含：{"amiId" : ["ami-12345678"] }

Runbook 內容中參考的 Systems Manager 參數。

變數存在於客戶帳戶內，或是可公開存取的參數，而且 Runbook 的 AssumeRole 可以存取變數。檢查會於建立時間執行，以確認 AssumeRole 可存取。無法在步驟輸入中直接參考參數。

 

...
parameters:
    LatestAmi:
    type: String
    default: >-
      {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}
    description: The latest Windows Server 2016 AMI queried from the public parameter.
mainSteps:
  - name: launchInstance
    action: 'aws:runInstances'
    maxAttempts: 3
    timeoutSeconds: 1200
    onFailure: Abort
    inputs:
      ImageId: '{{LatestAmi}}'
...

在步驟定義中參考的系統變數

當自動化啟動時，系統變數會替換至 Runbook。插入 Runbook 的值與替換發生的時間相關。例如，由於執行步驟之間耗費的時間，因此在步驟 1 插入的時間變數值會不同於在步驟 3 插入的值。系統變數不必在 Runbook 的參數清單中設定。

 
...
  "mainSteps": [
    {
      "name": "RunSomeCommands",
      "action": "aws:runCommand",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "DocumentName": "AWS:RunPowerShell",
        "InstanceIds": ["{{LaunchInstance.InstanceIds}}"],
        "Parameters": {
            "commands" : [
                "echo {The time is now {{global:DATE_TIME}}}"
            ]
        }
    }
}, ...

在步驟定義中參考的自動化變數。

自動化變數不必在 Runbook 的參數清單中設定。唯一支援的自動化變數為 automation:EXECUTION_ID。

 
...
"mainSteps": [
    {
      "name": "invokeLambdaFunction",
      "action": "aws:invokeLambdaFunction",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "FunctionName": "Hello-World-LambdaFunction",

"Payload" : "{ "executionId" : "{{automation:EXECUTION_ID}}" }"
      }
    }
...

請在下一個步驟定義中參閱前一個步驟的輸出。

此為參數重新導向。參考先前步驟的輸出時會使用語法 {{stepName.OutputName}}。客戶無法在 Runbook 參數使用此語法。在參照步驟執行時，會解決此問題。此參數不列於 Runbook 參數中。

 
...
"mainSteps": [
    {
      "name": "LaunchInstance",
      "action": "aws:runInstances",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "ImageId": "{{amiId}}",
        "MinInstanceCount": 1,
        "MaxInstanceCount": 2
      }
    },
    {
      "name":"changeState",
      "action": "aws:changeInstanceState",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "InstanceIds": ["{{LaunchInstance.InstanceIds}}"],
        "DesiredState": "terminated"
      }
    }

...

不支援的案例

案例 註解 範例

建立時，為 assumeRole 提供的 Systems Manager 參數

不支援.

 
...

{
  "description": "Test all Automation resolvable parameters",
  "schemaVersion": "0.3",
  "assumeRole": "{{ssm:administratorRoleARN}}",
  "parameters": {

...

直接在步驟輸入中參考的 Systems Manager 參數。

建立時傳回 InvalidDocumentContent 例外狀況。

 

...
mainSteps:
  - name: launchInstance
    action: 'aws:runInstances'
    maxAttempts: 3
    timeoutSeconds: 1200
    onFailure: Abort
    inputs:
      ImageId: '{{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}'
...

變數步驟定義

Runbook 步驟的定義是由變數建構。

 
...

"mainSteps": [
    {
      "name": "LaunchInstance",
      "action": "aws:runInstances",
      "{{attemptModel}}": 1,
      "onFailure": "Continue",
      "inputs": {
        "ImageId": "ami-12345678",
        "MinInstanceCount": 1,
        "MaxInstanceCount": 2
      }

...

User supplies input : { "attemptModel" : "minAttempts" }

交互參照 Runbook 參數

使用者會在開始時間提供輸入參數，而這是 Runbook 中另一個參數的參考。

 
...
"parameters": {
    "amiId": {
      "type": "String",
      "default": "ami-7f2e6015",
      "description": "list of commands to run as part of first step"
    },
    "alternateAmiId": {
      "type": "String",
      "description": "The alternate AMI to try if this first fails".

"default" : "{{amiId}}"
    },

...

多層級擴展

Runbook 會定義一個評估變數名稱的變數。這位於變數分隔符號內 (即 {{ }})，且會擴展至該變數/參數的值。

 
...
  "parameters": {
    "firstParameter": {
      "type": "String",
      "default": "param2",
      "description": "The parameter to reference"
    },
    "secondParameter": {
      "type": "String",
      "default" : "echo {Hello world}",
      "description": "What to run"
    }
  },
  "mainSteps": [{
      "name": "runFixedCmds",
      "action": "aws:runCommand",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "DocumentName": "AWS-RunPowerShellScript",

"InstanceIds" : "{{LaunchInstance.InstanceIds}}",
        "Parameters": {
          "commands": [ "{{ {{firstParameter}} }}"]

}

...

Note: The customer intention here would be to run a command of "echo {Hello world}"

參考 Runbook 步驟的輸出，其為不同的變數類型

使用者參考後續步驟內先前 Runbook 步驟的輸出。輸出為不符合後續步驟中動作需求的變數類型。

 
...
mainSteps:
- name: getImageId
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: DescribeImages
    Filters:  
    - Name: "name"
      Values: 
      - "{{ImageName}}"
  outputs:
  - Name: ImageIdList
    Selector: "$.Images"
    Type: "StringList"
- name: copyMyImages
  action: aws:copyImage
  maxAttempts: 3
  onFailure: Abort
  inputs:
    SourceImageId: {{getImageId.ImageIdList}}
    SourceRegion: ap-northeast-2
    ImageName: Encrypted Copies of LAMP base AMI in ap-northeast-2
    Encrypted: true 
... 
Note: You must provide the type required by the Automation action. 
In this case, aws:copyImage requires a "String" type variable but the preceding step outputs a "StringList" type variable.