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 le cadre de documentation des AWSTOE composants pour les composants personnalisés
Pour créer un composant à l'aide de la structure de composants AWS Task Orchestrator and Executor (AWSTOE), vous devez fournir un document basé sur YAML qui représente les phases et les étapes applicables au composant que vous créez. Services AWS utilisent votre composant lorsqu'ils créent une nouvelle image de machine Amazon (AMI) ou une nouvelle image de conteneur.
**Topics**
+ [Flux de travail documentaire des composants](#component-doc-workflow)
+ [Journalisation des composants](#component-logging)
+ [Chainage des entrées et des sorties](#document-chaining)
+ [Schéma du document et définitions](#document-schema)
+ [Exemples de documents](#document-example)
+ [Utiliser des variables dans votre document de composant personnalisé](toe-user-defined-variables.md)
+ [Utiliser des constructions conditionnelles dans AWSTOE](toe-conditional-constructs.md)
+ [Utiliser des opérateurs de comparaison dans les documents relatifs aux AWSTOE composants](toe-comparison-operators.md)
+ [Utiliser des opérateurs logiques dans les documents relatifs aux AWSTOE composants](toe-logical-operators.md)
+ [Utiliser des constructions en boucle dans AWSTOE](toe-looping-constructs.md)
## Flux de travail documentaire des composants
Le document du AWSTOE composant utilise des phases et des étapes pour regrouper les tâches associées et organiser ces tâches dans un flux de travail logique pour le composant.
**Astuce**
Le service qui utilise votre composant pour créer une image peut implémenter des règles concernant les phases à utiliser pour son processus de génération et le moment où ces phases sont autorisées à s'exécuter. Il est important d'en tenir compte lors de la conception de votre composant.
**Phases**
Les phases représentent la progression de votre flux de travail tout au long du processus de création de l'image. Par exemple, le service Image Builder utilise `build` et met en `validate` phase les images qu'il produit au cours de sa *phase de création*. Il utilise les `container-host-test` phases `test` et au cours de sa *phase de test* pour s'assurer que l'instantané d'image ou l'image du conteneur produit les résultats attendus avant de créer l'AMI finale ou de distribuer l'image du conteneur.
Lorsque le composant s'exécute, les commandes associées à chaque phase sont appliquées dans l'ordre dans lequel elles apparaissent dans le document du composant.
**Règles pour les phases**
+ Chaque nom de phase doit être unique dans un document.
+ Vous pouvez définir de nombreuses phases dans votre document.
+ Vous devez inclure au moins l'une des phases suivantes dans votre document :
+ **build** — pour Image Builder, cette phase est généralement utilisée pendant la *phase de construction*.
+ **valider** — pour Image Builder, cette phase est généralement utilisée pendant la *phase de construction*.
+ **test** — pour Image Builder, cette phase est généralement utilisée pendant la *phase de test*.
+ Les phases s'exécutent toujours dans l'ordre dans lequel elles sont définies dans le document. L'ordre dans lequel elles sont spécifiées pour AWSTOE les commandes du n' AWS CLI a aucun effet.
**Étapes**
Les étapes sont des unités de travail individuelles qui définissent le flux de travail au sein de chaque phase. Les étapes sont exécutées par ordre séquentiel. Cependant, l'entrée ou la sortie d'une étape peuvent également alimenter une étape suivante en tant qu'entrée. C'est ce qu'on appelle le « chaînage ».
**Règles relatives aux étapes**
+ Le nom de l'étape doit être unique pour la phase.
+ L'étape doit utiliser une action prise en charge (module d'action) qui renvoie un code de sortie.
Pour obtenir la liste complète des modules d'action pris en charge, leur fonctionnement, leurs input/output valeurs et des exemples, voir[Modules d'action pris en charge par le gestionnaire de AWSTOE composants](toe-action-modules.md).
## Journalisation des composants
AWSTOE crée un nouveau dossier journal sur les instances EC2 utilisées pour créer et tester une nouvelle image, chaque fois que votre composant s'exécute. Pour les images de conteneur, le dossier journal est stocké dans le conteneur.
Pour faciliter le dépannage en cas de problème lors du processus de création de l'image, le document d'entrée et tous les fichiers de sortie AWSTOE créés lors de l'exécution du composant sont stockés dans le dossier journal.
Le nom du dossier journal comprend les éléments suivants :
1. **Répertoire des journaux** : lorsqu'un service exécute un AWSTOE composant, il est transmis dans le répertoire des journaux, ainsi que les autres paramètres de la commande. Dans les exemples suivants, nous montrons le format de fichier journal utilisé par Image Builder.
+ **Linux et macOS** : `/var/lib/amazon/toe/`
+ **Windows** : `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\`
1. **Préfixe de fichier** — Il s'agit d'un préfixe standard utilisé pour tous les composants : « »`TOE_`.
1. Durée d'**exécution : il s'**agit d'un horodatage au format YYYY-MM-DD \$1HH-MM-SS\$1UTC-0.
1. **ID d'exécution** : il s'agit du GUID attribué lors de l' AWSTOE exécution d'un ou de plusieurs composants.
Exemple : `/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4`
AWSTOE stocke les fichiers principaux suivants dans le dossier journal :
**Fichiers d'entrée**
+ **document.yaml** — Document utilisé comme entrée pour la commande. Une fois le composant exécuté, ce fichier est stocké sous forme d'artefact.
**Fichiers de sortie**
+ **application.log** — Le journal de l'application contient des informations horodatées AWSTOE sur le niveau de débogage indiquant ce qui se passe pendant l'exécution du composant.
+ **detailedoutput.json** — Ce fichier JSON contient des informations détaillées sur l'état d'exécution, les entrées, les sorties et les échecs pour tous les documents, phases et étapes applicables au composant lors de son exécution.
+ **console.log** — Le journal de la console contient toutes les informations de sortie standard (stdout) et d'erreur standard (stderr) écrites sur la console pendant l'exécution du composant. AWSTOE
+ **chaining.json** — Ce fichier JSON représente les optimisations AWSTOE appliquées pour résoudre les expressions de chaînage.
**Note**
Le dossier journal peut également contenir d'autres fichiers temporaires qui ne sont pas abordés ici.
## Chainage des entrées et des sorties
L'application AWSTOE de gestion de configuration fournit une fonctionnalité permettant de chaîner les entrées et les sorties en écrivant des références dans les formats suivants :
`{{ phase_name.step_name.inputs/outputs.variable }}`
or
`{{ phase_name.step_name.inputs/outputs[index].variable }}`
La fonction de chaînage vous permet de recycler le code et d'améliorer la maintenabilité du document.
**Règles de chaînage**
+ Les expressions de chaînage ne peuvent être utilisées que dans la section des entrées de chaque étape.
+ Les instructions contenant des expressions de chaînage doivent être placées entre guillemets. Par exemple :
+ **Expression non valide** : `echo {{ phase.step.inputs.variable }}`
+ **Expression valide** : `"echo {{ phase.step.inputs.variable }}"`
+ **Expression valide** : `'echo {{ phase.step.inputs.variable }}'`
+ Les expressions de chaînage peuvent faire référence à des variables issues d'autres étapes et phases du même document. Cependant, le service d'appel peut avoir des règles qui exigent que le chaînage des expressions ne fonctionne que dans le contexte d'une seule étape. Par exemple, Image Builder ne prend pas en charge le chaînage entre la *phase de création* et la *phase de test*, car il exécute chaque étape indépendamment.
+ Les index des expressions de chaînage suivent une indexation basée sur zéro. L'indice commence par zéro (0) pour référencer le premier élément.
**Exemples**
Pour faire référence à la variable source dans la deuxième entrée de l'étape d'exemple suivante, le modèle de chaînage est`{{ 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'
```
Pour faire référence à la variable de sortie (égale à « Hello ») de l'étape d'exemple suivante, le modèle de chaînage est`{{ build.SamplePowerShellStep.outputs.stdout }}`.
```
phases:
- name: 'build'
steps:
- name: SamplePowerShellStep
action: ExecutePowerShell
timeoutSeconds: 120
onFailure: Abort
maxAttempts: 3
inputs:
commands:
- 'Write-Host "Hello"'
```
## Schéma du document et définitions
Le schéma YAML d'un document est le suivant.
```
name: (optional)
description: (optional)
schemaVersion: "string"
phases:
- name: "string"
steps:
- name: "string"
action: "string"
timeoutSeconds: integer
onFailure: "Abort|Continue|Ignore"
maxAttempts: integer
inputs:
```
Les définitions de schéma d'un document sont les suivantes.
| Champ | Description | Type | Obligatoire |
| --- | --- | --- | --- |
| name | Nom du document. | String | Non |
| description | Description du document. | String | Non |
| schemaVersion | Version du schéma du document, actuellement 1.0. | String | Oui |
| phases | Une liste des phases avec leurs étapes. | List | Oui |
Les définitions du schéma d'une phase sont les suivantes.
| Champ | Description | Type | Obligatoire |
| --- | --- | --- | --- |
| name | Nom de la phase. | String | Oui |
| steps | Liste des étapes de la phase. | List | Oui |
Les définitions du schéma d'une étape sont les suivantes.
| Champ | Description | Type | Obligatoire | Valeur par défaut |
| --- | --- | --- | --- | --- |
| name | Nom défini par l'utilisateur pour l'étape. | String | | |
| action | Mot-clé relatif au module qui exécute l'étape. | String | | |
| timeoutSeconds | Nombre de secondes pendant lesquelles l'étape s'exécute avant d'échouer ou de réessayer. Supporte également la valeur -1, ce qui indique un délai d'expiration infini. 0 et les autres valeurs négatives ne sont pas autorisées. | Entier | Non | 7 200 secondes (120 minutes) |
| onFailure | Spécifie ce que l'étape doit faire en cas d'échec. Les valeurs valides sont les suivantes : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/imagebuilder/latest/userguide/toe-use-documents.html) | String | Non | Interruption |
| maxAttempts | Nombre maximum de tentatives autorisées avant d'échouer à l'étape. | Entier | Non | 1 |
| inputs | Contient les paramètres requis par le module d'action pour exécuter l'étape. | Dict | Oui | |
## Exemples de documents
Les exemples suivants présentent des documents de AWSTOE composants qui exécutent des tâches pour le système d'exploitation cible.
------
#### [ Linux ]
**Exemple 1 : Exécuter un fichier binaire personnalisé**
Voici un exemple de document qui télécharge et exécute un fichier binaire personnalisé sur une instance 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 ]
**Exemple 1 : Installation des mises à jour Windows**
Voici un exemple de document qui installe toutes les mises à jour Windows disponibles, exécute un script de configuration, valide les modifications avant la création de l'AMI et teste les modifications après la création de l'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}}'
```
**Exemple 2 : installer le AWS CLI sur une instance Windows**
Voici un exemple de document qui installe le AWS CLI sur une instance Windows à l'aide du fichier d'installation.
```
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 }}'
```
**Exemple 3 : installer le AWS CLI avec le programme d'installation MSI**
Voici un exemple de document qui installe le AWS CLI avec le programme d'installation 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 ]
**Exemple 1 : Exécuter un fichier binaire macOS personnalisé**
Voici un exemple de document qui télécharge et exécute un fichier binaire personnalisé sur une instance de 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 }}'
```
------
# 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) }}"
```
# Utiliser des constructions conditionnelles dans AWSTOE
Les constructions conditionnelles exécutent différentes actions dans le document de votre composant selon que l'expression conditionnelle spécifiée est évaluée à `true` ou. `false` Vous pouvez utiliser la `if` construction pour contrôler le flux d'exécution dans le document de votre composant.
## si Construct
Vous pouvez utiliser la `if` construction pour évaluer si une étape doit être exécutée ou non. Par défaut, lorsque l'expression `if` conditionnelle est évaluée à`true`, AWSTOE exécute l'étape, et lorsque la condition est évaluée à`false`, AWSTOE ignore l'étape. Si une étape est ignorée, elle est considérée comme une étape réussie lorsqu' AWSTOE il est déterminé si la phase et le document ont été exécutés correctement.
**Note**
Une `if` instruction n'est évaluée qu'une seule fois, même si l'étape déclenche un redémarrage. Si une étape redémarre, elle reconnaît que l'`if`instruction a déjà été évaluée et continue là où elle s'est arrêtée.
### Syntaxe
```
if:
- :
[then: ]
[else: ]
```
| Nom de la touche | Obligatoire | Description |
| --- | --- | --- |
| expression conditionnelle | Oui | L'expression conditionnelle peut contenir exactement l'un des types d'opérateurs suivants au niveau supérieur. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/imagebuilder/latest/userguide/toe-conditional-constructs.html) Si votre expression doit satisfaire plusieurs conditions, utilisez un opérateur logique pour spécifier vos conditions. |
| then | Non | Définit l'action à effectuer si l'expression conditionnelle est évaluée à`true`. |
| else | Non | Définit l'action à effectuer si l'expression conditionnelle est évaluée à`false`. |
| action par étapes | Conditionnel | Lorsque vous utilisez `then` ou`else`, vous devez spécifier l'une des étapes suivantes : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/imagebuilder/latest/userguide/toe-conditional-constructs.html) |
**Exemple 1 : installer le package**
Les exemples d'étapes suivants, tirés d'un document de AWSTOE composant, utilisent des opérateurs logiques pour tester une valeur de paramètre et exécuter les commandes du gestionnaire de packages appropriées pour installer une application si le package est décompressé.
```
- 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
```
**Exemple 2 : sauter une étape**
L'exemple suivant montre deux manières de sauter une étape. L'un utilise un opérateur logique et l'autre un opérateur de comparaison avec l'action `Skip` step.
```
# 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'
```
# Utiliser des opérateurs de comparaison dans les documents relatifs aux AWSTOE composants
Vous pouvez utiliser les opérateurs de comparaison suivants avec le module **[Affirmer](toe-action-modules.md#action-modules-assertion)** d'action et avec les expressions conditionnelles qui utilisent le[si ConstructSyntaxe](toe-conditional-constructs.md#toe-conditional-if). Un opérateur de comparaison peut agir sur une seule valeur, par exemple`stringIsEmpty`, ou il peut comparer une valeur de référence à une deuxième valeur (valeur variable) pour déterminer si l'expression conditionnelle est évaluée à `true` ou`false`.
Si la comparaison fonctionne sur deux valeurs, la seconde valeur peut être une variable de chaînage.
Lorsque vous comparez des valeurs d'un type différent, les conversions de valeurs suivantes peuvent avoir lieu avant la comparaison :
+ Pour les comparaisons numériques, si la valeur de la variable est une chaîne, AWSTOE convertit la chaîne en nombre avant l'évaluation. Si la conversion n'est pas possible, la comparaison est renvoyée`false`. Par exemple, si la valeur de la variable est`"1.0"`, la conversion fonctionne, mais si c'est la valeur de la variable, `"a10"` la conversion échoue.
+ Pour les comparaisons de chaînes, si la valeur de la variable est un nombre, elle est AWSTOE convertie en chaîne avant l'évaluation.
## Comparez les chaînes
Les opérateurs de comparaison suivants fonctionnent avec des chaînes pour comparer des valeurs, pour tester la présence d'espaces ou d'une chaîne vide, ou pour comparer une valeur d'entrée à un modèle d'expression régulière. Les comparaisons de chaînes ne font pas la distinction majuscules/majuscules et ne réduisent pas les espaces entre le début et la fin des entrées de chaîne.
**Opérateurs de comparaison de chaînes**
+ [stringIsEmpty](#stringIsEmpty)
+ [stringIsWhitespace](#stringIsWhitespace)
+ [stringEquals](#stringEquals)
+ [stringLessThan](#stringLessThan)
+ [stringLessThanEquals](#stringLessThanEquals)
+ [stringGreaterThan](#stringGreaterThan)
+ [stringGreaterThanEquals](#stringGreaterThanEquals)
+ [patternMatches](#patternMatches)
**stringIsEmpty**
L'`stringIsEmpty`opérateur revient `true` si la chaîne spécifiée ne contient aucun caractère. Par exemple :
```
# Evaluates to true
stringIsEmpty: ""
# Evaluates to false
stringIsEmpty: " "
# Evaluates to false
stringIsEmpty: "Hello."
```
**stringIsWhitespace**
Teste si la chaîne spécifiée pour ne `stringIsWhitespace` contient que des espaces. Par exemple :
```
# Evaluates to true
stringIsWhitespace: " "
# Evaluates to false
stringIsWhitespace: ""
# Evaluates to false
stringIsWhitespace: " Hello?"
```
**String est égal**
Teste si la chaîne spécifiée pour `stringEquals` correspond exactement à la chaîne spécifiée dans le `value` paramètre. Par exemple :
```
# 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**
Teste si la chaîne spécifiée pour `stringLessThan` est inférieure à la chaîne spécifiée dans le `value` paramètre. Par exemple :
```
# 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'
```
**stringLessThanÉgal**
Teste si la chaîne spécifiée pour `stringLessThanEquals` est inférieure ou égale à la chaîne spécifiée dans le `value` paramètre. Par exemple :
```
# 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**
Teste si la chaîne spécifiée pour `stringGreaterThan` est supérieure à la chaîne spécifiée dans le `value` paramètre. Par exemple :
```
# 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'
```
**stringGreaterThanÉgal**
Teste si la chaîne spécifiée pour `stringGreaterThanEquals` est supérieure ou égale à la chaîne spécifiée dans le `value` paramètre. Par exemple :
```
# 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'
```
**Correspondances à motifs**
Teste si la chaîne spécifiée dans le `value` paramètre correspond au modèle d'expression régulière spécifié pour`patternMatches`. La comparaison utilise le [package Golang regexp](https://pkg.go.dev/regexp), qui est conforme à la syntaxe. RE2 Pour plus d'informations sur RE2 les règles, consultez le référentiel [google/ re2](https://github.com/google/re2/wiki/Syntax) dans *GitHub*.
L'exemple suivant montre une correspondance de modèle qui renvoie `true` :
```
patternMatches: '^[a-z]+$'
value: 'ThisIsValue'
```
## Comparez les chiffres
Les opérateurs de comparaison suivants fonctionnent avec des nombres. Les valeurs fournies pour ces opérateurs doivent être de l'un des types suivants, conformément à la spécification YAML. Support pour les comparaisons numériques utilisant l'opérateur de comparaison de gros paquets Golang, par exemple : [func (\$1Float](https://pkg.go.dev/math/big#Float.Cmp)) Cmp.
+ Entier
+ Float (basé sur float64, qui prend en charge les nombres de -1,7e\$1308 à \$11,7e\$1308)
+ Une chaîne qui correspond au modèle d'expression régulière suivant : `^[-+]?([0-9]+[.])?[0-9]+$`
**Opérateurs de comparaison de nombres**
+ [numberEquals](#numberEquals)
+ [numberLessThan](#numberLessThan)
+ [numberLessThanEquals](#numberLessThanEquals)
+ [numberGreaterThan](#numberGreaterThan)
+ [numberGreaterThanEquals](#numberGreaterThanEquals)
**Le nombre est égal**
Teste si le nombre spécifié pour `numberEquals` est égal au nombre spécifié dans le `value` paramètre. Tous les exemples de comparaison suivants renvoient `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**
Teste si le nombre spécifié pour `numberLessThan` est inférieur au nombre spécifié dans le `value` paramètre. Par exemple :
```
# Evaluates to true
numberLessThan: 2
value: 1
# Evaluates to true
numberLessThan: 2
value: 1.9
# Evaluates to false
numberLessThan: 2
value: '2'
```
**numberLessThanÉgal**
Teste si le nombre spécifié pour `numberLessThanEquals` est inférieur ou égal au nombre spécifié dans le `value` paramètre. Par exemple :
```
# 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**
Teste si le nombre spécifié pour `numberGreaterThan` est supérieur au nombre spécifié dans le `value` paramètre. Par exemple :
```
# Evaluates to true
numberGreaterThan: 1
value: 2
# Evaluates to true
numberGreaterThan: 1
value: 1.1
# Evaluates to false
numberGreaterThan: 1
value: '1'
```
**numberGreaterThanÉgal**
Teste si le nombre spécifié pour `numberGreaterThanEquals` est supérieur ou égal au nombre spécifié dans le `value` paramètre. Par exemple :
```
# 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
```
## Vérifier les fichiers
Les opérateurs de comparaison suivants vérifient le hachage du fichier ou vérifient si un fichier ou un dossier existe.
**Opérateurs de fichiers et de dossiers**
+ [binaryExists](#binaryExists)
+ [fileExists](#fileExists)
+ [folderExists](#folderExists)
+ [fileMD5Equals](#fileMD5Equals)
+ [fileSHA1Equals](#fileSHA1Equals)
+ [fileSHA256Equals](#fileSHA256Equals)
+ [fileSHA512Equals](#fileSHA512Equals)
**Le binaire existe**
Teste si une application est disponible dans le chemin actuel. Par exemple :
```
binaryExists: 'foo'
```
Sur les systèmes Linux et macOS, pour une application nommée*foo*, cela fonctionne de la même manière que la commande bash suivante :**type *foo* >/dev/null 2>&1**, où **\$1? == 0** indique une comparaison réussie.
Sur les systèmes Windows, pour une application nommée*foo*, cela fonctionne de la même manière que la PowerShell commande **& C:\$1Windows\$1System32\$1where.exe /Q *foo*** où **\$1LASTEXITCODE = 0** indique une comparaison réussie.
**Le fichier existe**
Teste si un fichier existe au chemin spécifié. Vous pouvez fournir un chemin absolu ou relatif. Si l'emplacement que vous spécifiez existe et est un fichier, la comparaison est évaluée à`true`. Par exemple :
```
fileExists: '/path/to/file'
```
Sur les systèmes Linux et macOS, cela fonctionne de la même manière que la commande bash suivante :**-d */path/to/file***, où **\$1? == 0** indique une comparaison réussie.
Sur les systèmes Windows, cela fonctionne de la même manière que la PowerShell commande**Test-Path -Path '*C:\$1path\$1to\$1file*' -PathType 'Leaf'**.
**Le dossier existe**
Teste si un dossier existe sur le chemin spécifié. Vous pouvez fournir un chemin absolu ou relatif. Si l'emplacement que vous spécifiez existe et qu'il s'agit d'un dossier, la comparaison est évaluée à`true`. Par exemple :
```
folderExists: '/path/to/folder'
```
Sur les systèmes Linux et macOS, cela fonctionne de la même manière que la commande bash suivante :**-d */path/to/folder***, où **\$1? == 0** indique une comparaison réussie.
Sur les systèmes Windows, cela fonctionne de la même manière que la PowerShell commande**Test-Path -Path '*C:\$1path\$1to\$1folder*' -PathType 'Container'**.
**le fichier MD5 est égal**
Teste si le MD5 hachage d'un fichier est égal à une valeur spécifiée. Par exemple :
```
fileMD5Equals: ''
path: '/path/to/file'
```
**le fichier SHA1 est égal**
Teste si le SHA1 hachage d'un fichier est égal à une valeur spécifiée. Par exemple :
```
fileSHA1Equals: ''
path: '/path/to/file'
```
**le fichier SHA256 est égal**
Teste si le SHA256 hachage d'un fichier est égal à une valeur spécifiée. Par exemple :
```
fileSHA256Equals: ''
path: '/path/to/file'
```
**le fichier SHA512 est égal**
Teste si le SHA512 hachage d'un fichier est égal à une valeur spécifiée. Par exemple :
```
fileSHA512Equals: ''
path: '/path/to/file'
```
# Utiliser des opérateurs logiques dans les documents relatifs aux AWSTOE composants
Vous pouvez utiliser les opérateurs logiques suivants pour ajouter ou modifier des expressions conditionnelles dans votre document de composant. AWSTOE évalue les expressions conditionnelles dans l'ordre dans lequel les conditions sont spécifiées. Pour plus d'informations sur les opérateurs de comparaison pour les documents de composants, consultez[Utiliser des opérateurs de comparaison dans les documents relatifs aux AWSTOE composants](toe-comparison-operators.md).
**et **
Avec l'`and`opérateur, vous pouvez évaluer deux ou plusieurs comparaisons sous la forme d'une seule expression. L'expression est évaluée `true` lorsque toutes les conditions de la liste sont vraies. Dans le cas contraire, l'expression est évaluée à. `false`
**Exemples :**
L'exemple suivant effectue deux comparaisons : une chaîne et un nombre. Les deux comparaisons étant vraies, l'expression est évaluée comme vraie.
```
and:
- stringEquals: 'test_string'
value: 'test_string'
- numberEquals: 1
value: 1
```
L'exemple suivant effectue également deux comparaisons. La première comparaison est fausse, c'est à ce moment que l'évaluation s'arrête et que la seconde comparaison est ignorée. L'expression est évaluée à. `false`
```
and:
- stringEquals: 'test_string'
value: 'Hello world!'
- numberEquals: 1
value: 1
```
**ou**
Avec l'`or`opérateur, vous pouvez évaluer deux ou plusieurs comparaisons sous la forme d'une seule expression. L'expression indique `true` si l'une des comparaisons spécifiées est vraie. Si aucune des comparaisons spécifiées n'est évaluée à`true`, l'expression est évaluée à`false`.
**Exemples :**
L'exemple suivant effectue deux comparaisons : une chaîne et un nombre. La première comparaison étant vraie, l'expression est évaluée à `true` et la seconde comparaison est ignorée.
```
or:
- stringEquals: 'test_string'
value: 'test_string'
- numberEquals: 1
value: 3
```
L'exemple suivant effectue également deux comparaisons. La première comparaison est fausse, et l'évaluation se poursuit. La deuxième comparaison étant vraie, l'expression est évaluée à`true`.
```
or:
- stringEquals: 'test_string'
value: 'Hello world!'
- numberEquals: 1
value: 1
```
Dans le dernier exemple, les deux comparaisons étant fausses, l'expression est évaluée à`false`.
```
or:
- stringEquals: 'test_string'
value: 'Hello world!'
- numberEquals: 1
value: 3
```
**pas**
Avec l'`not`opérateur, vous pouvez annuler une seule comparaison. L'expression indique `true` si la comparaison est fausse. Si la comparaison est vraie, l'expression est évaluée à`false`.
**Exemples :**
L'exemple suivant effectue une comparaison de chaînes. La comparaison étant fausse, l'expression est évaluée à`true`.
```
not:
- stringEquals: 'test_string'
value: 'Hello world!'
```
L'exemple suivant effectue également une comparaison de chaînes. La comparaison étant vraie, l'expression est évaluée à`false`.
```
not:
- stringEquals: 'test_string'
value: 'test_string'
```
# Utiliser des constructions en boucle dans AWSTOE
Cette section fournit des informations pour vous aider à créer des constructions en boucle dans le. AWSTOE Les constructions en boucle définissent une séquence répétée d'instructions. Vous pouvez utiliser les types de constructions en boucle suivants dans : AWSTOE
+ `for`constructs — Itérer sur une séquence bornée d'entiers.
+ `forEach`construit
+ `forEach`boucle avec liste d'entrées : itère sur une collection limitée de chaînes.
+ `forEach`boucle avec liste délimitée : itère sur une collection limitée de chaînes jointes par un délimiteur.
**Note**
Les constructions en boucle ne prennent en charge que les types de données sous forme de chaîne.
**Topics**
+ [Variables d'itération de référence](#toe-loop-iteration-variables)
+ [Types de constructions en boucle](#toe-loop-types)
+ [Champs d'étape](#toe-loop-step-fields)
+ [Sorties d'étape et d'itération](#toe-loop-step-output)
## Variables d'itération de référence
Pour faire référence à l'index et à la valeur de la variable d'itération en cours, l'expression de référence `{{ loop.* }}` doit être utilisée dans le corps d'entrée d'une étape contenant une construction en boucle. Cette expression ne peut pas être utilisée pour faire référence aux variables d'itération de la construction en boucle d'une autre étape.
L'expression de référence comprend les membres suivants :
+ `{{ loop.index }}`— Position ordinale de l'itération en cours, indexée à. `0`
+ `{{ loop.value }}`— La valeur associée à la variable d'itération en cours.
### Noms des boucles
Toutes les constructions en boucle ont un champ de nom facultatif pour l'identification. Si un nom de boucle est fourni, il peut être utilisé pour faire référence à des variables d'itération dans le corps d'entrée de l'étape. Pour faire référence aux indices d'itération et aux valeurs d'une boucle nommée, utilisez `{{ .* }}` with `{{ loop.* }}` dans le corps de saisie de l'étape. Cette expression ne peut pas être utilisée pour faire référence à la construction en boucle nommée d'une autre étape.
L'expression de référence comprend les membres suivants :
+ `{{ .index }}`— Position ordinale de l'itération en cours de la boucle nommée, qui est indexée à. `0`
+ `{{ .value }}`— La valeur associée à la variable d'itération actuelle de la boucle nommée.
### Résoudre les expressions de référence
AWSTOE Résout les expressions de référence comme suit :
+ `{{ .* }}`— AWSTOE résout cette expression selon la logique suivante :
+ Si la boucle de l'étape en cours d'exécution correspond à la `` valeur, l'expression de référence est résolue en fonction de la structure en boucle de l'étape en cours d'exécution.
+ ``aboutit à la construction en boucle nommée si elle apparaît dans l'étape en cours d'exécution.
+ `{{ loop.* }}`— AWSTOE résout l'expression à l'aide de la construction en boucle définie dans l'étape en cours d'exécution.
Si des expressions de référence sont utilisées dans une étape ne contenant pas de boucle, les expressions AWSTOE ne sont pas résolues et elles apparaissent dans l'étape sans être remplacées.
**Note**
Les expressions de référence doivent être placées entre guillemets pour être correctement interprétées par le compilateur YAML.
## Types de constructions en boucle
Cette section fournit des informations et des exemples sur les types de construction en boucle qui peuvent être utilisés dans le AWSTOE.
**Topics**
+ [`for`boucle](#toe-loop-types-for)
+ [`forEach`boucle avec liste d'entrées](#toe-loop-types-foreach)
+ [`forEach`boucle avec liste délimitée](#toe-loop-types-foreach-delimited)
### `for`boucle
La `for` boucle itère sur une plage d'entiers spécifiée dans une limite définie par le début et la fin des variables. Les valeurs itératives font partie de l'ensemble `[start, end]` et incluent les valeurs limites.
AWSTOE vérifie les `updateBy` valeurs `start``end`, et pour s'assurer que la combinaison ne donne pas lieu à une boucle infinie.
`for`schéma de boucle
```
- name: "StepName"
action: "ActionModule"
loop:
name: "string"
for:
start: int
end: int
updateBy: int
inputs:
...
```
**`for`entrée en boucle**
| Champ | Description | Type | Obligatoire | Par défaut |
| --- | --- | --- | --- | --- |
| `name` | Nom unique de la boucle. Il doit être unique par rapport aux autres noms de boucle de la même phase. | String | Non | "" |
| `start` | Valeur de départ de l'itération. N'accepte pas le chaînage d'expressions. | Entier | Oui | N/A |
| `end` | Valeur finale de l'itération. N'accepte pas le chaînage d'expressions. | Entier | Oui | N/A |
| `updateBy` | Différence selon laquelle une valeur itérative est mise à jour par addition. Il doit s'agir d'une valeur négative ou positive différente de zéro. N'accepte pas le chaînage d'expressions. | Entier | Oui | N/A |
`for`exemple d'entrée en boucle
```
- 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
```
### `forEach`boucle avec liste d'entrées
La `forEach` boucle itère sur une liste explicite de valeurs, qui peuvent être des chaînes ou des expressions enchaînées.
`forEach`boucle avec schéma de liste d'entrées
```
- name: "StepName"
action: "ActionModule"
loop:
name: "string"
forEach:
- "string"
inputs:
...
```
**`forEach`boucle avec entrée de liste d'entrées**
| Champ | Description | Type | Obligatoire | Par défaut |
| --- | --- | --- | --- | --- |
| `name` | Nom unique de la boucle. Il doit être unique par rapport aux autres noms de boucle de la même phase. | String | Non | "" |
| Liste des chaînes de `forEach` boucles | Liste des chaînes pour l'itération. Accepte les expressions chaînées sous forme de chaînes dans la liste. Les expressions chaînées doivent être placées entre guillemets pour que le compilateur YAML puisse les interpréter correctement. | Liste de chaînes | Oui | N/A |
`forEach`boucle avec liste d'entrées, exemple 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
```
`forEach`boucle avec liste d'entrées, exemple 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 }}"
```
`forEach`exemple de boucle avec liste d'entrées 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 }}"
```
### `forEach`boucle avec liste délimitée
La boucle itère sur une chaîne contenant des valeurs séparées par un délimiteur. Pour itérer sur les constituants de la chaîne, utilisez AWSTOE le délimiteur pour diviser la chaîne en un tableau adapté à l'itération.
`forEach`boucle avec schéma de liste délimité
```
- name: "StepName"
action: "ActionModule"
loop:
name: "string"
forEach:
list: "string"
delimiter: ".,;:\n\t -_"
inputs:
...
```
**`forEach`boucle avec entrée de liste délimitée**
| Champ | Description | Type | Obligatoire | Par défaut |
| --- | --- | --- | --- | --- |
| `name` | Nom unique attribué à la boucle. Il doit être unique par rapport aux autres noms de boucles de la même phase. | String | Non | "" |
| `list` | Chaîne composée de chaînes constitutives reliées par un caractère délimiteur commun. Accepte également les expressions chaînées. Dans le cas d'expressions chaînées, assurez-vous qu'elles sont placées entre guillemets pour une interprétation correcte par le compilateur YAML. | String | Oui | N/A |
| `delimiter` | Caractère utilisé pour séparer les chaînes d'un bloc. La virgule est la virgule par défaut. Un seul caractère délimiteur est autorisé dans la liste donnée : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/imagebuilder/latest/userguide/toe-looping-constructs.html) Les expressions de chaînage ne peuvent pas être utilisées. | String | Non | Virgule : "," |
**Note**
La valeur de `list` est traitée comme une chaîne immuable. Si la source de `list` est modifiée pendant l'exécution, elle ne sera pas reflétée pendant l'exécution.
`forEach`boucle avec liste délimitée, exemple 1
Cet exemple utilise le modèle d'expression de chaînage suivant pour faire référence à la sortie d'une autre étape :`..[inputs | outputs].`.
```
- name: "RunMSIs"
action: "ExecuteBinary"
loop:
forEach:
list: "{{ build.GetAllMSIPathsForInstallation.outputs.stdout }}"
delimiter: "\n"
inputs:
commands:
path: "{{ loop.value }}"
```
`forEach`boucle avec liste délimitée, exemple 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 }}"
```
## Champs d'étape
Les boucles font partie d'une étape. Aucun champ lié à l'exécution d'une étape n'est appliqué aux itérations individuelles. Les champs d'étape s'appliquent uniquement au niveau de l'étape, comme suit :
+ *TimeoutSeconds* — Toutes les itérations de la boucle doivent être exécutées dans le délai spécifié par ce champ. Si le délai d'exécution de la boucle expire, AWSTOE exécute la politique de nouvelle tentative de l'étape et réinitialise le paramètre de délai d'expiration pour chaque nouvelle tentative. Si le délai d'exécution de la boucle dépasse le délai d'expiration après avoir atteint le nombre maximal de tentatives, le message d'échec de l'étape indique que le délai d'exécution de la boucle a expiré.
+ *OnFailure* — La gestion des défaillances est appliquée à l'étape comme suit :
+ Si *OnFailure* est défini sur`Abort`, AWSTOE quitte la boucle et réessaie l'étape conformément à la politique de nouvelles tentatives. Une fois le nombre maximal de tentatives atteint, AWSTOE marque l'étape en cours comme ayant échoué et arrête l'exécution du processus.
AWSTOE définit le code d'état de la phase parent et du document sur`Failed`.
**Note**
Aucune autre étape n'est exécutée après l'échec de l'étape.
+ Si *OnFailure* est défini sur`Continue`, AWSTOE quitte la boucle et réessaie l'étape conformément à la politique de nouvelles tentatives. Une fois le nombre maximal de tentatives atteint, AWSTOE marque l'étape en cours comme ayant échoué et passe à l'étape suivante.
AWSTOE définit le code d'état de la phase parent et du document sur`Failed`.
+ Si *OnFailure* est défini sur`Ignore`, AWSTOE quitte la boucle et réessaie l'étape conformément à la politique de nouvelles tentatives. Une fois le nombre maximal de tentatives atteint, AWSTOE marque l'étape en cours comme telle `IgnoredFailure` et passe à l'étape suivante.
AWSTOE définit le code d'état de la phase parent et du document sur`SuccessWithIgnoredFailure`.
**Note**
Ceci est toujours considéré comme une exécution réussie, mais inclut des informations vous indiquant qu'une ou plusieurs étapes ont échoué et ont été ignorées.
+ *MaxAttempts — À chaque nouvelle tentative*, l'étape complète et toutes les itérations sont exécutées depuis le début.
+ *status* — État général de l'exécution d'une étape. `status`ne représente pas le statut des itérations individuelles. Le statut d'une étape comportant des boucles est déterminé comme suit :
+ Si une seule itération échoue, le statut d'une étape indique un échec.
+ Si toutes les itérations aboutissent, le statut d'une étape indique un succès.
+ *StartTime : heure* de début globale de l'exécution d'une étape. Ne représente pas l'heure de début des itérations individuelles.
+ *EndTime — Heure* de fin globale de l'exécution d'une étape. Ne représente pas l'heure de fin des itérations individuelles.
+ *FailureMessage* — Inclut les indices d'itération qui ont échoué en cas d'erreurs autres que le délai d'expiration. En cas d'erreur de temporisation, le message indique que l'exécution de la boucle a échoué. Aucun message d'erreur individuel n'est fourni pour chaque itération afin de minimiser la taille des messages d'échec.
## Sorties d'étape et d'itération
Chaque itération contient une sortie. À la fin d'une exécution en boucle, AWSTOE consolide toutes les sorties d'itération réussies dans. `detailedOutput.json` Les sorties consolidées sont un assemblage de valeurs appartenant aux clés de sortie correspondantes telles que définies dans le schéma de sortie du module d'action. L'exemple suivant montre comment les sorties sont consolidées :
**Sortie de `ExecuteBash` pour l'itération 1**
```
{
"stdout":"Hello"
}
```
**Sortie de `ExecuteBash` pour l'itération 2**
```
{
"stdout":"World"
}
```
**Sortie de `ExecuteBash` for Step**
```
{
"stdout":"Hello\nWorld"
}
```
Par exemple, `ExecuteBash``ExecutePowerShell`, et `ExecuteBinary` sont des modules d'action qui renvoient `STDOUT` en tant que sortie du module d'action. `STDOUT`les messages sont joints au nouveau caractère de ligne pour produire le résultat global de l'étape`detailedOutput.json`.
AWSTOE ne consolidera pas les résultats des itérations infructueuses.