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

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

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

aws:executeAwsApi：此 Automation 操作调用并运行 AWS API 操作。支持大多数 API 操作，但某些 API 操作未经过测试。例如，支持以下 API 操作：CreateImage、删除存储桶、RebootDBInstance 和 CreateGroups 等。不支持流式处理 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-ConfigureS3BucketLogging、AWS-CreateDynamoDBBackup 和 AWS-RestartEC2Instance 文档。对于您创建的所有自定义自动化文档，如果这些文档使用调用其他服务的操作调用其他 AWS 服务，此要求同样适用。例如，如果您使用 aws:executeAwsApi、aws:CreateStack 或 aws: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 操作

打开文本编辑器并将以下 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:

在此工作流程的第一步中，需要确定实例是否已在运行。可以使用 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 被列为响应对象。出于本演练的目的，请将 DBInstances 和 DBInstanceStatus 指定为 PropertySelectors。请注意，PropertySelectors 是使用 JSONPath 输入的。也就是说，您需要对 Automation 文档中的信息进行格式化，如下所示：
  
  PropertySelector: "$.DBInstances[0].DBInstanceStatus"。
6. 指定一个或多个 DesiredValues。如果不知道要指定的值，可以运行 DescribeDBInstances API 操作确定可能的值。在本演练中，请指定 available 和 starting。
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"]
```

在 mainSteps 部分中指定 aws:executeAwsApi 操作，以便在上一个操作确定实例未启动时启动实例。

查看架构以了解 aws:executeAwsApi 的所有可用输入。
指定 Amazon RDS StartDBInstance API 操作来启动实例。
将收集的信息输入到 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}}"

在 mainSteps 部分中指定 aws:waitForAwsResourceProperty 操作，以便在完成 Automation 工作流程前等待实例启动。

查看架构以了解 aws:waitForAwsResourceProperty 的所有可用输入。
指定 Amazon RDS DescribeDBInstances API 操作来确定实例状态。
将 $.DBInstances[0].DBInstanceStatus 指定为 PropertySelector。
将 available 指定为 DesiredValue。
将收集的信息输入到 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
...

将文件保存为 sample.yaml。

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


aws ssm create-document --name sampleDoc --document-type Automation --document-format YAML --content file://sample.yaml

运行以下命令以使用刚刚创建的文档运行 Automation 执行。开始执行后，记下 Systems Manager 返回的执行 ID。
```
aws ssm start-automation-execution --document-name sampleDoc 
```

运行以下命令查看执行状态。


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 文档的更多详细信息。

通过以下网址打开 AWS Systems Manager 控制台：https://console.amazonaws.cn/systems-manager/。
在导航窗格中，选择文档。

-或者-

如果 AWS Systems Manager 主页首先打开，请选择菜单图标 ( ) 以打开导航窗格，然后在导航窗格中选择文档。
选择一个文档，然后选择查看详细信息。
选择内容选项卡。

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

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