Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Utiliser des variables dans votre document de composant personnalisé
Les variables permettent d'étiqueter les données avec des noms significatifs qui peuvent être utilisés dans l'ensemble d'une application. Vous pouvez définir des variables personnalisées avec des formats simples et lisibles pour les flux de travail complexes, et les référencer dans le document du composant d'application YAML correspondant à un AWSTOE composant.
Cette section fournit des informations pour vous aider à définir les variables de votre AWSTOE composant dans le document du composant d'application YAML, notamment la syntaxe, les contraintes de nom et des exemples.
## Constantes
Les constantes sont des variables immuables qui ne peuvent pas être modifiées ou remplacées une fois définies. Les constantes peuvent être définies à l'aide des valeurs figurant dans la `constants` section d'un AWSTOE document.
**Règles pour les noms de constantes**
+ Le nom doit comporter entre 3 et 128 caractères.
+ Le nom ne peut contenir que des caractères alphanumériques (a-z, A-Z, 0-9), des tirets (-) ou des traits de soulignement (\$1).
+ Le nom doit être unique dans le document.
+ Le nom doit être spécifié sous forme de chaîne YAML.
**Syntaxe**
```
constants:
- :
type:
value:
```
| Nom de la touche | Obligatoire | Description |
| --- | --- | --- |
| `name` | Oui | Nom de la constante. Doit être unique pour le document (il ne doit pas être identique aux autres noms de paramètres ou constantes). |
| `value` | Oui | Valeur de la constante. |
| `type` | Oui | Type de constante. Le type pris en charge eststring. |
**Valeurs constantes de référence dans un document**
Vous pouvez référencer des constantes dans les entrées d'étape ou de boucle à l'intérieur de votre document YAML, comme suit :
+ Les références constantes distinguent les majuscules et minuscules, et le nom doit correspondre exactement.
+ Le nom doit être placé entre accolades `{{` *MyConstant* `}}` doubles.
+ Les espaces sont autorisés à l'intérieur des bretelles et sont automatiquement découpés. Par exemple, toutes les références suivantes sont valides :
`{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}`
+ La référence dans le document YAML doit être spécifiée sous forme de chaîne (entre guillemets simples ou doubles).
Par exemple : n'`- {{ MyConstant }}`est pas valide, car il n'est pas identifié comme une chaîne.
Toutefois, les références suivantes sont toutes deux valides : `- '{{ MyConstant }}'` et`- "{{ MyConstant }}"`.
**Exemples**
Constante référencée dans les entrées d'étape
```
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 référencée dans les entrées de boucle
```
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 }}
```
## Parameters
Les paramètres sont des variables mutables, avec des paramètres que l'application appelante peut fournir au moment de l'exécution. Vous pouvez définir des paramètres dans la `Parameters` section du document YAML.
**Règles relatives aux noms de paramètres**
+ Le nom doit comporter entre 3 et 128 caractères.
+ Le nom ne peut contenir que des caractères alphanumériques (a-z, A-Z, 0-9), des tirets (-) ou des traits de soulignement (\$1).
+ Le nom doit être unique dans le document.
+ Le nom doit être spécifié sous forme de chaîne YAML.
### Syntaxe
```
parameters:
- :
type:
default:
description:
```
| Nom de la touche | Obligatoire | Description |
| --- | --- | --- |
| `name` | Oui | Nom du paramètre. Doit être unique pour le document (il ne doit pas être identique aux autres noms de paramètres ou constantes). |
| `type` | Oui | Type de données du paramètre. Les types pris en charge incluent :`string`. |
| `default` | Non | La valeur par défaut du paramètre. |
| `description` | Non | Décrit le paramètre. |
### Valeurs des paramètres de référence dans un document
Vous pouvez référencer des paramètres dans des entrées par étapes ou en boucle dans votre document YAML, comme suit :
+ Les références aux paramètres distinguent les majuscules et minuscules, et le nom doit correspondre exactement.
+ Le nom doit être placé entre accolades `{{` *MyParameter* `}}` doubles.
+ Les espaces sont autorisés à l'intérieur des bretelles et sont automatiquement découpés. Par exemple, toutes les références suivantes sont valides :
`{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}`
+ La référence dans le document YAML doit être spécifiée sous forme de chaîne (entre guillemets simples ou doubles).
Par exemple : n'`- {{ MyParameter }}`est pas valide, car il n'est pas identifié comme une chaîne.
Toutefois, les références suivantes sont toutes deux valides : `- '{{ MyParameter }}'` et`- "{{ MyParameter }}"`.
**Exemples**
Les exemples suivants montrent comment utiliser des paramètres dans votre document YAML :
+ Référez-vous à un paramètre dans les entrées d'étape :
```
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'
```
+ Référez-vous à un paramètre dans les entrées de boucle :
```
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 }}
```
### Remplacer les paramètres lors de l'exécution
Vous pouvez utiliser l'`--parameters`option AWS CLI avec une paire clé-valeur pour définir une valeur de paramètre lors de l'exécution.
+ Spécifiez la paire clé-valeur du paramètre sous forme de nom et de valeur, séparés par un signe égal (=).
+ Les paramètres multiples doivent être séparés par une virgule.
+ Les noms de paramètres introuvables dans le document du composant YAML sont ignorés.
+ Le nom et la valeur du paramètre sont tous deux obligatoires.
**Important**
Les paramètres des composants sont des valeurs en texte brut et sont connectés AWS CloudTrail. Nous vous recommandons d'utiliser AWS Secrets Manager le AWS Systems Manager Parameter Store pour stocker vos secrets. Pour plus d'informations sur Secrets Manager, voir [Qu'est-ce que Secrets Manager ?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) dans le *guide de AWS Secrets Manager l'utilisateur*. Pour plus d'informations sur AWS Systems Manager Parameter Store, voir [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) dans le *guide de AWS Systems Manager l'utilisateur*.
#### Syntaxe
```
--parameters name1=value1,name2=value2...
```
| Option CLI | Obligatoire | Description |
| --- | --- | --- |
| --paramètres *name* =*value*,... | Non | Cette option prend une liste de paires clé-valeur, avec le nom du paramètre comme clé. |
**Exemples**
Les exemples suivants montrent comment utiliser des paramètres dans votre document YAML :
+ La paire clé-valeur du paramètre spécifiée dans cette `--parameter` option n'est pas valide :
```
--parameters ntp-server=
```
+ Définissez une paire clé-valeur de paramètre avec l'`--parameter`option dans le champ : AWS CLI
```
--parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com
```
+ Définissez plusieurs paires clé-valeur de paramètres à l'aide de l'`--parameter`option suivante : AWS CLI
```
--parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com
```
## Utiliser les paramètres du magasin de paramètres de Systems Manager
Vous pouvez référencer les AWS Systems Manager paramètres du magasin de paramètres (paramètres SSM) dans les documents de vos composants en préfixant les variables par. `aws:ssm` Par exemple,
`{{ aws:ssm:/my/param }}`se résout à la valeur du paramètre `/my/param` SSM.
Cette fonctionnalité prend en charge les types de paramètres SSM suivants :
+ Chaîne — Correspond au type de AWSTOE chaîne.
+ StringList — Correspond au AWSTOE `stringList` type.
+ SecureString — Correspond au type de AWSTOE chaîne.
Pour plus d'informations sur le magasin de paramètres, voir [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) dans le *guide de AWS Systems Manager l'utilisateur*.
Vous pouvez également référencer des AWS Secrets Manager secrets à l'aide d'un paramètre `SecureString` SSM. Par exemple : `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`. Pour plus d'informations, consultez la section [Référencement de AWS Secrets Manager secrets à partir des paramètres du Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html).
**Important**
Image Builder exclut la résolution des `SecureString` paramètres de ses journaux. Cependant, vous devez également vous assurer que les informations sensibles ne sont pas enregistrées par le biais des commandes émises dans le document du composant. Par exemple, si vous utilisez la `echo` commande avec une chaîne sécurisée, la commande écrit une valeur en texte brut dans le journal.
### Autorisations IAM requises
Pour utiliser les paramètres de Systems Manager dans vos composants, votre rôle d'instance doit être `ssm:GetParameter` autorisé à accéder à l'ARN de la ressource de paramètres. Par exemple :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:GetParameter",
"Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*"
}
]
}
```
------
Pour accéder aux valeurs chiffrées, vous devez également disposer des autorisations suivantes :
+ Ajoutez `kms:Decrypt` des `SecureString` paramètres ou AWS Secrets Manager des valeurs chiffrés gérés par un client AWS KMS key.
+ Ajoutez `secretsmanager:GetSecretValue` si vous faites référence à un secret du Secrets Manager.
### Référencer un paramètre SSM dans un document de composant
L'exemple suivant montre comment référencer un paramètre Systems Manager Parameter Store parmi les paramètres Systems Manager d'un composant :
```
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 }}."
```
### Résolution des variables d'exécution dynamiques pour les paramètres SSM
AWSTOE fournit la fonction intégrée suivante que vous pouvez utiliser dans les références de variables pour manipuler ou transformer des valeurs lors de l'exécution.
#### fonction de résolution
La `resolve` fonction résout une référence de variable à l'intérieur d'une autre référence de variable, permettant un référencement dynamique des noms de variables. Cela est utile lorsque vous travaillez avec des paramètres SSM où une partie du chemin du paramètre peut être variable et transmise en tant que paramètre de document.
La `resolve` fonction prend uniquement en charge la résolution dynamique de la partie du nom d'un paramètre SSM.
##### Syntaxe
`dynamic_variable`Dans l'exemple suivant, le nom d'un paramètre SSM doit être l'un des suivants :
+ Une référence de paramètre SSM (par exemple,`aws:ssm:/my/param`)
+ Une référence aux paramètres d'un document de composant (par exemple,`parameter-name`)
```
{{ aws:ssm:resolve(dynamic_variable) }}
```
##### Exemple : résolution d'un paramètre SSM lors de l'exécution
L'exemple suivant montre comment utiliser la `resolve` fonction dans un document de composant 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) }}"
```