Uso de salidas de acción como entradas - AWS Systems Manager

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