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á. # 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) }}" ```