As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Use a estrutura de documentos de AWSTOE componentes para componentes personalizados Para criar um componente usando a estrutura de componentes AWS Task Orchestrator and Executor (AWSTOE), você deve fornecer um documento baseado em YAML que represente as fases e etapas que se aplicam ao componente criado. Serviços da AWS use seu componente ao criar uma nova Amazon Machine Image (AMI) ou imagem de contêiner. **Topics** + [Fluxo de trabalho do documento de componente](#component-doc-workflow) + [Registro em log do componente](#component-logging) + [Encadeamento de entrada e saída](#document-chaining) + [Esquema e definições do documento](#document-schema) + [Documentos de exemplo](#document-example) + [Usar variáveis em seu documento de componente personalizado](toe-user-defined-variables.md) + [Use construções condicionais em AWSTOE](toe-conditional-constructs.md) + [Use operadores de comparação em documentos de AWSTOE componentes](toe-comparison-operators.md) + [Use operadores lógicos em documentos de AWSTOE componentes](toe-logical-operators.md) + [Use construções em loop em AWSTOE](toe-looping-constructs.md) ## Fluxo de trabalho do documento de componente O documento do AWSTOE componente usa fases e etapas para agrupar tarefas relacionadas e organizar essas tarefas em um fluxo de trabalho lógico para o componente. **dica** O serviço que usa seu componente para criar uma imagem pode implementar regras sobre quais fases usar no processo de criação e quando essas fases podem ser executadas. É importante considerar isso ao projetar seu componente. **Fases** As fases representam a progressão do seu fluxo de trabalho por meio do processo de compilação da imagem. Por exemplo, o serviço Image Builder usa as fases `build` e `validate` durante seu *estágio de compilação* para as imagens que ele produz. Ele usa as fases `test` e `container-host-test` durante o *estágio de teste* para garantir que o snapshot da imagem ou a imagem do contêiner produza os resultados esperados antes de criar a AMI final ou distribuir a imagem do contêiner. Quando o componente é executado, os comandos associados a cada fase são aplicados na ordem em que aparecem no documento do componente. **Regras para as fases** + Cada nome de fase deve ser exclusivo dentro de um documento. + Você pode definir várias fases em seu documento. + Você deve incluir pelo menos uma das fases a seguir em seu documento: + **compilação**: para o Image Builder, essa fase geralmente é usada durante o *estágio de compilação*. + **validação**: para o Image Builder, essa fase geralmente é usada durante o *estágio de compilação*. + **teste**: para o Image Builder, essa fase geralmente é usada durante o *estágio de teste*. + As fases sempre são executadas na ordem em que são definidas no documento. A ordem na qual eles são especificados para AWSTOE os comandos no não AWS CLI tem efeito. **Etapas** As etapas são unidades individuais de trabalho que definem o fluxo de trabalho em cada fase. As etapas são executadas em ordem sequencial. No entanto, a entrada ou saída de uma etapa também pode alimentar uma etapa subsequente como entrada. Isso é chamado de “encadeamento”. **Regras para as etapas** + O nome da etapa deve ser exclusivo para a fase. + A etapa deve usar uma ação compatível (módulo de ação) que retorne um código de saída. Para obter uma lista completa dos módulos de ação compatíveis, como eles funcionam, input/output valores e exemplos, consulte[Módulos de ação suportados pelo gerenciador de AWSTOE componentes](toe-action-modules.md). ## Registro em log do componente AWSTOE cria uma nova pasta de log nas instâncias do EC2 que é usada para criar e testar uma nova imagem sempre que seu componente é executado. Para imagens de contêiner, a pasta de log é armazenada no contêiner. Para ajudar na solução de problemas se algo der errado durante o processo de criação da imagem, o documento de entrada e todos os arquivos de saída AWSTOE criados durante a execução do componente são armazenados na pasta de registro. O nome da pasta de log é composto pelas seguintes partes: 1. **Diretório de log** — quando um serviço executa um AWSTOE componente, ele passa para o diretório de log, junto com outras configurações do comando. Nos exemplos a seguir, mostramos o formato de arquivo de log usado pelo Image Builder. + **Linux e macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **Prefixo do arquivo**: esse é um prefixo padrão usado para todos os componentes: “`TOE_`”. 1. **Tempo de execução** — Este é um timestamp no formato YYYY-MM-DD \$1HH-MM-SS\$1UTC-0. 1. **ID de execução** — Esse é o GUID atribuído ao AWSTOE executar um ou mais componentes. Exemplo: `/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4` AWSTOE armazena os seguintes arquivos principais na pasta de log: **Arquivos de entrada** + **document.yaml**: o documento usado como entrada para o comando. Depois que o componente é executado, esse arquivo é armazenado como um artefato. **Arquivos de saída** + **application.log**: O log do aplicativo contém informações de nível de depuração com o timestamp do AWSTOE sobre o que está acontecendo enquanto o componente está sendo executado. + **detailedoutput.json**: esse arquivo JSON tem informações detalhadas sobre o status de execução, entradas, saídas e falhas de todos os documentos, fases e etapas que se aplicam ao componente enquanto ele é executado. + **console.log** — O log do console contém todas as informações de saída padrão (stdout) e erro padrão (stderr) que são AWSTOE gravadas no console enquanto o componente está em execução. + **chaining.json — Esse arquivo JSON** representa otimizações aplicadas para resolver expressões de encadeamento. AWSTOE **nota** A pasta de log também pode conter outros arquivos temporários que não são abordados aqui. ## Encadeamento de entrada e saída O aplicativo de gerenciamento de AWSTOE configuração fornece um recurso para encadear entradas e saídas escrevendo referências nos seguintes formatos: `{{ phase_name.step_name.inputs/outputs.variable }}` or `{{ phase_name.step_name.inputs/outputs[index].variable }}` O atributo de encadeamento permite que você recicle o código e melhore a capacidade de manutenção do documento. **Regras para o encadeamento** + Expressões de encadeamento só podem ser usadas na seção de entradas de cada etapa. + Instruções com expressões encadeadas devem estar entre aspas. Por exemplo: + **Expressão inválida**: `echo {{ phase.step.inputs.variable }}` + **Expressão válida**: `"echo {{ phase.step.inputs.variable }}"` + **Expressão válida**: `'echo {{ phase.step.inputs.variable }}'` + Expressões de encadeamento podem referenciar variáveis de outras etapas e fases no mesmo documento. No entanto, o serviço de chamada pode ter regras que exijam que as expressões de encadeamento operem somente no contexto de um único estágio. Por exemplo, o Image Builder não é compatível com o encadeamento do *estágio de compilação* até o *estágio de teste*, pois ele executa cada estágio de forma independente. + Os índices em expressões de encadeamento seguem a indexação com base em zero. O índice começa com zero (0) para referenciar o primeiro elemento. **Exemplos** Para se referir à variável de origem na segunda entrada da etapa de exemplo a seguir, o padrão de encadeamento é `{{ build.SampleS3Download.inputs[1].source }}`. ``` phases: - name: 'build' steps: - name: SampleS3Download action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://sample-bucket/sample1.ps1' destination: 'C:\sample1.ps1' - source: 's3://sample-bucket/sample2.ps1' destination: 'C:\sample2.ps1' ``` Para se referir à variável de saída (igual a "Hello") da etapa de exemplo a seguir, o padrão de encadeamento é `{{ build.SamplePowerShellStep.outputs.stdout }}`. ``` phases: - name: 'build' steps: - name: SamplePowerShellStep action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## Esquema e definições do documento Veja a seguir o esquema YAML para um documento. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` As definições de esquema para um documento são as seguintes. | Campo | Description | Tipo | Obrigatório | | --- | --- | --- | --- | | name | O nome do documento. | String | Não | | descrição | Descrição do documento. | String | Não | | schemaVersion | Versão do esquema do documento, atualmente 1.0. | String | Sim | | phases | Uma lista de fases com suas etapas. | Lista | Sim | As definições de esquema para uma fase são as seguintes. | Campo | Description | Tipo | Obrigatório | | --- | --- | --- | --- | | name | Nome da fase. | String | Sim | | steps | Lista das etapas da fase. | Lista | Sim | As definições de esquema para uma etapa são as seguintes. | Campo | Description | Tipo | Obrigatório | Valor padrão | | --- | --- | --- | --- | --- | | name | Nome definido pelo usuário para a etapa. | String | | | | ação | Palavra-chave referente ao módulo que executa a etapa. | String | | | | timeoutSeconds | Número de segundos em que a etapa é executada antes de falhar ou tentar novamente. Além disso, suporta o valor -1, que indica um tempo limite infinito. 0 e outros valores negativos não são permitidos. | Inteiro | Não | 7.200 segundos (120 minutos) | | onFailure | Especifica o que a etapa deve fazer em caso de falha. Os valores válidos são os seguintes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/imagebuilder/latest/userguide/toe-use-documents.html) | String | Não | Anular | | maxAttempts | Número máximo de tentativas permitidas antes de falhar na etapa. | Inteiro | Não | 1 | | inputs | Contém os parâmetros exigidos pelo módulo de ação para executar a etapa. | Dict | Sim | | ## Documentos de exemplo Os exemplos a seguir mostram documentos de AWSTOE componentes que executam tarefas para o sistema operacional de destino. ------ #### [ Linux ] **Exemplo 1: executar um arquivo binário personalizado** Veja a seguir um exemplo de documento para baixar e executar um arquivo binário personalizado em uma instância do Linux. ``` name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ Windows ] **Exemplo 1: instalar atualizações do Windows** Veja a seguir um exemplo de documento para instalar todas as atualizações disponíveis do Windows, executar um script de configuração, validar as alterações antes da criação da AMI e testar as alterações após a criação da AMI. ``` name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}' ``` **Exemplo 2: instalar o AWS CLI em uma instância do Windows** Veja a seguir um exemplo de documento que instala o AWS CLI em uma instância do Windows, usando o arquivo de configuração. ``` name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` **Exemplo 3: Instale o AWS CLI com o instalador MSI** A seguir está um exemplo de documento que instala o AWS CLI com o instalador MSI. ``` name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ macOS ] **Exemplo 1: executar um arquivo binário personalizado no macOS** Veja a seguir um exemplo de documento para baixar e executar um arquivo binário personalizado em uma instância do macOS. ``` name: macOSBin description: Download and run a binary file on macOS. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ # Usar variáveis em seu documento de componente personalizado As variáveis oferecem uma forma de rotular dados com nomes significativos que podem ser usados em todo o aplicativo. Você pode definir variáveis personalizadas com formatos simples e legíveis para fluxos de trabalho complexos e referenciá-las no documento do componente do aplicativo YAML para um componente. AWSTOE Esta seção fornece informações para ajudá-lo a definir variáveis para seu AWSTOE componente no documento do componente do aplicativo YAML, incluindo sintaxe, restrições de nome e exemplos. ## Constantes Constantes são variáveis imutáveis que não podem ser modificadas ou substituídas depois de definidas. As constantes podem ser definidas usando valores na `constants` seção de um AWSTOE documento. **Regras para denominação de constantes** + O nome deve ter entre 3 e 128 caracteres. + O nome pode conter somente os caracteres alfanuméricos (A-Z, a-z, 0-9), hífens (-) ou sublinhados (\$1). + O nome deve ser exclusivo dentro do documento. + O nome deve ser especificado como uma cadeia YAML. **Sintaxe** ``` constants: - : type: value: ``` | Nome da chave | Obrigatório | Descrição | | --- | --- | --- | | `name` | Sim | Nome da constante. Deve ser exclusivo para o documento (não deve ser igual a nenhum outro nome de parâmetro ou constante). | | `value` | Sim | Valor da constante. | | `type` | Sim | Tipo da constante. O tipo compatível é string. | **Valores de constante de referência em um documento** Você pode referenciar constantes em informações de etapa ou loop dentro do seu documento YAML, da seguinte maneira: + As referências da constante diferenciam letras maiúsculas de minúsculas e o nome deve corresponder exatamente. + O nome deve estar entre colchetes duplos. `{{` *MyConstant* `}}` + Dentro dos parêntesis, os espaços são permitidos e são cortados automaticamente. Por exemplo, todas as referências a seguir são válidas: `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}` + A referência no documento YAML deve ser especificada como uma string (entre aspas simples ou duplas). Por exemplo: `- {{ MyConstant }}` não é válido, pois não é identificado como uma string. No entanto, as seguintes referências são válidas: `- '{{ MyConstant }}'` e `- "{{ MyConstant }}"`. **Exemplos** Constante referenciada nas informações da etapa ``` name: Download AWS CLI version 2 schemaVersion: 1.0 constants: - Source: type: string value: https://awscli.amazonaws.com/AWSCLIV2.msi phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` Constante referenciada nas informações de loop ``` name: PingHosts schemaVersion: 1.0 constants: - Hosts: type: string value: 127.0.0.1,amazon.com phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ## Parâmetros Os parâmetros são variáveis mutáveis, com configurações que o aplicativo de chamada pode fornecer no runtime. Você pode definir parâmetros na seção `Parameters` do documento YAML. **Regras para denominação de parâmetro** + O nome deve ter entre 3 e 128 caracteres. + O nome pode conter somente os caracteres alfanuméricos (A-Z, a-z, 0-9), hífens (-) ou sublinhados (\$1). + O nome deve ser exclusivo dentro do documento. + O nome deve ser especificado como uma cadeia YAML. ### Sintaxe ``` parameters: - : type: default: description: ``` | Nome da chave | Obrigatório | Descrição | | --- | --- | --- | | `name` | Sim | O nome do parâmetro. Deve ser exclusivo para o documento (não deve ser igual a nenhum outro nome de parâmetro ou constante). | | `type` | Sim | O tipo de dado válido do parâmetro. Os tipos compatíveis incluem: `string`. | | `default` | Não | O valor padrão do parâmetro. | | `description` | Não | Descreve o parâmetro. | ### Valores de parâmetros de referência em um documento Você pode referenciar parâmetros em etapa ou loop dentro do seu documento YAML, da seguinte maneira: + As referências de parâmetro diferenciam letras maiúsculas de minúsculas e o nome deve corresponder exatamente. + O nome deve estar entre colchetes duplos. `{{` *MyParameter* `}}` + Dentro dos parêntesis, os espaços são permitidos e são cortados automaticamente. Por exemplo, todas as referências a seguir são válidas: `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}` + A referência no documento YAML deve ser especificada como uma string (entre aspas simples ou duplas). Por exemplo: `- {{ MyParameter }}` não é válido, pois não é identificado como uma string. No entanto, as seguintes referências são válidas: `- '{{ MyParameter }}'` e `- "{{ MyParameter }}"`. **Exemplos** Os exemplos a seguir mostram como usar parâmetros no seu documento YAML: + Consulte um parâmetro nas informações da etapa: ``` name: Download AWS CLI version 2 schemaVersion: 1.0 parameters: - Source: type: string default: 'https://awscli.amazonaws.com/AWSCLIV2.msi' description: The AWS CLI installer source URL. phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` + Consulte um parâmetro nas informações de loop: ``` name: PingHosts schemaVersion: 1.0 parameters: - Hosts: type: string default: 127.0.0.1,amazon.com description: A comma separated list of hosts to ping. phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ### Substituir parâmetros no runtime Você pode usar a `--parameters` opção AWS CLI com um par de valores-chave para definir um valor de parâmetro em tempo de execução. + Especifique o par chave-valor do parâmetro como nome e valor, separados por um sinal de igual (=). + Vários parâmetros devem ser separados por uma vírgula. + Os nomes dos parâmetros que não são encontrados no documento do componente YAML são ignorados. + O nome e o valor do parâmetro são obrigatórios. **Importante** Os parâmetros do componente são valores de texto simples e estão logados em AWS CloudTrail. Recomendamos que você use AWS Secrets Manager ou o AWS Systems Manager Parameter Store para armazenar seus segredos. Para obter mais informações sobre o Secrets Manager, consulte ‭[O que é o Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)‭‬ no *AWS Secrets Manager Guia do usuário‭*. Para obter mais informações sobre o ‭ AWS Systems Manager Parameter Store, consulte [AWS Systems Manager ‬ Parameter Store‭‬](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) no *AWS Systems Manager ‬ Guia do usuário‭*. #### Sintaxe ``` --parameters name1=value1,name2=value2... ``` | Opção da CLI: | Obrigatório | Description | | --- | --- | --- | | --parâmetros *name* =*value*,... | Não | Essa opção usa uma lista de pares chave-valor, com o nome do parâmetro como chave. | **Exemplos** Os exemplos a seguir mostram como usar parâmetros no seu documento YAML: + O par valor-chave do parâmetro especificado nessa opção do `--parameter` não é válido: ``` --parameters ntp-server= ``` + Defina um par valor-chave de parâmetro com a opção do `--parameter` no AWS CLI: ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + Defina vários pares valor-chave de parâmetros com a opção `--parameter` no AWS CLI: ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Use os parâmetros do Systems Manager Parameter Store Você pode referenciar os parâmetros do AWS Systems Manager Parameter Store (parâmetros SSM) em seus documentos de componentes prefixando variáveis com. `aws:ssm` Por exemplo, `{{ aws:ssm:/my/param }}`resolve o valor do parâmetro SSM. `/my/param` Esse recurso oferece suporte aos seguintes tipos de parâmetros SSM: + String — Mapeia para o tipo de AWSTOE string. + StringList — Mapas para o AWSTOE `stringList` tipo. + SecureString — Mapeia para o tipo de AWSTOE string. Para obter mais informações sobre o Parameter Store, consulte [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) no *Guia AWS Systems Manager do usuário*. Você também pode referenciar AWS Secrets Manager segredos usando um parâmetro `SecureString` SSM. Por exemplo: `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`. Para obter mais informações, consulte Como [referenciar AWS Secrets Manager segredos dos parâmetros do Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html). **Importante** O Image Builder exclui a resolução de `SecureString` parâmetros de seus registros. No entanto, você também é responsável por garantir que informações confidenciais não sejam registradas por meio de comandos emitidos no documento do componente. Por exemplo, se você usar o `echo` comando com uma string segura, o comando grava um valor em texto simples no log. ### Permissões obrigatórias do IAM Para usar os parâmetros do Systems Manager em seus componentes, sua função de instância deve ter a `ssm:GetParameter` permissão para o recurso de parâmetros ARN. Por exemplo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" } ] } ``` ------ Para acessar valores criptografados, você também precisará das seguintes permissões: + Adicione `kms:Decrypt` `SecureString` parâmetros ou AWS Secrets Manager valores que são criptografados com um cliente gerenciado AWS KMS key. + Adicione `secretsmanager:GetSecretValue` se você fizer referência a um segredo do Secrets Manager. ### Fazer referência a um parâmetro SSM em um documento componente O exemplo a seguir mostra como referenciar um parâmetro do Systems Manager Parameter Store dos parâmetros do Systems Manager em um componente: ``` name: UseSSMParameterVariable description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter. schemaVersion: 1.0 phases: - name: verify steps: - name: EchoParameterValue action: ExecuteBash inputs: commands: - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}." ``` ### Resolução variável de tempo de execução dinâmico para parâmetros SSM AWSTOE fornece a seguinte função integrada que você pode usar em referências de variáveis para manipular ou transformar valores em tempo de execução. #### função de resolução A `resolve` função resolve uma referência de variável dentro de outra referência de variável, permitindo a referência dinâmica de nomes de variáveis. Isso é útil ao trabalhar com parâmetros SSM em que parte do caminho do parâmetro pode ser variável e transmitida como um parâmetro do documento. A `resolve` função suporta somente a resolução dinâmica da parte do nome de um parâmetro SSM. ##### Sintaxe O `dynamic_variable` exemplo a seguir representa o nome de um parâmetro SSM e deve ser um dos seguintes: + Uma referência de parâmetro SSM (por exemplo,`aws:ssm:/my/param`) + Uma referência de parâmetro do documento do componente (por exemplo,`parameter-name`) ``` {{ aws:ssm:resolve(dynamic_variable) }} ``` ##### Exemplo: Resolver um parâmetro SSM em tempo de execução O exemplo a seguir mostra como usar a `resolve` função em um documento do componente YAML: ``` name: SsmParameterTest description: This component verifies an SSM parameter variable reference with the echo command. schemaVersion: 1.0 parameters: - parameter-name: type: string description: "test" phases: - name: validate steps: - name: PrintDynamicVariable action: ExecuteBash inputs: commands: - echo "{{ aws:ssm:resolve(parameter-name) }}" ``` # Use construções condicionais em AWSTOE Os constructos condicionais realizam diferentes ações no documento do componente dependendo de a expressão condicional especificada ser avaliada como `true` ou `false`. Você pode usar o constructo `if` para controlar o fluxo de execução no documento do componente. ## Constructo “if” Você pode usar o constructo `if` para avaliar se uma etapa deve ser executada ou não. Por padrão, quando a expressão condicional `if` é avaliada como `true`, o AWSTOE executa a etapa e, quando a condição é avaliada como `false`, o AWSTOE pula a etapa. Se uma etapa for ignorada, ela poderá ser tratada como bem-sucedida quando o AWSTOE avaliar se a fase e o documento foram executados com êxito. **nota** Uma instrução `if` só é avaliada uma vez, mesmo que a etapa acione uma reinicialização. Se uma etapa for reiniciada, ela reconhecerá que a instrução `if` já foi avaliada e continuará de onde parou. ### Sintaxe ``` if: - : [then: ] [else: ] ``` | Nome da chave | Obrigatório | Description | | --- | --- | --- | | Expressão condicional | Sim | A expressão condicional pode conter exatamente um dos seguintes tipos de operador no nível superior. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/imagebuilder/latest/userguide/toe-conditional-constructs.html) Se sua expressão precisar satisfazer várias condições, use um operador lógico para especificar suas condições. | | then | Não | Define a ação a ser executada se a expressão condicional for avaliada como `true`. | | else | Não | Define a ação a ser executada se a expressão condicional for avaliada como `false`. | | ações de etapa | Condicional | Ao usar `then` ou `else`, você deve especificar uma das seguintes ações de etapa: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/imagebuilder/latest/userguide/toe-conditional-constructs.html) | **Exemplo 1: instalar um pacote** As etapas de exemplo a seguir de um documento de AWSTOE componente usam operadores lógicos para testar um valor de parâmetro e executar os comandos apropriados do gerenciador de pacotes para instalar um aplicativo se o pacote for descompactado. ``` - name: InstallUnzipAptGet action: ExecuteBash if: and: - binaryExists: 'apt-get' - not: binaryExists: 'unzip' inputs: commands: - sudo apt-get update - sudo apt-get install -y unzip - name: InstallUnzipYum action: ExecuteBash if: and: - binaryExists: 'yum' - not: binaryExists: 'unzip' inputs: commands: - sudo yum install -y unzip - name: InstallUnzipZypper action: ExecuteBash if: and: - binaryExists: 'zypper' - not: binaryExists: 'unzip' inputs: commands: - sudo zypper refresh - sudo zypper install -y unzip ``` **Exemplo 2: ignorar uma etapa** O exemplo a seguir mostra duas maneiras de pular uma etapa. Uma usa um operador lógico e a outra usa um operador de comparação com a ação de etapa `Skip`. ``` # Creates a file if it does not exist using not - name: CreateMyConfigFile-1 action: ExecuteBash if: not: fileExists: '/etc/my_config' inputs: commands: - echo "Hello world" > '/etc/my_config' # Creates a file if it does not exist using then and else - name: CreateMyConfigFile-2 action: ExecuteBash if: fileExists: '/etc/my_config' then: Skip else: Execute inputs: commands: - echo "Hello world" > '/etc/my_config' ``` # Use operadores de comparação em documentos de AWSTOE componentes Você pode usar os operadores de comparação a seguir com o módulo de ação **[Assert](toe-action-modules.md#action-modules-assertion)** e com expressões condicionais que usam o [Constructo “if”Sintaxe](toe-conditional-constructs.md#toe-conditional-if). Um operador de comparação pode operar em um único valor (por exemplo, `stringIsEmpty`) ou comparar um valor de referência com um segundo valor (valor variável) para determinar se a expressão condicional é avaliada como `true` ou `false`. Se a comparação operar em dois valores, o segundo valor poderá ser uma variável de encadeamento. Ao comparar valores de um tipo diferente, as seguintes conversões de valor podem ocorrer antes da comparação: + Para comparações numéricas, se o valor da variável for uma string, AWSTOE converte a string em um número antes da avaliação. Se a conversão não for possível, a comparação responderá com `false`. Por exemplo, se o valor da variável for `"1.0"`, a conversão funcionará, mas, se o valor da variável for `"a10"`, a conversão falhará. + Para comparações de strings, se o valor da variável for um número, AWSTOE converte-o em uma string antes da avaliação. ## Comparar strings Os operadores de comparação a seguir funcionam com strings de caracteres para comparar valores, testar espaços ou uma string vazia ou comparar um valor de entrada com um padrão regex. As comparações de strings não diferenciam maiúsculas de minúsculas e não removem os espaços do início ou do final das entradas de string. **Operadores de comparação de strings** + [stringIsEmpty](#stringIsEmpty) + [stringIsWhitespace](#stringIsWhitespace) + [stringEquals](#stringEquals) + [stringLessThan](#stringLessThan) + [stringLessThanEquals](#stringLessThanEquals) + [stringGreaterThan](#stringGreaterThan) + [stringGreaterThanEquals](#stringGreaterThanEquals) + [patternMatches](#patternMatches) **stringIsEmpty** O operador `stringIsEmpty` responderá com `true` se a string especificada não contiver nenhum caractere. Por exemplo: ``` # Evaluates to true stringIsEmpty: "" # Evaluates to false stringIsEmpty: " " # Evaluates to false stringIsEmpty: "Hello." ``` **stringIsWhitespace** Testa se a string especificada para `stringIsWhitespace` contém somente espaços. Por exemplo: ``` # Evaluates to true stringIsWhitespace: " " # Evaluates to false stringIsWhitespace: "" # Evaluates to false stringIsWhitespace: " Hello?" ``` **stringEquals** Testa se a string especificada para `stringEquals` é uma correspondência exata para a string especificada no parâmetro `value`. Por exemplo: ``` # Evaluates to true stringEquals: 'Testing, testing...' value: 'Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Hello again.' # Evaluates to false stringEquals: 'Testing, testing...' value: 'TESTING, TESTING....' # Evaluates to false stringEquals: 'Testing, testing...' value: ' Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Testing, testing... ' ``` **stringLessThan** Testa se a string especificada para `stringLessThan` é menor do que a string especificada no parâmetro `value`. Por exemplo: ``` # Evaluates to true # This comparison operator isn't case sensitive stringlessThan: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringlessThan: 'b' value: 'a' # Evaluates to true # Numeric strings compare as less than alphabetic strings stringlessThan: 'a' value: '0' # Evaluates to false stringlessThan: '0' value: 'a' ``` **stringLessThanIgual** Testa se a string especificada para `stringLessThanEquals` é menor ou igual à string especificada no parâmetro `value`. Por exemplo: ``` # Evaluates to true - 'a' is equal to 'a' stringLessThanEquals: 'a' value: 'a' # Evaluates to true - since the comparison isn't case sensitive, 'a' is equal to 'A' stringLessThanEquals: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringLessThanEquals: 'b' value: 'a' # Evaluates to true - '0' is less than 'a' stringLessThanEquals: 'a' value: '0' # Evaluates to false - 'a' is greater than '0' stringLessThanEquals: '0' value: 'a' ``` **stringGreaterThan** Testa se a string especificada para `stringGreaterThan` é maior do que a string especificada no parâmetro `value`. Por exemplo: ``` # Evaluates to false - since the comparison isn't case sensitive, 'A' is equal to 'a' stringGreaterThan: 'a' value: 'A' # Evaluates to true - 'b' is greater than 'a' stringGreaterThan: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThan: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThan: 'a' value: '0' ``` **stringGreaterThanIgual** Testa se a string especificada para `stringGreaterThanEquals` é maior ou igual à string especificada no parâmetro `value`. Por exemplo: ``` # Evaluates to true - 'a' is equal to 'A' stringGreaterThanEquals: 'A' value: 'a' # Evaluates to true - 'b' is greater than 'a' stringGreaterThanEquals: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThanEquals: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThanEquals: 'a' value: '0' ``` **patternMatches** Testa se a string especificada para `value` corresponde ao padrão regex especificado para `patternMatches`. A comparação usa o [pacote Golang regexp](https://pkg.go.dev/regexp), que está em conformidade com a sintaxe. RE2 Para obter mais informações sobre RE2 regras, consulte o repositório [google/ re2](https://github.com/google/re2/wiki/Syntax) em. *GitHub* O exemplo a seguir mostra uma correspondência de padrões que responde com `true`: ``` patternMatches: '^[a-z]+$' value: 'ThisIsValue' ``` ## Comparar números Os operadores de comparação a seguir funcionam com números. Os valores fornecidos para esses operadores devem ser de um dos tipos a seguir, de acordo com a especificação YAML. O suporte a comparações numéricas usa o operador de comparação do pacote Golang Big, por exemplo: [func (\$1Float) Cmp](https://pkg.go.dev/math/big#Float.Cmp). + Inteiro + Float (com base no float64, compatível com números de -1.7e\$1308 a \$11.7e\$1308) + Uma string que corresponde ao seguinte padrão de regex: `^[-+]?([0-9]+[.])?[0-9]+$` **Operadores de comparação de números** + [numberEquals](#numberEquals) + [numberLessThan](#numberLessThan) + [numberLessThanEquals](#numberLessThanEquals) + [numberGreaterThan](#numberGreaterThan) + [numberGreaterThanEquals](#numberGreaterThanEquals) **numberEquals** Testa se o número especificado para `numberEquals` é igual ao número especificado no parâmetro `value`. Todos os seguintes exemplos de comparação respondem com `true`: ``` # Values provided as a positive number numberEquals: 1 value: 1 # Comparison value provided as a string numberEquals: '1' value: 1 # Value provided as a string numberEquals: 1 value: '1' # Values provided as floats numberEquals: 5.0 value: 5.0 # Values provided as a negative number numberEquals: -1 value: -1 ``` **numberLessThan** Testa se o número especificado para `numberLessThan` é menor do que o número especificado no parâmetro `value`. Por exemplo: ``` # Evaluates to true numberLessThan: 2 value: 1 # Evaluates to true numberLessThan: 2 value: 1.9 # Evaluates to false numberLessThan: 2 value: '2' ``` **numberLessThanIgual** Testa se o número especificado para `numberLessThanEquals` é menor ou igual ao número especificado no parâmetro `value`. Por exemplo: ``` # Evaluates to true numberLessThanEquals: 2 value: 1 # Evaluates to true numberLessThanEquals: 2 value: 1.9 # Evaluates to true numberLessThanEquals: 2 value: '2' # Evaluates to false numberLessThanEquals: 2 value: 2.1 ``` **numberGreaterThan** Testa se o número especificado para `numberGreaterThan` é maior do que o número especificado no parâmetro `value`. Por exemplo: ``` # Evaluates to true numberGreaterThan: 1 value: 2 # Evaluates to true numberGreaterThan: 1 value: 1.1 # Evaluates to false numberGreaterThan: 1 value: '1' ``` **numberGreaterThanIgual** Testa se o número especificado para `numberGreaterThanEquals` é maior ou igual ao número especificado no parâmetro `value`. Por exemplo: ``` # Evaluates to true numberGreaterThanEquals: 1 value: 2 # Evaluates to true numberGreaterThanEquals: 1 value: 1.1 # Evaluates to true numberGreaterThanEquals: 1 value: '1' # Evaluates to false numberGreaterThanEquals: 1 value: 0.8 ``` ## Verificar arquivos Os operadores de comparação a seguir verificam o hash do arquivo ou se um arquivo ou pasta existe. **Operadores de arquivos e pastas** + [binaryExists](#binaryExists) + [fileExists](#fileExists) + [folderExists](#folderExists) + [fileMD5Equals](#fileMD5Equals) + [fileSHA1Equals](#fileSHA1Equals) + [fileSHA256Equals](#fileSHA256Equals) + [fileSHA512Equals](#fileSHA512Equals) **binaryExists** Testa se uma aplicação está disponível no caminho atual. Por exemplo: ``` binaryExists: 'foo' ``` Em sistemas Linux e macOS, para um aplicativo chamado*foo*, isso funciona da mesma forma que o seguinte comando bash:**type *foo* >/dev/null 2>&1**, onde **\$1? == 0** indica uma comparação bem-sucedida. Em sistemas Windows, para um aplicativo chamado*foo*, isso funciona da mesma forma que o PowerShell comando **& C:\$1Windows\$1System32\$1where.exe /Q *foo*** que **\$1LASTEXITCODE = 0** indica uma comparação bem-sucedida. **fileExists** Testa se um arquivo existe no caminho especificado. Você pode fornecer um caminho absoluto ou relativo. Se o local especificado existir e for um arquivo, a comparação será avaliada como `true`. Por exemplo: ``` fileExists: '/path/to/file' ``` Nos sistemas Linux e macOS, isso funciona da mesma forma que o seguinte comando bash: **-d */path/to/file***, em que **\$1? == 0** indica uma comparação bem-sucedida. Nos sistemas Windows, isso funciona da mesma forma que o PowerShell comando**Test-Path -Path '*C:\$1path\$1to\$1file*' -PathType 'Leaf'**. **folderExists** Testa se uma pasta existe no caminho especificado. Você pode fornecer um caminho absoluto ou relativo. Se o local especificado existir e for uma pasta, a comparação será avaliada como `true`. Por exemplo: ``` folderExists: '/path/to/folder' ``` Nos sistemas Linux e macOS, isso funciona da mesma forma que o seguinte comando bash: **-d */path/to/folder***, em que **\$1? == 0** indica uma comparação bem-sucedida. Nos sistemas Windows, isso funciona da mesma forma que o PowerShell comando**Test-Path -Path '*C:\$1path\$1to\$1folder*' -PathType 'Container'**. **arquivo é igual MD5 a** Testa se o MD5 hash de um arquivo é igual a um valor especificado. Por exemplo: ``` fileMD5Equals: '' path: '/path/to/file' ``` **arquivo é igual SHA1 a** Testa se o SHA1 hash de um arquivo é igual a um valor especificado. Por exemplo: ``` fileSHA1Equals: '' path: '/path/to/file' ``` **arquivo é igual SHA256 a** Testa se o SHA256 hash de um arquivo é igual a um valor especificado. Por exemplo: ``` fileSHA256Equals: '' path: '/path/to/file' ``` **arquivo é igual SHA512 a** Testa se o SHA512 hash de um arquivo é igual a um valor especificado. Por exemplo: ``` fileSHA512Equals: '' path: '/path/to/file' ``` # Use operadores lógicos em documentos de AWSTOE componentes Você pode usar os operadores lógicos a seguir para adicionar ou modificar expressões condicionais no documento do componente. AWSTOE avalia expressões condicionais na ordem em que as condições são especificadas. Para obter mais informações sobre operadores de comparação para documentos de componente, consulte [Use operadores de comparação em documentos de AWSTOE componentes](toe-comparison-operators.md). **and** Com o operador `and`, você pode avaliar duas ou mais comparações como uma única expressão. A expressão é avaliada como `true` quando todas as condições na lista são verdadeiras. Caso contrário, a expressão será avaliada como `false`. **Exemplos:** O exemplo a seguir faz duas comparações: uma string e um número. Ambas as comparações são verdadeiras, então a expressão é avaliada como verdadeira. ``` and: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 1 ``` O exemplo a seguir também realiza duas comparações. A primeira comparação é falsa e, em dado momento, a avaliação é interrompida e a segunda comparação é ignorada. A expressão é avaliada como `false`. ``` and: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` **or** Com o operador `or`, você pode avaliar duas ou mais comparações como uma única expressão. A expressão é avaliada como `true` quando uma das comparações especificadas é verdadeira. Se nenhuma das comparações especificadas for avaliada como `true`, a expressão será avaliada como `false`. **Exemplos:** O exemplo a seguir faz duas comparações: uma string e um número. A primeira comparação é verdadeira, então a expressão é avaliada como `true` e a segunda comparação é ignorada. ``` or: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 3 ``` O exemplo a seguir também realiza duas comparações. A primeira comparação é falsa e a avaliação continua. A segunda comparação é verdadeira, então a expressão é avaliada como `true`. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` No exemplo final, ambas as comparações são falsas, então a expressão é avaliada como `false`. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 3 ``` **not** Com o operador `not`, você pode negar uma única comparação. A expressão é avaliada como `true` se a comparação for falsa. Se a comparação for verdadeira, a expressão será avaliada como `false`. **Exemplos:** O exemplo a seguir executa uma comparação de strings. A comparação é falsa, então a expressão é avaliada como `true`. ``` not: - stringEquals: 'test_string' value: 'Hello world!' ``` O exemplo a seguir também executa uma comparação de strings. A comparação é verdadeira, então a expressão é avaliada como `false`. ``` not: - stringEquals: 'test_string' value: 'test_string' ``` # Use construções em loop em AWSTOE Esta seção fornece informações para ajudar você a criar estruturas em loop no AWSTOE. Estruturas em loop definem uma sequência repetida de instruções. Você pode usar os seguintes tipos de estruturas em loop no AWSTOE: + `for` estruturas: itere sobre uma sequência limitada de inteiros. + `forEach` estruturas + `forEach` loop com lista de entrada: itera sobre uma coleção finita de strings. + `forEach` loop com lista delimitada: itera sobre uma coleção finita de strings unidas por um delimitador. **nota** As estruturas em loop suportam somente tipos de dados de string. **Topics** + [Variáveis de iteração de referência](#toe-loop-iteration-variables) + [Tipos de estruturas em loop](#toe-loop-types) + [Campos de etapa](#toe-loop-step-fields) + [Saídas de etapa e iteração](#toe-loop-step-output) ## Variáveis de iteração de referência Para se referir ao índice e ao valor da variável de iteração atual, a expressão de referência `{{ loop.* }}` deve ser usada no corpo de entrada de uma etapa que contém uma estrutura em loop. Essa expressão não pode ser usada para se referir às variáveis de iteração da estrutura em loop de outra etapa. A expressão de referência consiste nos seguintes membros: + `{{ loop.index }}`: a posição ordinal da iteração atual, indexada em `0`. + `{{ loop.value }}`: o valor associado à variável de iteração atual. ### Nomes de loop Todas as estruturas em loop têm um campo de nome opcional para identificação. Se um nome de loop for fornecido, ele poderá ser usado para se referir às variáveis de iteração no corpo de entrada da etapa. Para se referir aos índices e valores de iteração de um loop nomeado, use `{{ .* }}` com `{{ loop.* }}` no corpo de entrada da etapa. Essa expressão não pode ser usada para se referir à estrutura em loop nomeada de outra etapa. A expressão de referência consiste nos seguintes membros: + `{{ .index }}`: a posição ordinal da iteração atual do loop nomeado, indexada em `0`. + `{{ .value }}`: o valor associado à variável de iteração atual do loop nomeado. ### Resolver expressões de referência AWSTOE Resolve as expressões de referência da seguinte forma: + `{{ .* }}`— AWSTOE resolve essa expressão usando a seguinte lógica: + Se o loop da etapa em execução no momento corresponder ao valor do ``, a expressão de referência será resolvida para a estrutura em loop da etapa em execução no momento. + `` resolve para a estrutura em loop nomeada se ela aparecer na etapa em execução no momento. + `{{ loop.* }}`— AWSTOE resolve a expressão usando a construção de loop definida na etapa atualmente em execução. Se expressões de referência forem usadas em uma etapa que não contém um loop, elas AWSTOE não resolverão as expressões e elas aparecerão na etapa sem substituição. **nota** As expressões de referência devem estar entre aspas duplas para serem interpretadas corretamente pelo compilador YAML. ## Tipos de estruturas em loop Esta seção fornece informações e exemplos sobre os tipos de estrutura em loop que podem ser usados no AWSTOE. **Topics** + [loop `for`](#toe-loop-types-for) + [loop `forEach` com lista de entrada](#toe-loop-types-foreach) + [loop `forEach` com lista delimitada](#toe-loop-types-foreach-delimited) ### loop `for` O loop `for` itera em um intervalo de inteiros especificado dentro de um limite delineado pelo início e pelo fim das variáveis. Os valores de iteração estão no conjunto `[start, end]` e incluem valores limite. AWSTOE verifica os `updateBy` valores `start``end`, e para garantir que a combinação não resulte em um loop infinito. esquema de loop `for` ``` - name: "StepName" action: "ActionModule" loop: name: "string" for: start: int end: int updateBy: int inputs: ... ``` **entrada de loop `for`** | Campo | Description | Tipo | Obrigatório | Padrão | | --- | --- | --- | --- | --- | | `name` | Nome exclusivo do loop. Ele deve ser exclusivo em comparação com outros nomes de loop na mesma fase. | String | Não | "" | | `start` | Valor inicial da iteração. Não aceita expressões de encadeamento. | Inteiro | Sim | n/a | | `end` | Valor final da iteração. Não aceita expressões de encadeamento. | Inteiro | Sim | n/a | | `updateBy` | Diferença pela qual um valor iterativo é atualizado por meio da adição. Deve ser um valor negativo ou positivo diferente de zero. Não aceita expressões de encadeamento. | Inteiro | Sim | n/a | exemplo de entrada de loop `for` ``` - name: "CalculateFileUploadLatencies" action: "ExecutePowerShell" loop: for: start: 100000 end: 1000000 updateBy: 100000 inputs: commands: - | $f = new-object System.IO.FileStream c:\temp\test{{ loop.index }}.txt, Create, ReadWrite $f.SetLength({{ loop.value }}MB) $f.Close() - c:\users\administrator\downloads\latencyTest.exe --file c:\temp\test{{ loop.index }}.txt - AWS s3 cp c:\users\administrator\downloads\latencyMetrics.json s3://bucket/latencyMetrics.json - | Remove-Item -Path c:\temp\test{{ loop.index }}.txt Remove-Item -Path c:\users\administrator\downloads\latencyMetrics.json ``` ### loop `forEach` com lista de entrada O loop `forEach` itera em uma lista explícita de valores, que podem ser cadeias de caracteres e expressões encadeadas. loop `forEach` com esquema de lista de entrada ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: - "string" inputs: ... ``` **loop `forEach` com entrada de lista de entrada** | Campo | Description | Tipo | Obrigatório | Padrão | | --- | --- | --- | --- | --- | | `name` | Nome exclusivo do loop. Ele deve ser exclusivo em comparação com outros nomes de loop na mesma fase. | String | Não | "" | | Lista de string de loop `forEach` | Lista de strings para iteração. Aceita expressões encadeadas como cadeias de strings na lista. As expressões encadeadas devem estar entre aspas duplas para serem interpretadas corretamente pelo compilador YAML. | Lista de strings | Sim | n/a | loop `forEach` com lista de entrada (exemplo 1) ``` - name: "ExecuteCustomScripts" action: "ExecuteBash" loop: name: BatchExecLoop forEach: - /tmp/script1.sh - /tmp/script2.sh - /tmp/script3.sh inputs: commands: - echo "Count {{ BatchExecLoop.index }}" - sh "{{ loop.value }}" - | retVal=$? if [ $retVal -ne 0 ]; then echo "Failed" else echo "Passed" fi ``` loop `forEach` com lista de entrada (exemplo 2) ``` - name: "RunMSIWithDifferentArgs" action: "ExecuteBinary" loop: name: MultiArgLoop forEach: - "ARG1=C:\Users ARG2=1" - "ARG1=C:\Users" - "ARG1=C:\Users ARG3=C:\Users\Administrator\Documents\f1.txt" inputs: commands: path: "c:\users\administrator\downloads\runner.exe" args: - "{{ MultiArgLoop.value }}" ``` loop `forEach` com lista de entrada (exemplo 3) ``` - name: "DownloadAllBinaries" action: "S3Download" loop: name: MultiArgLoop forEach: - "bin1.exe" - "bin10.exe" - "bin5.exe" inputs: - source: "s3://bucket/{{ loop.value }}" destination: "c:\temp\{{ loop.value }}" ``` ### loop `forEach` com lista delimitada O loop itera sobre uma string contendo valores separados por um delimitador. Para iterar sobre os constituintes da string, AWSTOE usa o delimitador para dividir a string em uma matriz adequada para iteração. loop `forEach` com esquema de lista delimitada ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: list: "string" delimiter: ".,;:\n\t -_" inputs: ... ``` **loop `forEach` com entrada de lista delimitada** | Campo | Description | Tipo | Obrigatório | Padrão | | --- | --- | --- | --- | --- | | `name` | Nome exclusivo dado ao loop. Deve ser exclusivo quando comparado com outros nomes de loop na mesma fase. | String | Não | "" | | `list` | Uma string composta por strings constituintes unidas por um caractere delimitador comum. Também aceita expressões encadeadas. No caso de expressões encadeadas, certifique-se de que elas estejam entre aspas duplas para uma interpretação correta pelo compilador YAML. | String | Sim | n/a | | `delimiter` | Caractere usado para separar as strings dentro de um bloco. O padrão é o caractere de vírgula. Somente um caractere delimitador é permitido na lista fornecida: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/imagebuilder/latest/userguide/toe-looping-constructs.html) Expressões encadeadas não podem ser usadas. | String | Não | Vírgula: "," | **nota** O valor de `list` é tratado como uma string imutável. Se a fonte de `list` for alterada durante o runtime, ela não será refletida durante a execução. loop `forEach` com lista delimitada (exemplo 1) Este exemplo usa o seguinte padrão de expressão de encadeamento para se referir à saída de outra etapa: `..[inputs | outputs].`. ``` - name: "RunMSIs" action: "ExecuteBinary" loop: forEach: list: "{{ build.GetAllMSIPathsForInstallation.outputs.stdout }}" delimiter: "\n" inputs: commands: path: "{{ loop.value }}" ``` loop `forEach` com lista delimitada (exemplo 2) ``` - name: "UploadMetricFiles" action: "S3Upload" loop: forEach: list: "/tmp/m1.txt,/tmp/m2.txt,/tmp/m3.txt,..." inputs: commands: - source: "{{ loop.value }}" destination: "s3://bucket/key/{{ loop.value }}" ``` ## Campos de etapa Os loops fazem parte de uma etapa. Qualquer campo relacionado à execução de uma etapa não é aplicado a iterações individuais. Os campos de etapa se aplicam somente no nível da etapa, da seguinte forma: + *TimeoutSeconds*: todas as iterações do loop devem ser executadas dentro do período especificado por esse campo. Se a execução do loop atingir o tempo limite, AWSTOE execute a política de repetição da etapa e redefina o parâmetro de tempo limite para cada nova tentativa. Se a execução do loop exceder o valor do tempo limite após atingir o número máximo de novas tentativas, a mensagem de falha da etapa indicará que a execução do loop atingiu o tempo limite. + *onFailure*: o tratamento de falhas é aplicado à etapa da seguinte forma: + Se *OnFailure* estiver definido como`Abort`, AWSTOE sai do loop e repete a etapa de acordo com a política de repetição. Após o número máximo de tentativas de repetição, AWSTOE marca a etapa atual como falhada e interrompe a execução do processo. AWSTOE define o código de status da fase principal e do documento como`Failed`. **nota** Nenhuma outra etapa é executada após a etapa malsucedida. + Se *onFailure* estiver definido como `Continue`, AWSTOE sai do loop e repete a etapa de acordo com a política de repetição. Após o número máximo de tentativas de repetição, AWSTOE marca a etapa atual como falhada e continua executando a próxima etapa. AWSTOE define o código de status da fase principal e do documento como`Failed`. + Se *onFailure* estiver definido como `Ignore`, AWSTOE sai do loop e repete a etapa de acordo com a política de repetição. Após o número máximo de tentativas de repetição, AWSTOE marca a etapa atual como `IgnoredFailure` e continua executando a próxima etapa. AWSTOE define o código de status da fase principal e do documento como`SuccessWithIgnoredFailure`. **nota** Isso ainda é considerado uma execução bem-sucedida, mas inclui informações para que você saiba que uma ou mais etapas falharam e foram ignoradas. + *maxAttempts*: para cada nova tentativa, toda a etapa e todas as iterações são executadas desde o início. + *status*: o status geral da execução de uma etapa. `status` não representa o status de iterações individuais. O status de uma etapa com loops é determinado da seguinte forma: + Se uma única iteração falhar na execução, o status de uma etapa aponta para uma falha. + Se todas as iterações forem bem-sucedidas, o status de uma etapa indicará um sucesso. + *startTime*: a hora geral de início da execução de uma etapa. Não representa a hora de início das iterações individuais. + *endTime*: a hora geral de término da execução de uma etapa. Não representa a hora de término das iterações individuais. + *failureMessage*: inclui os índices de iteração que falharam em caso de erros sem tempo limite. Em caso de erros de tempo limite, a mensagem indica que a execução do loop falhou. Mensagens de erro individuais para cada iteração não são fornecidas para minimizar o tamanho das mensagens de falha. ## Saídas de etapa e iteração Cada iteração contém uma saída. No final de uma execução de loop, AWSTOE consolida todas as saídas de iteração bem-sucedidas em. `detailedOutput.json` As saídas consolidadas são um agrupamento de valores que pertencem às chaves de saída correspondentes, conforme definido no esquema de saída do módulo de ação. O exemplo a seguir mostra como as saídas são consolidadas: **Saída de `ExecuteBash` para a Iteração 1** ``` { "stdout":"Hello" } ``` **Saída de `ExecuteBash` para a Iteração 2** ``` { "stdout":"World" } ``` **Saída de `ExecuteBash` para a Etapa** ``` { "stdout":"Hello\nWorld" } ``` Por exemplo, `ExecuteBash`, `ExecutePowerShell` e `ExecuteBinary` são módulos de ação que retornam `STDOUT` como saída do módulo de ação. As mensagens `STDOUT` são unidas ao novo caractere de linha para produzir a saída geral da etapa em `detailedOutput.json`. AWSTOE não consolidará os resultados de iterações malsucedidas.