• O AWS Systems Manager CloudWatch Dashboard não estará mais disponível a partir de 30 de abril de 2026. Os clientes podem continuar usando o console do Amazon CloudWatch para visualizar, criar e gerenciar os painéis do Amazon CloudWatch exatamente como fazem hoje. Para obter mais informações, consulte a [documentação do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# 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](#branch-runbook-examples).
## 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](#branch-action-output).
+ **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.
------
#### [ YAML ]
```
mainSteps:
- name: step name
action: aws:branch
inputs:
Choices:
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
Default:
step to jump to if all choices are false
```
------
#### [ JSON ]
```
{
"mainSteps":[
{
"name":"a name for the step",
"action":"aws:branch",
"inputs":{
"Choices":[
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
},
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
}
],
"Default":"step to jump to if all choices are false"
}
}
]
}
```
------
#### 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": "\$1\$1describeInstance.Platform\$1\$1"* é 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
...
```