AWS Systems Manager
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

从 Systems Manager Automation 工作流程调用其他 AWS 服务

您可以在 Automation 文档中使用以下 Automation 操作在 Automation 工作流程中调用其他 AWS 服务和其他 Systems Manager 功能。

  • aws:executeAwsApi:此 Automation 操作调用并运行 AWS API 操作。支持大多数 API 操作,但某些 API 操作未经过测试。例如,支持以下 API 操作:CreateImage删除存储桶RebootDBInstanceCreateGroups 等。不支持流式处理 API 操作,例如 Get Object 操作。

  • aws:waitForAwsResourceProperty:此 Automation 操作让工作流程等待特定的资源状态或事件状态,然后才继续工作流程。例如,您可以将此操作与 Amazon Relational Database Service (Amazon RDS) DescribeDBInstances API 操作配合使用来暂停 Automation 工作流程,以等待数据库实例启动。

  • aws:assertAwsResourceProperty:此 Automation 操作可用于对特定 Automation 步骤的资源状态或事件状态进行断言。例如,您可以指定某个 Automation 步骤必须等待 Amazon EC2 实例启动。然后,它将使用 running 的 DesiredValue 属性调用 Amazon EC2 DescribeInstanceStatus API 操作。这可确保 Automation 工作流程等待一个正在运行的实例,并在实例确实正在运行时继续。

下面是一个 YAML 格式的示例 Automation 文档,它使用 aws:executeAwsApi 操作禁用某个 Amazon S3 存储桶的读写权限。

--- description: Disable S3-Bucket's public WriteRead access via private ACL schemaVersion: "0.3" assumeRole: "{{ AutomationAssumeRole }}" parameters: S3BucketName: type: String description: (Required) S3 Bucket subject to access restriction AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: DisableS3BucketPublicReadWrite action: aws:executeAwsApi inputs: Service: s3 Api: PutBucketAcl Bucket: "{{S3BucketName}}" ACL: private isEnd: true ...

下面是一个使用所有三个操作的 YAML 格式的示例 Automation 文档。此文档执行以下操作:

  • 使用 aws:executeAwsApi 操作调用 Amazon EC2 DescribeImages API 操作来获取特定 Windows Server 2016 AMI 的名称。它将映像 ID 输出为 ImageId

  • 使用 aws:executeAwsApi 操作调用 Amazon EC2 RunInstances API 操作来启动一个实例,它使用上一步中的 ImageId。它将实例 ID 输出为 InstanceId

  • 使用 aws:waitForAwsResourceProperty 操作轮询 Amazon EC2 DescribeInstanceStatus API 操作来等待实例进入 running 状态。此操作的超时时间为 60 秒。如果实例在轮询 60 秒后未能进入 running 状态,则此步骤超时。

  • 使用 aws:assertAwsResourceProperty 操作调用 Amazon EC2 DescribeInstanceStatus API 操作来断言实例处于 running 状态。如果实例状态不为 running,则此步骤失败。

--- description: Sample Automation Document Using AWS API Actions schemaVersion: '0.3' assumeRole: "{{ AutomationAssumeRole }}" parameters: AutomationAssumeRole: type: String description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf." default: '' ImageName: type: String description: "(Optional) Image Name to launch ec2 instance with." default: "Windows_Server-2016-English-Full-Base-2018.07.11" mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ ImageName }}" outputs: - Name: ImageId Selector: "$.Images[0].ImageId" Type: "String" - name: launchOneInstance action: aws:executeAwsApi inputs: Service: ec2 Api: RunInstances ImageId: "{{ getImageId.ImageId }}" MaxCount: 1 MinCount: 1 outputs: - Name: InstanceId Selector: "$.Instances[0].InstanceId" Type: "String" - name: waitUntilInstanceStateRunning action: aws:waitForAwsResourceProperty # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty timeoutSeconds: 60 inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running - name: assertInstanceStateRunning action: aws:assertAwsResourceProperty inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running outputs: - "launchOneInstance.InstanceId" ...

使用输入和输出

前面介绍的每个 Automation 操作都允许您通过指定服务命名空间、API 操作名称、输入参数和输出参数来调用特定的 API 操作。输入由您选择的 API 操作定义。您可以在以下服务参考页面的左侧导航栏中选择服务来查看 API 操作(也称为方法)。在要调用的服务的 Client 部分中选择一种方法。例如,以下页面中列出了 Amazon Relational Database Service (Amazon RDS) 的所有 API 操作(方法):Amazon RDS 方法

您可以在以下位置查看每个 Automation 操作的架构:

架构包括使用每个操作所需字段的描述。

使用 Selector/PropertySelector 字段

每个 Automation 操作都要求您指定输出 Selector(对于 aws:executeAwsApi)或 PropertySelector(对于 aws:assertAwsResourceProperty 和 aws:waitForAwsResourceProperty)。这些字段用于处理 AWS API 操作的 JSON 响应。这些字段使用 JSONPath 语法。

以下是帮助说明这一概念的 aws:executeAwsAPi 操作的示例:

--- mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ ImageName }}" outputs: - Name: ImageId Selector: "$.Images[0].ImageId" Type: "String" ...

aws:executeAwsApi 步骤 getImageId 中,工作流程调用 DescribeImages API 操作并从 ec2 接收响应。然后,工作流程将 Selector - "$.Images[0].ImageId" 应用于 API 响应,并将所选值分配给输出 ImageId 变量。通过指定 "{{ getImageId.ImageId }}",同一 Automation 工作流程中的其他步骤可以使用 ImageId 的值。

以下是帮助说明这一概念的 aws:waitForAwsResourceProperty 操作的示例:

--- - name: waitUntilInstanceStateRunning action: aws:waitForAwsResourceProperty # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty timeoutSeconds: 60 inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running ...

aws:waitForAwsResourceProperty 步骤 waitUntilInstanceStateRunning 中,工作流程调用 DescribeInstanceStatus API 操作并从 ec2 接收响应。然后,工作流程将 PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" 应用于响应,并检查指定的返回值是否与 DesiredValues 列表中的值匹配(在本例中为 running)。此步骤重复这一过程,直到响应返回 running 实例状态。

在 Automation 工作流程中使用 JSONPath

JSONPath 表达式是以“$.”开头的字符串。“$.”用于选择 JSON 元素中的一个或多个组件。下面的列表包含有关 Systems Manager Automation 支持的 JSONPath 运算符的信息:

  • 点表示的子字段 (.):用于 JSON 对象。此运算符选择特定键的值。

  • 深层扫描 (..):用于 JSON 元素。此运算符逐级扫描 JSON 元素,并使用特定键选择值列表。注意,此运算符的返回类型始终为 JSON 数组。在 Automation 步骤输出类型上下文中,运算符可以是 StringList 或 MapList。

  • 数组索引 ([ ]):用于 JSON 数组。此运算符获取特定索引的值。

为了更好地理解 JSONPath 运算符,请查看以下 ec2 DescribeInstances API 操作的 JSON 响应。此响应下面提供了几个示例,它们说明通过向 DescribeInstances API 操作响应应用不同的 JSONPath 表达式获取的不同结果。

{
    "NextToken": "abcdefg",
    "Reservations": [
        {
            "OwnerId": "123456789012",
            "ReservationId": "r-abcd12345678910",
            "Instances": [
                {
                    "ImageId": "ami-12345678",
                    "BlockDeviceMappings": [
                        {
                            "Ebs": {
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "vol-000000000000"
                            },
                            "DeviceName": "/dev/xvda"
                        }
                    ],
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    }
                }
            ],
            "Groups": []
        },
        {
            "OwnerId": "123456789012",
            "ReservationId": "r-12345678910abcd",
            "Instances": [
                {
                    "ImageId": "ami-12345678",
                    "BlockDeviceMappings": [
                        {
                            "Ebs": {
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "vol-111111111111"
                            },
                            "DeviceName": "/dev/xvda"
                        }
                    ],
                    "State": {
                        "Code": 80,
                        "Name": "stopped"
                    }
                }
            ],
            "Groups": []
        }
    ]
}

JSONPath 示例 1:从 JSON 响应获取特定的 String

JSONPath: $.Reservations[0].Instances[0].ImageId Returns: "ami-12345678" Type: String

JSONPath 示例 2:从 JSON 响应获取特定的 Boolean

JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination Returns: true Type: Boolean

JSONPath 示例 3:从 JSON 响应获取特定的 Integer

JSONPath: $.Reservations[0].Instances[0].State.Code Returns: 16 Type: Integer

JSONPath 示例 4:深层扫描 JSON 响应,然后以 StringList 的形式获取 VolumeId 的所有值

JSONPath: $.Reservations..BlockDeviceMappings..VolumeId Returns: [ "vol-000000000000", "vol-111111111111" ] Type: StringList

JSONPath 示例 5:以 StringMap 的形式获取特定的 BlockDeviceMappings 对象

JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0] Returns: { "Ebs" : { "DeleteOnTermination" : true, "Status" : "attached", "VolumeId" : "vol-000000000000" }, "DeviceName" : "/dev/xvda" } Type: StringMap

JSONPath 示例 6:深层扫描 JSON 响应,然后以 MapList 的形式获取所有 State 对象

JSONPath: $.Reservations..Instances..State Returns: [ { "Code" : 16, "Name" : "running" }, { "Code" : 80, "Name" : "stopped" } ] Type: MapList

重要

如果您运行使用 AWS Identity and Access Management (IAM) 服务角色调用其他服务的自动化,请注意必须使用权限将该服务角色配置为调用这些服务。此要求适用于所有 AWS Automation 文档(AWS-* 文档),例如 AWS-ConfigureS3BucketLoggingAWS-CreateDynamoDBBackupAWS-RestartEC2Instance 文档。对于您创建的所有自定义自动化文档,如果这些文档使用调用其他服务的操作调用其他 AWS 服务,此要求同样适用。例如,如果您使用 aws:executeAwsApiaws:CreateStackaws:copyImage 操作等,则您必须配置具有权限的服务角色来调用这些服务。您可以通过将 IAM 内联策略添加到角色来启用其他 AWS 服务的权限。有关更多信息,请参阅(可选)添加 Automation 内联策略来调用其他 AWS 服务

示例演练:从 Systems Manager Automation 工作流程启动 Amazon RDS 实例

此示例演练说明如何创建和运行 YAML 格式的 Automation 文档。此文档使用所有三个 API 操作来检查 Amazon Relational Database Service (Amazon RDS) 数据库实例是否正在运行。如果实例未运行,则此工作流程将启动它。

从 Systems Manager Automation 调用 Amazon RDS API 操作

  1. 打开文本编辑器并将以下 Automation 文档内容粘贴到此文件中。指定 Automation 角色和要检查的实例 ID。稍后您将添加 mainSteps 操作。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "The_Automation_role_to_use_when_running_the_document" parameters: InstanceId: The_instance_ID_to_start type: String description: (Required) RDS instance ID to start AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps:
  2. 在此工作流程的第一步中,需要确定实例是否已在运行。可以使用 aws:assertAwsResourceProperty 操作来确定和断言特定的实例状态。在将 aws:assertAwsResourceProperty 操作添加到文档之前,必须确定并指定所需的输入。下面的列表介绍如何确定和指定所需的输入。您可以在列表后面的 Automation 文档中看到关于如何输入此信息的示例。

    1. 查看架构以了解 aws:assertAwsResourceProperty 操作的所有可用输入。

    2. 确定要调用的服务的命名空间。您可以查看 Amazon Web Services General Reference 中的 Amazon 资源名称 (ARN) 和 AWS 服务命名空间的 AWS 服务命名空间列表。Amazon RDS 的命名空间为 rds

    3. 确定哪个 Amazon RDS API 操作可用于查看数据库实例的状态。您可以在 Amazon RDS 方法页面上查看 API 操作(也称为方法)。

    4. 为 DescribeDBInstances API 操作指定一个或多个请求参数。例如,此操作使用 DBInstanceIdentifier 请求参数。

    5. 确定一个或多个 PropertySelectors。PropertySelector 是此 API 操作的请求返回的响应对象。例如,在 Amazon RDS 方法上。选择 describe_db_instances 方法,然后向下滚动到 Response Structure (响应结构) 部分。DBInstances 被列为响应对象。出于本演练的目的,请将 DBInstancesDBInstanceStatus 指定为 PropertySelectors。请注意,PropertySelectors 是使用 JSONPath 输入的。也就是说,您需要对 Automation 文档中的信息进行格式化,如下所示:

      PropertySelector: "$.DBInstances[0].DBInstanceStatus"

    6. 指定一个或多个 DesiredValues。如果不知道要指定的值,可以运行 DescribeDBInstances API 操作确定可能的值。在本演练中,请指定 availablestarting

    7. 将收集的信息输入到 Automation 文档中,如以下示例所示。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "The_Automation_role_to_use_when_running_the_document" parameters: InstanceId: The_instance_ID_to_start type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"]
  3. 在 mainSteps 部分中指定 aws:executeAwsApi 操作,以便在上一个操作确定实例未启动时启动实例。

    1. 查看架构以了解 aws:executeAwsApi 的所有可用输入。

    2. 指定 Amazon RDS StartDBInstance API 操作来启动实例。

    3. 将收集的信息输入到 Automation 文档中,如以下示例所示。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_document }}" parameters: InstanceId: type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] - name: StartInstance action: aws:executeAwsApi inputs: Service: rds Api: StartDBInstance DBInstanceIdentifier: "{{InstanceId}}"
  4. 在 mainSteps 部分中指定 aws:waitForAwsResourceProperty 操作,以便在完成 Automation 工作流程前等待实例启动。

    1. 查看架构以了解 aws:waitForAwsResourceProperty 的所有可用输入。

    2. 指定 Amazon RDS DescribeDBInstances API 操作来确定实例状态。

    3. $.DBInstances[0].DBInstanceStatus 指定为 PropertySelector

    4. available 指定为 DesiredValue

    5. 将收集的信息输入到 Automation 文档中,如以下示例所示。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_document }}" parameters: InstanceId: type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] - name: StartInstance action: aws:executeAwsApi inputs: Service: rds Api: StartDBInstance DBInstanceIdentifier: "{{InstanceId}}" - name: CheckStart action: aws:waitForAwsResourceProperty onFailure: Abort maxAttempts: 10 timeoutSeconds: 600 inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available"] isEnd: true ...
  5. 将文件保存为 sample.yaml。

  6. 在 AWS CLI 中运行以下命令,将文档添加到您的 AWS 账户。

    aws ssm create-document --name sampleDoc --document-type Automation --document-format YAML --content file://sample.yaml
  7. 运行以下命令以使用刚刚创建的文档运行 Automation 执行。开始执行后,记下 Systems Manager 返回的执行 ID。

    aws ssm start-automation-execution --document-name sampleDoc
  8. 运行以下命令查看执行状态。

    aws ssm get-automation-execution --automation-execution-id automation_execution_id

调用 AWS API 的预定义 Automation 文档

Systems Manager Automation 包括以下调用 AWS API 的预定义 SSM Automation 文档。

文档名称 目的

AWS-StartRdsInstance

启动 Amazon RDS 实例。

AWS-StopRdsInstance

停止 Amazon RDS 实例。

AWS-RebootRdsInstance

重启 Amazon RDS 实例。

AWS-CreateSnapshot

创建 Amazon Elastic Block Store (Amazon EBS) 卷快照。

AWS-DeleteSnapshot

删除 Amazon EBS 卷快照。

AWS-ConfigureS3BucketLogging

在 Amazon Simple Storage Service (Amazon S3) 存储桶上启用日志记录。

AWS-DisableS3BucketPublicReadWrite

使用专用 ACL 禁用 Amazon S3 存储桶的读写权限。

AWS-ConfigureS3BucketVersioning

在 Amazon S3 存储桶上启用或暂停版本控制。

AWS-DeleteDynamoDbBackup

删除 Amazon DynamoDB (DynamoDB) 表备份。

请单击上表中的链接,或使用以下过程在 Systems Manager 控制台中查看有关这些 Automation 文档的更多详细信息。

  1. 通过以下网址打开 AWS Systems Manager 控制台:https://console.amazonaws.cn/systems-manager/

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

    -或者-

    如果 AWS Systems Manager 主页首先打开,请选择菜单图标 ( ) 以打开导航窗格,然后在导航窗格中选择文档

  3. 选择一个文档,然后选择查看详细信息

  4. 选择内容选项卡。