本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
結構描述、功能以及範例
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文件結構描述的詳細資訊，請參閱工作階段文件結構描述。
Command 和 Policy 文件使用最新的結構描述版本，您可以善用以下功能。
| 功能 | 詳細資訊 |
|---|---|
|
文件編輯 |
文件現在可以進行更新。在版本 1.2 中，您需要將文件中任何更新儲存為不同名稱的文件。 |
|
自動版本控制 |
文件中任何更新建立新的版本。這並非結構描述的版本，而是文件的版本。 |
|
預設版本 |
如果您有多個版本的文件，您可以指定哪個版本為預設的文件。 |
|
定序 |
文件中中的外掛程式或步驟將按照您所指定的順序執行。 |
|
跨平台支援 |
跨平台支援允許您在相同的 SSM 文件中為不同的外掛程式指定不同的作業系統。跨平台支援使用 |
| 參數插補 | 插補表示將變數值插入或替換為字串。將其視為在使用字串前，使用實際值填入空格。在 SSM 文件環境中，參數插補允許字串參數在命令執行之前，插入到環境變數中，提供更高安全性以防止命令注入。設定為 |
注意
您必須將執行個體上的 AWS Systems Manager SSM Agent 更新為最新版本，才能使用新的 Systems Manager 功能和 SSM 文件功能。如需詳細資訊，請參閱使用 Run Command 更新 SSM Agent。
下表列出了主要的結構描述各版本的差異。
| 第 1.2 版 | 版本 2.2 (最新版本) | 詳細資訊 |
|---|---|---|
|
runtimeConfig |
mainSteps |
在版本 2.2 中， |
|
屬性 |
inputs |
在版本 2.2 中， |
|
commands |
runCommand |
在版本 2.2 中， |
|
id |
動作 |
在版本 2.2 中， |
|
不適用 |
name |
在版本 2.2 中， |
使用 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 文件上層元素。
結構描述版本 2.2 範例
下列範例會使用 aws:runPowerShellScript 外掛程式在目標執行個體上執行 PowerShell 命令。
結構描述版本 2.2 precondition 參數範例
結構描述版本 2.2 提供跨平台支援。這表示您可以在同一個 SSM 文件中為不同的外掛程式指定不同的作業系統。跨平台支援在步驟中使用 precondition 參數，如下所示。您也可以使用 precondition 參數來驗證您在 SSM 文件中定義的輸入參數。您可以在以下第二個範例中看到它。
具有 3.3.2746.0 之前 SSM Agent 版本的結構描述 2.2 版插補範例
在 3.3.2746.0 之前的 SSM Agent 版本上，Agent 會忽略 interpolationType 參數，並改為執行原始字串替換。如果您明確參考 SSM_，則必須明確設定此項目。在下列的 Linux 範例中，明確參考了 parameter-nameSSM_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 會重新執行此文件。
結構描述版本 2.2 庫存範例
您可以搭配使用以下 SSM 文件與 State Manager，收集有關執行個體的庫存中繼資料。
結構描述版本 2.2 AWS-ConfigureAWSPackage 範例
以下範例顯示 AWS-ConfigureAWSPackage 文件。mainSteps 區段包含 action 步驟中的 aws:configurePackage 外掛程式。
注意
在 Linux 作業系統上，只有支援 AmazonCloudWatchAgent 和 AWSSupport-EC2Rescue 的套件。
結構描述版本 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：{{ }}
以編譯語言使用參數
此範例示範在 Python 中安全處理參數：
回溯相容性範例
此範例說明如何安全地處理參數，同時保持回溯相容性：
注意
在不使用雙括號的 SSM 文件中，技術上不需要 allowedPattern：{{ }}
參數安全最佳實務
處理 SSM 文件中的參數時，請遵循下列最佳實務：
-
使用環境變數插補 – 一律將
interpolationType: "ENV_VAR"用於在命令執行中使用的字串參數。 -
實作輸入驗證 – 使用
allowedPattern，將參數值限制為安全模式。 -
處理舊式系統 – 包含不支援環境變數插補之舊版 SSM Agent 的備用邏輯。
-
逸出特殊字元 – 在命令中使用參數值時，請正確逸出特殊字元，以防止 shell 解譯。
-
限制參數範圍 – 為您的使用案例使用最嚴格的參數模式。
