Utilizzo della variabile JSONPath nei runbook

Utilizzo degli output delle operazioni come input

Diverse azioni di automazione restituiscono output predefiniti. Puoi passare questi output come input ai passaggi successivi nel runbook usando il formato {{stepName.outputName}}. Puoi inoltre definire output personalizzati per varie azioni di automazione nei tuoi runbook. Ciò consente di eseguire script o richiamare operazioni API per altre AWS servizi volte in modo da poter riutilizzare i valori come input nelle azioni successive. I tipi di parametri nei runbook sono statici. Ciò significa che il tipo di parametro non può essere modificato dopo che è stato definito. Per definire l'output di un passaggio, completa i seguenti campi:

Nome (obbligatorio): il nome dell'output utilizzato per fare riferimento al valore di output nei passaggi successivi.
Selettore (obbligatorio): l'espressione JSONPath utilizzata per determinare il valore di output.
Tipo: (facoltativo) il tipo di dati del valore restituito dal campo del selettore. I valori di tipo validi sono String, Integer, Boolean, StringList, StringMap, MapList. Il valore predefinito è String.

Se il valore di un output non corrisponde al tipo di dati specificato, Automation prova a convertire il tipo di dati. Ad esempio, se il valore restituito è un Integer, ma il Type specificato è String, allora il valore dell'output finale è un valore String. Sono supportati i seguenti tipi di conversione:

I valori String possono essere convertiti in StringList, Integer e Boolean.
I valori Integer possono essere convertiti in String, e StringList.
I valori Boolean possono essere convertiti in String, e StringList.
I valori StringList, IntegerList o BooleanList contenenti un elemento possono essere convertiti in StringInteger o Boolean.

Quando si utilizzano parametri o output con azioni di automazione, il tipo di dati non può essere modificato dinamicamente all'interno dell'input di un'azione.

Di seguito è riportato un runbook di esempio che illustra come definire gli output delle operazioni e come utilizzare tale valore come input per un'operazione successiva. l runbook eseguono le operazioni seguenti:

Utilizza l'aws:executeAwsApiazione per richiamare l'operazione dell' DescribeImages API Amazon EC2 per ottenere il nome di uno specifico Windows Server 2016. AMI Restituisce l'ID immagine come ImageId.
Utilizza l'aws:executeAwsApiazione per richiamare l'operazione dell' RunInstances API Amazon EC2 per avviare un'istanza che utilizza l'operazione del ImageId passaggio precedente. Restituisce l'ID di istanza come InstanceId.
Utilizza l' aws:waitForAwsResourcePropertyazione per eseguire il polling dell'operazione dell'API Amazon DescribeInstanceStatus EC2 per attendere che l'istanza running raggiunga lo stato. Il timeout dell'operazione è pari a 60 secondi. Si verifica il timeout della fase se l'istanza non raggiunge lo stato running dopo 60 secondi dall'avvio del polling.
Utilizza l'operazione aws:assertAwsResourceProperty per chiamare l'operazione API DescribeInstanceStatus di Amazon EC2 per affermare che l'istanza si trova nello stato running. La fase ha esito negativo se lo stato dell'istanza non è 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"
...

Ciascuna delle operazioni di automazione precedentemente descritte consente di chiamare un'operazione API specifica specificando lo spazio dei nomi del servizio, il nome dell'operazione API, i parametri di input e i parametri di output. Gli input vengono definiti dall'operazione API selezionata. Puoi visualizzare le operazioni API (definite anche metodi) scegliendo un servizio nel pannello di navigazione a sinistra nella pagina Services Reference (Informazioni di riferimento relative ai servizi). Scegliere un metodo nella sezione Client del servizio che si desidera chiamare. Ad esempio, tutte le operazioni API (metodi) per Amazon Relational Database Service (Amazon RDS) sono elencate nella seguente pagina: Amazon RDS methods (Metodi di Amazon RDS).

Puoi visualizzare lo schema per ciascuna operazione di automazione nelle seguenti posizioni:

Gli schemi includono le descrizioni dei campi obbligatori per l'utilizzo di ciascuna operazione.

Utilizzo dei campi Selector/ PropertySelector

Per ogni azione di automazione è necessario specificare un output Selector (per aws:executeAwsApi) o un PropertySelector (per aws:assertAwsResourceProperty e aws:waitForAwsResourceProperty). Questi campi vengono utilizzati per elaborare la risposta JSON da un' AWS operazione API. Questi campi utilizzano la sintassi JSONPath.

Ecco un esempio che illustra questo concetto per l'operazione 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"
...

Nella fase aws:executeAwsApi dell'elemento getImageId, l'automazione richiama l'operazione API DescribeImages e riceve una risposta da ec2. L'automazione applica quindi Selector - "$.Images[0].ImageId" alla risposta API e assegna il valore selezionato alla variabile di output ImageId. Altre fasi della stessa automazione possono utilizzare il valore di ImageId specificando "{{ getImageId.ImageId }}".

Ecco un esempio che illustra questo concetto per l'operazione 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
...

Nella fase aws:waitForAwsResourceProperty dell'elemento waitUntilInstanceStateRunning, l'automazione richiama l'operazione API DescribeInstanceStatus e riceve una risposta da ec2. L'automazione applica quindi PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" alla risposta e verifica se il valore restituito specificato corrisponde a un valore nell'elenco DesiredValues (in questo caso running). La fase ripete il processo finché la risposta non restituisce lo stato di istanza running.

Utilizzo della variabile JSONPath nei runbook

Un'espressione JSONPath è una stringa che inizia con «$». utilizzato per selezionare uno o più componenti all'interno di un elemento JSON. L'elenco seguente include informazioni sugli operatori JSONPath supportati dal servizio di automazione di Systems Manager:

Dot-notated child (.): da utilizzare con un oggetto JSON. Questo operatore seleziona il valore di una chiave specifica.
Deep-scan (..): da utilizzare con un elemento JSON. Questo operatore analizza il livello dell'elemento JSON per livello e seleziona un elenco di valori con la chiave specificata. Si noti che il tipo restituito di questo operatore è sempre un array JSON. Nel contesto di un tipo di output di un'azione di automazione, l'operatore può essere uno StringList o MapList.
Array-Index ([ ]): da utilizzare con un array JSON. Questo operatore recupera il valore di un indice specifico.
Filter ([?(espressione)]): da utilizzare con un array JSON. Questo operatore filtra i valori dell'array JSON che corrispondono ai criteri definiti nell'espressione del filtro. Le espressioni di filtro possono utilizzare solo i seguenti operatori: ==, !=, >, <, >= o <=. La combinazione di più espressioni di filtro con AND (&&) o OR (||) non è supportata. Si noti che il tipo restituito di questo operatore è sempre un array JSON.

Per comprendere meglio gli operatori JSONPath, analizzare la seguente risposta JSON dell'operazione API ec2 DescribeInstances. Dopo questa risposta sono disponibili alcuni esempi che illustrano i vari risultati derivanti dall'applicazione di diverse espressioni JSONPath alla risposta dell'operazione 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": []
        }
    ]
}

Esempio JSONPath 1: recupero di una stringa specifica da una risposta JSON


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

Returns:
"ami-12345678"

Type: String

Esempio JSONPath 2: recupero di un valore booleano specifico da una risposta JSON


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

Type: Boolean

Esempio JSONPath 3: recupero di un valore intero specifico da una risposta JSON


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

Type: Integer

Esempio 4 di JsonPath: esegue una scansione approfondita di una risposta JSON, quindi ottieni tutti i valori per VolumeId StringList


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

Type: StringList

Esempio JsonPath 5: ottieni un oggetto specifico come BlockDeviceMappings StringMap


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

Type: StringMap

Esempio 6 di JsonPath: scansiona in profondità una risposta JSON, quindi ottieni tutti gli oggetti State come MapList


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

Type: MapList

Esempio 7 di JSONPath: filtro per le istanze nello stato 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

Esempio 8 di JSONPath: restituisce ImageId per le istanze che non si trovano nello stato running


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

Returns:
[
  "ami-12345678"
]

Type: StringList | String

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Utilizzo di istruzioni condizionali nei runbook

Creazione di integrazioni webhook per Automazione