调用 Systems Manager 自动化运行手册中的其他 Amazon 服务 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

调用 Systems Manager 自动化运行手册中的其他 Amazon 服务

您可以调用其他 Amazon 服务和其他 Systems Manager 功能,方法是在运行手册中使用以下自动化操作:

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

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

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

以下是 YAML 格式的一个示例运行手册,可使用 aws:executeAwsApi 操作关闭 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 格式的示例运行手册。自动化执行以下操作:

  • 使用 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 runbook using Amazon API operations 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-2022-English-Full-Base*" 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" ...

使用输入和输出

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

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

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

使用 Selector/PropertySelector 字段

每个自动化操作都要求您指定一个输出 Selector(用于 aws:executeAwsApi)或 PropertySelector(用于 aws:assertAwsResourcePropertyaws:waitForAwsResourceProperty)。这些字段用于处理 Amazon 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 }}",同一自动化中的其他步骤可以使用 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 实例状态。

在运行手册中使用 JSONPath

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

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

  • 深层扫描 (..):用于 JSON 元素。此运算符逐级扫描 JSON 元素,并使用特定键选择值列表。此运算符的返回类型始终为 JSON 数组。在自动化步骤输出类型上下文中,运算符可以是 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
重要

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

示例演练:从 Systems Manager 自动化运行手册启动 Amazon RDS 实例

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

从运行手册中调用 Amazon RDS API 操作

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

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "The_Automation_role_to_use_when_running_the_runbook" 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 操作添加到运行手册前,您必须确定并指定所需的输入。下面的列表介绍如何确定和指定所需的输入。您可以在列表后面的运行手册中看到关于如何输入此信息的示例。

    1. 查看架构以了解 aws:assertAwsResourceProperty - 断言 Amazon 资源状态或事件状态 操作的所有可用输入。

    2. 确定要调用的服务的命名空间。您可以查看 Amazon Resource Names (ARNs) 中的 Amazon 服务命名空间,以及 Amazon Web Services 一般参考中的 Amazon 服务命名空间。Amazon RDS 的命名空间为 rds

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

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

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

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

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

    7. 将收集的信息输入到运行手册中,如以下示例所示。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "The_Automation_role_to_use_when_running_the_runbook" 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 - 调用并运行 Amazon API 操作 的所有可用输入。

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

    3. 将收集的信息输入到运行手册中,如以下示例所示。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_runbook }}" 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 操作,以便在完成自动化前等待实例启动。

    1. 查看架构以了解 aws:waitForAwsResourceProperty - 等待 Amazon 资源属性 的所有可用输入。

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

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

    4. available 指定为 DesiredValue

    5. 将收集的信息输入到运行手册中,如以下示例所示。

    --- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_runbook }}" 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. 在 Amazon CLI 中运行以下命令,将运行手册添加到您的 Amazon Web Services 账户。

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

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

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

调用 Amazon API 的预定义运行手册

Systems Manager 自动化包括以下调用 Amazon API 的预定义运行手册。

运行手册名称 目的

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 关闭 S3 存储桶的读写权限。

AWS-ConfigureS3BucketVersioning

在 S3 存储桶上允许或暂停版本控制。

AWS-DeleteDynamoDbBackup

删除 Amazon DynamoDB 表备份。

选择上表中的链接,或使用以下过程在 Systems Manager 控制台中查看有关这些运行手册的更多详细信息。

  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

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

    -或者-

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

  3. 选择运行手册,然后选择查看详细信息

  4. 选择内容选项卡。