Uso de JSONPath en un manual de procedimientos

Uso de salidas de acción como entradas

Varias acciones de automatización devuelven salidas predefinidas. Puede pasar estas salidas como entradas a pasos posteriores de su manual de procedimientos utilizando el formato {{stepName.outputName}}. También puede definir salidas personalizadas para las acciones de automatización en sus manuales de procedimientos. Esto le permite ejecutar scripts o invocar operaciones API para otros Servicios de AWS una vez para que pueda reutilizar los valores como entradas en acciones posteriores. Los tipos de parámetros de los manuales de procedimientos son estáticos. Esto significa que el tipo de parámetro no se puede cambiar después de definirlo. Para definir la salida de un paso, proporcione los siguientes campos:

Nombre: (Requeridas) El nombre de la salida que se utiliza para hacer referencia al valor de salida en los pasos posteriores.
Selector: (Requerido) La expresión JSONPath que se utiliza para determinar el valor de salida.
Tipo: (Opcional) El tipo de datos del valor devuelto por el campo selector. Los tipo de valores válidos son String, Integer, Boolean, StringList, StringMap, MapList. El valor predeterminado es String.

Si el valor de una salida no coincide con el tipo de datos que especificó, la automatización intentará convertir el tipo de datos. Por ejemplo, si el valor devuelto es un Integer, pero el valor Type especificado es String, el valor de salida final es un valor String. Las siguientes conversiones de tipos son compatibles:

Los valores String se pueden convertir en StringList, Integer y Boolean.
Los valores Integer se pueden convertir en String y StringList.
Los valores Boolean se pueden convertir en String y StringList.
Los valores StringList, IntegerList, o BooleanList que contienen un elemento se pueden convertir en String, Integer, o Boolean.

Cuando se utilizan parámetros con acciones de automatización, el tipo de parámetro no se puede cambiar dinámicamente dentro de la entrada de una acción.

Este es un ejemplo de un manual de procedimientos que demuestra cómo definir salidas de acción y hacer referencia al valor como entrada para una acción posterior. El manual de procedimientos hace lo siguiente:

Utiliza la acción aws:executeAwsApi para llamar a la operación de la API de Amazon EC2 DescribeImages a fin de obtener el nombre de una AMI de Windows Server 2016 específica. Da como salida el ID de la imagen como ImageId.
Utiliza la acción aws:executeAwsApi para llamar a la operación de la API de Amazon EC2 RunInstances a fin de lanzar una instancia que utiliza el ImageId del paso anterior. Da como salida el ID de la instancia como InstanceId.
Utiliza la acción aws:waitForAwsResourceProperty para sondear la operación de API de Amazon EC2 DescribeInstanceStatus a fin de esperar hasta que la instancia alcance el estado running. La acción agota el tiempo de espera en 60 segundos. El paso agota el tiempo de espera si el estado de la instancia no consigue alcanzar el estado running después de 60 segundos de sondeo.
Usa la acción aws:assertAwsResourceProperty para llamar a la operación de la API de Amazon EC2 DescribeInstanceStatus y confirmar que la instancia se encuentra en estado running. El paso presenta un error si el estado de la instancia no es 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"
...

Cada una de las acciones de automatización descritas anteriormente le permiten llamar una operación de la API determinada mediante la especificación del espacio de nombres de servicio, el nombre de la operación de la API, los parámetros de entrada y los parámetros de salida. Las entradas se definen con la operación de la API que elija. Puede ver las operaciones de la API (también llamadas métodos) si elige un servicio en el panel de navegación ubicado a la izquierda, en la siguiente página: Services Reference. Elija un método en la sección Cliente para el servicio que desea invocar. Por ejemplo, todas las operaciones de la API (los métodos) para Amazon Relational Database Service (Amazon RDS) se indican en la siguiente página: métodos de Amazon RDS.

Puede ver el esquema para cada acción de automatización en las siguientes ubicaciones:

Los esquemas incluyen descripciones de los campos obligatorios para utilizar cada acción.

Uso de los campos Selector/PropertySelector

Cada acción de Automation requiere que especifique una salida Selector (para aws:executeAwsApi) o un PropertySelector (para aws:assertAwsResourceProperty y aws:waitForAwsResourceProperty). Estos campos se utilizan para procesar la respuesta JSON desde una operación de la API de AWS. Estos campos utilizan la sintaxis de JSONPath.

A continuación, se muestra un ejemplo que tiene como objetivo ilustrar este concepto para la acción 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"
...

En aws:executeAwsApi del paso getImageId, la automatización invoca la operación de la API DescribeImages y recibe una respuesta de ec2. A continuación, la automatización aplica Selector - "$.Images[0].ImageId" a la respuesta de la API y asigna el valor seleccionado a la variable ImageId de salida. Otros pasos de la misma automatización pueden utilizar el valor de ImageId especificando "{{ getImageId.ImageId }}".

A continuación, se muestra un ejemplo que tiene como objetivo ilustrar este concepto para la acción 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
...

En aws:waitForAwsResourceProperty del paso waitUntilInstanceStateRunning, la automatización invoca la operación de la API DescribeInstanceStatus y recibe una respuesta de ec2. La automatización aplica PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" a la respuesta y comprueba si el valor devuelto especificado coincide con un valor en la lista DesiredValues (en este caso, running). El paso repite el proceso hasta que la respuesta devuelve un estado de instancia de running.

Uso de JSONPath en un manual de procedimientos

Una expresión JSONPath es una cadena que comienza con “$” que se utiliza para seleccionar uno de varios componentes dentro de un elemento JSON. La siguiente lista incluye información sobre los operadores de JSONPath que Automatización de Systems Manager admite:

Elemento secundario con notación de puntos (.): utilizar con un objeto JSON. Este operador selecciona el valor de una clave específica.
Análisis profundo (..): utilizar con un elemento JSON. Este operador analiza el nivel de elemento JSON por nivel y selecciona una lista de valores con la clave específica. El tipo de retorno de este operador siempre es una matriz JSON. En el contexto de un tipo de salida de la acción de automatización, el operador puede ser StringList o MapList.
Índice de matriz ([ ]): utilizar con una matriz JSON. Este operador obtiene el valor de un índice específico.
Filtro ([?(expresión)]): se usa con una matriz JSON. Este operador filtra los valores de la matriz JSON que coinciden con los criterios definidos en la expresión de filtro. Las expresiones de filtro solo pueden utilizar los siguientes operadores: ==,! =, >, <, >= o <=. La combinación de varias expresiones de filtro con AND (&&) u OR (||) no es compatible. El tipo de retorno de este operador siempre es una matriz JSON.

Para comprender mejor los operadores de JSONPath, revise la siguiente respuesta de JSON de la operación de la API de EC2 DescribeInstances. Debajo de esta respuesta se muestran algunos ejemplos con resultados diferentes si se aplican distintas expresiones JSONPath a la respuesta de la operación de la 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": []
        }
    ]
}

Ejemplo de JSONPath 1: obtener una cadena específica de una respuesta de JSON


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

Returns:
"ami-12345678"

Type: String

Ejemplo de JSONPath 2: obtener un booleano específico de una respuesta de JSON


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

Type: Boolean

Ejemplo de JSONPath 3: obtener un entero específico de una respuesta de JSON


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

Type: Integer

Ejemplo de JSONPath 4: analizar en profundidad una respuesta de JSON y, a continuación, obtener todos los valores para VolumeId como una StringList


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

Type: StringList

Ejemplo de JSONPath 5: obtener un objeto BlockDeviceMappings como un StringMap


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

Type: StringMap

Ejemplo de JSONPath 6: analizar en profundidad una respuesta de JSON y, a continuación, obtener todos los objetos de estado como una MapList


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

Type: MapList

Ejemplo 7 de JSONPath: filtro para instancias en el running estado


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

Ejemplo 8 de JSONPath: devuelve el ImageId de instancias que no están en el running estado


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

Returns:
[
  "ami-12345678"
]

Type: StringList | String

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Uso de instrucciones condicionales en manuales de procedimientos

Crear integraciones webhook para Automation