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

从 Systems Manager 自动化运行手册调用其他 Amazon Web Services

您可以在运行手册中使用以下自动化操作，从而调用其他 Amazon Web Services和其他 Systems Manager 功能：

以下是 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 格式的示例运行手册。自动化执行以下操作：

---
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:assertAwsResourceProperty 和 aws: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 运算符的信息：

为了更好地理解 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

从 Systems Manager 自动化运行手册启动 Amazon RDS 实例

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