本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
結構描述、功能以及範例
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件指定不同的操作系統。跨平台支援使用 |
注意
您必須使 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文件的輸入參數，並platformType使用LinuxMacOS、和的值Windows。只支援 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文件中看到 precondition 參數的範例。
結構描述版本 2.2
頂層元素
下列範例顯示使用結構描述 2.2 版之SSM文件的頂層元素。
結構描述版本 2.2 範例
下列範例會使用aws:runPowerShellScript外掛程式在目標執行個體上執行 PowerShell 命令。
結構描述版本 2.2 precondition 參數範例
結構描述版本 2.2 提供跨平台支援。這意味著在單個SSM文檔中，您可以為不同的插件指定不同的操作系統。跨平台支援在步驟中使用 precondition 參數，如下所示。您也可以使用precondition參數來驗證您在SSM文件中定義的輸入參數。您可以在以下第二個範例中看到它。
結構描述版本 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-RunShellScriptSSM文檔。該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 自動化工作流程簿的頂層元素。
{ "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自動化手冊示例
下列範例以YAML格式顯示自動化工作流程簿的內容。文件結構描述的這份 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/amzn-ami-hvm-x86_64-gp2 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}' 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.8 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.8 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
