数据元素和参数 - AWS Systems Manager
顶级数据元素文档参数 type 示例查看 SSM 命令文档内容

数据元素和参数

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

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

顶级数据元素

schemaVersion

要使用的架构版本。

类型：版本

必需：是

description

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

类型：字符串

必需：否

参数

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

对于经常使用的参数，建议在 Parameter Store（AWS Systems Manager 的一种功能）中存储这些参数。然后，可以在文档中定义参数，并引用 Parameter Store 参数作为默认值。要引用 Parameter Store 参数，请使用以下语法。

{{ssm:parameter-name}}

可以使用参数通过与任何其他文档参数相同的方式引用 Parameter Store 参数。在以下示例中，commands 参数的默认值是 Parameter Store 参数 myShellCommands。如果将 commands 参数指定为 runCommand 字符串，文档将运行存储在 myShellCommands 参数中的命令。

YAML
---
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 }}"]
mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:
    - "{{ commands }}"
JSON
{
    "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 }}"]
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }
注意

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

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

类型：结构

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

  • type：(必需) 允许的值包括：String、StringList、Integer、Boolean、MapList 和 StringMap。要查看每种类型的示例，请参阅下一节中的 文档参数 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 正则表达式库在 API 级别进行。第二次验证是在处理文档之前通过使用 GO 正则表达式库在 SSM Agent 上进行。

    YAML
    InstanceId:
  type: String
  description: "(Required) The instance ID to target."
  allowedPattern: "^i-[a-z0-9]{8,17}$"
  default: ''
    JSON
    "InstanceId": {
  "type": "String",
  "description": "(Required) The instance ID to target.",
  "allowedPattern": "^i-[a-z0-9]{8,17}$",
  "default": ""
}

  • displayType：（可选）用于在 AWS Management Console 中显示 textfield 或 textarea。textfield 是单行文本框。textarea 是多行文本区域。

  • minItems：(可选) 允许的最小项目数。

  • maxItems：(可选) 允许的最大项目数。

  • minChars：(可选) 允许的最小参数字符数。

  • maxChars：(可选) 允许的最大参数字符数。

必需：否

variables

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

类型：Boolean | Integer | MapList | String | StringList | StringMap

必需：否

YAML
variables:
    payload:
        type: StringMap
        default: "{}"
JSON
{
    "variables": [
        "payload": {
            "type": "StringMap",
            "default": "{}"
        }
    ]
}
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 操作且已在一个或多个步骤中指定附件的文档。

对于脚本运行时系统支持，自动化运行手册支持 Python 3.7、Python 3.8、PowerShell Core 6.0 和 PowerShell 7.0 的脚本。有关在自动化运行手册中包含脚本的更多信息，请参阅 在运行手册中使用脚本 和 正在使用文档生成器创建运行手册。

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

YAML
---
files:
  launch.py:
    checksums:
      sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
JSON
"files": {
    "launch.py": {
        "checksums": {
            "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
        }
    }
}

类型：Dictionary<string,FilesConfiguration>

必需：否

文档参数 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。

String

使用引号括起来的零个或多个 Unicode 字符序列。例如，"i-1234567890abcdef0"。使用反斜杠转义。

YAML
---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."
JSON
"InstanceId":{
  "type":"String",
  "description":"(Optional) The target EC2 instance ID."
}
StringList

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

YAML
---
commands:
  type: StringList
  description: "(Required) Specify a shell script or a command to run."
  default: ""
  minItems: 1
  displayType: textarea
JSON
"commands":{
  "type":"StringList",
  "description":"(Required) Specify a shell script or a command to run.",
  "minItems":1,
  "displayType":"textarea"
}
布尔值

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

YAML
---
canRun:
  type: Boolean
  description: ''
  default: true
JSON
"canRun": {
  "type": "Boolean",
  "description": "",
  "default": true
}
整数

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

YAML
---
timeout:
  type: Integer
  description: The type of action to perform.
  default: 100
JSON
"timeout": {
  "type": "Integer",
  "description": "The type of action to perform.",
  "default": 100    
}
StringMap

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

YAML
---
notificationConfig:
  type: StringMap
  description: The configuration for events to be notified about
  default:
    NotificationType: 'Command'
    NotificationEvents:
    - 'Failed'
    NotificationArn: "$dependency.topicArn"
  maxChars: 150
JSON
"notificationConfig" : {
  "type" : "StringMap",
  "description" : "The configuration for events to be notified about",
  "default" : {
    "NotificationType" : "Command",
    "NotificationEvents" : ["Failed"],
    "NotificationArn" : "$dependency.topicArn"
  },
  "maxChars" : 150
}
MapList

StringMap 对象的列表。

YAML
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
JSON
"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/，打开 AWS Systems Manager 控制台。

  2. 在导航窗格中，选择文档。

  3. 在搜索框中，选择文档类型，然后选择命令。

  4. 选择文档的名称，然后选择内容选项卡。

  5. 在内容字段中，查看文档的可用参数和操作步骤。

    例如，下图显示 (1) version 和 (2) allowDowngrade 是 AWS-UpdateSSMAgent 文档的可选参数，并且文档运行的第一个操作是 (3) aws:updateSsmAgent。

    在 Systems Manager 控制台中查看 SSM 文档内容