資料元素和參數

本主題描述 SSM 文件中使用的資料元素。用於建立文件的結構描述版本會定義文件接受的語法和資料元素。建議命令文件使用結構描述版本 2.2 或更新版本。Automation Runbook 使用結構描述版本 0.3。此外，Automation Runbook 支援使用 Markdown (一種標示語言)，可讓您新增維基樣式的描述至文件內，以及在文件內新增個別步驟。如需關於使用 Markdown 的詳細資訊，請參閱《AWS Management Console 入門指南》中的在主控台中使用 Markdown。

下一節說明您可以在 SSM 文件中包含的資料元素。

頂層資料元素

schemaVersion

要使用的結構描述版本。

類型：版本

必要：是

description

您提供來描述文件用途的資訊。您也可以使用此欄位來指定參數是否需要執行文件的值，或者提供參數的值是否為選用項目。您可以在本主題的範例中看到必要參數和選用參數。

類型：字串

必要：否

parameters

一種結構，定義文件接受的參數。

對於您經常使用的參數，我們建議您將這些參數儲存在中Parameter Store，功能 AWS Systems Manager。然後，您可以在文件中定義參考 Parameter Store 參數作為預設值的參數。若要參考 Parameter Store 參數，請使用下列語法。

{{ssm:parameter-name}}

您可以使用參考 Parameter Store 參數的參數，方式與任何其他文件參數相同。在下列範例中，commands 參數的預設值是 Parameter Store 參數 myShellCommands。透過將 commands 參數指定為 runCommand 字串，文件會執行在 myShellCommands 參數中儲存的命令。

YAML

---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
  commands:
    type: StringList
    description: "(Required) The commands to run on the instance."
    default: ["{{ ssm:myShellCommands }}"]
mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:
    - "{{ commands }}"

JSON

{
    "schemaVersion": "2.2",
    "description": "runShellScript with command strings stored as Parameter Store parameter",
    "parameters": {
      "commands": {
        "type": "StringList",
        "description": "(Required) The commands to run on the instance.",
        "default": ["{{ ssm:myShellCommands }}"]
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }

注意

您在文件的 parameters 部分可以參考 String 和 StringList Parameter Store 參數。您無法參考 SecureString Parameter Store 參數。

如需有關 Parameter Store 的詳細資訊，請參閱「AWS Systems Manager Parameter Store」。

類型：結構

parameters 結結構接受下列的欄位和數值：

• type：(必要) 允許的值包括：String、StringList、Integer、Boolean、MapList 和 StringMap。若要查看每個類型的範例，在下一個部分請參閱 SSM 文件參數 type 範例。

  注意

  指令類型文件僅支援 String 和 StringList 參數類型。

• description(選用) 參數說明。

• default：(選擇性) 在 Parameter Store 中預設的參數值或參考值。

• allowedValues：(選擇性) 參數允許的值陣列。定義參數的允許值會驗證使用者輸入。如果使用者輸入不允許的值，則無法開始執行。

  YAML

  DirectoryType:
    type: String
    description: "(Required) The directory type to launch."
    default: AwsMad
    allowedValues:
    - AdConnector
    - AwsMad
    - SimpleAd

  JSON

  "DirectoryType": {
    "type": "String",
    "description": "(Required) The directory type to launch.",
    "default": "AwsMad",
    "allowedValues": [
      "AdConnector",
      "AwsMad",
      "SimpleAd"
    ]
  }

• allowedPattern：(選擇性) 規則運算式，可驗證使用者輸入是否符合參數定義的模式。如果使用者輸入不符合允許的模式，則無法開始執行。

  注意

  Systems Manager 執行兩次 allowedPattern 驗證。當您使用文件時，在 API 層級使用 Java regex 程式庫執行第一次驗證。在處理文件之前，藉由使用 GO Regexp 程式庫，在 SSM Agent 上執行第二次驗證。

  YAML

  InstanceId:
    type: String
    description: "(Required) The instance ID to target."
    allowedPattern: "^i-[a-z0-9]{8,17}$"
    default: ''

  JSON

  "InstanceId": {
    "type": "String",
    "description": "(Required) The instance ID to target.",
    "allowedPattern": "^i-[a-z0-9]{8,17}$",
    "default": ""
  }

• displayType: (選擇性) 用於textarea在中顯示 a textfield 或 a AWS Management Console。 textfield是單行文字方塊。 textarea是多行文字區域。

• minItems：(選擇性) 允許項目數量的最小值。

• maxItems：(選擇性) 允許項目數量的最大值。

• minChars：(選擇性) 允許參數字元數量的最小值。

• maxChars：(選擇性) 允許參數字元數量的最大值。

必要：否

variables

(僅限結構描述版本 0.3) 您可以在 Automation 執行手冊中的整個步驟中參考或更新的值。變數類似於參數，但有一個非常重要的差異。參數值在執行手冊的內容中是靜態的，但變數的值可以在執行手冊的內容中進行變更。更新變數的值時，資料類型必須與定義的資料類型相符。如需有關在自動化操作中更新變數值的資訊，請參閱 aws:updateVariable - 更新執行手冊變數的值

類型：布爾 | 整數 MapList | 字符串 | StringList | StringMap

必要：否

YAML

variables:
    payload:
        type: StringMap
        default: "{}"

JSON

{
    "variables": [
        "payload": {
            "type": "StringMap",
            "default": "{}"
        }
    ]
}

runtimeConfig

(結構描述 1.2 版) 一個或多個 Systems Manager 外掛程式套用的執行個體組態。不能保證外掛程式按順序執行。

類型：字典 < 字串，> PluginConfiguration

必要：否

mainSteps

(僅限結構描述版本 0.3、2.0 和 2.2) 可以包含多個步驟 (外掛程式) 的物件。外掛程式在步驟中定義。步驟會按文件中列出的順序執行。

類型：字典 < 字串，> PluginConfiguration

必要：是

outputs

(僅限結構描述版本 0.3) 執行此文件所產生的資料，可用於其他程序。例如，如果您的文件建立了新文件AMI，您可以指定 "CreateImage。 ImageId"作為輸出值，然後使用此輸出在後續的自動化執行中建立新的執行個體。如需輸出的詳細資訊，請參閱 使用動作輸出作為輸入。

類型：字典 < 字串，> OutputConfiguration

必要：否

files

(僅限結構描述 0.3) 連接至文件並在自動化執行期間執行的指令碼檔案 (及其檢查總和)。僅適用於包含 aws:executeScript 動作，以及已在一或多個步驟中指定附件的文件。

對於腳本運行時支持，自動化手冊支持腳本為 Python 3.7，Python 3.8， PowerShell 核心 6.0 和 PowerShell 7.0。如需有關在 Automation Runbook 中包含指令碼的詳細資訊，請參閱 在執行手冊中使用指令碼 和 使用文件建置器建立執行手冊。

當創建帶有附件的自動化手冊時，您還必須使用--attachments選項（對於 AWS CLI）或Attachments（用於 API 和 SDK）指定附件文件。您可以為本機檔案和存放在 Amazon Simple Storage Service (Amazon S3) 儲存貯體中的檔案指定檔案位置。如需詳細資訊，請參閱 AWS Systems Manager API 參考中的附件。

YAML

---
files:
  launch.py:
    checksums:
      sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE

JSON

"files": {
    "launch.py": {
        "checksums": {
            "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
        }
    }
}

類型：字典 < 字串，> FilesConfiguration

必要：否

SSM 文件參數 type 範例

SSM 文件中的參數類型是靜態的。這意味著參數類型在定義後便無法變更。將參數與 SSM 文件外掛程式搭配使用時，無法在外掛程式的輸入中動態變更參數的類型。例如，您無法在 aws:runShellScript 外掛程式的 runCommand 輸入中參考 Integer 參數，因為此輸入接受字串或字串清單。若要對外掛程式輸入使用參數，參數類型必須與接受的類型相符。例如，您必須為 aws:updateSsmAgent 外掛程式的 allowDowngrade 輸入指定 Boolean 類型參數。如果您的參數類型與外掛程式的輸入類型不相符，則 SSM 文件便無法驗證，且系統不會建立文件。當在其他外掛程式或 AWS Systems Manager 自動化動作的輸入內下游使用參數時，也會發生這種情況。例如，您無法參考 aws:runDocument 外掛程式 documentParameters 輸入中的 StringList 參數。即使下游 SSM 文件參數類型是 StringList 參數且與您參考的參數相符，此 documentParameters 輸入仍會接受字串映射。

搭配使用參數與 自動化動作時，在大多數情況下建立 SSM 文件並不會驗證參數類型。只有當您使用 aws:runCommand 動作時，才會在您建立 SSM 文件時驗證參數類型。在所有其他情況下，則會在執行動作之前驗證動作的輸入之時，在自動化執行期間進行參數驗證。例如，如果您的輸入參數為 String，而您將其參考為 aws:runInstances 動作的 MaxInstanceCount 輸入的數值，則會建立 SSM 文件。不過，執行文件時，自動化會在驗證 aws:runInstances 動作時會失敗，因為 MaxInstanceCount 輸入需要 Integer.

以下是每個參數 type 的範例。

字串

一連串零或多個 Unicode 字元以雙引號框住。例如，"i-1234567890abcdef0"。使用反斜線逸出。

YAML

---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."

JSON

"InstanceId":{
  "type":"String",
  "description":"(Optional) The target EC2 instance ID."
}

StringList

由逗號分隔的字串項目清單。例如，["cd 〜", "pwd"]。

YAML

---
commands:
  type: StringList
  description: "(Required) Specify a shell script or a command to run."
  default: ""
  minItems: 1
  displayType: textarea

JSON

"commands":{
  "type":"StringList",
  "description":"(Required) Specify a shell script or a command to run.",
  "minItems":1,
  "displayType":"textarea"
}

Boolean

僅接受 true 或 false。不接受「true」或 0。

YAML

---
canRun:
  type: Boolean
  description: ''
  default: true

JSON

"canRun": {
  "type": "Boolean",
  "description": "",
  "default": true
}

Integer

整數號碼。不接受十進位小數，例如 3.14159 或以雙引號括住的號碼，例如 "3"。

YAML

---
timeout:
  type: Integer
  description: The type of action to perform.
  default: 100

JSON

"timeout": {
  "type": "Integer",
  "description": "The type of action to perform.",
  "default": 100    
}

StringMap

金鑰與值的映射。金鑰和值必須是字串。例如，{"Env": "Prod"}。

YAML

---
notificationConfig:
  type: StringMap
  description: The configuration for events to be notified about
  default:
    NotificationType: 'Command'
    NotificationEvents:
    - 'Failed'
    NotificationArn: "$dependency.topicArn"
  maxChars: 150

JSON

"notificationConfig" : {
  "type" : "StringMap",
  "description" : "The configuration for events to be notified about",
  "default" : {
    "NotificationType" : "Command",
    "NotificationEvents" : ["Failed"],
    "NotificationArn" : "$dependency.topicArn"
  },
  "maxChars" : 150
}

MapList

StringMap 物件清單。

YAML

blockDeviceMappings:
  type: MapList
  description: The mappings for the create image inputs
  default:
  - DeviceName: "/dev/sda1"
    Ebs:
      VolumeSize: "50"
  - DeviceName: "/dev/sdm"
    Ebs:
      VolumeSize: "100"
  maxItems: 2

JSON

"blockDeviceMappings":{
  "type":"MapList",
  "description":"The mappings for the create image inputs",
  "default":[
    {
      "DeviceName":"/dev/sda1",
      "Ebs":{
        "VolumeSize":"50"
      }
    },
    {
      "DeviceName":"/dev/sdm",
      "Ebs":{
        "VolumeSize":"100"
      }
    }
  ],
  "maxItems":2
}

檢視 SSM 命令文件內容

若要預覽 AWS Systems Manager (SSM) Command 文件的必要和選用參數，除了文件執行的動作外，您還可以在 Systems Manager 主控台中檢視文件的內容。

若要檢視 SSM 命令文件內容

1. 開啟主 AWS Systems Manager 控台，網址為 https://console.aws.amazon.com/systems-manager/。

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

   -或-

   如果 AWS Systems Manager 首頁首頁開啟，請選擇功能表圖示 ( ) 以開啟導覽窗格，然後在導覽窗格中選擇 [文件]。

3. 在搜尋方塊中，選取 Document type (文件類型)，然後選取 Command (命令)。

4. 選擇文件名稱，然後選擇 Content (內容) 標籤。

5. 在內容欄位中，檢閱文件的可用參數和動作步驟。

   例如，下圖顯示 (1) version 與 (2) allowDowngrade 是 AWS-UpdateSSMAgent 文件的可選參數，並且文件執行的第一個操作是 (3) aws:updateSsmAgent。