数据元素和参数

本主题介绍 SSM 文档中使用的数据元素。用于创建文档的架构版本定义了文档接受的语法和数据元素。我们建议您对命令文档使用架构版本 2.2 或更高版本。自动化运行手册使用架构版本 0.3。此外，自动化运行手册还支持使用 Markdown（一种标记语言），它允许您为文档和文档中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的详细信息，请参阅《Amazon Web Services Management Console 入门指南》中的在控制台中使用 Markdown。

以下部分介绍了 SSM 文档中可以包含的数据元素。

顶级数据元素

schemaVersion

要使用的架构版本。

类型：版本

必需：是

description

您提供的描述文档目的的信息。您还可以使用此字段来指定参数是否需要一个值才能运行文档，或者为参数提供值是否为可选项。可在本主题的所有示例中查看必需参数和可选参数。

类型：字符串

必需：否

参数

定义文档接受的参数的结构。

为增强处理字符串参数的安全性，可通过指定 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 参数中的命令。

注意

您可以在文档的 parameters 部分引用 String 和 StringList Parameter Store 参数。您不能引用 SecureString Parameter Store 参数。

有关 Parameter Store 的更多信息，请参阅 Amazon Systems Manager Parameter Store。

类型：结构

parameters 结构接受以下字段和值：

type：(必需) 允许的值包括：String、StringList、Integer、Boolean、MapList 和 StringMap。要查看每种类型的示例，请参阅下一节中的文档参数 type 示例。

注意
命令类型文档仅支持 String 和 StringList 参数类型。
description：(可选) 关于参数的描述。
default：（可选）参数的默认值或对 Parameter Store 中参数的引用。

allowedValues：（可选）参数允许的值数组。定义参数的允许值将验证用户输入。如果用户输入了不允许的值，则执行将无法启动。

allowedPattern：（可选）验证用户输入是否与参数的定义模式匹配的正则表达式。如果用户输入与允许的模式不匹配，则执行无法启动。

注意
Systems Manager 会执行两次 allowedPattern 验证。第一次验证是在您使用文档时利用 Java 正则表达式库在 API 级别进行。第二次验证是在处理文档之前通过使用 GO 正则表达式库在 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 Management Console 中显示 textfield 或 textarea。textfield 是单行文本框。textarea 是多行文本区域。
minItems：(可选) 允许的最小项目数。
maxItems：(可选) 允许的最大项目数。
minChars：(可选) 允许的最小参数字符数。
maxChars：(可选) 允许的最大参数字符数。
interpolationType：（可选）定义在执行命令之前如何处理参数值。如果设置为 ENV_VAR，则可以将参数值用作名为 SSM_parameter-name 的环境变量。此功能通过将参数值视为文字字符串，从而帮助防范命令注入攻击。

类型：字符串

有效值：ENV_VAR

必需：否

variables

（仅限架构版本 0.3）您可以在自动化运行手册的整个步骤中引用或更新的值。变量与参数类似，但在重要方面有所区别。参数值在运行手册的上下文中是静态的，但是变量的值可以在运行手册的上下文中更改。更新变量的值时，数据类型必须与定义的数据类型相匹配。有关更新自动化中的变量值的信息，请参阅 aws:updateVariable – 更新运行手册变量的值

必需：否

runtimeConfig

(仅限 1.2 版架构) 由一个或多个 Systems Manager 插件应用的实例的配置。不保证插件按顺序运行。

类型：Dictionary<string,PluginConfiguration>

必需：否

mainSteps

（仅架构版本 0.3、2.0 和 2.2）可以包含多个步骤（插件）的对象。插件在步骤内定义。步骤按文档中列出的先后顺序运行。

类型：Dictionary<string,PluginConfiguration>

必需：是

outputs

（仅架构版本 0.3）通过执行本文档而生成的可用于其他进程的数据。例如，如果文档创建新的 AMI，您可以指定 “CreateImage.ImageId” 作为输出值，然后使用该输出以在后续自动化执行中创建新的实例。有关输出的更多信息，请参阅使用操作输出作为输入。

类型：Dictionary<string,OutputConfiguration>

必需：否

文件

（仅架构版本 0.3）附加到文档并在自动化执行期间运行的脚本文件（及其校验和）。仅适用于包含 aws:executeScript 操作且已在一个或多个步骤中指定附件的文档。

要了解自动化运行手册支持的运行时，请参阅 aws:executeScript - 运行脚本。有关在自动化运行手册中包含脚本的更多信息，请参阅在运行手册中使用脚本和自动化运行手册的视觉对象设计体验。

使用附件创建自动化运行手册时，可以使用 --attachments 选项（对于 Amazon CLI）或 Attachments（对于 API 和开发工具包）指定附件文件。您可以为存储在 Amazon Simple Storage Service（Amazon S3）存储桶中的 SSM 文档和文件指定文件位置。有关更多信息，请参阅 Amazon Systems Manager API 参考中的附件。

类型：Dictionary<string,FilesConfiguration>

必需：否

文档参数 `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 字段，以启用环境变量插值增强安全性。

StringList

以逗号分隔的字符串项目列表。例如，["cd ~", "pwd"]。

布尔值

仅接受 true 或 false。不接受 "true" 或 0。

整数

整数。不接受小数（例如 3.14159）或使用引号的数字（例如 "3"）。

StringMap

键到值的映射。密钥和值必须是字符串。例如，{"Env": "Prod"}。

MapList

StringMap 对象的列表。

查看 SSM 命令文档内容

要预览需要的和可选参数 Amazon Systems Manager(SSM) 命令文档，除了文档运行的操作外，您还可以在 Systems Manager 控制台中查看此文档的内容。

查看 SSM 命令文档内容

访问 https://console.aws.amazon.com/systems-manager/，打开 Amazon Systems Manager 控制台。
在导航窗格中，选择文档。
在搜索框中，选择文档类型，然后选择命令。
选择文档的名称，然后选择内容选项卡。
在内容字段中，查看文档的可用参数和操作步骤。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

架构、功能和示例

命令文档插件参考

数据元素和参数

顶级数据元素

注意

注意

注意

注意

文档参数 type 示例

查看 SSM 命令文档内容

查看 SSM 命令文档内容

文档参数 `type` 示例