Uso de saídas de ações como entradas - AWS Systems Manager
Uso de JSONPath em runbooks

Uso de saídas de ações como entradas

Várias ações de automação retornam saídas predefinidas. Você pode passar essas saídas como entradas para etapas posteriores em seu runbook usando o formato {{stepName.outputName}}. Também é possível definir saídas personalizadas para várias ações de automação em seus runbooks. Isso permite que você execute scripts ou invoque operações de API para outros Serviços da AWS uma vez, para que você possa reutilizar os valores como entradas em ações posteriores. Os tipos de parâmetro em runbooks são estáticos. Isso significa que o tipo de parâmetro não pode ser alterado depois de definido. Para definir uma saída de etapa, forneça os seguintes campos:

  • Nome (obrigatório): o nome da saída usado para referenciar o valor de saída em etapas posteriores.

  • Seletor (obrigatório): a expressão JSONPath usada para determinar o valor de saída.

  • Tipo (opcional): o tipo de dados do valor retornado pelo campo seletor. Os valores de tipo válidos são String, Integer, Boolean, StringList ,StringMap, MapList. O valor padrão é String.

Se o valor de uma saída não corresponder ao tipo de dados que você especificou, o Automation tentará converter o tipo de dados. Por exemplo, se o valor retornado for um Integer, mas o Type especificado for String, o valor final da saída será um valor String. As seguintes conversões de tipos são permitidas:

  • Valores String podem ser convertidos em StringList, Integer e Boolean.

  • Valores Integer podem ser convertidos em String e StringList.

  • Valores Boolean podem ser convertidos em String e StringList.

  • Valores StringList, IntegerList ou BooleanList contendo um elemento podem ser convertidos em String, Integer ou Boolean.

Ao usar parâmetros ou saídas com ações de automação, o tipo de dados não pode ser alterado dinamicamente na entrada de uma ação.

Aqui está um exemplo de runbook que demonstra como definir saídas de ações e como referenciar o valor como entrada para uma ação posterior. Os runbooks fazem o seguinte:

  • Usa a ação aws:executeAwsApi para chamar a operação de API do Amazon EC2 DescribeImages para obter o nome de uma determinada AMI do Windows Server 2016. Ela gera o ID de imagem como ImageId.

  • Usa a ação aws:executeAwsApi para chamar a operação de API do Amazon EC2 RunInstances para iniciar uma instância que usa o ImageId da etapa anterior. Ela gera o ID de instância como InstanceId.

  • Usa a ação aws:waitForAwsResourceProperty para sondar a operação de API do Amazon EC2 DescribeInstanceStatus para aguardar que a instância alcance o estado running. A ação atinge o tempo limite em 60 segundos. A etapa atinge o limite de tempo se o estado da instância não chegar a running após 60 segundos de sondagem.

  • Usa a ação aws:assertAwsResourceProperty para chamar a operação da API DescribeInstanceStatus do Amazon EC2 para afirmar que a instância está no estado running. A etapa falhará se o estado da instância não for 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 uma das ações de automação descritas anteriormente permite que você chame uma operação de API específica, determinando o namespace do serviço, o nome da operação de API, os parâmetros de entrada e os parâmetros de saída. As entradas são definidas pela operação de API que você escolher. Você pode visualizar as operações de API (também chamadas de métodos), escolhendo um serviço na navegação à esquerda na seguinte página de Referência de serviços: Escolha um método na seção Client (Cliente) para o serviço que você deseja invocar. Por exemplo, todas as operações de API (métodos) do Amazon Relational Database Service (Amazon RDS) estão listadas na seguinte página: Amazon RDS methods (Métodos do Amazon RDS).

Você pode visualizar o esquema para cada ação de automação nos seguintes locais:

Os esquemas incluem as descrições dos campos obrigatórios para o uso de cada ação.

Usar os campos Selector/PropertySelector (Seletor/Seletor de propriedades)

Cada ação do Automation exige que você especifique uma saída Selector (paraaws:executeAwsApi) ou um PropertySelector (para aws:assertAwsResourceProperty e aws:waitForAwsResourceProperty). Esses campos são usados para processar a resposta do JSON de uma operação de API da AWS. Esses campos usam a sintaxe JSONPath.

Este é um exemplo para ajudar a ilustrar esse conceito para a ação 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"
...

Na etapa aws:executeAwsApi do getImageId, a automação invoca a operação da API DescribeImages e recebe uma resposta do ec2. A automação então aplica Selector - "$.Images[0].ImageId" à resposta da API e atribui o valor selecionado à variável ImageId do resultado. Outras etapas na mesma automação podem usar o valor de ImageId especificando "{{ getImageId.ImageId }}".

Este é um exemplo para ajudar a ilustrar esse conceito para a ação 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
...

Na etapa aws:waitForAwsResourceProperty do waitUntilInstanceStateRunning, a automação invoca a operação da API DescribeInstanceStatus e recebe uma resposta do ec2. Depois, a automação aplica PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" à resposta e verifica se o valor retornado corresponde a um valor na lista DesiredValues (neste caso, running). A etapa repetirá o processo até que a resposta retorne um estado de instância de running.

Uso de JSONPath em runbooks

Uma expressão JSONPath é uma string que começa com “$”. que é usado para selecionar um ou mais componentes em um elemento JSON. A lista a seguir inclui informações sobre operadores JSONPath que são compatíveis com o Systems Manager Automation:

  • Filho com notação de pontos (.): use com um objeto JSON. Esse operador seleciona o valor de uma chave específica.

  • Varredura profunda (..): use com um elemento JSON. Esse operador examina o elemento JSON nível por nível e seleciona uma lista de valores com a chave específica. O tipo de retorno desse operador é sempre uma matriz JSON. No contexto de um tipo de saída da etapa de automação, o operador pode ser StringList ou MapList.

  • Índice de matriz ([ ]): use com uma matriz JSON. Esse operador obtém o valor de um índice específico.

  • Filtro ([?(expression)]): use com uma matriz JSON. Esse operador filtra os valores da matriz JSON que correspondem aos critérios definidos na expressão do filtro. As expressões de filtro só podem usar os seguintes operadores: ==, !=, >, <, >= ou <=. A combinação de várias expressões de filtro com AND (&&) ou OR (||) não é possível. O tipo de retorno desse operador é sempre uma matriz JSON.

Para compreender melhor os operadores JSONPath, revise a seguinte resposta do JSON da operação de API DescribeInstances do ec2. Abaixo dessa resposta estão vários exemplos que mostram resultados diferentes aplicando diferentes expressões JSONPath à com base na operação da 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": []
        }
    ]
}

Exemplo 1 do JSONPath: obtenha uma string específica de uma resposta JSON

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

Returns:
"ami-12345678"

Type: String

Exemplo 2 do JSONPath: obtenha um booliano específico de uma resposta JSON

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

Type: Boolean

Exemplo 3 do JSONPath: obtenha um número inteiro específico de uma resposta JSON

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

Type: Integer

Exemplo 4 do JSONPath: faça uma verificação detalhada de uma resposta JSON e, em seguida, obtenha todos os valores para VolumeId como uma StringList 

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

Type: StringList

Exemplo 5 do JSONPath: obter um objeto específico BlockDeviceMappings como um StringMap

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

Type: StringMap

Exemplo 6 do JSONPath: faça uma verificação detalhada de uma resposta JSON e, em seguida, obtenha todos os objetos de estado como uma MapList

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

Type: MapList

Exemplo 7 do JSONPath: filtro para instâncias no estado 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

Exemplo 8 do JSONPath: retornar o ImageId de instâncias que não estão no estado running

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

Returns:
[
  "ami-12345678"
]

Type: StringList | String