• Amazon Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# Amazon Systems Manager 文档
Amazon Systems Manager 文档 (SSM document) 定义 Systems Manager 对您的托管实例执行的操作。Systems Manager 包括 100 个预先配置的文档，您可以在运行时通过指定参数进行使用。您可以在 Systems Manager 文档控制台中找到预配置的文档，方法是选择 **Owned by Amazon**（Amazon 所有）选项卡，或者通过在调用 `ListDocuments` API 操作时指定 Amazon `Owner` 筛选条件。文档使用 JavaScript 对象表示法 (JSON) 或 YAML，并包括您指定的步骤和参数。
为增强安全性，从 2025 年 7 月 14 日起，SSM 文档在处理参数时支持环境变量插值。此功能在 2.2 版架构和 3.3.2746.0 或更高版本的 SSM Agent 中可用，可帮助防范命令注入攻击。
要开始使用 SSM 文档，请打开 [Systems Manager 控制台](https://console.amazonaws.cn/systems-manager/documents)。在导航窗格中，选择**文档**。
**重要**
在 Systems Manager 中，*Amazon 拥有的* SSM 文档是由 Amazon Web Services 自己创建和管理的文档。*Amazon 拥有的*文档在文档名称中包含 `AWS-*` 之类的前缀。文档的所有者被视为 Amazon，而不是 Amazon 内的特定用户账户。这些文档可供所有人公开使用。
## 我的组织如何从 Documents 工具获益？
Documents（Amazon Systems Manager 中的一项工具）具有以下优点：
+ **文档类别**
为了帮助您找到所需的文档，请根据要搜索的文档类型选择一个类别。要扩大搜索范围，您可以选择同一文档类型的多个类别。不支持选择不同文档类型的类别。分类仅支持 Amazon 拥有的文档。
+ **文档版本**
您可以创建并保存不同版本的文档。您可以为每个文档指定默认版本。文档的默认版本可以更新到较新版本或恢复到较旧版本。当您更改文档的内容时，Systems Manager 将自动递增文档的版本。您可以通过在控制台、Amazon Command Line Interface (Amazon CLI) 命令或 API 调用中指定文档版本来检索或使用任何版本的文档。
+ **根据您的需求自定义文档**
如果您要通过文档自定义步骤和操作，可以自行创建文档。系统将文档与您的 Amazon Web Services 账户 一起存储在创建其所在的 Amazon Web Services 区域 中。有关如何创建 SSM 文档的更多信息，请参阅 [创建 SSM 文档内容](documents-creating-content.md)。
+ **标记文档**
您可以标记文档，以便根据为其分配的标签快速识别一个或多个文档。例如，您可以为特定环境、部门、用户、组或时间段的文档添加标签。此外，您还可以通过创建一个指定用户或组可访问的标签的 Amazon Identity and Access Management (IAM) policy 来限制对文档的访问。
+ **共享文档**
您可以将文档公开，或者将它们与同一 Amazon Web Services 区域 区域中的特定 Amazon Web Services 账户 共享。在账户之间共享文档可能很有用，例如，如果您希望提供给客户或员工的所有 Amazon Elastic Compute Cloud (Amazon EC2) 实例都能够具有相同配置。除了保持实例上的应用程序或补丁的最新状态，您可能还希望限制客户实例执行某些活动。或者，您可能需要确保整个组织的员工账户使用的实例均被授予访问特定内部资源的访问权限。有关更多信息，请参阅 [共享 SSM 文档](documents-ssm-sharing.md)。
## 谁应该使用文档？
+ 任何希望使用 Systems Manager 工具大规模提高其运营效率、减少与手动干预相关的错误以及缩短解决常见问题的时间的 Amazon 客户。
+ 希望自动执行部署和配置任务的基础设施专家。
+ 想要可靠地解决常见问题、提高故障排除效率和减少重复性操作的管理员。
+ 想要自动执行通常需要手动执行的任务的用户。
## SSM 文档有哪些类型？
下表介绍了不同类型的 SSM 文档及其使用。
****
| Type | 一起使用 | Details |
| --- | --- | --- |
| ApplicationConfiguration ApplicationConfigurationSchema | [Amazon AppConfig](https://docs.amazonaws.cn/appconfig/latest/userguide/what-is-appconfig.html) | Amazon AppConfig 是 Amazon Systems Manager 中的一项工具，可让您创建、管理以及快速部署应用程序配置。您可以通过创建使用 `ApplicationConfiguration` 文档类型的文档，从而将配置数据存储到 SSM 文档中。有关更多信息，请参阅《Amazon AppConfig 用户指南》**中的[自由度配置](https://docs.amazonaws.cn/appconfig/latest/userguide/appconfig-creating-configuration-and-profile.html#free-form-configurations)。 如果在 SSM 文档中创建配置，则必须指定对应的 JSON Schema。该 schema 使用 `ApplicationConfigurationSchema` 文档类型，并且与一组规则类似，它会定义每个应用程序配置设置允许的属性。有关更多信息，请参阅《Amazon AppConfig 用户指南》**中的[关于验证器](https://docs.amazonaws.cn/appconfig/latest/userguide/appconfig-creating-configuration-and-profile-validators.html)。 |
| 自动化运行手册 | [自动化](systems-manager-automation.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | 在执行常规维护和部署任务 – 如创建或更新 Amazon Machine Image (AMI)时使用自动化手册 - 使用自动化运行手册。State Manager 使用自动化运行手册应用配置。这些操作可以在实例生命周期内的任何时刻在一个或多个目标上运行。Maintenance Windows 使用自动化运行手册基于指定的计划执行常规维护和部署任务。 macOS 的 EC2 实例也支持基于 Linux 的操作系统支持的所有自动化运行手册。 |
| 更改日历文档 | [Change Calendar](systems-manager-change-calendar.md) | Change Calendar 是 Amazon Systems Manager 中的一项工具，使用 `ChangeCalendar` 文档类型。Change Calendar 文档存储日历条目和关联的事件，这些事件可以允许或阻止自动化操作更改您的环境。在 Change Calendar 中，文档以明文格式存储 [iCalendar 2.0](https://icalendar.org/) 数据。 Change Calendar 在 EC2 实例上不支持 macOS。 |
| Amazon CloudFormation 模板 | [Amazon CloudFormation](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/Welcome.html) | Amazon CloudFormation 模板描述您要在 CloudFormation 堆栈中调配的资源。通过将 CloudFormation 模板存储为 Systems Manager 文档，您可以受益于 Systems Manager 文档功能。其中包括创建和比较模板的多个版本，以及与同一 Amazon Web Services 区域 中的其它账号共享模板。 您可以使用 Application Manager（Systems Manager 中的一项工具）创建和编辑 CloudFormation 模板及堆栈。有关更多信息，请参阅 [在 Application Manager 中使用 Amazon CloudFormation 模板和堆栈](application-manager-working-stacks.md)。 |
| 命令文档 | [Run Command](run-command.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | Run Command 是 Amazon Systems Manager 中的一项工具，使用命令文档运行命令。State Manager是 Amazon Systems Manager 中的一项工具，使用命令文档应用配置。这些操作可以在实例生命周期内的任何时刻在一个或多个目标上运行。Maintenance Windows 是 Amazon Systems Manager 中的一项工具，使用命令文档基于指定的计划应用配置。 大多数命令文档在所有 Linux 和 Systems Manager 所支持的 Windows Server 操作系统上受支持。macOS 的 EC2 实例支持以下命令文档： [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/systems-manager/latest/userguide/documents.html) |
| Amazon Config 一致性包模板 | [Amazon Config](https://docs.amazonaws.cn/config/latest/developerguide/WhatIsConfig.html) | Amazon Config 一致性包模板是 YAML 格式的文档，用于创建包含 Amazon Config 规则（托管或自定义）和修复操作列表的一致性包。 有关更多信息，请参阅[一致性包](https://docs.amazonaws.cn/config/latest/developerguide/conformance-packs.html)。 |
| 软件包文档 | [Distributor](distributor.md) | 在 Distributor（Amazon Systems Manager 中的一项工具）中，软件包用 SSM 文档表示。软件包文档包括附加的 ZIP 存档文件，其中包含要在托管实例上安装的软件或资产。在 Distributor 中创建软件包会创建软件包文档。 Oracle Linux 和 macOS 托管实例上不受支持 Distributor。 |
| 策略文档 | [State Manager](systems-manager-state.md) | Inventory 是 Amazon Systems Manager 中的一项工具，使用 `AWS-GatherSoftwareInventory` 策略文档和State Manager关联从托管式实例中收集清单数据。在创建您自己的 SSM 文档时，自动化文档和命令文档是在托管实例上实施策略的首选方法。 Systems Manager 清单和 `AWS-GatherSoftwareInventory` 策略文档在 Systems Manager 所支持的所有操作系统上均受支持。 |
| 事件后分析模板 | [Incident Manager 事件后分析](https://docs.amazonaws.cn/incident-manager/latest/userguide/analysis.html) | Incident Manager 使用事件后分析模板基于 Amazon 运营管理最佳实践创建分析。 使用模板创建分析，您的团队可以使用该分析来了解如何改进事件响应。 |
| 会话文档 | [Session Manager](session-manager.md) | Session Manager 是 Amazon Systems Manager 中的一项工具，使用会话文档确定要启动哪些类型的会话，例如端口转发会话、运行交互式命令的会话或创建 SSH 隧道的会话。 Systems Manager 支持的所有 Linux 和 Windows Server 操作系统都支持会话文档。macOS 的 EC2 实例支持以下命令文档： [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/systems-manager/latest/userguide/documents.html) |
**SSM 文档配额**
有关 SSM 服务配额的更多信息，请参阅《Amazon Web Services 一般参考》**中的 [Systems Manager Service Quotas](https://docs.amazonaws.cn/general/latest/gr/ssm.html#limits_ssm)。
**Topics**
+ [
## 我的组织如何从 Documents 工具获益？
](#ssm-docs-benefits)
+ [
## 谁应该使用文档？
](#documents-who)
+ [
## SSM 文档有哪些类型？
](#what-are-document-types)
+ [
# 文档组件
](documents-components.md)
+ [
# 创建 SSM 文档内容
](documents-creating-content.md)
+ [
# 使用文档
](documents-using.md)
+ [
# 参数处理问题的疑难解答
](parameter-troubleshooting.md)
# 文档组件
本部分包含有关构成 SSM 文档的组件的信息。
**Topics**
+ [
# 架构、功能和示例
](documents-schemas-features.md)
+ [
# 数据元素和参数
](documents-syntax-data-elements-parameters.md)
+ [
# 命令文档插件参考
](documents-command-ssm-plugin-reference.md)
# 架构、功能和示例
Amazon 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 版架构文档功能**
| 功能 | Details |
| --- | --- |
| 编辑文档 | 文档现在可以更新。如果版本为 1.2，对文档的任何更新都需要另存为其他名称。 |
| 自动版本控制 | 对文档的任何更新都会创建一个新版本。这不是架构版本，而是文档版本。 |
| 默认版本 | 如果您拥有某个文档的多个版本，可以指定哪个版本是默认文档。 |
| 顺序 | 文档中的插件或*步骤*按指定的顺序运行。 |
| 跨平台支持 | 跨平台支持可让您为同一个 SSM 文档中的不同插件指定不同操作系统。跨平台支持在某个步骤中使用 `precondition` 参数。 |
| 参数插值 | 插值是指将变量值插入或替换到字符串中。可以将其想象为在使用字符串之前用实际值填充空白。在 SSM 文档上下文中，参数插值允许在执行命令之前将字符串参数插值到环境变量中，从而更好地防范命令注入攻击。设置为 `ENV_VAR` 时，代理会创建一个包含参数值的环境变量 `SSM_parameter-name`。 |
**注意**
您必须将实例上的 Amazon Systems Manager SSM Agent 更新到最新版本才能使用新的 Systems Manager 功能和 SSM 文档功能。有关更多信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
下表列出了主要架构版本之间的区别。
****
| 版本 1.2 | 版本 2.2（最新版本） | Details |
| --- | --- | --- |
| runtimeConfig | mainSteps | 在版本 2.2 中，`mainSteps` 部分替换了 `runtimeConfig` 部分。这些区域有：`mainSteps` 部分允许 Systems Manager 按顺序运行步骤。 |
| 属性 | 输入 | 在版本 2.2 中，`inputs` 部分替换了 `properties` 部分。`inputs` 部分接受步骤参数。 |
| 命令 | runCommand | 在版本 2.2 中，`inputs` 部分接收 `runCommand` 参数，而不是 `commands` 参数。 |
| id | action | 在版本 2.2 中，`Action` 替换了 `ID`。这只是更改了名称。 |
| 不适用 | 名称 | 在版本 2.2 中，`name` 是用户定义的任意步骤名称。 |
**使用前提条件参数**
在 2.2 版或更高版本架构中，您可以使用 `precondition` 参数为每个插件指定目标操作系统验证您在 SSM 文档中定义的输入参数。`precondition` 参数支持引用 SSM 文档的输入参数，`platformType` 使用`Linux` 的值、`MacOS`,和 `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 文档中使用前提条件参数的示例。
## 架构版本 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 前提条件参数示例**
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"
]
}
}
]
}
```
------
**2.2 版架构插值示例（3.3.2746.0 之前的 SSM Agent 版本）**
在 3.3.2746.0 之前的 SSM 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 Amazon 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 Amazon 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`部分包括`aws:configurePackage`插件`action`步骤。
**注意**
在 Linux 操作系统上，仅支持 `AmazonCloudWatchAgent` 和 `AWSSupport-EC2Rescue` 软件包。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an Amazon
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 Amazon 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 版自动化运行手册的顶级元素。
```
{
"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/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 或更高版本。自动化运行手册使用架构版本 0.3。此外，自动化运行手册还支持使用 Markdown（一种标记语言），它允许您为文档和文档中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的详细信息，请参阅*《Amazon Web Services 管理控制台 入门指南》*中的[在控制台中使用 Markdown](https://docs.amazonaws.cn/general/latest/gr/aws-markdown.html)。
以下部分介绍了 SSM 文档中可以包含的数据元素。
## 顶级数据元素
**schemaVersion**
要使用的架构版本。
类型：版本
是否必需：是
**描述**
您提供的描述文档目的的信息。您还可以使用此字段来指定参数是否需要一个值才能运行文档，或者为参数提供值是否为可选项。可在本主题的所有示例中查看必需参数和可选参数。
类型：字符串
必需：否
**参数**
定义文档接受的参数的结构。
为增强处理字符串参数的安全性，可通过指定 `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（Amazon 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 的更多信息，请参阅 [Amazon Systems Manager Parameter Store](systems-manager-parameter-store.md)。
类型：结构
`parameters` 结构接受以下字段和值：
+ `type`：(必需) 允许的值包括：`String`、`StringList`、`Integer`、`Boolean`、`MapList` 和 `StringMap`。要查看每种类型的示例，请参阅下一节中的 [文档参数 `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` 验证。第一次验证是在您使用文档时利用 [Java 正则表达式库](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)在 API 级别进行。第二次验证是在处理文档之前通过使用 [GO 正则表达式库](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`：（可选）用于在 Amazon Web Services 管理控制台 中显示 `textfield` 或 `textarea`。`textfield` 是单行文本框。`textarea` 是多行文本区域。
+ `minItems`：(可选) 允许的最小项目数。
+ `maxItems`：(可选) 允许的最大项目数。
+ `minChars`：(可选) 允许的最小参数字符数。
+ `maxChars`：(可选) 允许的最大参数字符数。
+ `interpolationType`：（可选）定义在执行命令之前如何处理参数值。如果设置为 `ENV_VAR`，则可以将参数值用作名为 `SSM_parameter-name` 的环境变量。此功能通过将参数值视为文字字符串，从而帮助防范命令注入攻击。
类型：字符串
有效值：`ENV_VAR`
必需：否
**变量**
（仅限架构版本 0.3）您可以在自动化运行手册的整个步骤中引用或更新的值。变量与参数类似，但在重要方面有所区别。参数值在运行手册的上下文中是静态的，但是变量的值可以在运行手册的上下文中更改。更新变量的值时，数据类型必须与定义的数据类型相匹配。有关更新自动化中的变量值的信息，请参阅 [`aws:updateVariable` – 更新运行手册变量的值](automation-action-update-variable.md)
类型：Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
必需：否
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(仅限 1.2 版架构) 由一个或多个 Systems Manager 插件应用的实例的配置。不保证插件按顺序运行。
类型：Dictionary
必需：否
**mainSteps**
（仅架构版本 0.3、2.0 和 2.2）可以包含多个步骤（插件）的对象。插件在步骤内定义。步骤按文档中列出的先后顺序运行。
类型：Dictionary
是否必需：是
**输出**
（仅架构版本 0.3）通过执行本文档而生成的可用于其他进程的数据。例如，如果文档创建新的 AMI，您可以指定 “CreateImage.ImageId” 作为输出值，然后使用该输出以在后续自动化执行中创建新的实例。有关输出的更多信息，请参阅 [使用操作输出作为输入](automation-action-outputs-inputs.md)。
类型：Dictionary
必需：否
**文件**
（仅架构版本 0.3）附加到文档并在自动化执行期间运行的脚本文件（及其校验和）。仅适用于包含 `aws:executeScript` 操作且已在一个或多个步骤中指定附件的文档。
要了解自动化运行手册支持的运行时，请参阅 [`aws:executeScript` - 运行脚本](automation-action-executeScript.md)。有关在自动化运行手册中包含脚本的更多信息，请参阅 [在运行手册中使用脚本](automation-document-script-considerations.md) 和 [自动化运行手册的视觉对象设计体验](automation-visual-designer.md)。
使用附件创建自动化运行手册时，可以使用 `--attachments` 选项（对于 Amazon CLI）或 `Attachments`（对于 API 和开发工具包）指定附件文件。您可以为存储在 Amazon Simple Storage Service（Amazon S3）存储桶中的 SSM 文档和文件指定文件位置。有关更多信息，请参阅 Amazon Systems Manager API 参考中的[附件](https://docs.amazonaws.cn/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
必需：否
## 文档参数 `type` 示例
SSM 文档中的参数类型是静态的。这意味着参数类型在定义后无法更改。将参数用于 SSM 文档插件时，不能在插件的输入中动态更改参数的类型。例如，您不能在 `aws:runShellScript` 插件的 `runCommand` 输入中引用 `Integer` 参数，因为此输入接受字符串或字符串列表。要将参数用于插件输入，参数类型必须与接受的类型匹配。例如，您必须为`aws:updateSsmAgent` 插件的 `allowDowngrade` 输入指定 `Boolean` 类型参数。如果参数类型与插件的输入类型不匹配，则 SSM 文档无法验证，并且系统不会创建文档。在其他插件或 Amazon Systems Manager 自动化操作的输入中使用下游参数时也是如此。例如，您不能引用 `aws:runDocument` 插件的 `documentParameters` 输入内的 `StringList` 参数。`documentParameters` 输入接受字符串映射，即使下游 SSM 文档参数类型是 `StringList` 参数并与您要引用的参数匹配。
将参数用于自动化操作时，大多数情况下创建 SSM 文档时不会验证参数类型。只有在使用 `aws:runCommand` 操作的情况下，才会在创建 SSM 文档时验证参数类型。在所有其他情况下，在运行操作之前验证该操作的输入时，会在自动化执行期间进行参数验证。例如，如果输入参数为 `String` 并将其引用为 `aws:runInstances` 操作 `MaxInstanceCount` 输入的值，则会创建 SSM 文档。但是，在运行该文档期间，验证 `aws:runInstances` 操作时自动化将失败，因为 `MaxInstanceCount` 输入需要 `Integer`。
下面是每个参数的示例 `type`。
字符串
使用引号括起来的零个或多个 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 \$1", "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"
}
```
布尔值
仅接受 `true` 或 `false`。不接受 "true" 或 0。
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
整数
整数。不接受小数（例如 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 命令文档内容
要预览需要的和可选参数 Amazon Systems Manager(SSM) 命令文档，除了文档运行的操作外，您还可以在 Systems Manager 控制台中查看此文档的内容。
**查看 SSM 命令文档内容**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.amazonaws.cn/systems-manager/)，打开 Amazon Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 在搜索框中，选择**文档类型**，然后选择**命令**。
1. 选择文档的名称，然后选择**内容**选项卡。
1. 在内容字段中，查看文档的可用参数和操作步骤。
# 命令文档插件参考
此参考介绍可在 Amazon Systems Manager (SSM) 命令类型文档中指定的插件。这些插件不能在使自动化操作的 SSM 自动化运行手册中使用。有关 Amazon Systems Manager 自动化操作的信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
Systems Manager 通过读取 SSM 文档的内容确定在托管实例上执行的操作。每个文档都包含代码执行部分。根据文档的架构版本，此代码执行部分可能包含一个或多个插件或步骤。为了便于理解本帮助主题，我们将这些插件和步骤都称为*插件*。本部分包含有关每个 Systems Manager 插件的信息。有关文档的详细信息（包括有关创建文档和架构版本之间的差异的信息），请参阅 [Amazon Systems Manager 文档](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)
## 共享输入
仅在版本 3.0.502 和更高版本的 SSM Agent 中，所有插件都可以使用以下输入：
**最终步骤**
您希望文档运行的最后一步。如果此输入是为某个步骤定义的，则它优先于 `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 操作系统中运行。
### 语法
#### Schema 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 }}"
}
}
]
}
```
------
#### Schema 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 }}"
}
]
}
}
}
```
------
### 属性
**action**
要执行的操作。
类型：Enum
有效值：`Install` \$1`Repair` \$1`Uninstall`
是否必需：是
**参数**
安装程序的参数。
类型：字符串
必需：否
**source**
应用程序的 `.msi` 文件的 URL。
类型：字符串
是否必需：是
**sourceHash**
`.msi` 文件的 SHA256 哈希值。
类型：字符串
必需：否
## `aws:cloudWatch`
从中导出数据 Windows Server 添加到 Amazon CloudWatch 视台或 Amazon CloudWatch Logs 中，并使用云监控指标监控数据。此插件仅在 Windows Server 操作系统中运行。要详细了解如何配置 CloudWatch 与 Amazon Elastic Compute Cloud（Amazon EC2）的集成，请参阅《Amazon CloudWatch 用户指南》**中的[使用 CloudWatch 代理收集指标、日志和跟踪信息](https://docs.amazonaws.cn/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 用户指南》**中的[使用 CloudWatch 代理收集指标、日志和跟踪信息](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
您可以导出和监视以下数据类型：
**ApplicationEventLog**
将应用程序事件日志数据发送到 CloudWatch Logs。
**CustomLogs**
将任何基于文本的日志文件发送到 Amazon CloudWatch Logs。CloudWatch 插件会为日志文件创建指纹。系统随后将数据偏移与每个指纹进行关联。该插件会在出现更改时上传文件，记录偏移，然后将该偏移与指纹关联。此方法用于避免出现这种情况：用户启用插件后，将服务与包含大量文件的目录关联，然后系统会上传所有文件。
请注意，如果应用程序在轮询期间截断或尝试清除日志，为 `LogDirectoryPath` 指定的任何日志都可能丢失条目。例如，如果您要限制日志文件大小，请在达到此限制时创建新的日志文件，然后继续将数据写入新文件。
**ETW**
将 Windows (ETW) 事件跟踪数据发送到 CloudWatch Logs。
**IIS**
将 IIS 日志数据发送到 CloudWatch Logs
**PerformanceCounter**
将 Windows 性能计数器发送到 CloudWatch。您可以选择不同类别作为指标上传到 CloudWatch。对于要上传的每个性能计数器，创建具有唯一 ID 的 **PerformanceCounter** 部分 (例如“PerformanceCounter2”、“PerformanceCounter3”等)，然后配置其属性。
如果 Amazon 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 网站上的[国家语言支持 (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 库中的 [Encoding Class](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 安全日志的级别设置为 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** 位于