Trabalhar com a ação aws:branch Exemplos de como usar opções condicionais

Uso de instruções condicionais em runbooks

Por padrão, as etapas que você define na seção mainSteps de um runbook são executadas em ordem sequencial. Depois que uma ação é concluída, a próxima ação especificada na seção mainSteps começa. Além disso, se uma ação falhar, todo a automação falhará (por padrão). Você pode usar a ação de automação aws:branch e as opções do runbook descritas nesta seção para criar automações que executam ramificações condicionais. Isso significa que você pode criar fluxos automações que vão para outra etapa após avaliar diferentes escolhas ou que dinamicamente respondem a alterações quando uma etapa é concluída. Veja a seguir uma lista de opções que você pode usar para criar fluxos de trabalho de automação dinâmicos:

aws:branch: esta ação de automação permite que você crie a automação dinâmica que avalia várias opções em uma única etapa e, em seguida, salta para outra etapa no runbook com base nos resultados da avaliação.
nextStep: esta opção especifica qual etapa de uma automação deve ser processada imediatamente após a conclusão bem-sucedida de uma etapa.
isEnd: esta opção interrompe a execução de uma automação no final de determinada etapa. O valor padrão desta opção é falso.
isCritical: esta opção designa uma etapa como essencial para a conclusão bem-sucedida da automação. Se uma etapa com essa designação falhar, o Automation relatará o status final da automação como Failed. O valor padrão desta opção é true.
onFailure: esta opção indica se a automação deve ser anulada, deve continuar ou seguir para outra etapa, em caso de falha. O valor padrão desta opção é anular.

A seção a seguir descreve a ação de automação aws:branch. Para obter mais informações sobre as opções do nextStep, isEnd, isCritical e onFailure, consulte Runbooks aws:branch de exemplo.

Trabalhar com a ação `aws:branch`

A ação aws:branch oferece as opções de ramificação condicional mais dinâmicas para automações. Como mencionado anteriormente, essa ação permite que a automação avalie várias condições em uma única etapa e depois vá para uma nova etapa com base nos resultados da avaliação. A ação aws:branch funciona como uma instrução IF-ELIF-ELSE na programação.

Veja a seguir um exemplo de YAML de uma etapa aws:branch:


- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

Quando você especifica a ação aws:branch para uma etapa, você especifica as Choices que a automação deve avaliar. A automação pode avaliar as Choices com base no valor de um parâmetro especificado na seção Parameters do runbook. A automação também pode avaliar as Choices com base no resultado de uma etapa anterior.

A automação avalia cada opção usando uma expressão booleana. Se a avaliação determinar que a primeira opção é true, a automação pulará para a etapa designada para essa opção. Se a avaliação determinar que a primeira opção é false, a automação avaliará a próxima opção. Se a sua etapa inclui três Choices ou mais, a automação avaliará cada opção em ordem sequencial até avaliar uma opção que seja true. A automação pula para a etapa designada para a opção true.

Se nenhuma das Choices for true, a automação verificará se a etapa contém um valor Default. Um valor Default define uma etapa para a qual a automação deve saltar, se nenhuma das opções for true. Se nenhum valor Default for especificado para a etapa, a automação processará a próxima etapa no runbook.

Aqui está uma etapa aws:branch em YAML chamada chooseOSfromParameter. A etapa inclui duas Choices: (NextStep: runWindowsCommand) e (NextStep: runLinuxCommand). A automação avalia essas Choices para determinar qual comando deve ser executado para o sistema operacional apropriado. A Variable para cada opção usa {{OSName}}, que é um parâmetro que o autor do runbook definiu na seção Parameters do runbook.


mainSteps:
- name: chooseOSfromParameter
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OSName}}"
      StringEquals: Windows
    - NextStep: runLinuxCommand
      Variable: "{{OSName}}"
      StringEquals: Linux

Aqui está uma etapa aws:branch em YAML chamada chooseOSfromOutput. A etapa inclui duas Choices: (NextStep: runPowerShellCommand) e (NextStep: runShellCommand). A automação avalia essas Choices para determinar qual comando deve ser executado para o sistema operacional apropriado. A Variable para cada opção usa {{GetInstance.platform}}, que é o resultado de uma etapa anterior no runbook. Este exemplo também inclui uma opção chamada Default. Se a automação avaliar as duas Choices, e nenhuma opção for true, a automação pulará para uma etapa chamada PostProcessing.


mainSteps:
- name: chooseOSfromOutput
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

Criar uma etapa `aws:branch` em um runbook

Quando você cria uma etapa aws:branch em um runbook, você define as Choices que a automação deve avaliar para determinar a etapa que a automação deve passar em seguida. Como mencionado anteriormente, Choices são avaliadas usando uma expressão booliana. Cada opção deve definir as seguintes opções:

NextStep: a próxima etapa no runbook para processar se a opção designada é true.
Variável: especifique o nome de um parâmetro definido na seção Parameters do runbook, uma variável definida na seção Variables ou especifique um objeto de saída de uma etapa anterior.

Especifique valores de variáveis usando o formato a seguir.

Variable: "{{variable name}}"

Especifique valores de parâmetros usando o formato a seguir.

Variable: "{{parameter name}}"

Especifique variáveis de objetos de saída usando o seguinte formato:

Variable: "{{previousStepName.outputName}}"

nota
A criação da variável de saída é descrita em mais detalhes na próxima seção, Sobre a criação de variáveis de saída.
Operação: os critérios usados para avaliar a escolha, como StringEquals: Linux. A ação aws:branch oferece suporte às seguintes operações:
Operações de string
- StringEquals
- EqualsIgnoreCase
- StartsWith
- EndsWith
- Contém
Operações numéricas
- NumericEquals
- NumericGreater
- NumericLesser
- NumericGreaterOrEquals
- NumericLesser
- NumericLesserOrEquals
Operação booleana
- BooleanEquals
Importante
Quando você cria um runbook, o sistema valida cada operação dele. Se uma operação não for suportada, o sistema retornará um erro ao tentar criar o runbook.
Padrão: especifique uma etapa de contingência para a qual a automação deve ir se nenhuma das Choices for true.

nota
Se você não quiser especificar um valor Default, especifique a opção isEnd. Se nenhuma das Choices for true e nenhum valor Default for especificado, a automação será interrompida no final da etapa.

Use os modelos a seguir para ajudar a construir a etapa aws:branch no runbook. Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

Sobre a criação de variáveis de saída

Para criar uma opção aws:branch que faz referência à saída de uma etapa anterior, você precisa identificar o nome da etapa anterior e o nome do campo de saída. Você então combina os nomes da etapa e o campo usando o seguinte formato:

Variable: "{{previousStepName.outputName}}"

Por exemplo, a primeira etapa do exemplo a seguir é chamada de GetInstance. Depois, em outputs, há um campo chamado platform. Na segunda etapa (ChooseOSforCommands), o autor deseja fazer referência à saída do campo de plataforma como uma variável. Para criar a variável, basta combinar o nome da etapa (GetInstance) e o nome do campo de saída (plataforma) para criar Variable: "{{GetInstance.platform}}".


mainSteps:
- Name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
    Filters:
    - Key: InstanceIds
      Values: ["{{ InstanceId }}"]
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep

Aqui está um exemplo que mostra como "Variable": "{{describeInstance.Platform}}" é criado na etapa anterior e na saída.


- name: describeInstance
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: DescribeInstances
    InstanceIds:
    - "{{ InstanceId }}"
  outputs:
  - Name: Platform
    Selector: "$.Reservations[0].Instances[0].Platform"
    Type: String
  nextStep: branchOnInstancePlatform
- name: branchOnInstancePlatform
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runEC2RescueForWindows
      Variable: "{{ describeInstance.Platform }}"
      StringEquals: windows
    Default: runEC2RescueForLinux

Runbooks `aws:branch` de exemplo

Aqui estão alguns exemplos de runbooks que usam o aws:branch.

Exemplo 1: usar aws:branch com uma variável de saída para executar comandos com base no tipo de sistema operacional

Na primeira etapa deste exemplo (GetInstance), o autor do runbook usa a ação aws:executeAwsApi para chamar a operação de API ssm DescribeInstanceInformation. O autor usa essa ação para determinar o tipo de sistema operacional que está sendo usado por uma instância. A ação aws:executeAwsApi emite o ID da instância e o tipo de plataforma.

Na segunda etapa (ChooseOSforCommands), o autor usa a ação aws:branch com duas Choices (NextStep: runPowerShellCommand) e (NextStep: runShellCommand). A automação avalia o sistema operacional da instância usando o resultado da etapa anterior (Variable: "{{GetInstance.platform}}"). A automação pula para uma etapa do sistema operacional designado.


---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
mainSteps:
- name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep
- name: runShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runPowerShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunPowerShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

Exemplo 2: usar aws:branch com uma variável de parâmetro para executar comandos com base no tipo de sistema operacional

O autor do runbook define várias opções de parâmetro no início do runbook, na seção parameters. Um parâmetro é chamado de OperatingSystemName. Na primeira etapa (ChooseOS), o autor usa a ação aws:branch com duas Choices (NextStep: runWindowsCommand) e (NextStep: runLinuxCommand). A variável para essas Choices faz referência à opção de parâmetro especificada na seção de parâmetros (Variable: "{{OperatingSystemName}}"). Quando o usuário executa esse runbook, ele especifica um valor em runtime para OperatingSystemName. A automação usa o parâmetro de runtime durante a avaliação das Choices. A automação pula para uma etapa do sistema operacional designado com base no parâmetro do runtime para OperatingSystemName.


---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
  OperatingSystemName:
    type: String
  LinuxInstanceId:
    type: String
  WindowsInstanceId:
    type: String
mainSteps:
- name: ChooseOS
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: windows
    - NextStep: runLinuxCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: linux
    Default:
      Sleep
- name: runLinuxCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunShellScript"
    InstanceIds:
    - "{{LinuxInstanceId}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runWindowsCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunPowerShellScript"
    InstanceIds:
    - "{{WindowsInstanceId}}"
    Parameters:
      commands:
      - date
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

Criar automações de ramificação complexas com operadores

Você pode criar automações de ramificação complexas usando os operadores And, Or, e Not em suas etapas aws:branch.

O operador 'And' (‘E’)

Use o operador And quando você quiser que muitas variáveis sejam true para uma opção. No exemplo a seguir, a primeira opção avalia se uma instância está running e usa o sistema operacional Windows. Se a avaliação de ambas as variáveis for verdadeira, a automação pulará para a etapa runPowerShellCommand. Se uma ou mais das variáveis for false, a automação avaliará as variáveis para a segunda opção.


mainSteps:
- name: switch2
  action: aws:branch
  inputs:
    Choices:
    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Windows
      NextStep: runPowerShellCommand

    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Linux
      NextStep: runShellCommand
    Default:
      sleep3

O operador 'Or' (‘Ou’)

Use o operador Or quando você quiser que qualquer de diversas variáveis sejam verdadeiras para uma opção. No exemplo a seguir, a primeira opção avalia se uma string de parâmetro é Windows e se a saída de uma etapa AWS Lambda é verdadeira. Se a avaliação determinar que qualquer uma das variáveis é verdadeira, a automação pulará para a etapa RunPowerShellCommand. Se as duas variáveis forem falsas, a automação avaliará as variáveis para a segunda opção.


- Or:
  - Variable: "{{parameter1}}"
    StringEquals: Windows
  - Variable: "{{BooleanParam1}}"
    BooleanEquals: true
  NextStep: RunPowershellCommand
- Or:
  - Variable: "{{parameter2}}"
    StringEquals: Linux
  - Variable: "{{BooleanParam2}}"
    BooleanEquals: true
  NextStep: RunShellScript

O operador 'Not' (‘Não’)

Use o operador Not quando você desejar pular para uma etapa definida quando uma variável não for verdadeira. No exemplo a seguir, a primeira opção avalia se uma string de parâmetro é Not Linux. Se a avaliação determinar que a variável não é Linux, a automação pulará para a etapa sleep2. Se a avaliação da primeira opção determinar que ela é Linux, a automação avaliará a próxima opção.


mainSteps:
- name: switch
  action: aws:branch
  inputs:
    Choices:
    - NextStep: sleep2
      Not:
        Variable: "{{testParam}}"
        StringEquals: Linux
    - NextStep: sleep1
      Variable: "{{testParam}}"
      StringEquals: Windows
    Default:
      sleep3

Exemplos de como usar opções condicionais

Esta seção inclui vários exemplos de como usar as opções dinâmicas em um runbook. Cada exemplo nesta seção estende o seguinte runbook: Este runbook tem duas ações. A primeira ação é chamada de InstallMsiPackage. Ela usa a ação aws:runCommand para instalar um aplicativo em uma instância do Windows Server. A segunda ação é chamada de TestInstall. Ela usa a ação aws:invokeLambdaFunction para executar um teste do aplicativo instalado, se o aplicativo foi instalado com êxito. A etapa um especifica onFailure: Abort. Isso significa que, se a instalação da aplicação não foi bem-sucedida, a automação será interrompida antes da segunda etapa.

Exemplo 1: runbook com duas ações lineares


---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
  automationAssumeRole:
    type: String
    description: "(Required) Assume role."
  packageName:
    type: String
    description: "(Required) MSI package to be installed."
  instanceIds:
    type: String
    description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
  action: aws:runCommand
  maxAttempts: 2
  onFailure: Abort
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
...

Criar uma automação dinâmica que pula para etapas diferentes usando a opção onFailure

O exemplo a seguir usa as opções onFailure: step:step name, nextStep e isEnd para criar uma automação dinâmica. Nesse exemplo, se a ação InstallMsiPackage falhar, a automação saltará para uma ação chamada PostFailure (onFailure: step:PostFailure) para executar uma função do AWS Lambda, a fim de realizar alguma ação no evento em que a instalação falhou. Se a instalação for bem-sucedida, o processo de automação pulará para a ação TestInstall (nextStep: TestInstall). Ambas as etapas TestInstall e PostFailure usam a opção isEnd (isEnd: true) para que a automação termine quando uma dessas etapas for concluída.

nota

O uso da opção isEnd na última etapa da seção mainSteps é opcional. Se a última etapa não pular para outras etapas, a automação será interrompida depois de executar a ação na última etapa.

Exemplo 2: automação dinâmica que salta para diferentes etapas


mainSteps
- name: InstallMsiPackage
  action: aws:runCommand
  onFailure: step:PostFailure
  maxAttempts: 2
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
  nextStep: TestInstall
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
  isEnd: true
- name: PostFailure
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: PostFailureRecoveryLambdaFunction
  isEnd: true
...

nota

Antes de processar um runbook, o sistema verifica se o runbook não cria um loop infinito. Se um loop infinito for detectado, a automação retornará um erro e um círculo de rastreamento mostrando as etapas que criam o loop.

Criar uma automação dinâmica que define etapas essenciais

Você pode especificar que uma etapa é essencial para o sucesso geral da automação. Se uma etapa essencial falhar, o Automation informará o status da automação como Failed, mesmo se uma ou mais etapas forem executadas com êxito. No exemplo a seguir, o usuário identifica a etapa VerifyDependencies se a etapa InstallMsiPackage falhar (onFailure: step:VerifyDependencies). O usuário especifica que a etapa InstallMsiPackage não é essencial (isCritical: false). Neste exemplo, se o aplicativo falhar ao instalar, a automação processará a etapa VerifyDependencies para determinar se uma ou mais dependências estão ausentes, o que deve ter causado a falha na instalação do aplicativo.

Exemplo 3: definir as etapas essenciais para a automação


---
name: InstallMsiPackage
action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
  InstanceIds:
  - "{{instanceIds}}"
  DocumentName: AWS-RunPowerShellScript
  Parameters:
    commands:
    - msiexec /i {{packageName}}
nextStep: TestPackage
...

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Uso de scripts em runbooks

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

Uso de instruções condicionais em runbooks

Trabalhar com a ação aws:branch

Criar uma etapa aws:branch em um runbook

nota

Operações de string

Operações numéricas

Operação booleana

Importante

nota

Sobre a criação de variáveis de saída

Runbooks aws:branch de exemplo

Criar automações de ramificação complexas com operadores

O operador 'And' (‘E’)

O operador 'Or' (‘Ou’)

O operador 'Not' (‘Não’)

Exemplos de como usar opções condicionais

nota

nota

Trabalhar com a ação `aws:branch`

Criar uma etapa `aws:branch` em um runbook

Runbooks `aws:branch` de exemplo