Utilisation de JSONPath dans des runbooks

Utilisation des sorties d'action comme entrées

Plusieurs actions d’automatisation renvoient des résultats prédéfinis. Vous pouvez transmettre ces sorties en tant qu’entrées aux étapes ultérieures de votre runbook en utilisant le format {{stepName.outputName}}. Vous pouvez définir des sorties pour différentes actions d’automatisation dans vos runbooks. Cela vous permet d'exécuter des scripts ou d'invoquer des opérations d'API pour d'autres Services AWS une fois, afin de pouvoir réutiliser les valeurs en tant qu'entrées dans des actions ultérieures. Les types de paramètres des runbooks sont statiques. Cela signifie que le type de paramètre ne peut pas être modifié après avoir été défini. Pour définir une sortie d’étape, fournir les champs suivants :

Nom : (Obligatoire) le nom de sortie utilisé pour faire référence à la valeur de la sortie dans les étapes ultérieures.
Sélecteur : (Obligatoire) expression JSONPath utilisée pour déterminer la valeur de sortie.
Type : (Facultatif) type de données de la valeur renvoyée par le champ de sélection. Les valeurs de type valides sont String, Integer, Boolean, StringList, StringMap, MapList. La valeur par défaut est String.

Si la valeur d’une sortie ne correspond pas au type de données que vous avez spécifié, l’Automatisation essaie de convertir le type de données. Par exemple, si la valeur renvoyée est Integer, mais que le Type spécifié est String, la valeur de sortie finale est une valeur String. Les types de conversions suivants sont pris en charge :

Les valeurs String peuvent être converties en StringList, Integer et Boolean.
Les valeurs Integer peuvent être converties en String et StringList.
Les valeurs Boolean peuvent être converties en String et StringList.
Les valeurs StringList, IntegerList ou BooleanList contenant un élément peuvent être converties en String, Integer ou Boolean.

Lorsque vous utilisez des paramètres ou des sorties avec des actions d’automatisation, le type de donnée ne peut pas être modifié dynamiquement dans l’entrée d’une action.

Voici un exemple de runbook qui montre comment définir les sorties d'action et référencer la valeur en tant qu'entrée pour une action ultérieure. Les runbooks réalisent les opérations suivantes :

Il utilise l'action aws:executeAwsApi pour appeler l'action d'API Amazon EC2 DescribeImages afin d'obtenir le nom d'une AMI Windows Server 2016. Il génère l'ID d'image en tant que ImageId.
Il utilise l'action aws:executeAwsApi pour appeler l'opération d'API Amazon EC2 RunInstances afin de lancer une instance qui utilise l'ImageId de l'étape précédente. Il génère l'ID d'instance en tant que InstanceId.
Il utilise l'action aws:waitForAwsResourceProperty pour interroger l'opération d'API Amazon EC2 DescribeInstanceStatus afin d'attendre que l'instance atteigne l'état running. L'action arrive à expiration dans les 60 secondes. L'étape arrive à expiration si l'état de l'instance ne parvient pas à atteindre running après 60 secondes d'interrogation.
Utilise l'action aws:assertAwsResourceProperty pour appeler l'opération d'API DescribeInstanceStatus d'Amazon EC2 afin d'affirmer que l'instance a le statut running. L'étape échoue si l'état de l'instance n'est pas running.


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

Chacune des actions d'automatisation décrites précédemment vous permet d'appeler une opération d'API spécifique en définissant l'espace de noms de service, l'opération d'API, les paramètres d'entrée et les paramètres de sortie. Les entrées sont définies par l'opération d'API que vous sélectionnez. Vous pouvez consulter les opérations d'API (également appelées méthodes) en choisissant un service dans le panneau de navigation de gauche sur la page Services Reference (Référence des services) suivante. Sélectionnez une méthode dans la section Client pour le service que vous voulez appeler. Par exemple, toutes les opérations d'API (méthodes) pour Amazon Relational Database Service (Amazon RDS) sont répertoriées à la page suivante : Méthodes pour Amazon RDS.

Vous pouvez consulter le schéma de chaque action d'automatisation dans les emplacements suivants :

Les schémas incluent les descriptions des champs obligatoires pour l'utilisation de chaque action.

Utilisation des champs Selector/PropertySelector

Chaque action Automation exige que vous spécifiiez une sortie Selector (pour aws:executeAwsApi) ou PropertySelector (pour aws:assertAwsResourceProperty et aws:waitForAwsResourceProperty). Ces champs sont utilisés pour traiter la réponse JSON à partir d'une opération d'API AWS. Ces champs utilisent la syntaxe JSONPath.

Voici un exemple pour vous aider à illustrer ce concept pour l'action 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"
...

Dans l'étape getImageId aws:executeAwsApi, l'automatisation appelle l'opération d'API DescribeImages et reçoit une réponse d'ec2. L'automatisation applique ensuite Selector - "$.Images[0].ImageId" à la réponse de l'API et attribue la valeur sélectionnée pour à la variable ImageId de sortie. D'autres étapes dans la même automatisation peuvent utiliser la valeur ImageId en spécifiant "{{ getImageId.ImageId }}".

Voici un exemple pour vous aider à illustrer ce concept pour l'action 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
...

Dans l'étape waitUntilInstanceStateRunning aws:waitForAwsResourceProperty, l'automatisation appelle l'opération d'API DescribeInstanceStatus et reçoit une réponse d'ec2. L'automatisation applique ensuite PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" à la réponse et vérifie si la valeur renvoyée correspond à une valeur spécifiée dans la liste DesiredValues (dans ce cas, running). L'étape répète le processus jusqu'à ce que la réponse renvoie l'état d'instance running.

Utilisation de JSONPath dans des runbooks

Une expression JSONPath est une chaîne commençant par « $. » qui est utilisée pour sélectionner un ou plusieurs composants d'un élément JSON. La liste suivante inclut des informations sur les opérateurs JSONPath qui sont pris en charge par Systems Manager Automation :

Enfant à notation point (.) : à utiliser avec un objet JSON. Cet opérateur sélectionne la valeur d'une clé spécifique.
Analyse approfondie (..) : à utiliser avec un élément JSON. Cet opérateur numérise l'élément JSON niveau par niveau et sélectionne une liste de valeurs avec la clé spécifique. Le type de retour de cet opérateur est toujours un tableau JSON. Dans le contexte d'une action d'automatisation comme type de sortie, l'opérateur peut être soit StringList, soit MapList.
Index de tableau ([]) : à utiliser avec un tableau JSON. Cet opérateur obtient la valeur d'un index spécifique.
Filtre ([?(expression)]) : à utiliser avec un tableau JSON. Cet opérateur filtre les valeurs des tableaux JSON qui correspondent aux critères définis dans l’expression du filtre. Les expressions de filtre ne peuvent utiliser que les opérateurs suivants : ==, ! =, >, <, >= ou <=. La combinaison de plusieurs expressions de filtre avec AND (&&) ou OR (||) n’est pas prise en charge. Le type de retour de cet opérateur est toujours un tableau JSON.

Pour mieux comprendre les opérateurs JSONPath, examinez la réponse JSON suivante à partir de l'opération d'API EC2 DescribeInstances. À la suite de cette réponse figurent plusieurs exemples qui illustrent différents résultats en appliquant différentes expressions JSONPath à la réponse à partir de l'opération d'API DescribeInstances.

{
    "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": []
        }
    ]
}

Exemple JSONPath 1 : obtention d'une chaîne spécifique à partir d'une réponse JSON


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

Returns:
"ami-12345678"

Type: String

Exemple JSONPath 2 : obtention d'une valeur booléenne spécifique à partir d'une réponse JSON


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

Type: Boolean

Exemple JSONPath 3 : obtention d'un entier spécifique à partir d'une réponse JSON


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

Type: Integer

Exemple JSONPath 4 : analyse approfondie d'une réponse JSON, puis obtention de toutes les valeurs pour VolumeId en tant que StringList


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

Type: StringList

Exemple JSONPath 5 : obtention d'un objet BlockDeviceMappings spécifique en tant que StringMap


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

Type: StringMap

Exemple JSONPath 6 : analyse approfondie d'une réponse JSON, puis obtention de touts les objets d'état en tant que MapList


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

Type: MapList

JSONPath exemple 7 : filtre pour les instances dans l’état running


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 exemple 8 : renvoie le ImageId des instances qui ne sont pas dans l’état running


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

Returns:
[
  "ami-12345678"
]

Type: StringList | String

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Utilisation d'instructions conditionnelles dans les runbooks

Création d'intégrations webhook pour Automation