• 2026 年 4 月 30 日之後， AWS Systems Manager CloudWatch Dashboard 將不再可用。客戶可以繼續使用 Amazon CloudWatch 主控台來檢視、建立和管理其 Amazon CloudWatch 儀表板，就像現在一樣。如需詳細資訊，請參閱 [Amazon CloudWatch Dashboard 文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。

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

# 文件組成部分


本節包含有關 SSM 文件組成部分件的資訊。

**Topics**
+ [

# 結構描述、功能以及範例
](documents-schemas-features.md)
+ [

# 資料元素和參數
](documents-syntax-data-elements-parameters.md)
+ [

# 命令文件外掛程式參考
](documents-command-ssm-plugin-reference.md)

# 結構描述、功能以及範例


AWS Systems Manager (SSM) 文件使用以下結構描述版本。
+ `Command` 類型的文件可以使用結構描述 1.2、2.0 和 2.2 版本。如果您使用的文件為結構描述 1.2 版本，我們建議您使用結構描述 2.2 版本建立文件。
+ `Policy` 類型的文件必須使用結構描述 2.0 版本或更新版本。
+ `Automation` 類型的文件必須使用結構描述 0.3 版本。
+ `Session` 類型的文件必須使用結構描述 1.0 版本。
+ 您可以以 JSON 或 YAML 建立文件。

如需有關`Session`文件結構描述的詳細資訊，請參閱[工作階段文件結構描述](session-manager-schema.md)。

`Command` 和 `Policy` 文件使用最新的結構描述版本，您可以善用以下功能。


**結構描述版本 2.2 文件的功能**  

| 功能 | 詳細資訊 | 
| --- | --- | 
|  文件編輯  |  文件現在可以進行更新。在版本 1.2 中，您需要將文件中任何更新儲存為不同名稱的文件。  | 
|  自動版本控制  |  文件中任何更新建立新的版本。這並非結構描述的版本，而是文件的版本。  | 
|  預設版本  |  如果您有多個版本的文件，您可以指定哪個版本為預設的文件。  | 
|  定序  |  文件中中的外掛程式或*步驟*將按照您所指定的順序執行。  | 
|  跨平台支援  |  跨平台支援允許您在相同的 SSM 文件中為不同的外掛程式指定不同的作業系統。跨平台支援使用 `precondition` 參數，只需要幾個步驟。  | 
| 參數插補 | 插補表示將變數值插入或替換為字串。將其視為在使用字串前，使用實際值填入空格。在 SSM 文件環境中，參數插補允許字串參數在命令執行之前，插入到環境變數中，提供更高安全性以防止命令注入。設定為 `ENV_VAR` 時，Agent 會建立名為 `SSM_parameter-name` 的環境變數，其中包含參數的值。 | 

**注意**  
您必須將執行個體上的 AWS Systems Manager SSM Agent 更新為最新版本，才能使用新的 Systems Manager 功能和 SSM 文件功能。如需詳細資訊，請參閱[使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。

下表列出了主要的結構描述各版本的差異。


****  

| 第 1.2 版 | 版本 2.2 (最新版本) | 詳細資訊 | 
| --- | --- | --- | 
|  runtimeConfig  |  mainSteps  |  在版本 2.2 中，`mainSteps` 區塊取代了 `runtimeConfig`。`mainSteps` 區段可讓 Systems Manager 按順序執行步驟。  | 
|  屬性  |  inputs  |  在版本 2.2 中，`inputs` 區塊取代了 `properties` 區塊。`inputs` 區塊接受了參數的做法步驟。  | 
|  commands  |  runCommand  |  在版本 2.2 中，`inputs` 區塊接受 `runCommand` 的參數，而非 `commands` 的參數。  | 
|  id  |  動作  |  在版本 2.2 中，`Action` 取代了 `ID`。這是名稱變更。  | 
|  不適用  |  name  |  在版本 2.2 中，`name` 是一個任何使用者替步驟定義的名稱。  | 

**使用 precondition 參數**  
使用結構描述 2.2 版或更新版本，您可以使用 `precondition` 參數為每個外掛程式指定目標作業系統，或驗證您在 SSM 文件中定義的輸入參數。`precondition` 參數支援引用 SSM 文件的輸入參數，以及使用值 `Linux`、`MacOS` 以及 `Windows` 的 `platformType`。只支援 `StringEquals` 運算子。

對於文件使用結構描述版本 2.2 或更新版本，如果未指定 `precondition`，每個外掛程式是根據外掛程式的相容性來決定在作業系統執行或略過。與作業系統的外掛程式相容性會在 `precondition` 之前評估。對於文件使用結構描述 2.0 或更舊版本，不相容的外掛程式會產生錯誤。

例如，在結構描述版本 2.2 文件中，如果未指定 `precondition` 但有列出`aws:runShellScript` 外掛程式，則在 Linux 執行個體上會執行該步驟，但在 Windows Server 執行個體上會略過該步驟，因為 `aws:runShellScript` 與 Windows Server 執行個體不相容。但就結構描述版本 2.0 文件來說，如果您指定 `aws:runShellScript` 外掛程式，然後在 Windows Server 執行個體上執行該文件，則執行會失敗。您可以在本節稍後的 SSM 文件中查看先決條件參數範例。

## 結構描述版本 2.2


**頂層元素**  
以下範例顯示使用結構描述版本 2.2 的 SSM 文件上層元素。

------
#### [ YAML ]

```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
  parameter 1:
    property 1: "value"
    property 2: "value"
  parameter 2:
    property 1: "value"
    property 2: "value"
mainSteps:
  - action: Plugin name
    name: A name for the step.
    inputs:
      input 1: "value"
      input 2: "value"
      input 3: "{{ parameter 1 }}"
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "A description of the document.",
   "parameters": {
       "parameter 1": {
           "property 1": "value",
           "property 2": "value"
        },
        "parameter 2":{
           "property 1": "value",
           "property 2": "value"
        } 
    },
   "mainSteps": [
      {
         "action": "Plugin name",
         "name": "A name for the step.",
         "inputs": {
            "input 1": "value",
            "input 2": "value",
            "input 3": "{{ parameter 1 }}"
         }
      }
   ]
}
```

------

**結構描述版本 2.2 範例**  
下列範例會使用 `aws:runPowerShellScript` 外掛程式在目標執行個體上執行 PowerShell 命令。

------
#### [ YAML ]

```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
  Message:
    type: "String"
    description: "Example parameter"
    default: "Hello World"
    allowedValues: 
    - "Hello World"
mainSteps:
  - action: "aws:runPowerShellScript"
    name: "example"
    inputs:
      timeoutSeconds: '60'
      runCommand:
      - "Write-Output {{Message}}"
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "Example document",
   "parameters": {
      "Message": {
         "type": "String",
         "description": "Example parameter",
         "default": "Hello World",
         "allowedValues": ["Hello World"]
      }
   },
   "mainSteps": [
      {
         "action": "aws:runPowerShellScript",
         "name": "example",
         "inputs": {
            "timeoutSeconds": "60",
            "runCommand": [
               "Write-Output {{Message}}"
            ]
         }
      }
   ]
}
```

------

**結構描述版本 2.2 precondition 參數範例**  
結構描述版本 2.2 提供跨平台支援。這表示您可以在同一個 SSM 文件中為不同的外掛程式指定不同的作業系統。跨平台支援在步驟中使用 `precondition` 參數，如下所示。您也可以使用 `precondition` 參數來驗證您在 SSM 文件中定義的輸入參數。您可以在以下第二個範例中看到它。

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
  name: PatchWindows
  precondition:
    StringEquals:
    - platformType
    - Windows
  inputs:
    runCommand:
    - cmds
- action: aws:runShellScript
  name: PatchLinux
  precondition:
    StringEquals:
    - platformType
    - Linux
  inputs:
    runCommand:
    - cmds
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "cross-platform sample",
   "mainSteps": [
      {
         "action": "aws:runPowerShellScript",
         "name": "PatchWindows",
         "precondition": {
            "StringEquals": [
               "platformType",
               "Windows"
            ]
         },
         "inputs": {
            "runCommand": [
               "cmds"
            ]
         }
      },
      {
         "action": "aws:runShellScript",
         "name": "PatchLinux",
         "precondition": {
            "StringEquals": [
               "platformType",
               "Linux"
            ]
         },
         "inputs": {
            "runCommand": [
               "cmds"
            ]
         }
      }
   ]
}
```

------

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
parameters:
  action:
    type: String
    allowedValues:
    - Install
    - Uninstall
  confirmed:
    type: String
    allowedValues:
    - True
    - False
mainSteps:
- action: aws:runShellScript
  name: InstallAwsCLI
  precondition:
    StringEquals:
    - "{{ action }}"
    - "Install"
  inputs:
    runCommand:
    - sudo apt install aws-cli
- action: aws:runShellScript
  name: UninstallAwsCLI
  precondition:
    StringEquals:
    - "{{ action }} {{ confirmed }}"
    - "Uninstall True"
  inputs:
    runCommand:
    - sudo apt remove aws-cli
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "parameters": {
      "action": {
         "type": "String",
         "allowedValues": [
            "Install",
            "Uninstall"
         ]
      },
      "confirmed": {
         "type": "String",
         "allowedValues": [
            true,
            false
         ]
      }
   },
   "mainSteps": [
      {
         "action": "aws:runShellScript",
         "name": "InstallAwsCLI",
         "precondition": {
            "StringEquals": [
               "{{ action }}",
               "Install"
            ]
         },
         "inputs": {
            "runCommand": [
               "sudo apt install aws-cli"
            ]
         }
      },
      {
         "action": "aws:runShellScript",
         "name": "UninstallAwsCLI",
         "precondition": {
            "StringEquals": [
               "{{ action }} {{ confirmed }}",
               "Uninstall True"
            ]
         },
         "inputs": {
            "runCommand": [
               "sudo apt remove aws-cli"
            ]
         }
      }
   ]
}
```

------

**具有 3.3.2746.0 之前 SSM Agent 版本的結構描述 2.2 版插補範例**  
在 3.3.2746.0 之前的 SSM Agent 版本上，Agent 會忽略 `interpolationType` 參數，並改為執行原始字串替換。如果您明確參考 `SSM_parameter-name`，則必須明確設定此項目。在下列的 Linux 範例中，明確參考了 `SSM_Message` 環境變數。

```
{
    "schemaVersion": "2.2",
    "description": "An example document",
    "parameters": {
        "Message": {
            "type": "String",
            "description": "Message to be printed",
            "default": "Hello",
            "interpolationType" : "ENV_VAR",
	     "allowedPattern: "^[^"]*$"

        }
    },
    "mainSteps": [{
        "action": "aws:runShellScript",
        "name": "printMessage",
        "inputs": {
            "runCommand": [
              "if [ -z "${SSM_Message+x}" ]; then",
              "    export SSM_Message=\"{{Message}}\"",
              "fi",
              "",
              "echo $SSM_Message"
            ]
        }
    }
}
```

**注意**  
如果 SSM 文件不使用雙括號，則技術上不需要 `allowedPattern`：`{{ }}`

**結構描述版本 2.2 State Manager 範例**  
您可以搭配使用以下 SSM 文件與 State Manager (Systems Manager 中的工具)，以下載並安裝 ClamAV 防毒軟體。State Manager 會強制實施特定組態，這表示每次執行 State Manager 關聯時，系統會檢查是否已安裝 ClamAV 軟體。如果不是，State Manager 會重新執行此文件。

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
  name: configureServer
  inputs:
    runCommand:
    - sudo yum install -y httpd24
    - sudo yum --enablerepo=epel install -y clamav
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "State Manager Bootstrap Example",
   "parameters": {},
   "mainSteps": [
      {
         "action": "aws:runShellScript",
         "name": "configureServer",
         "inputs": {
            "runCommand": [
               "sudo yum install -y httpd24",
               "sudo yum --enablerepo=epel install -y clamav"
            ]
         }
      }
   ]
}
```

------

**結構描述版本 2.2 庫存範例**  
您可以搭配使用以下 SSM 文件與 State Manager，收集有關執行個體的庫存中繼資料。

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
  applications:
    type: String
    default: Enabled
    description: "(Optional) Collect data for installed applications."
    allowedValues:
    - Enabled
    - Disabled
  awsComponents:
    type: String
    default: Enabled
    description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
    allowedValues:
    - Enabled
    - Disabled
  networkConfig:
    type: String
    default: Enabled
    description: "(Optional) Collect data for Network configurations."
    allowedValues:
    - Enabled
    - Disabled
  windowsUpdates:
    type: String
    default: Enabled
    description: "(Optional) Collect data for all Windows Updates."
    allowedValues:
    - Enabled
    - Disabled
  instanceDetailedInformation:
    type: String
    default: Enabled
    description: "(Optional) Collect additional information about the instance, including
      the CPU model, speed, and the number of cores, to name a few."
    allowedValues:
    - Enabled
    - Disabled
  customInventory:
    type: String
    default: Enabled
    description: "(Optional) Collect data for custom inventory."
    allowedValues:
    - Enabled
    - Disabled
mainSteps:
- action: aws:softwareInventory
  name: collectSoftwareInventoryItems
  inputs:
    applications: "{{ applications }}"
    awsComponents: "{{ awsComponents }}"
    networkConfig: "{{ networkConfig }}"
    windowsUpdates: "{{ windowsUpdates }}"
    instanceDetailedInformation: "{{ instanceDetailedInformation }}"
    customInventory: "{{ customInventory }}"
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "Software Inventory Policy Document.",
   "parameters": {
      "applications": {
         "type": "String",
         "default": "Enabled",
         "description": "(Optional) Collect data for installed applications.",
         "allowedValues": [
            "Enabled",
            "Disabled"
         ]
      },
      "awsComponents": {
         "type": "String",
         "default": "Enabled",
         "description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
         "allowedValues": [
            "Enabled",
            "Disabled"
         ]
      },
      "networkConfig": {
         "type": "String",
         "default": "Enabled",
         "description": "(Optional) Collect data for Network configurations.",
         "allowedValues": [
            "Enabled",
            "Disabled"
         ]
      },
      "windowsUpdates": {
         "type": "String",
         "default": "Enabled",
         "description": "(Optional) Collect data for all Windows Updates.",
         "allowedValues": [
            "Enabled",
            "Disabled"
         ]
      },
      "instanceDetailedInformation": {
         "type": "String",
         "default": "Enabled",
         "description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
         "allowedValues": [
            "Enabled",
            "Disabled"
         ]
      },
      "customInventory": {
         "type": "String",
         "default": "Enabled",
         "description": "(Optional) Collect data for custom inventory.",
         "allowedValues": [
            "Enabled",
            "Disabled"
         ]
      }
   },
   "mainSteps": [
      {
         "action": "aws:softwareInventory",
         "name": "collectSoftwareInventoryItems",
         "inputs": {
            "applications": "{{ applications }}",
            "awsComponents": "{{ awsComponents }}",
            "networkConfig": "{{ networkConfig }}",
            "windowsUpdates": "{{ windowsUpdates }}",
            "instanceDetailedInformation": "{{ instanceDetailedInformation }}",
            "customInventory": "{{ customInventory }}"
         }
      }
   ]
}
```

------

**結構描述版本 2.2 `AWS-ConfigureAWSPackage` 範例**  
以下範例顯示 `AWS-ConfigureAWSPackage` 文件。`mainSteps` 區段包含 `action` 步驟中的 `aws:configurePackage` 外掛程式。

**注意**  
在 Linux 作業系統上，只有支援 `AmazonCloudWatchAgent` 和 `AWSSupport-EC2Rescue` 的套件。

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
  AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
  action:
    description: "(Required) Specify whether or not to install or uninstall the package."
    type: String
    allowedValues:
    - Install
    - Uninstall
  name:
    description: "(Required) The package to install/uninstall."
    type: String
    allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
  version:
    type: String
    description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
  name: configurePackage
  inputs:
    name: "{{ name }}"
    action: "{{ action }}"
    version: "{{ version }}"
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
   "parameters": {
      "action": {
         "description":"(Required) Specify whether or not to install or uninstall the package.",
         "type":"String",
         "allowedValues":[
            "Install",
            "Uninstall"
         ]
      },
      "name": {
         "description": "(Required) The package to install/uninstall.",
         "type": "String",
         "allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
      },
      "version": {
         "type": "String",
         "description": "(Optional) A specific version of the package to install or uninstall."
      }
   },
   "mainSteps":[
      {
         "action": "aws:configurePackage",
         "name": "configurePackage",
         "inputs": {
            "name": "{{ name }}",
            "action": "{{ action }}",
            "version": "{{ version }}"
         }
      }
   ]
}
```

------

## 結構描述版本 1.2


以下範例顯示結構描述版本 1.2 文件的上層元素。

```
{
   "schemaVersion":"1.2",
   "description":"A description of the SSM document.",
   "parameters":{
      "parameter 1":{
         "one or more parameter properties"
      },
      "parameter 2":{
         "one or more parameter properties"
      },
      "parameter 3":{
         "one or more parameter properties"
      }
   },
   "runtimeConfig":{
      "plugin 1":{
         "properties":[
            {
               "one or more plugin properties"
            }
         ]
      }
   }
}
```

**結構描述版本 1.2 `aws:runShellScript` 範例**  
以下範例顯示 `AWS-RunShellScript` SSM 文件。**runtimeConfig** 區段包含 `aws:runShellScript` 外掛程式。

```
{
    "schemaVersion":"1.2",
    "description":"Run a shell script or specify the commands to run.",
    "parameters":{
        "commands":{
            "type":"StringList",
            "description":"(Required) Specify a shell script or a command to run.",
            "minItems":1,
            "displayType":"textarea"
        },
        "workingDirectory":{
            "type":"String",
            "default":"",
            "description":"(Optional) The path to the working directory on your instance.",
            "maxChars":4096
        },
        "executionTimeout":{
            "type":"String",
            "default":"3600",
            "description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
            "allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
        }
    },
    "runtimeConfig":{
        "aws:runShellScript":{
            "properties":[
                {
                    "id":"0.aws:runShellScript",
                    "runCommand":"{{ commands }}",
                    "workingDirectory":"{{ workingDirectory }}",
                    "timeoutSeconds":"{{ executionTimeout }}"
                }
            ]
        }
    }
}
```

## 結構描述版本 0.3


**頂層元素**  
下列範例以 JSON 格式顯示結構描述 0.3 版 Automation Runbook 的最上層元素。

```
{
    "description": "document-description",
    "schemaVersion": "0.3",
    "assumeRole": "{{assumeRole}}",
    "parameters": {
        "parameter1": {
            "type": "String",
            "description": "parameter-1-description",
            "default": ""
        },
        "parameter2": {
            "type": "String",
            "description": "parameter-2-description",
            "default": ""
        }
    },
    "variables": {
        "variable1": {
            "type": "StringMap",
            "description": "variable-1-description",
            "default": {}
        },
        "variable2": {
            "type": "String",
            "description": "variable-2-description",
            "default": "default-value"
        }
    },
    "mainSteps": [
        {
            "name": "myStepName",
            "action": "action-name",
            "maxAttempts": 1,
            "inputs": {
                "Handler": "python-only-handler-name",
                "Runtime": "runtime-name",
                "Attachment": "script-or-zip-name"
            },
            "outputs": {
                "Name": "output-name",
                "Selector": "selector.value",
                "Type": "data-type"
            }
        }
    ],
    "files": {
        "script-or-zip-name": {
            "checksums": {
                "sha256": "checksum"
            },
            "size": 1234
        }
    }
}
```

**YAML Automation Runbook 範例**  
下列範例以 YAML 格式顯示 Automation Runbook 的內容。文件結構描述的這份 0.3 版運作範例，也示範了如何使用 Markdown 來格式化文件描述。

```
description: >-
  ##Title: LaunchInstanceAndCheckState

  -----

  **Purpose**: This Automation runbook first launches an EC2 instance
  using the AMI ID provided in the parameter ```imageId```. The second step of
  this document continuously checks the instance status check value for the
  launched instance until the status ```ok``` is returned.


  ##Parameters:

  -----

  Name | Type | Description | Default Value

  ------------- | ------------- | ------------- | -------------

  assumeRole | String | (Optional) The ARN of the role that allows Automation to
  perform the actions on your behalf. | -

  imageId  | String | (Optional) The AMI ID to use for launching the instance.
  The default value uses the latest Amazon Linux AMI ID available. | {{
  ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
  imageId:
    type: String
    default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
    description: >-
      (Optional) The AMI ID to use for launching the instance. The default value
      uses the latest released Amazon Linux AMI ID.
  tagValue:
    type: String
    default: ' LaunchedBySsmAutomation'
    description: >-
      (Optional) The tag value to add to the instance. The default value is
      LaunchedBySsmAutomation.
  instanceType:
    type: String
    default: t2.micro
    description: >-
      (Optional) The instance type to use for the instance. The default value is
      t2.micro.
mainSteps:
  - name: LaunchEc2Instance
    action: 'aws:executeScript'
    outputs:
      - Name: payload
        Selector: $.Payload
        Type: StringMap
    inputs:
      Runtime: python3.11
      Handler: launch_instance
      Script: ''
      InputPayload:
        image_id: '{{ imageId }}'
        tag_value: '{{ tagValue }}'
        instance_type: '{{ instanceType }}'
      Attachment: launch.py
    description: >-
      **About This Step**


      This step first launches an EC2 instance using the ```aws:executeScript```
      action and the provided python script.
  - name: WaitForInstanceStatusOk
    action: 'aws:executeScript'
    inputs:
      Runtime: python3.11
      Handler: poll_instance
      Script: |-
        def poll_instance(events, context):
          import boto3
          import time

          ec2 = boto3.client('ec2')

          instance_id = events['InstanceId']

          print('[INFO] Waiting for instance status check to report ok', instance_id)

          instance_status = "null"

          while True:
            res = ec2.describe_instance_status(InstanceIds=[instance_id])

            if len(res['InstanceStatuses']) == 0:
              print("Instance status information is not available yet")
              time.sleep(5)
              continue

            instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']

            print('[INFO] Polling to get status of the instance', instance_status)

            if instance_status == 'ok':
              break

            time.sleep(10)

          return {'Status': instance_status, 'InstanceId': instance_id}
      InputPayload: '{{ LaunchEc2Instance.payload }}'
    description: >-
      **About This Step**


      The python script continuously polls the instance status check value for
      the instance launched in Step 1 until the ```ok``` status is returned.
files:
  launch.py:
    checksums:
      sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```

## 安全參數處理範例


下列範例示範使用環境變數 `interpolationType` 來安全處理參數。

### 基本安全命令執行


此範例說明如何安全地處理命令參數：

**注意**  
在不使用雙括號的 SSM 文件中，技術上不需要 `allowedPattern`：`{{ }}`

------
#### [ YAML ]

```
---

schemaVersion: '2.2'
description: An example document.
parameters:
  Message:
    type: String
    description: "Message to be printed"
    default: Hello
    interpolationType: ENV_VAR
    allowedPattern: "^[^"]*$"
mainSteps:
  - action: aws:runShellScript
    name: printMessage
    precondition:
      StringEquals:
        - platformType
        - Linux
    inputs:
      runCommand:
        - echo {{Message}}
```

------
#### [ JSON ]

```
{
    "schemaVersion": "2.2",
    "description": "An example document.",
    "parameters": {
        "Message": {
            "type": "String",
            "description": "Message to be printed",
            "default": "Hello",
            "interpolationType": "ENV_VAR",
            "allowedPattern": "^[^"]*$"
        }
    },
    "mainSteps": [{
        "action": "aws:runShellScript",
        "name": "printMessage",
        "precondition": {
           "StringEquals": ["platformType", "Linux"]
        },
        "inputs": {
            "runCommand": [
              "echo {{Message}}"
            ]
        }
    }]
}
```

------

### 以編譯語言使用參數


此範例示範在 Python 中安全處理參數：

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
  inputData:
    type: String
    description: 'Input data for processing'
    interpolationType: 'ENV_VAR'
mainSteps:
  - action: aws:runPowerShellScript
    name: runPython
    inputs:
      runCommand:
        - |
          python3 -c '
          import os
          import json
          
          # Safely access parameter through environment variable
          input_data = os.environ.get("SSM_inputData", "")
          
          # Process the data
          try:
              processed_data = json.loads(input_data)
              print(f"Successfully processed: {processed_data}")
          except json.JSONDecodeError:
              print("Invalid JSON input")
          '
```

------

### 回溯相容性範例


此範例說明如何安全地處理參數，同時保持回溯相容性：

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
  userInput:
    type: String
    description: 'User input to process'
    interpolationType: 'ENV_VAR'
    allowedPattern: '^[^"]*$'

mainSteps:
  - action: aws:runShellScript
    name: processInput
    inputs:
      runCommand:
        - |
          # Handle both modern and legacy agent versions
          if [ -z "${SSM_userInput+x}" ]; then
              # Legacy agent - fall back to direct parameter reference
              export SSM_userInput="{{userInput}}"
          fi
          
          # Process the input securely
          echo "Processing input: $SSM_userInput"
```

------

**注意**  
在不使用雙括號的 SSM 文件中，技術上不需要 `allowedPattern`：`{{ }}`

## 參數安全最佳實務


處理 SSM 文件中的參數時，請遵循下列最佳實務：
+ **使用環境變數插補** – 一律將 `interpolationType: "ENV_VAR"` 用於在命令執行中使用的字串參數。
+ **實作輸入驗證** – 使用 `allowedPattern`，將參數值限制為安全模式。
+ **處理舊式系統** – 包含不支援環境變數插補之舊版 SSM Agent 的備用邏輯。
+ **逸出特殊字元** – 在命令中使用參數值時，請正確逸出特殊字元，以防止 shell 解譯。
+ **限制參數範圍** – 為您的使用案例使用最嚴格的參數模式。

# 資料元素和參數


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

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

## 頂層資料元素


**schemaVersion**  
要使用的結構描述版本。  
類型：版本  
必要：是

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

**parameters**  
一種結構，定義文件接受的參數。  
為了在處理字串參數時增強安全性，您可以透過指定 `interpolationType` 屬性，使用環境變數插補。設定為 `ENV_VAR` 時，系統會建立名為 `SSM_parameter-name` 的環境變數，其中包含參數值。  
以下包含使用環境變數 `interpolationType` 的參數範例：  

```
{
    "schemaVersion": "2.2",
    "description": "An example document.",
    "parameters": {
        "Message": {
            "type": "String",
            "description": "Message to be printed",
            "default": "Hello",
            "interpolationType" : "ENV_VAR",
            "allowedPattern": "^[^"]*$"

        }
    },
    "mainSteps": [{
        "action": "aws:runShellScript",
        "name": "printMessage",
        "precondition" : {
           "StringEquals" : ["platformType", "Linux"]
        },
        "inputs": {
            "runCommand": [
              "echo {{Message}}"
            ]
        }
    }
}
```
在不使用雙括號的 SSM 文件中，技術上不需要 `allowedPattern`：`{{ }}`
對於常用的參數，建議您將這些參數存放在 Parameter Store ( AWS Systems Manager中的工具) 中。然後，您可以在文件中定義參考 Parameter Store 參數作為預設值的參數。若要參考 Parameter Store 參數，請使用下列語法。  

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

```
---
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 }}"],
            interpolationType : 'ENV_VAR'
            allowedPattern: '^[^"]*$'

mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:"{{ commands }}"
```

```
{
    "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 }}"],
        "interpolationType" : "ENV_VAR"
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }
```
您在文件的 `parameters` 部分可以參考 `String` 和 `StringList` Parameter Store 參數。您無法參考 `SecureString` Parameter Store 參數。
如需有關 Parameter Store 的詳細資訊，請參閱「[AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)」。  
類型：結構  
`parameters` 結結構接受下列的欄位和數值：  
+ `type`：(必要) 允許的值包括：`String`、`StringList`、`Integer`、`Boolean`、`MapList` 和 `StringMap`。若要查看每個類型的範例，在下一個部分請參閱 [SSM 文件參數 `type` 範例](#top-level-properties-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 程式庫](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)執行第一次驗證。在處理文件之前，藉由使用 [GO Regexp 程式庫](https://pkg.go.dev/regexp)，在 SSM Agent 上執行第二次驗證。

------
#### [ YAML ]

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

------
#### [ JSON ]

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

------
+ `displayType`：（選用） 用來在 `textarea`中顯示 `textfield`或 AWS 管理主控台。 `textfield` 是單行文字方塊。 `textarea` 是多行文字區域。
+ `minItems`：(選擇性) 允許項目數量的最小值。
+ `maxItems`：(選擇性) 允許項目數量的最大值。
+ `minChars`：(選擇性) 允許參數字元數量的最小值。
+ `maxChars`：(選擇性) 允許參數字元數量的最大值。
+ `interpolationType`：(選用) 定義在命令執行之前如何處理參數值。設定為 `ENV_VAR` 時，參數值將作為名為 `SSM_parameter-name` 的環境變數。此功能將參數值視為常值字串，有助於防止命令注入。

  類型：字串

  有效值：`ENV_VAR`
必要：否

**variables**  
(僅限結構描述版本 0.3) 您可以在 Automation 執行手冊中的整個步驟中參考或更新的值。變數類似於參數，但有一個非常重要的差異。參數值在執行手冊的內容中是靜態的，但變數的值可以在執行手冊的內容中進行變更。更新變數的值時，資料類型必須與定義的資料類型相符。如需有關在自動化操作中更新變數值的資訊，請參閱 [`aws:updateVariable` - 更新執行手冊變數的值](automation-action-update-variable.md)  
類型：布林值 \$1 整數 \$1 MapList \$1 字串 \$1 StringList \$1 StringMap  
必要：否  

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

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

**runtimeConfig**  
(結構描述 1.2 版) 一個或多個 Systems Manager 外掛程式套用的執行個體組態。不能保證外掛程式按順序執行。  
類型：Dictionary<string,PluginConfiguration>  
必要：否

**mainSteps**  
(僅限結構描述版本 0.3、2.0 和 2.2) 可以包含多個步驟 (外掛程式) 的物件。外掛程式在步驟中定義。步驟會按文件中列出的順序執行。  
類型：Dictionary<string,PluginConfiguration>  
必要：是

**outputs**  
(僅限結構描述版本 0.3) 執行此文件所產生的資料，可用於其他程序。例如，如果您的文件建立新 AMI，您可以將 "CreateImage.ImageId" 指定為輸出值，然後使用此輸出在後續自動化執行中建立新的執行個體。如需輸出的詳細資訊，請參閱 [使用動作輸出作為輸入](automation-action-outputs-inputs.md)。  
類型：Dictionary<string,OutputConfiguration>  
必要：否

**files**  
(僅限結構描述 0.3) 連接至文件並在自動化執行期間執行的指令碼檔案 (及其檢查總和)。僅適用於包含 `aws:executeScript` 動作，以及已在一或多個步驟中指定附件的文件。  
若要了解 Automation 執行手冊支援的執行時期，請參閱 [`aws:executeScript` – 執行指令碼](automation-action-executeScript.md)。如需有關在 Automation Runbook 中包含指令碼的詳細資訊，請參閱 [在執行手冊中使用指令碼](automation-document-script-considerations.md) 和 [Automation 執行手冊的視覺化設計體驗](automation-visual-designer.md)。  
使用附件建立 Automation Runbook 時，您還必須使用 `--attachments` 選項 （適用於 AWS CLI) 或 `Attachments`（適用於 API 和 SDK) 指定附件檔案。您可以為存放在 Amazon Simple Storage Service (Amazon S3) 儲存貯體中的 SSM 文件和檔案指定檔案位置。如需詳細資訊，請參閱 AWS Systems Manager API 參考中的[附件](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)。  

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

```
"files": {
    "launch.py": {
        "checksums": {
            "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
        }
    }
}
```
類型：Dictionary<string,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` 的範例。

String  
一連串零或多個 Unicode 字元以雙引號框住。例如，"i-1234567890abcdef0"。使用反斜線逸出。  
字串參數可包含具有 `ENV_VAR` 值的選用 `interpolationType` 欄位，以啟用環境變數插補，進而提升安全性。  

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

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

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

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

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

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

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

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

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

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

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

StringMap  
金鑰與值的映射。金鑰和值必須是字串。例如，\$1"Env": "Prod"\$1。  

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

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

MapList  
StringMap 物件清單。  

```
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
```

```
"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) 命令文件的必要和選用參數，除了文件執行的動作之外，您還可以在 Systems Manager 主控台中檢視文件的內容。

**若要檢視 SSM 命令文件內容**

1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 AWS Systems Manager 主控台。

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

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

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

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

   例如，下圖顯示 (1) `version` 與 (2) `allowDowngrade` 是 `AWS-UpdateSSMAgent` 文件的可選參數，並且文件執行的第一個操作是 (3) `aws:updateSsmAgent`。  
![\[在 Systems Manager 主控台中檢視 SSM 文件內容\]](http://docs.aws.amazon.com/zh_tw/systems-manager/latest/userguide/images/view-document-content.png)

# 命令文件外掛程式參考


此參考說明您可以在 AWS Systems Manager (SSM) 命令類型文件中指定的外掛程式。這些外掛程式無法在使用 Automation 動作時用於 SSM Automation Runbook。如需 AWS Systems Manager 自動化動作的詳細資訊，請參閱 [Systems Manager Automation 動作參考](automation-actions.md)。

Systems Manager 會讀取 SSM 文件的內容，以決定在受管執行個體上執行的動作。每個文件包含程式碼執行部分。根據您文件的結構描述版本，這個程式碼執行部分可以包含一或多個外掛程式或步驟。有關於此的說明主題，外掛程式和步驟稱為 *外掛程式*。本節包含關於每個 Systems Manager 外掛程式的資訊。如需有關文件，包含建立文件和結構描述版本之間差異的更多資訊，請參閱 [AWS Systems Manager Documents](documents.md)。

對於接受字串參數的外掛程式 (例如 `aws:runShellScript` 和 `aws:runPowerShellScript`)，`interpolationType` 參數可以透過將參數輸入視為字串常值，而非潛在的可執行命令，來增強安全性。例如：

```
{
    "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 }}"],
        "interpolationType" : "ENV_VAR"
      }
    },
    //truncated
 }
```

**注意**  
此處說明的一些外掛程式僅能夠在 Windows Server 執行個體或 Linux 執行個體上執行。每個外掛程式須注意平台相容性。  
macOS 的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體支援下列文件外掛程式：  
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`

**Topics**
+ [

## 共用的輸入
](#shared-inputs)
+ [

## `aws:applications`
](#aws-applications)
+ [

## `aws:cloudWatch`
](#aws-cloudWatch)
+ [

## `aws:configureDocker`
](#aws-configuredocker)
+ [

## `aws:configurePackage`
](#aws-configurepackage)
+ [

## `aws:domainJoin`
](#aws-domainJoin)
+ [

## `aws:downloadContent`
](#aws-downloadContent)
+ [

## `aws:psModule`
](#aws-psModule)
+ [

## `aws:refreshAssociation`
](#aws-refreshassociation)
+ [

## `aws:runDockerAction`
](#aws-rundockeraction)
+ [

## `aws:runDocument`
](#aws-rundocument)
+ [

## `aws:runPowerShellScript`
](#aws-runPowerShellScript)
+ [

## `aws:runShellScript`
](#aws-runShellScript)
+ [

## `aws:softwareInventory`
](#aws-softwareinventory)
+ [

## `aws:updateAgent`
](#aws-updateagent)
+ [

## `aws:updateSsmAgent`
](#aws-updatessmagent)

## 共用的輸入


透過 SSM Agent 3.0.502 版及更新版本，所有外掛程式都可使用以下輸入：

**finallyStep**  
您想要文件執行的最後一個步驟。如果對步驟定義了此輸入，則它的優先順序高於在 `onFailure` 或 `onSuccess` 輸入中指定的 `exit` 值。若要讓具有此輸入的步驟預期執行，該步驟必須是在文件的 `mainSteps` 中定義的最後一步。  
類型：布林值  
有效值：`true` \$1 `false`  
必要：否

**onFailure**  
如果您為具有 `exit` 值的外掛程式指定此輸入，且該步驟失敗，則步驟狀態會反映失敗，而且文件不會執行任何剩餘的步驟，除非已定義 `finallyStep`。如果您為具有 `successAndExit` 值的外掛程式指定此輸入，且該步驟失敗，則步驟狀態會顯示成功，而且文件不會執行任何剩餘的步驟，除非已定義 `finallyStep`。  
類型：字串  
有效值：`exit` \$1 `successAndExit`  
必要：否

**onSuccess**  
如果您為外掛程式指定此輸入，且該步驟成功執行，則文件不會執行任何剩餘的步驟，除非已定義 `finallyStep`。  
類型：字串  
有效值：`exit`  
必要：否

------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
  customDocumentParameter:
    type: String
    description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
  name: runCustomConfiguration
  inputs:
    documentType: SSMDocument
    documentPath: "yourCustomDocument"
    documentParameters: '"documentParameter":{{customDocumentParameter}}'
    onSuccess: exit
- action: aws:runDocument
  name: ifConfigurationFailure
  inputs:
    documentType: SSMDocument
    documentPath: "yourCustomRepairDocument"
    onFailure: exit
- action: aws:runDocument
  name: finalConfiguration
  inputs:
    documentType: SSMDocument
    documentPath: "yourCustomFinalDocument"
    finallyStep: true
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "Shared inputs example",
   "parameters": {
      "customDocumentParameter": {
         "type": "String",
         "description": "Example parameter for a custom Command-type document."
      }
   },
   "mainSteps":[
      {
         "action": "aws:runDocument",
         "name": "runCustomConfiguration",
         "inputs": {
            "documentType": "SSMDocument",
            "documentPath": "yourCustomDocument",
            "documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
            "onSuccess": "exit"
         }
      },
      {
         "action": "aws:runDocument",
         "name": "ifConfigurationFailure",
         "inputs": {
            "documentType": "SSMDocument",
            "documentPath": "yourCustomRepairDocument",
            "onFailure": "exit"
         }
      },
      {
         "action": "aws:runDocument",
         "name":"finalConfiguration",
         "inputs": {
            "documentType": "SSMDocument",
            "documentPath": "yourCustomFinalDocument",
            "finallyStep": true
         }
      }
   ]
}
```

------

## `aws:applications`


安裝、修復或解除安裝在 EC2 執行個體上的應用程式。這個外掛程式只能在 Windows Server 作業系統上執行。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
  source:
    description: "(Required) Source of msi."
    type: String
mainSteps:
- action: aws:applications
  name: example
  inputs:
    action: Install
    source: "{{ source }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion":"2.2",
  "description":"aws:applications",
  "parameters":{
    "source":{
    "description":"(Required) Source of msi.",
    "type":"String"
    }
  },
  "mainSteps":[
    {
      "action":"aws:applications",
      "name":"example",
      "inputs":{
        "action":"Install",
        "source":"{{ source }}"
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:applications:
    properties:
    - id: 0.aws:applications
      action: "{{ action }}"
      parameters: "{{ parameters }}"
      source: "{{ source }}"
      sourceHash: "{{ sourceHash }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:applications":{
         "properties":[
            {
               "id":"0.aws:applications",
               "action":"{{ action }}",
               "parameters":"{{ parameters }}",
               "source":"{{ source }}",
               "sourceHash":"{{ sourceHash }}"
            }
         ]
      }
   }
}
```

------

### Properties


**動作**  
採取動作  
類型：列舉  
有效值：`Install` \$1 `Repair` \$1 `Uninstall`  
必要：是

**parameters**  
安裝的參數。  
類型：字串  
必要：否

**source**  
應用程式的 `.msi` 檔案 URL。  
類型：字串  
必要：是

**sourceHash**  
`.msi` 檔案的 SHA256 雜湊。  
類型：字串  
必要：否

## `aws:cloudWatch`


將資料從 Windows Server 匯出到 Amazon CloudWatch 或 Amazon CloudWatch Logs，並使用 CloudWatch 指標監控資料。這個外掛程式只能在 Windows Server 作業系統上執行。如需有關設定 CloudWatch 與 Amazon Elastic Compute Cloud (Amazon EC2) 整合的詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的 [Collecting metrics, logs, and traces with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。

**重要**  
統一的 CloudWatch 代理程式已取代 SSM Agent 作為將日誌資料傳送至 Amazon CloudWatch Logs 的工具。不支援 SSM Agent aws:cloudWatch 插件。建議只使用統一的 CloudWatch 代理程式來執行日誌收集流程。如需詳細資訊，請參閱下列主題：  
[將節點日誌傳送至統一 CloudWatch Logs (CloudWatch 代理程式)](monitoring-cloudwatch-agent.md)
[將 Windows Server 節點日誌收集遷移到 CloudWatch 代理程式](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
《Amazon CloudWatch 使用者指南》**中的 [Collecting metrics, logs, and traces with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。

您可以匯出和監控以下資料類型：

**ApplicationEventLog**  
將應用程式事件日誌資料傳送至 CloudWatch Logs。

**CustomLogs**  
將任何文字類日誌檔案傳送至 Amazon CloudWatch Logs。CloudWatch 外掛程式為日誌檔案建立指紋。系統會將資料位移與每個指紋建立關聯。當檔案改變時，外掛程式上傳檔案並記錄位移然後建立與指紋的關聯。此方法用於避免使用者開啟外掛程式，將服務與包含大量檔案的目錄關聯，並且系統會上傳所有檔案。  
請注意，如果您的應用程式在輪詢時嘗試截斷或清理日誌的任何日誌，任何 `LogDirectoryPath` 指定的日誌將可能遺失項目。例如，如果您想要限制的日誌檔案大小，達到該限制時建立新的日誌檔，然後持續將資料寫入新的檔案。

**ETW**  
將 Event Tracing for Windows (ETW) 資料傳送到 CloudWatch Logs。

**IIS**  
將 IIS 日誌資料傳送到 CloudWatch Logs。

**PerformanceCounter**  
將 Windows 效能計數器傳送到 CloudWatch。您可以選擇不同類別以作為指標上傳至 CloudWatch。對於每個您要上傳的效能計數器，建立一個 **PerformanceCounter** 部分具有唯一的 ID (例如，「PerformanceCounter2」、」 PerformanceCounter3」等) 和屬性設定。  
如果 AWS Systems Manager SSM Agent或 CloudWatch 外掛程式停止，效能計數器資料不會記錄在 CloudWatch 中。此行為不同於自訂日誌或 Windows 事件日誌。自訂日誌和 Windows 事件日誌會保留效能計數器資料，並且在 SSM Agent 或 CloudWatch 外掛程式能夠使用之後，將這些資料上傳到 CloudWatch。

**SecurityEventLog**  
將安全性日誌資料傳送至 CloudWatch Logs。

**SystemEventLog**  
將系統事件日誌資料傳送至 CloudWatch Logs。

您可以定義以下資料的目的地：

**CloudWatch**  
傳送您的效能計數器指標資料的目的地。您可以用唯一的 ID 增加多個區段 (例如「CloudWatch2」和「CloudWatch3」)，並替不同的區域指定新的 ID 然後傳遞相同的資料到不同的地點。

**CloudWatchLogs**  
傳送您的效能計數器日誌資料的目的地。您可以用唯一的 ID 增加多個區段 (例如「CloudWatchLogs2」和「CloudWatchLogs3」)，並替不同的區域指定新的 ID 然後傳遞相同的資料到不同的地點。

### 語法


```
"runtimeConfig":{
        "aws:cloudWatch":{
            "settings":{
                "startType":"{{ status }}"
            },
            "properties":"{{ properties }}"
        }
    }
```

### 設定和屬性


**AccessKey**  
您的 存取金鑰 ID。此屬性是必要的，除非您使用 IAM 角色啟動執行個體。此屬性無法用於 SSM。  
類型：字串  
必要：否

**CategoryName**  
效能監控從效能計數器類別而來。  
類型：字串  
必要：是

**CounterName**  
效能監控的名稱從效能計數器類別而來。  
類型：字串  
必要：是

**CultureName**  
要記錄時間戳記的所在地區。如果 **CultureName** 為空白，它會預設為 Windows Server 執行個體使用的相同地區設定。  
類型：字串  
有效的數值: 支援數值的清單，請參閱 Microsoft 網頁中的 [National Language Support (NLS) (國家語言支援 (NLS) 參考)](https://msdn.microsoft.com/en-us/library/cc233982.aspx)。不支援 **div**、**div-MV**、**hu** 和 **hu-HU** 值。  
必要：否

**DimensionName**  
Amazon CloudWatch 指標的維度。若您指定 `DimensionName`，您必須指定 `DimensionValue`。在列出指標時，這些參數會提供另一種視圖。您也可以針對多個指標使用同一種維度，如此就能檢視屬於特定維度的所有指標。  
類型：字串  
必要：否

**DimensionValue**  
Amazon CloudWatch 指標的維度值。  
類型：字串  
必要：否

**編碼**  
使用的檔案編碼 (例如，UTF-8)。使用編碼名稱，而非顯示名稱。  
類型：字串  
有效數值: 如需支援值的清單，請參閱 Microsoft Learn Library 中的[編碼類別](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0)。  
必要：是

**篩選條件**  
日誌名稱的字首。將此參數留白，以監控所有檔案。  
類型：字串  
有效數值: 如需支援值的清單，請參閱 [ MSDN 上的 FileSystemWatcherFilter 屬性](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx)主題。  
必要：否

**流程**  
要上傳的每個資料類型，以及資料目的地 (CloudWatch 或 CloudWatch Logs)。例如，若要將在 `"Id": "PerformanceCounter"` 下定義的效能計數器傳送至在 `"Id": "CloudWatch"` 下定義的 CloudWatch 目的地，請輸入 **"PerformanceCounter,CloudWatch"**。同樣，若要將自訂日誌、ETW 日誌和系統日誌傳送至在 `"Id": "ETW"` 下定義的 CloudWatch Logs 目的地，請輸入 **"(ETW),CloudWatchLogs"**。除此之外，您可以將相同的效能計數器或日誌檔案傳送到一個以上的目的地。例如，如果要將應用程式日誌傳送到您在 `"Id": "CloudWatchLogs"` 和 `"Id": "CloudWatchLogs2"` 區段中所定義的兩個不同目的地，輸入 **"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"**。  
類型：字串  
有效數值 (來源): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`   
有效值 (目的地)：`CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*   
必要：是

**FullName**  
元件的完全名稱。  
類型：字串  
必要：是

**Id**  
識別資料來源或目的地。這識別符在組態檔案中必須是唯一的。  
類型：字串  
必要：是

**InstanceName**  
效能計數器執行個體的名稱。請勿使用星號 (\$1) 來表示所有的執行個體，因為每個效能計數器元件只支援一個指標。不過您可以使用 **\$1Total**。  
類型：字串  
必要：是

**層級**  
要傳送至 Amazon CloudWatch 的訊息類型。  
類型：字串  
有效值：  
+ **1** – 只上傳錯誤訊息。
+ **2** – 只上傳警告訊息。
+ **4** – 只上傳資訊訊息。
您可以一起新增值，以包含多個類型訊息。例如，**3** 表示錯誤訊息 (**1**) 和警告訊息 (**2**)都包含。數值 **7** 表示包含錯誤訊息 (**1**)、警告訊息 (**2**) 和資訊訊息 (**4**)。  
必要：是  
Windows Security Logs 應該設定層級為 7。

**LineCount**  
標頭中的行數，以辨識日誌檔案。例如，IIS 日誌檔幾乎都具有相同的標頭。您可以輸入 **3**，這會讀取日誌檔標頭的前三行來進行辨識。在 IIS 日誌檔中，第三行是日期和時間戳記，這在不同的日誌檔中是不一樣的。  
類型：整數  
必要：否

**LogDirectoryPath**  
對於 CustomLogs，此屬性是指 EC2 執行個體上存放日誌的路徑。對於 IIS 日誌，資料夾替個別的網站存放 IIS 日誌 (例如，**C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***)。IIS 日誌只支援 W3C 日誌格式。不支援 IIS、NCSA 和自訂格式。  
類型：字串  
必要：是

**LogGroup**  
您的日誌群組名稱。CloudWatch 主控台的 **Log Groups** (日誌群組) 畫面中會顯示此名稱。  
類型：字串  
必要：是

**LogName**  
日誌檔案的名稱。  

1. 若要在導覽窗格的事件檢視器中查找日誌名稱，請選取 **Applications and Services Logs** (應用程式和服務日誌)。

1. 在日誌清單中，在您要上傳的日誌上按一下滑鼠右鍵 (例如 `Microsoft` > `Windows` > `Backup` > `Operational`)，然後選取**建立自訂檢視**。

1. 在 **Create Custom View** (建立自訂檢視) 對話方塊中，選取 **XML** 標籤。**LogName** 位於 < 選取途徑 => 標籤 (例如，`Microsoft-Windows-Backup`)。複製此文字到 **LogName** 參數。
類型：字串  
有效值：`Application` \$1 `Security` \$1 `System` \$1 `Microsoft-Windows-WinINet/Analytic`  
必要：是

**LogStream**  
日誌串流目的地的名稱 若您使用 **\$1instance\$1id\$1**，日誌串流名稱是這個執行個體 ID 的預設值。  
類型：字串  
有效值：`{instance_id}` \$1 `{hostname}` \$1 `{ip_address}` *<log\$1stream\$1name>*  
如果輸入的日誌串流名稱尚未存在，CloudWatch Logs 會自動為您建立。您可以使用文字字串或預先定義的變數 (**\$1instance\$1id\$1**, **\$1hostname\$1**, **\$1ip\$1address\$1**，或是組合全部三者來定義日誌串流名稱。  
此參數中指定的日誌串流名稱會顯示在 CloudWatch 主控台的**Log Groups > Streams for *<YourLogStream>*** (日誌群組 > YourLogStream 串流) 畫面中。  
必要：是

**MetricName**  
您希望能包含效能資料的 CloudWatch 指標。  
請不要在名稱中使用特殊字元。如果您這麼做了、指標和相關警示可能不會運作。
類型：字串  
必要：是

**NameSpace**  
將會在指標命名空間寫入效能計數器資料。  
類型：字串  
必要：是

**PollInterval**  
上傳新的效能計數器和日誌資料時需要延遲多少秒。  
類型：整數  
有效值：將此屬性設為 5 個或多個秒。十五秒 (00:00:15) 是建議。  
必要：是

**區域**  
您要傳送日誌資料的 AWS 區域 。雖然您可以將效能計數器，傳送到與您傳送日誌資料所在位置不同的區域，還是建議您將此參數，設定為與執行個體執行位置相同的區域。  
類型：字串  
有效值：Systems Manager 和 CloudWatch Logs AWS 區域 支援的 區域 IDs，例如 `us-east-2`、 `eu-west-1`和 `ap-southeast-1`。如需每個服務 AWS 區域 支援的 清單，請參閱《》中的 [Amazon CloudWatch Logs Service Endpoints](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html#cwl_region) 和 [Systems Manager 服務端點](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region)*Amazon Web Services 一般參考*。  
必要：是

**SecretKey**  
您的 私密存取金鑰。此屬性是必要的，除非您使用 IAM 角色啟動執行個體。  
類型：字串  
必要：否

**startType**  
開啟或關閉執行個體上的 CloudWatch。  
類型：字串  
有效值：`Enabled` \$1 `Disabled`  
必要：是

**TimestampFormat**  
要使用的時間戳記格式。如需支援值的清單，請參閱 MSDN 上的[自訂日期和時間格式字串](http://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx)主題。  
類型：字串  
必要：是

**TimeZoneKind**  
當您的日誌時間戳記中沒有時區資訊時，您需要提供時區資訊。如果此參數保留空白，且如果您的時間戳記不包含時區資訊，則 CloudWatch Logs 預設為本機時區。如果時間戳記已包含時區資訊，則會忽略此參數。  
類型：字串  
有效值：`Local` \$1 `UTC`  
必要：否

**單位**  
適合指標的測量單位。  
類型：字串  
有效數值: 秒 \$1 微秒 \$1 毫秒 \$1 位元組 \$1 千位元組 (KB) \$1 百萬位元組 (MB) \$1 十億位元組 (GB) \$1 兆位元組 (TB) \$1 位元 \$1 千位元 (kb) \$1 百萬位元 (Mb) \$1 十億位元 (Gb) \$1 兆位元 (Tb) \$1 百分比 \$1 計數 \$1 位元組/秒 \$1 千位元組 (KB)/秒 \$1 百萬位元組 (MB)/秒 \$1 十億位元組 (GB)/秒 \$1 兆位元組 (TB)/秒 \$1 位元/秒 \$1 千位元 (kb)/ 秒 \$1 百萬位元 (Mb)/秒 \$1 十億位元 (Gb)/秒 \$1 兆位元 (Tb)/秒 \$1 計數/秒 \$1 無。  
必要：是

## `aws:configureDocker`


(結構描述 2.0 版本或更新版本) 設定執行個體來處理 Docker 和容器。大部分 Linux 變體和 Windows Server 作業系統都支援此外掛程式。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:configureDocker
parameters:
  action:
    description: "(Required) The type of action to perform."
    type: String
    default: Install
    allowedValues:
    - Install
    - Uninstall
mainSteps:
- action: aws:configureDocker
  name: configureDocker
  inputs:
    action: "{{ action }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:configureDocker plugin",
  "parameters": {
    "action": {
      "description": "(Required) The type of action to perform.",
      "type": "String",
      "default": "Install",
      "allowedValues": [
        "Install",
        "Uninstall"
      ]
    }
  },
  "mainSteps": [
    {
      "action": "aws:configureDocker",
      "name": "configureDocker",
      "inputs": {
        "action": "{{ action }}"
      }
    }
  ]
}
```

------

### 輸入


**動作**  
執行動作的類型。  
類型：列舉  
有效值：`Install` \$1 `Uninstall`  
必要：是

## `aws:configurePackage`


（結構描述 2.0 版或更新版本） 安裝或解除安裝 AWS Systems Manager Distributor套件。您可以安裝最新版本、預設版本或您指定的套件版本。也支援 AWS 提供的套件。這個外掛程式可在 Windows Server 和 Linux 作業系統上執行，但 Linux 作業系統不支援所有的可用套件。

的可用 AWS 套件Windows Server包括下列項目：`AWSPVDriver`、`AWSNVMe`、`AwsEnaNetworkDriver`、`AwsVssComponents`、`CodeDeployAgent`、 `AmazonCloudWatchAgent`和 `AWSSupport-EC2Rescue.`

Linux 作業系統的可用 AWS 套件包括下列項目：`CodeDeployAgent`、 `AmazonCloudWatchAgent`和 `AWSSupport-EC2Rescue`。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:configurePackage
parameters:
  name:
    description: "(Required) The name of the AWS package to install or uninstall."
    type: String
  action:
    description: "(Required) The type of action to perform."
    type: String
    default: Install
    allowedValues:
    - Install
    - Uninstall
  ssmParameter:
    description: "(Required) Argument stored in Parameter Store."
    type: String
    default: "{{ ssm:parameter_store_arg }}"
mainSteps:
- action: aws:configurePackage
  name: configurePackage
  inputs:
    name: "{{ name }}"
    action: "{{ action }}"
    additionalArguments: 
      "{\"SSM_parameter_store_arg\": \"{{ ssmParameter }}\", \"SSM_custom_arg\": \"myValue\"}"
```

------
#### [ JSON ]

```
{
   "schemaVersion": "2.2",
   "description": "aws:configurePackage",
   "parameters": {
      "name": {
         "description": "(Required) The name of the AWS package to install or uninstall.",
         "type": "String"
      },
      "action": {
         "description": "(Required) The type of action to perform.",
         "type": "String",
         "default": "Install",
         "allowedValues": [
            "Install",
            "Uninstall"
         ]
      },
      "ssmParameter": {
         "description": "(Required) Argument stored in Parameter Store.",
         "type": "String",
         "default": "{{ ssm:parameter_store_arg }}"
      }
   },
   "mainSteps": [
      {
         "action": "aws:configurePackage",
         "name": "configurePackage",
         "inputs": {
            "name": "{{ name }}",
            "action": "{{ action }}",
            "additionalArguments": "{\"SSM_parameter_store_arg\": \"{{ ssmParameter }}\", \"SSM_custom_arg\": \"myValue\"}"
         }
      }
   ]
}
```

------

### 輸入


**name**  
要安裝或解除安裝的 AWS 套件名稱。可用套件包括：`AWSPVDriver`、`AwsEnaNetworkDriver`、`AwsVssComponents` 和 `AmazonCloudWatchAgent`。  
類型：字串  
必要：是

**動作**  
安裝或解除安裝套件  
類型：列舉  
有效值：`Install` \$1 `Uninstall`  
必要：是

**installationType**  
要執行的安裝類型。如果您指定 `Uninstall and reinstall`，套件會完全解除安裝，然後重新安裝。在重新安裝完成之前，應用程式無法使用。如果您指定 `In-place update`，根據您在更新指令碼中提供的指示，只會將新的或變更的檔案新增至現有的安裝。應用程式在整個更新程序中仍然可用。已發佈 AWS的套件不支援 `In-place update`選項。 `Uninstall and reinstall`是預設值。  
類型：列舉  
有效值：`Uninstall and reinstall` \$1 `In-place update`  
必要：否

**additionalArguments**  
提供給安裝、解除安裝或更新指令碼的 JSON 字串格式的其他參數。每個參數必須加上字首 `SSM_`。通過使用慣例 `{{ssm:parameter-name}}`，您可以參考其他引數中的 Parameter Store 參數。若要在安裝、解除安裝或更新指令碼中使用其他參數，您必須使用適用於作業系統的語法，將參數作為環境變數參考。例如，在 PowerShell 中，將 `SSM_arg` 引數作為 `$Env:SSM_arg` 參考。您定義的引數數目沒有限制，但額外的引數輸入有 4096 個字元限制。此限制包括您定義的所有金鑰和值。  
類型：StringMap  
必要：否

**version**  
特定版本的套件安裝或解除安裝。如果安裝，系統預設會安裝最新發佈的版本。如果移除，系統預設移除目前已安裝的版本。如果沒有找到任何安裝的版本，執行下載和解除安裝最新版本的動作。  
類型：字串  
必要：否

## `aws:domainJoin`


將 EC2 執行個體加入網域。這個外掛程式可在 Linux 和 Windows Server 作業系統上執行。此外掛程式會將 Linux 執行個體的主機名稱變更為 EC2AMAZ-*XXXXXXX* 格式。如需加入 EC2 執行個體的詳細資訊，請參閱《 *AWS Directory Service 管理指南*》中的[將 EC2 執行個體加入您的 AWS Managed Microsoft AD Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_join_instance.html)。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:domainJoin
parameters:
  directoryId:
    description: "(Required) The ID of the directory."
    type: String
  directoryName:
    description: "(Required) The name of the domain."
    type: String
  directoryOU:
    description: "(Optional) The organizational unit to assign the computer object to."
    type: String
  dnsIpAddresses:
    description: "(Required) The IP addresses of the DNS servers for your directory."
    type: StringList
  hostname:
    description: "(Optional) The hostname you want to assign to the node."
    type: String
mainSteps:
- action: aws:domainJoin
  name: domainJoin
  inputs:
    directoryId: "{{ directoryId }}"
    directoryName: "{{ directoryName }}"
    directoryOU: "{{ directoryOU }}"
    dnsIpAddresses: "{{ dnsIpAddresses }}"
    hostname: "{{ hostname }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:domainJoin",
  "parameters": {
    "directoryId": {
      "description": "(Required) The ID of the directory.",
      "type": "String"
    },
    "directoryName": {
      "description": "(Required) The name of the domain.",
      "type": "String"
    },
    "directoryOU": {
        "description": "(Optional) The organizational unit to assign the computer object to.",
        "type": "String"
      },
    "dnsIpAddresses": {
      "description": "(Required) The IP addresses of the DNS servers for your directory.",
      "type": "StringList"
    },
    "hostname": {
        "description": "(Optional) The hostname you want to assign to the node.",
        "type": "String"
      }
  },
  "mainSteps": [
    {
      "action": "aws:domainJoin",
      "name": "domainJoin",
      "inputs": {
        "directoryId": "{{ directoryId }}",
        "directoryName": "{{ directoryName }}",
        "directoryOU":"{{ directoryOU }}",
        "dnsIpAddresses":"{{ dnsIpAddresses }}",
        "hostname":"{{ hostname }}"
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:domainJoin:
    properties:
      directoryId: "{{ directoryId }}"
      directoryName: "{{ directoryName }}"
      directoryOU: "{{ directoryOU }}"
      dnsIpAddresses: "{{ dnsIpAddresses }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:domainJoin":{
         "properties":{
            "directoryId":"{{ directoryId }}",
            "directoryName":"{{ directoryName }}",
            "directoryOU":"{{ directoryOU }}",
            "dnsIpAddresses":"{{ dnsIpAddresses }}"
         }
      }
   }
}
```

------

### Properties


**directoryId**  
目錄的 ID。  
類型：字串  
必要：是  
範例："directoryId": "d-1234567890"

**directoryName**  
網域的名稱。  
類型：字串  
必要：是  
範例："directoryName": "example.com"

**directoryOU**  
組織單位 (OU)。  
類型：字串  
必要：否  
範例："directoryOU": "OU=test,DC=example,DC=com"

**dnsIpAddresses**  
DNS 的 IP 地址。  
類型：StringList  
必要：是  
範例："dnsIpAddresses": ["198.51.100.1","198.51.100.2"]

**hostname**  
要指派給節點的主機名稱。如果未提供，則不會變更 Windows Server 執行個體的名稱，而 Linux 執行個體將使用預設命名模式。如果提供，Windows Server 執行個體將使用確切提供的值，而對於 Linux 執行個體，其作為字首 (除非 `keepHostName` 設定為 "true")。  
類型：字串  
必要：否

**keepHostName**  
確定在加入網域時是否變更 Linux 執行個體的主機名稱。這是僅限 Linux 的參數。依預設 (沒有對 `hostname`、`hostnameNumAppendDigits` 的輸入，而且 `keepHostName` 為 "false")，Linux 主機將被重新命名為模式 EC2AMAZ-XXXXXX。設定為 "true" 時，主機會保留原始主機名稱，並忽略對 `hostname` 和 `hostnameNumAppendDigits` 的輸入。  
類型：布林值  
必要：否

**hostnameNumAppendDigits**  
定義要在主機名稱值之後附加的隨機數字位數數量。這是僅限 Linux 的參數，並且可與 `hostname` 參數搭配使用。如果未提供 `hostname`，則會予以忽略。  
類型：字串  
允許的值：1 至 5  
必要：否

### 範例


如需範例，請參閱[AWS Managed Microsoft AD管理指南](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ec2-join-aws-domain.html)中的*將 Amazon EC2 執行個體加入您的AWS Directory Service *。

## `aws:downloadContent`


(結構描述 2.0 版本或更新版本) 從遠端位置下載 SSM 文件和指令碼。不支援 GitHub Enterprise 儲存庫。Linux 和 Windows Server 作業系統上支援此外掛程式。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:downloadContent
parameters:
  sourceType:
    description: "(Required) The download source."
    type: String
  sourceInfo:
    description: "(Required) The information required to retrieve the content from
      the required source."
    type: StringMap
mainSteps:
- action: aws:downloadContent
  name: downloadContent
  inputs:
    sourceType: "{{ sourceType }}"
    sourceInfo: "{{ sourceInfo }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:downloadContent",
  "parameters": {
    "sourceType": {
    "description": "(Required) The download source.",
    "type": "String"
  },
  "sourceInfo": {
    "description": "(Required) The information required to retrieve the content from the required source.",
    "type": "StringMap"
    }
  },
  "mainSteps": [
    {
      "action": "aws:downloadContent",
      "name": "downloadContent",
      "inputs": {
        "sourceType":"{{ sourceType }}",
        "sourceInfo":"{{ sourceInfo }}"
      }
    }
  ]
}
```

------

### 輸入


**sourceType**  
下載來源。Systems Manager 支援下列來源類型，用於下載指令碼和 SSM 文件：`GitHub`、`Git`、`HTTP`、`S3` 和 `SSMDocument`。  
類型：字串  
必要：是

**sourceInfo**  
從所需的來源中擷取所需的資訊內容。  
類型：StringMap  
必要：是  
 **對於來源類型 `GitHub,`，請指定以下資訊：**  
+ 擁有者：儲存庫擁有者。
+ 儲存庫: 儲存庫的名稱。
+ 路徑：您想要下載的檔案或目錄路徑。
+ getOptions：可從主要分支以外的分支或從儲存庫中的特定遞交中擷取內容的額外選項。如果您使用主要分支中的最新遞交，則可省略 getOptions。如果您的儲存庫是在 2020 年 10 月 1 日之後建立的，則預設分支可能被命名為 main 而不是 master。在此情況下，您需要指定 getOptions 參數的值。

  此參數使用以下的格式：
  + branch:refs/heads/*branch\$1name*

    預設值為 `master`。

    若要指定非預設分支，請使用以下格式：

    branch:refs/heads/*branch\$1name*
  + commitID：*commitID*

    預設值為 `head`。

    若要在最新遞交以外之其他遞交中使用您 SSM 文件的版本，請指定完整的遞交 ID。例如：

    ```
    "getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
    ```
+ tokenInfo：您存放 GitHub 存取權杖資訊所在的 Systems Manager 參數 (SecureString 參數)，格式為 `{{ssm-secure:secure-string-token-name}}`。
**注意**  
此 `tokenInfo` 欄位是唯一支援 SecureString 參數的 SSM 文件外掛程式欄位。其他欄位不支援 SecureString 參數，其他 SSM 文件外掛程式也不支援。

```
{
    "owner":"TestUser",
    "repository":"GitHubTest",
    "path":"scripts/python/test-script",
    "getOptions":"branch:master",
    "tokenInfo":"{{ssm-secure:secure-string-token}}"
}
```
 **對於來源類型 `Git`，您必須指定以下資訊：**  
+ repository

  您想要下載的檔案或目錄的 Git 存放庫 URL。

  類型：字串
此外，您還可以指定下列選用參數：  
+ getOptions

  可從主要分支以外的分支或從儲存庫中的特定遞交中擷取內容的額外選項。如果您使用主要分支中的最新遞交，則可省略 getOptions。

  類型：字串

  此參數使用以下的格式：
  + branch:refs/heads/*branch\$1name*

    預設值為 `master`。

    只有當 SSM 文件存放於 `master` 以外的分支時，才需要 `"branch"`。例如：

    ```
    "getOptions": "branch:refs/heads/main"
    ```
  + commitID：*commitID*

    預設值為 `head`。

    若要在最新遞交以外之其他遞交中使用您 SSM 文件的版本，請指定完整的遞交 ID。例如：

    ```
    "getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
    ```
+ privateSSHKey

  連線至您指定的 `repository` 時，要使用的 SSH 金鑰。您可以使用下列格式來參考 SSH 金鑰值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。

  類型：字串
+ skipHostKeyChecking

  連線至您指定的 `repository` 時，確定 StrictHostKeyChecking 選項的值。預設值為 `false`。

  類型：布林值
+ 使用者名稱

  使用 HTTP 連線至您指定的 `repository` 時，要使用的使用者名稱。您可以使用下列格式來參考使用者名稱值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。

  類型：字串
+ password

  使用 HTTP 連線至您指定的 `repository` 時，要使用的密碼。您可以使用下列格式來參考密碼值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。

  類型：字串
 **對於來源類型 `HTTP`，您必須指定以下資訊：**  
+ url

  您想要下載的檔案或目錄的 URL。

  類型：字串
此外，您還可以指定下列選用參數：  
+ allowInsecureDownload

  判斷是否可透過未使用 Secure Socket Layer (SSL) 或 Transport Layer Security (TLS) 進行加密的連線來執行下載。預設值為 `false`。不建議在未加密的情況下執行下載。如果您選擇這樣做，您應承擔所有相關風險。安全性是 AWS 與您之間的共同責任。這被描述為共同的責任模式。如需進一步了解，請參閱[共同的責任模型](https://aws.amazon.com/compliance/shared-responsibility-model/)。

  類型：布林值
+ authMethod

  當連線至您指定的 `url` 時，判斷是否要使用使用者名稱和密碼進行身分驗證。如果您指定 `Basic` 或 `Digest`，則必須提供 `username` 和 `password` 參數的值。若要使用 `Digest` 方法，必須在您的執行個體上安裝 SSM Agent 3.0.1181.0 版或更新版本。`Digest` 方法支援 MD5 和 SHA256 加密。

  類型：字串

  有效值：`None` \$1 `Basic` \$1 `Digest`
+ 使用者名稱

  使用 `Basic` 身分驗證連線至您指定的 `url` 時，要使用的使用者名稱。您可以使用下列格式來參考使用者名稱值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。

  類型：字串
+ password

  使用 `Basic` 身分驗證連線至您指定的 `url` 時，要使用的密碼。您可以使用下列格式來參考密碼值的 `SecureString` 參數：`{{ssm-secure:your-secure-string-parameter}}`。

  類型：字串
 **對於來源類型 `S3`，請指定以下資訊：**  
+ 路徑：您想要從 Amazon S3 中下載的檔案或目錄的 URL。
從 S3 儲存貯體下載檔案時，.etag 檔案會在下載目錄中產生。

```
{
    "path": "https://s3.amazonaws.com/amzn-s3-demo-bucket/powershell/helloPowershell.ps1" 
}
```
 **對於來源類型 `SSMDocument`，請指定下列其中*一項*：**  
+ 名稱：名稱和文件的版本，格式如下：`name:version`。版本是非必須的。

  ```
  {
      "name": "Example-RunPowerShellScript:3" 
  }
  ```
+ 名稱：文件的 ARN，格式如下：`arn:aws:ssm:region:account_id:document/document_name`

  ```
  {
     "name":"arn:aws:ssm:us-east-2:3344556677:document/MySharedDoc"
  }
  ```

**destinationPath**  
將您想要下載的檔案選用在的執行個體上的本機路徑。如果您不指定路徑的相對路徑，內容會下載到您的命令 ID 相對應的路徑。  
類型：字串  
必要：否

## `aws:psModule`


在 Amazon EC2 執行個體上安裝 PowerShell 模組。這個外掛程式只能在 Windows Server 作業系統上執行。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:psModule
parameters:
  source:
    description: "(Required) The URL or local path on the instance to the application
      .zip file."
    type: String
mainSteps:
- action: aws:psModule
  name: psModule
  inputs:
    source: "{{ source }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:psModule",
  "parameters": {
    "source": {
      "description": "(Required) The URL or local path on the instance to the application .zip file.",
      "type": "String"
    }
  },
  "mainSteps": [
    {
      "action": "aws:psModule",
      "name": "psModule",
      "inputs": {
        "source": "{{ source }}"
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:psModule:
    properties:
    - runCommand: "{{ commands }}"
      source: "{{ source }}"
      sourceHash: "{{ sourceHash }}"
      workingDirectory: "{{ workingDirectory }}"
      timeoutSeconds: "{{ executionTimeout }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:psModule":{
         "properties":[
            {
               "runCommand":"{{ commands }}",
               "source":"{{ source }}",
               "sourceHash":"{{ sourceHash }}",
               "workingDirectory":"{{ workingDirectory }}",
               "timeoutSeconds":"{{ executionTimeout }}"
            }
         ]
      }
   }
}
```

------

### Properties


**runCommand**  
在模組安裝完畢後，PowerShell 的命令來執行。  
類型：StringList  
必要：否

**source**  
在的執行個體上應用程式 `.zip` 檔案的本機路徑或 URL。  
類型：字串  
必要：是

**sourceHash**  
`.zip` 檔案的 SHA256 雜湊。  
類型：字串  
必要：否

**timeoutSeconds**  
在命令完成到被認定為失敗之間的秒數。  
類型：字串  
必要：否

**workingDirectory**  
在您的執行個體上的工作目錄路徑。  
類型：字串  
必要：否

## `aws:refreshAssociation`


(結構描述 2.0 版本或更新版本) 更新 (強制套用) 有需要的關聯。這個動作會根據選中的關聯或者全部與目標有聯結的關聯裡的定義來改變系統的狀態。這個外掛程式可在 Linux 和 Microsoft Windows Server 作業系統上執行。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:refreshAssociation
parameters:
  associationIds:
    description: "(Optional) List of association IDs. If empty, all associations bound
      to the specified target are applied."
    type: StringList
mainSteps:
- action: aws:refreshAssociation
  name: refreshAssociation
  inputs:
    associationIds:
    - "{{ associationIds }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:refreshAssociation",
  "parameters": {
    "associationIds": {
      "description": "(Optional) List of association IDs. If empty, all associations bound to the specified target are applied.",
      "type": "StringList"
    }
  },
  "mainSteps": [
    {
      "action": "aws:refreshAssociation",
      "name": "refreshAssociation",
      "inputs": {
        "associationIds": [
          "{{ associationIds }}"
        ]
      }
    }
  ]
}
```

------

### 輸入


**associationIds**  
列出的關聯 ID。如果空，所有綁定到指定的目標的關聯都會被套用。  
類型：StringList  
必要：否

## `aws:runDockerAction`


(結構描述 2.0 版本或更新版本) 在容器上執行 Docker 動作。這個外掛程式可在 Linux 和 Microsoft Windows Server 作業系統上執行。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
mainSteps:
- action: aws:runDockerAction
  name: RunDockerAction
  inputs:
    action: "{{ action }}"
    container: "{{ container }}"
    image: "{{ image }}"
    memory: "{{ memory }}"
    cpuShares: "{{ cpuShares }}"
    volume: "{{ volume }}"
    cmd: "{{ cmd }}"
    env: "{{ env }}"
    user: "{{ user }}"
    publish: "{{ publish }}"
    workingDirectory: "{{ workingDirectory }}"
    timeoutSeconds: "{{ timeoutSeconds }}"
```

------
#### [ JSON ]

```
{
   "mainSteps":[
      {
         "action":"aws:runDockerAction",
         "name":"RunDockerAction",
         "inputs":{
            "action":"{{ action }}",
            "container":"{{ container }}",
            "image":"{{ image }}",
            "memory":"{{ memory }}",
            "cpuShares":"{{ cpuShares }}",
            "volume":"{{ volume }}",
            "cmd":"{{ cmd }}",
            "env":"{{ env }}",
            "user":"{{ user }}",
            "publish":"{{ publish }}",
            "workingDirectory": "{{ workingDirectory }}",
            "timeoutSeconds": "{{ timeoutSeconds }}"
         }
      }
   ]
}
```

------

### 輸入


**動作**  
執行動作的類型。  
類型：字串  
必要：是

**容器**  
Docker 容器的 ID。  
類型：字串  
必要：否

**image**  
Docker 影像名稱  
類型：字串  
必要：否

**命令提示字元**  
容器指令  
類型：字串  
必要：否

**memory**  
容器記憶體限制。  
類型：字串  
必要：否

**cpuShares**  
CPU 容器共享 (相對重量)。  
類型：字串  
必要：否

**磁碟區**  
容器磁碟容量。  
類型：StringList  
必要：否

**env**  
容器的環境變數。  
類型：字串  
必要：否

**user**  
容器的使用者名稱。  
類型：字串  
必要：否

**發布**  
容器發佈的連接埠。  
類型：字串  
必要：否

**workingDirectory**  
您受管節點上的工作目錄路徑。  
類型：字串  
必要：否

**timeoutSeconds**  
在命令完成到被認定為失敗之間的秒數。  
類型：字串  
必要：否

## `aws:runDocument`


(結構描述 2.0 版本或更新版本) 執行存放在 Systems Manager 或在本機共用的 SSM 文件。您可以搭配使用此外掛程式與 [`aws:downloadContent`](#aws-downloadContent)外掛程式，將 SSM 文件從遠端位置下載到本機共用，然後執行它。Linux 和 Windows Server 作業系統上支援此外掛程式。此外掛程式不支援執行 `AWS-UpdateSSMAgent` 文件或任何使用 `aws:updateSsmAgent` 外掛程式的文件。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:runDocument
parameters:
  documentType:
    description: "(Required) The document type to run."
    type: String
    allowedValues:
    - LocalPath
    - SSMDocument
mainSteps:
- action: aws:runDocument
  name: runDocument
  inputs:
    documentType: "{{ documentType }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:runDocument",
  "parameters": {
    "documentType": {
      "description": "(Required) The document type to run.",
      "type": "String",
      "allowedValues": [
        "LocalPath",
        "SSMDocument"
      ]
    }
  },
  "mainSteps": [
    {
      "action": "aws:runDocument",
      "name": "runDocument",
      "inputs": {
        "documentType": "{{ documentType }}"
      }
    }
  ]
}
```

------

### 輸入


**documentType**  
執行的文件類型。您可以執行本機文件 (`LocalPath`) 或存放在 Systems Manager (`SSMDocument`) 的文件。  
類型：字串  
必要：是

**documentPath**  
文件的路徑。如果 `documentType` 是 `LocalPath`，請指定在本機共享的文件路徑。如果 `documentType` 是 `SSMDocument`，請指定文件的名稱。  
類型：字串  
必要：否

**documentParameters**  
文件的參數。  
類型：StringMap  
必要：否

## `aws:runPowerShellScript`


執行 PowerShell 指令碼或指定路徑來執行指令碼。這個外掛程式可在 Microsoft Windows Server 和 Linux 作業系統上執行。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:runPowerShellScript
parameters:
  commands:
    type: String
    description: "(Required) The commands to run or the path to an existing script
      on the instance."
    default: Write-Host "Hello World"
mainSteps:
- action: aws:runPowerShellScript
  name: runPowerShellScript
  inputs:
    timeoutSeconds: '60'
    runCommand:
    - "{{ commands }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:runPowerShellScript",
  "parameters": {
    "commands": {
      "type": "String",
      "description": "(Required) The commands to run or the path to an existing script on the instance.",
      "default": "Write-Host \"Hello World\""
    }
  },
  "mainSteps": [
    {
      "action": "aws:runPowerShellScript",
      "name": "runPowerShellScript",
      "inputs": {
        "timeoutSeconds": "60",
        "runCommand": [
          "{{ commands }}"
        ]
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:runPowerShellScript:
    properties:
    - id: 0.aws:runPowerShellScript
      runCommand: "{{ commands }}"
      workingDirectory: "{{ workingDirectory }}"
      timeoutSeconds: "{{ executionTimeout }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:runPowerShellScript":{
         "properties":[
            {
               "id":"0.aws:runPowerShellScript",
               "runCommand":"{{ commands }}",
               "workingDirectory":"{{ workingDirectory }}",
               "timeoutSeconds":"{{ executionTimeout }}"
            }
         ]
      }
   }
}
```

------

### Properties


**runCommand**  
指定命令或指定在執行個體上現有的指令碼的路徑來執行。  
類型：StringList  
必要：是

**timeoutSeconds**  
在命令完成到被認定為失敗之間的秒數。如果達到逾時，Systems Manager 停止命令執行。  
類型：字串  
必要：否

**workingDirectory**  
在您的執行個體上的工作目錄路徑。  
類型：字串  
必要：否

## `aws:runShellScript`


執行 Linux shell 指令碼或指定路徑來執行指令碼。這個外掛程式只可在 Linux 作業系統上執行。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:runShellScript
parameters:
  commands:
    type: String
    description: "(Required) The commands to run or the path to an existing script
      on the instance."
    default: echo Hello World
mainSteps:
- action: aws:runShellScript
  name: runShellScript
  inputs:
    timeoutSeconds: '60'
    runCommand:
    - "{{ commands }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:runShellScript",
  "parameters": {
    "commands": {
      "type": "String",
      "description": "(Required) The commands to run or the path to an existing script on the instance.",
      "default": "echo Hello World"
    }
  },
  "mainSteps": [
    {
      "action": "aws:runShellScript",
      "name": "runShellScript",
      "inputs": {
        "timeoutSeconds": "60",
        "runCommand": [
          "{{ commands }}"
        ]
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:runShellScript:
    properties:
    - runCommand: "{{ commands }}"
      workingDirectory: "{{ workingDirectory }}"
      timeoutSeconds: "{{ executionTimeout }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:runShellScript":{
         "properties":[
            {
               "runCommand":"{{ commands }}",
               "workingDirectory":"{{ workingDirectory }}",
               "timeoutSeconds":"{{ executionTimeout }}"
            }
         ]
      }
   }
}
```

------

### Properties


**runCommand**  
指定命令或指定在執行個體上現有的指令碼的路徑來執行。  
類型：StringList  
必要：是

**timeoutSeconds**  
在命令完成到被認定為失敗之間的秒數。如果達到逾時，Systems Manager 停止命令執行。  
類型：字串  
必要：否

**workingDirectory**  
在您的執行個體上的工作目錄路徑。  
類型：字串  
必要：否

## `aws:softwareInventory`


(結構描述 2.0 版本或更新版本) 在受管執行個體上收集與應用程式、檔案和組態相關的中繼資料。這個外掛程式可在 Linux 和 Microsoft Windows Server 作業系統上執行。當您設定清查集合時，請先建立 AWS Systems Manager State Manager關聯。Systems Manager 會在執行關聯時收集庫存資料。如果沒有先建立關聯，則當您試圖叫用 `aws:softwareInventory` 外掛程式時，系統會傳回以下錯誤：

```
The aws:softwareInventory plugin can only be invoked via ssm-associate.
```

執行個體一次只能設定一個庫存關聯。若您為執行個體設定兩個以上的關聯，庫存關聯便不會執行，並且也不會收集任何庫存資料。如需收集庫存的相關資訊，請參閱 [AWS Systems Manager庫存](systems-manager-inventory.md)。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
mainSteps:
- action: aws:softwareInventory
  name: collectSoftwareInventoryItems
  inputs:
    applications: "{{ applications }}"
    awsComponents: "{{ awsComponents }}"
    networkConfig: "{{ networkConfig }}"
    files: "{{ files }}"
    services: "{{ services }}"
    windowsRoles: "{{ windowsRoles }}"
    windowsRegistry: "{{ windowsRegistry}}"
    windowsUpdates: "{{ windowsUpdates }}"
    instanceDetailedInformation: "{{ instanceDetailedInformation }}"
    customInventory: "{{ customInventory }}"
```

------
#### [ JSON ]

```
{
   "mainSteps":[
      {
         "action":"aws:softwareInventory",
         "name":"collectSoftwareInventoryItems",
         "inputs":{
            "applications":"{{ applications }}",
            "awsComponents":"{{ awsComponents }}",
            "networkConfig":"{{ networkConfig }}",
            "files":"{{ files }}",
            "services":"{{ services }}",
            "windowsRoles":"{{ windowsRoles }}",
            "windowsRegistry":"{{ windowsRegistry}}",
            "windowsUpdates":"{{ windowsUpdates }}",
            "instanceDetailedInformation":"{{ instanceDetailedInformation }}",
            "customInventory":"{{ customInventory }}"
         }
      }
   ]
}
```

------

### 輸入


**應用程式**  
(選用) 收集已安裝應用程式的中繼資料。  
類型：字串  
必要：否

**awsComponents**  
（選用） 收集 amazon-ssm-agent 等 AWS 元件的中繼資料。  
類型：字串  
必要：否

**files**  
(選用，需要 SSM Agent 2.2.64.0 版或更新版本) 收集檔案的中繼資料，包括檔案名稱、檔案的建立時間、上次修改和存取檔案的時間以及檔案大小等。如需收集檔案庫存的相關資訊，請參閱 [使用檔案與 Windows 登錄檔清查](inventory-file-and-registry.md)。  
類型：字串  
必要：否

**networkConfig**  
(選用) 收集網路組態的中繼資料。  
類型：字串  
必要：否

**billingInfo**  
(選用) 收集與 AMI 帳單代碼相關聯的平台詳細資訊中繼資料。  
類型：字串  
必要：否

**windowsUpdates**  
(選用) 收集所有 Windows 更新的中繼資料。  
類型：字串  
必要：否

**instanceDetailedInformation**  
(選用) 收集的執行個體資訊比預設庫存外掛程式 (`aws:instanceInformation`) 提供的更多，包括 CPU 模型、速度和核心數量等。  
類型：字串  
必要：否

**services**  
(選用，僅 Windows 作業系統需要 SSM Agent 2.2.64.0 版或更新版本) 收集服務組態的中繼資料。  
類型：字串  
必要：否

**windowsRegistry**  
(選用，僅 Windows 作業系統需要 SSM Agent 2.2.64.0 版或更新版本) 收集 Windows 登錄機碼和值。而且，您還能選擇機碼路徑，並以遞迴方式收集所有機碼和值。此外，您也可以收集指定路徑的特定登錄機碼及其值。庫存將收集機碼路徑、名稱、類型與值。如需收集 Windows 登錄檔庫存的詳細資訊，請參閱 [使用檔案與 Windows 登錄檔清查](inventory-file-and-registry.md)。  
類型：字串  
必要：否

**windowsRoles**  
(選用，僅 Windows 作業系統需要 SSM Agent 2.2.64.0 版或更新版本) 收集適用於 Microsoft Windows 角色組態的中繼資料。  
類型：字串  
必要：否

**customInventory**  
(選用) 收集自訂庫存資料。如需自訂庫存的詳細資訊，請參閱[使用自訂庫存](inventory-custom.md)。  
類型：字串  
必要：否

**customInventoryDirectory**  
(選用) 從指定的目錄中收集自訂庫存資料。如需自訂庫存的詳細資訊，請參閱[使用自訂庫存](inventory-custom.md)。  
類型：字串  
必要：否

## `aws:updateAgent`


更新 EC2Config 服務到最新版本或指定 EC2Config 服務的舊版本。這個外掛程式只能在 Microsoft Windows Server 作業系統上執行。如需有關 EC2Config 服務的詳細資訊，請參閱《Amazon EC2 使用者指南》**中的 [Configuring a Windows Instance using the EC2Config service (legacy)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-service.html)。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:updateAgent
mainSteps:
- action: aws:updateAgent
  name: updateAgent
  inputs:
    agentName: Ec2Config
    source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:updateAgent",
  "mainSteps": [
    {
      "action": "aws:updateAgent",
      "name": "updateAgent",
      "inputs": {
        "agentName": "Ec2Config",
        "source": "https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json"
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:updateAgent:
    properties:
      agentName: Ec2Config
      source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
      allowDowngrade: "{{ allowDowngrade }}"
      targetVersion: "{{ version }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:updateAgent":{
         "properties":{
            "agentName":"Ec2Config",
            "source":"https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json",
            "allowDowngrade":"{{ allowDowngrade }}",
            "targetVersion":"{{ version }}"
         }
      }
   }
}
```

------

### Properties


**agentName**  
EC2Config。這是執行 EC2Config 服務的代理名稱。  
類型：字串  
必要：是

**allowDowngrade**  
允許 EC2Config 服務降級到較舊的版本。如果設定為非，該服務只可以升級到較新版本 (預設)。如果設定為是，指定之前的舊版本。  
類型：布林值  
必要：否

**source**  
Systems Manager 複製 EC2Config 版本進行安裝的位置。您無法變更此位置。  
類型：字串  
必要：是

**targetVersion**  
安裝指定版本的 EC2Config 服務。如果未指定，服務會更新到最新版本。  
類型：字串  
必要：否

## `aws:updateSsmAgent`


將 SSM Agent 更新到最新版本或指定舊版本。這個外掛程式可在 Linux 和 Windows Server 作業系統上執行。如需詳細資訊，請參閱[使用 SSM Agent](ssm-agent.md)。

### 語法


#### 結構描述 2.2


------
#### [ YAML ]

```
---
schemaVersion: '2.2'
description: aws:updateSsmAgent
parameters:
  allowDowngrade:
    default: 'false'
    description: "(Optional) Allow the Amazon SSM Agent service to be downgraded to
      an earlier version. If set to false, the service can be upgraded to newer versions
      only (default). If set to true, specify the earlier version."
    type: String
    allowedValues:
    - 'true'
    - 'false'
mainSteps:
- action: aws:updateSsmAgent
  name: updateSSMAgent
  inputs:
    agentName: amazon-ssm-agent
    source: https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json
    allowDowngrade: "{{ allowDowngrade }}"
```

------
#### [ JSON ]

```
{
  "schemaVersion": "2.2",
  "description": "aws:updateSsmAgent",
  "parameters": {
    "allowDowngrade": {
      "default": "false",
      "description": "(Required) Allow the Amazon SSM Agent service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version.",
      "type": "String",
      "allowedValues": [
        "true",
        "false"
      ]
    }
  },
  "mainSteps": [
    {
      "action": "aws:updateSsmAgent",
      "name": "awsupdateSsmAgent",
      "inputs": {
        "agentName": "amazon-ssm-agent",
        "source": "https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json",
        "allowDowngrade": "{{ allowDowngrade }}"
      }
    }
  ]
}
```

------

#### 結構描述 1.2


------
#### [ YAML ]

```
---
runtimeConfig:
  aws:updateSsmAgent:
    properties:
    - agentName: amazon-ssm-agent
      source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
      allowDowngrade: "{{ allowDowngrade }}"
```

------
#### [ JSON ]

```
{
   "runtimeConfig":{
      "aws:updateSsmAgent":{
         "properties":[
            {
               "agentName":"amazon-ssm-agent",
               "source":"https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json",
               "allowDowngrade":"{{ allowDowngrade }}"
            }
         ]
      }
   }
}
```

------

### Properties


**agentName**  
amazon-ssm-agent。這是在執行個體上處理請求和執行命令的 Systems Manager 代理程式名稱。  
類型：字串  
必要：是

**allowDowngrade**  
允許 SSM Agent 降級到較早的版本。如果設定為非，代理程式只可以升級到較新版本 (預設)。如果設定為是，指定之前的舊版本。  
類型：布林值  
必要：是

**source**  
Systems Manager 複製 SSM Agent 版本進行安裝的位置。您無法變更此位置。  
類型：字串  
必要：是

**targetVersion**  
指定安裝 SSM Agent 的版本。如果未指定，代理程式會更新到最新版本。  
類型：字串  
必要：否