Verwenden von Aktionsausgaben als Eingaben

Verschiedene Automatisierungs-Aktionen geben vordefinierte Ausgaben zurück. Sie können diese Ausgaben mithilfe des Formats {{stepName.outputName}} als Eingaben an spätere Schritte in Ihrem Runbook übergeben. Sie können benutzerdefinierte Ausgaben für Automatisierungs-Aktionen in Ihren Runbooks definieren. Auf diese Weise können Sie Skripts ausführen oder API-Operationen für andere AWS-Services einmalig aufrufen, sodass Sie die Werte als Eingaben in späteren Aktionen wiederverwenden können. Parametertypen in Runbooks sind statisch. Dies bedeutet, dass der Parametertyp nicht geändert werden kann, nachdem er definiert wurde. Um eine Schrittausgabe zu definieren, geben Sie die folgenden Felder an:

Name: (Erforderlich) Der Ausgabename, der in späteren Schritten verwendet wird, um auf den Ausgabewert zu verweisen.
Selektor: (Erforderlich) Der JSONPath Ausdruck, der zur Bestimmung des Ausgabewerts verwendet wird.
Typ: (Optional) Der Datentyp des Werts, der vom Auswahlfeld zurückgegeben wird. Gültige Typwerte sind String, Integer, Boolean, StringList, StringMap, MapList. Der Standardwert ist String.

Wenn der Wert einer Ausgabe nicht dem von Ihnen angegebenen Datentyp entspricht, versucht Automation, den Datentyp zu konvertieren. Wenn der zurückgegebene Wert beispielsweise ein Integer ist, der angegebene Type jedoch ein String ist, ist der endgültige Ausgabewert ein String-Wert. Die folgenden Typkonvertierungen werden unterstützt:

String-Werte können in StringList, Integer und Boolean umgewandelt werden.
Integer-Werte können in String und StringList umgewandelt werden.
Boolean-Werte können in String und StringList umgewandelt werden.
StringList-, IntegerList-, oder BooleanList-Werte, die ein Element enthalten, können in String, Integer oder Boolean umgewandelt werden.

Bei der Verwendung von Parametern oder Ausgaben mit Automatisierungs-Aktionen kann der Datentyp nicht dynamisch innerhalb der Eingabe einer Aktion geändert werden.

Hier ist ein Beispiel-Runbook, das veranschaulicht, wie Sie Aktionsausgaben definieren und auf den Wert als Eingabe für eine spätere Aktion verweisen. Die Runbooks tun Folgendes:

Verwendet die aws:executeAwsApi Aktion, um den EC2 DescribeImages Amazon-API-Vorgang aufzurufen, um den Namen eines bestimmten Windows Server 2016 abzurufenAMI. Es gibt die Image-ID als ImageId aus.
Verwendet die aws:executeAwsApi Aktion, um den EC2 RunInstances Amazon-API-Vorgang aufzurufen, um eine Instance zu starten, die den ImageId aus dem vorherigen Schritt verwendet. Es gibt die Instance-ID als InstanceId aus.
Verwendet die aws:waitForAwsResourceProperty Aktion, um den EC2 DescribeInstanceStatus Amazon-API-Vorgang abzufragen, um darauf zu warten, dass die Instance den running Status erreicht. Die Aktion endet nach 60 Sekunden durch Timeout. Der Schritt endet durch Timeout, wenn die Instance nach 60 Sekunden Abfrage nicht den Status running erreicht.
Verwendet die aws:assertAwsResourceProperty Aktion, um den EC2 DescribeInstanceStatus Amazon-API-Vorgang aufzurufen, um zu bestätigen, dass sich die Instance im running Status befindet. Der Schritt schlägt fehl, wenn der Status der Instance nicht running ist.


---
description: Sample runbook using AWS 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
  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"
...

Sie können mit jeder der oben beschriebenen Automatisierungsaktionen eine bestimmte API-Operation aufrufen, indem Sie den Service-Namespace, den Namen der API-Operation, die Eingabeparameter und die Ausgabeparameter angeben. Eingaben werden von der ausgewählten API-Operation bestimmt. Sie können die API-Operationen (auch als Methoden bezeichnet) anzeigen, indem Sie einen Service in der linken Navigationsleiste auf der folgenden Service-Referenzen-Seite auswählen. Wählen Sie eine Methode im Abschnitt Client für den Service, den Sie aufrufen möchten. Beispielsweise werden alle API-Vorgänge (Methoden) für Amazon Relational Database Service (Amazon RDS) auf der folgenden Seite aufgelistet: Amazon RDS-Methoden.

Sie können das Schema für jede Automatisierungsaktion an den folgenden Orten anzeigen:

Die Schemata umfassen Beschreibungen der erforderlichen Felder für jede Aktion.

Verwendung der Selector/PropertySelector Felder

Jede Automatisierungsaktion erfordert, dass Sie entweder eine Ausgabe Selector (für aws:executeAwsApi) oder einen PropertySelector (für aws:assertAwsResourceProperty und aws:waitForAwsResourceProperty) enthalten. Diese Felder werden verwendet, um die JSON-Antwort aus einer AWS API-Operation zu verarbeiten. Diese Felder verwenden die JSONPath Syntax.

Hier finden Sie ein Beispiel, das dieses Konzept für die Aktion aws:executeAwsAPi erläutert.


---
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"
...

Im aws:executeAwsApi-SchrittgetImageId ruft die Automatisierung die DescribeImages-API-Operation auf und empfängt eine Antwort von ec2. Die Automatisierung wendet dann Selector - "$.Images[0].ImageId" auf die API-Antwort an und weist der ImageId-Ausgabevariablen den ausgewählten Wert zu. Weitere Schritte in dieser Automatisierung können den Wert von ImageId verwenden, indem "{{ getImageId.ImageId }}" angegeben wird.

Hier finden Sie ein Beispiel, das dieses Konzept für die Aktion aws:waitForAwsResourceProperty erläutert.


---
- 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
...

Im aws:waitForAwsResourceProperty-SchrittwaitUntilInstanceStateRunning ruft die Automatisierung die DescribeInstanceStatus-API-Operation auf und empfängt eine Antwort von ec2. Die Automatisierung wendet dann PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" auf die Antwort an und prüft, ob der angegebene zurückgegebene Wert einem Wert in der Liste DesiredValues entspricht (in diesem Fall running). Der Schritt wiederholt den Prozess, bis die Antwort den Instance-Status running zurückgibt.

Verwendung JSONPath in Runbooks

Ein JSONPath Ausdruck ist eine Zeichenfolge, die mit „$“ beginnt. die zur Auswahl einer oder mehrerer Komponenten in einem JSON-Element verwendet wird. Die folgende Liste enthält Informationen zu JSONPath Operatoren, die von Systems Manager Automation unterstützt werden:

Dot-notated child (.): Verwendung mit einem JSON-Objekt. Dieser Operator wählt den Wert eines bestimmten Schlüssels aus.
Deep-scan (..): Verwendung mit einem JSON-Element. Dieser Operator untersucht das JSON-Element Ebene für Ebene und wählt eine Liste von Werten mit dem spezifischen Schlüssel aus. Der Rückgabetyp dieses Operators ist immer ein JSON-Array. Im Kontext eines Ausgabetyps einer Automatisierungsaktion kann der Operator entweder StringList oder sein MapList.
Array-Index ([ ]): Verwendung mit einem JSON-Array. Dieser Operator ruft den Wert eines bestimmten Index ab.
Filter ([? (expression)]): Wird mit einem JSON-Array verwendet. Dieser Operator filtert JSON-Array-Werte, die den im Filterausdruck definierten Kriterien entsprechen. Filterausdrücke können nur die folgenden Operatoren verwenden: ==,! =, >, <, >= oder <=. Die Kombination mehrerer Filterausdrücke mit AND (&&) oder OR (||) wird nicht unterstützt. Der Rückgabetyp dieses Operators ist immer ein JSON-Array.

Um JSONPath Operatoren besser zu verstehen, lesen Sie sich die folgende JSON-Antwort aus dem DescribeInstances ec2-API-Vorgang durch. Auf diese Antwort folgen mehrere Beispiele, die unterschiedliche Ergebnisse zeigen, indem unterschiedliche JSONPath Ausdrücke auf die Antwort aus dem DescribeInstances API-Vorgang angewendet werden.

{
    "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 Beispiel 1: Rufen Sie eine bestimmte Zeichenfolge aus einer JSON-Antwort ab


JSONPath: 
$.Reservations[0].Instances[0].ImageId 

Returns:
"ami-12345678"

Type: String

JSONPath Beispiel 2: Rufen Sie einen bestimmten booleschen Wert aus einer JSON-Antwort ab


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

Type: Boolean

JSONPath Beispiel 3: Holen Sie sich eine bestimmte Ganzzahl aus einer JSON-Antwort


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

Type: Integer

JSONPath Beispiel 4: Eine JSON-Antwort gründlich scannen und dann alle Werte für VolumeId als StringList


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

Type: StringList

JSONPath Beispiel 5: Holen Sie sich ein bestimmtes BlockDeviceMappings Objekt als StringMap


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

Type: StringMap

JSONPath Beispiel 6: Tiefenscan einer JSON-Antwort und Abrufen aller State-Objekte als MapList


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

Type: MapList

JSONPath Beispiel 7: Filtern Sie nach Instanzen im running Bundesstaat


JSONPath:
$.Reservations..Instances[?(@.State.Name == 'running')]

Returns:
[
  {
    "ImageId": "ami-12345678",
    "BlockDeviceMappings": [
      {
        "Ebs": {
          "DeleteOnTermination": true,
          "Status": "attached",
          "VolumeId": "vol-000000000000"
        },
        "DeviceName": "/dev/xvda"
      }
    ],
    "State": {
      "Code": 16,
      "Name": "running"
    }
  }
]

Type: MapList

JSONPath Beispiel 8: Gibt die Anzahl ImageId der Instanzen zurück, die sich nicht im running Status befinden


JSONPath:
$.Reservations..Instances[?(@.State.Name != 'running')].ImageId

Returns:
[
  "ami-12345678"
]

Type: StringList | String

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Verwendung bedingter Anweisungen in Runbooks

Erstellen von Webhook-Integrationen für Automation