• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# 数据元素和参数
本主题介绍 SSM 文档中使用的数据元素。用于创建文档的架构版本定义了文档接受的语法和数据元素。我们建议您对命令文档使用架构版本 2.2 或更高版本。自动化运行手册使用架构版本 0.3。此外，自动化运行手册还支持使用 Markdown（一种标记语言），它允许您为文档和文档中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的详细信息，请参阅*《AWS 管理控制台 入门指南》*中的[在控制台中使用 Markdown](https://docs.aws.amazon.com/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（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`。要查看每种类型的示例，请参阅下一节中的 [文档参数 `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`：（可选）用于在 AWS 管理控制台 中显示 `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` 选项（对于 AWS CLI）或 `Attachments`（对于 API 和开发工具包）指定附件文件。您可以为存储在 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
必需：否
## 文档参数 `type` 示例
SSM 文档中的参数类型是静态的。这意味着参数类型在定义后无法更改。将参数用于 SSM 文档插件时，不能在插件的输入中动态更改参数的类型。例如，您不能在 `aws:runShellScript` 插件的 `runCommand` 输入中引用 `Integer` 参数，因为此输入接受字符串或字符串列表。要将参数用于插件输入，参数类型必须与接受的类型匹配。例如，您必须为`aws:updateSsmAgent` 插件的 `allowDowngrade` 输入指定 `Boolean` 类型参数。如果参数类型与插件的输入类型不匹配，则 SSM 文档无法验证，并且系统不会创建文档。在其他插件或 AWS 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 命令文档内容
要预览需要的和可选参数 AWS Systems Manager(SSM) 命令文档，除了文档运行的操作外，您还可以在 Systems Manager 控制台中查看此文档的内容。
**查看 SSM 命令文档内容**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 在搜索框中，选择**文档类型**，然后选择**命令**。
1. 选择文档的名称，然后选择**内容**选项卡。
1. 在内容字段中，查看文档的可用参数和操作步骤。
例如，下图显示 (1) `version` 和 (2) `allowDowngrade` 是 `AWS-UpdateSSMAgent` 文档的可选参数，并且文档运行的第一个操作是 (3) `aws:updateSsmAgent`。
![\[在 Systems Manager 控制台中查看 SSM 文档内容\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/view-document-content.png)