Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Utilice el marco de documentos de TOE de AWS componentes para componentes personalizados Para crear un componente mediante el marco de componentes Ejecutor y orquestador de tareas de AWS (TOE de AWS), debes proporcionar un documento basado en YAML que represente las fases y los pasos que se aplican al componente que crees. Servicios de AWS utilice su componente cuando creen una nueva imagen de máquina de Amazon (AMI) o imagen de contenedor. **Topics** + [Flujo de trabajo de documentos de componentes](#component-doc-workflow) + [Registro de componentes](#component-logging) + [Encadenamiento de entrada y salida](#document-chaining) + [Esquema y definiciones del documento](#document-schema) + [Ejemplos de documento](#document-example) + [Uso de variables en su documento de componentes personalizados](toe-user-defined-variables.md) + [Utilice construcciones condicionales en TOE de AWS](toe-conditional-constructs.md) + [Utilice operadores de comparación en los documentos TOE de AWS de componentes](toe-comparison-operators.md) + [Utilice operadores lógicos en los documentos TOE de AWS de componentes](toe-logical-operators.md) + [Utilice construcciones en bucle en TOE de AWS](toe-looping-constructs.md) ## Flujo de trabajo de documentos de componentes El documento del TOE de AWS componente utiliza fases y pasos para agrupar las tareas relacionadas y organizar esas tareas en un flujo de trabajo lógico para el componente. **sugerencia** El servicio que usa su componente para crear una imagen puede implementar reglas sobre qué fases usar en su proceso de compilación y cuándo se permite la ejecución de esas fases. Es importante tener esto en cuenta a la hora de diseñar el componente. **Fases** Las fases representan la progresión del flujo de trabajo a lo largo del proceso de compilación de imágenes. Por ejemplo, el servicio Generador de Imágenes utiliza las fases `build` y `validate` durante la *etapa de compilación* para las imágenes que produce. Utiliza las fases `test` y `container-host-test` durante la *etapa de prueba* para garantizar que la instantánea de la imagen o la imagen del contenedor generen los resultados esperados antes de crear la AMI final o distribuir la imagen del contenedor. Cuando se ejecuta el componente, los comandos asociados a cada fase se aplican en el orden en el que aparecen en el documento del componente. **Reglas para las fases** + Cada nombre de fase debe ser único dentro de un documento. + Puede definir muchas fases en el documento. + Debe incluir al menos una de las siguientes fases en su documento: + **compilación**: en el caso de Generador de Imágenes, esta fase se suele utilizar durante la *etapa de compilación*. + **validación**: en el caso de Generador de Imágenes, esta fase se suele utilizar durante la *etapa de compilación*. + **prueba**: en el caso de Generador de Imágenes, esta fase se suele utilizar durante la *etapa de prueba*. + Las fases siempre se ejecutan en el orden en que están definidas en el documento. El orden en el que se especifican para TOE de AWS los comandos del no AWS CLI tiene ningún efecto. **Steps** Los pasos son unidades de trabajo individuales que definen el flujo de trabajo dentro de cada fase. Los pasos se ejecutan en orden secuencial. Sin embargo, la entrada o salida de un paso también puede introducirse a un paso posterior como entrada. Esto se llama “encadenamiento”. **Reglas para los pasos** + El nombre del paso debe ser único para la fase. + El paso debe usar una acción compatible (módulo de acción) que devuelva un código de salida. Para obtener una lista completa de los módulos de acción compatibles, su funcionamiento, input/output valores y ejemplos, consulte[Módulos de acción compatibles con el administrador de TOE de AWS componentes](toe-action-modules.md). ## Registro de componentes TOE de AWS crea una nueva carpeta de registro en las instancias de EC2 que se utilizan para crear y probar una nueva imagen cada vez que se ejecuta el componente. En el caso de las imágenes del contenedor, la carpeta de registro se almacena en el contenedor. Para ayudar a solucionar problemas en caso de que algo vaya mal durante el proceso de creación de la imagen, el documento de entrada y todos los archivos de salida que se TOE de AWS crean al ejecutar el componente se almacenan en la carpeta de registro. El nombre de la carpeta de registro consta de las siguientes partes: 1. **Directorio de registro**: cuando un servicio ejecuta un TOE de AWS componente, pasa al directorio de registro junto con otras configuraciones del comando. En los siguientes ejemplos, mostramos el formato de archivo de registro que utiliza Generador de Imágenes. + **Linux y macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **Prefijo del archivo**: se trata de un prefijo estándar que se utiliza para todos los componentes: “`TOE_`”. 1. Tiempo de **ejecución: es una marca de tiempo** en formato YYYY-MM-DD \$1HH-MM-SS\$1UTC-0. 1. **ID de ejecución: es el GUID** que se asigna cuando se ejecutan uno o más componentes. TOE de AWS Ejemplo: `/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4` TOE de AWS almacena los siguientes archivos principales en la carpeta de registro: **Archivos de entrada** + **document.yaml**: el documento que se utiliza como entrada para el comando. Una vez ejecutado el componente, este archivo se almacena como un artefacto. **Archivos de salida** + **application.log**: el registro de la aplicación contiene información a nivel de depuración con marca de tiempo de TOE de AWS sobre lo que ocurre mientras se ejecuta el componente. + **detailedoutput.json**: este archivo JSON contiene información detallada sobre el estado de la ejecución, las entradas, las salidas y los errores de todos los documentos, fases y pasos que se aplican al componente a medida que se ejecuta. + **console.log**: el registro de la consola contiene toda la información de salida estándar (stdout) y de error estándar (stderr) que TOE de AWS se graba en la consola mientras el componente está en ejecución. + **chaining.json**: este archivo JSON representa las optimizaciones que se aplicaron para resolver las expresiones de encadenamiento. TOE de AWS **nota** Es posible que la carpeta de registro también contenga otros archivos temporales que no se incluyen aquí. ## Encadenamiento de entrada y salida La aplicación TOE de AWS de gestión de la configuración proporciona una función para encadenar entradas y salidas mediante la escritura de referencias en los siguientes formatos: `{{ phase_name.step_name.inputs/outputs.variable }}` o `{{ phase_name.step_name.inputs/outputs[index].variable }}` La característica de encadenamiento permite reciclar el código y mejorar la capacidad de mantenimiento del documento. **Reglas de encadenamiento** + Las expresiones encadenadas solo se pueden usar en la sección de entradas de cada paso. + Las declaraciones con expresiones encadenadas deben ir entre comillas. Por ejemplo: + **Expresión no válida**: `echo {{ phase.step.inputs.variable }}` + **Expresión válida**: `"echo {{ phase.step.inputs.variable }}"` + **Expresión válida**: `'echo {{ phase.step.inputs.variable }}'` + Las expresiones encadenadas pueden hacer referencia a variables de otros pasos y fases del mismo documento. Sin embargo, el servicio que lleva a cabo las llamadas puede tener reglas que requieran que las expresiones encadenadas funcionen solo en el contexto de una sola etapa. Por ejemplo, Generador de Imágenes no admite el encadenamiento de la *etapa de compilación* a la *etapa de prueba*, ya que ejecuta cada etapa de forma independiente. + Los índices de las expresiones encadenadas siguen la indexación basada en cero. El índice comienza con cero (0) para hacer referencia al primer elemento. **Ejemplos** Para hacer referencia a la variable de origen en la segunda entrada del siguiente paso de ejemplo, el patrón de encadenamiento es `{{ 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 hacer referencia a la variable de salida (igual a “Hola”) en el siguiente paso de ejemplo, el patrón de encadenamiento es `{{ build.SamplePowerShellStep.outputs.stdout }}`. ``` phases: - name: 'build' steps: - name: SamplePowerShellStep action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## Esquema y definiciones del documento El siguiente es el esquema YAML de un documento. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` Las definiciones de esquema de un documento son las siguientes: | Campo | Description (Descripción) | Tipo | Obligatorio/a | | --- | --- | --- | --- | | Nombre | Nombre del documento. | Cadena | No | | description | Descripción del documento. | Cadena | No | | schemaVersion | versión esquemática del documento, actualmente 1.0. | Cadena | Sí | | phases | Una lista de fases con sus pasos. | Enumeración | Sí | Las definiciones de esquema de una fase son las siguientes. | Campo | Description (Descripción) | Tipo | Obligatorio/a | | --- | --- | --- | --- | | Nombre | Nombre de la fase. | Cadena | Sí | | pasos | Lista de los pasos de la fase. | Enumeración | Sí | Las definiciones de esquema de un paso son las siguientes. | Campo | Description (Descripción) | Tipo | Obligatorio/a | Predeterminado | | --- | --- | --- | --- | --- | | Nombre | Nombre definido por el usuario para el paso. | Cadena | | | | acción | Palabra clave relacionada con el módulo que ejecuta el paso. | Cadena | | | | timeoutSeconds | Número de segundos que dura el paso antes de fallar o volver a intentar. Además, admite el valor -1, que indica un tiempo de espera infinito. No se admiten valores 0 ni otros valores negativos. | Entero | No | 7200 segundos (120 minutos) | | onFailure | Especifica lo que debe hacer el paso en caso de error. Los valores válidos son los siguientes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/imagebuilder/latest/userguide/toe-use-documents.html) | Cadena | No | Anular | | maxAttempts | Número máximo de intentos permitidos antes del fallo del paso. | Entero | No | 1 | | inputs | Contiene los parámetros requeridos por el módulo de acción para ejecutar el paso. | Dict | Sí | | ## Ejemplos de documento Los siguientes ejemplos muestran los documentos de los AWSTOE componentes que realizan tareas para el sistema operativo de destino. ------ #### [ Linux ] **Ejemplo 1: ejecución de un archivo binario personalizado** El siguiente es un ejemplo de documento que descarga y ejecuta un archivo binario personalizado en una instancia 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 ] **Ejemplo 1: instalación de actualizaciones de Windows** El siguiente es un ejemplo de documento que instala todas las actualizaciones disponibles de Windows, ejecuta un script de configuración, valida los cambios antes de crear la AMI y prueba los cambios después de crear la 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}}' ``` **Ejemplo 2: Instálelo AWS CLI en una instancia de Windows** El siguiente es un ejemplo de documento que lo instala AWS CLI en una instancia de Windows mediante el archivo de configuración. ``` 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 }}' ``` **Ejemplo 3: Instálelo AWS CLI con el instalador MSI** El siguiente es un ejemplo de documento que lo instala AWS CLI con el 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 ] **Ejemplo 1: ejecución de un archivo binario de macOS personalizado** El siguiente es un ejemplo de documento que descarga y ejecuta un archivo binario personalizado en una instancia 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 }}' ``` ------ # Uso de variables en su documento de componentes personalizados Las variables proporcionan una forma de etiquetar los datos con nombres significativos que se pueden usar en toda la aplicación. Puedes definir variables personalizadas con formatos sencillos y legibles para flujos de trabajo complejos y hacer referencia a ellas en el documento del componente de la aplicación YAML de un TOE de AWS componente. En esta sección, se proporciona información que te ayudará a definir las variables de tu TOE de AWS componente en el documento de componentes de la aplicación YAML, incluida la sintaxis, las restricciones de nombres y algunos ejemplos. ## Constantes Las constantes son variables inmutables que no se pueden modificar ni anular una vez definidas. Las constantes se pueden definir mediante los valores de la `constants` sección de un TOE de AWS documento. **Reglas de nomenclatura de constantes** + El nombre debe tener entre 3 y 128 caracteres de extensión. + El nombre solo puede contener caracteres alfanuméricos (a-z, A-Z y 0-9), guiones (-) o guiones bajos (\$1). + El nombre debe ser único dentro del documento. + El nombre debe estar especificado como una cadena YAML. **Sintaxis** ``` constants: - : type: value: ``` | Nombre de la clave | Obligatorio | Descripción | | --- | --- | --- | | `name` | Sí | Nombre de la constante. Debe ser único para el documento (no debe coincidir con ningún otro nombre de parámetro o constante). | | `value` | Sí | Valor de la constante. | | `type` | Sí | Tipo de la constante. El tipo admitido es string. | **Valores constantes de referencia en un documento** Puede hacer referencia a las constantes en entradas escalonadas o en bucle dentro de su documento YAML, de la siguiente manera: + Las referencias constantes distinguen mayúsculas y minúsculas y el nombre debe coincidir exactamente. + El nombre debe estar entre corchetes dobles. `{{` *MyConstant* `}}` + Se permiten espacios dentro de las llaves y se recortan automáticamente. Por ejemplo, todas las referencias siguientes son válidas: `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}` + La referencia del documento YAML debe especificarse como una cadena (entre comillas simples o dobles). Por ejemplo: `- {{ MyConstant }}` no es válido, ya que no se identifica como una cadena. Sin embargo, las siguientes referencias son válidas: `- '{{ MyConstant }}'` y `- "{{ MyConstant }}"`. **Ejemplos** Constante referenciada en las entradas escalonadas ``` 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 en las entradas de bucle ``` 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 Los parámetros son variables mutables, con ajustes que la aplicación que realiza la llamada puede proporcionar en el tiempo de ejecución. Puede definir los parámetros en la sección `Parameters` del documento YAML. **Reglas para nombres de parámetros** + El nombre debe tener entre 3 y 128 caracteres de extensión. + El nombre solo puede contener caracteres alfanuméricos (a-z, A-Z y 0-9), guiones (-) o guiones bajos (\$1). + El nombre debe ser único dentro del documento. + El nombre debe estar especificado como una cadena YAML. ### Sintaxis ``` parameters: - : type: default: description: ``` | Nombre de la clave | Obligatorio | Descripción | | --- | --- | --- | | `name` | Sí | El nombre del parámetro. Debe ser único para el documento (no debe coincidir con ningún otro nombre de parámetro o constante). | | `type` | Sí | El tipo de datos del parámetro. Los tipos admitidos incluyen: `string`. | | `default` | No | El valor predeterminado para el parámetro. | | `description` | No | Describe el parámetro. | ### Valores de parámetros de referencia en un documento Puede hacer referencia a los parámetros en entradas escalonadas o en bucle dentro de su documento YAML, de la siguiente manera: + Las referencias de parámetros distinguen mayúsculas y minúsculas y el nombre debe coincidir exactamente. + El nombre debe estar entre `{{` *MyParameter* `}}` corchetes dobles. + Se permiten espacios dentro de las llaves y se recortan automáticamente. Por ejemplo, todas las referencias siguientes son válidas: `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}` + La referencia del documento YAML debe especificarse como una cadena (entre comillas simples o dobles). Por ejemplo: `- {{ MyParameter }}` no es válido, ya que no se identifica como una cadena. Sin embargo, las siguientes referencias son válidas: `- '{{ MyParameter }}'` y `- "{{ MyParameter }}"`. **Ejemplos** En los siguientes ejemplos, se muestra cómo utilizar los parámetros del documento YAML: + Consulte un parámetro en las entradas escalonadas: ``` 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 un parámetro en las entradas de bucle: ``` 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 }} ``` ### Anulación de los parámetros en tiempo de ejecución Puede utilizar la `--parameters` opción AWS CLI con un par clave-valor para establecer el valor de un parámetro en tiempo de ejecución. + Especifique el par clave-valor del parámetro como nombre y valor, separados por un signo igual (=). + Varios parámetros deben estar separados por una coma. + Se ignoran los nombres de los parámetros que no se encuentran en el documento de componentes de YAML. + Tanto el nombre como el valor del parámetro son obligatorios. **importante** Los parámetros del componente son valores de texto sin formato y se registran en AWS CloudTrail. Le recomendamos que utilice AWS Secrets Manager nuestro almacén de AWS Systems Manager parámetros para almacenar sus secretos. Para obtener más información sobre Secrets Manager, consulte [¿Qué es Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) en la *Guía del usuario de AWS Secrets Manager *. Para obtener más información acerca del almacén de parámetros de AWS Systems Manager , consulte [Almacén de parámetros de AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) en la *Guía del usuario de AWS Systems Manager *. #### Sintaxis ``` --parameters name1=value1,name2=value2... ``` | Opción de la CLI | Obligatorio | Description (Descripción) | | --- | --- | --- | | --parámetros *name* =*value*,... | No | Esta opción toma una lista de pares clave-valor, con el nombre del parámetro como clave. | **Ejemplos** En los siguientes ejemplos, se muestra cómo utilizar los parámetros del documento YAML: + El par clave-valor del parámetro especificado en esta opción `--parameter` no es válido: ``` --parameters ntp-server= ``` + Establezca un par clave-valor de un parámetro con la opción `--parameter` en el AWS CLI: ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + Establezca varios pares clave-valor de parámetros con la opción `--parameter` en el AWS CLI: ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Utilice los parámetros del almacén de parámetros de Systems Manager Puede hacer referencia a los AWS Systems Manager parámetros del almacén de parámetros (parámetros SSM) en los documentos de sus componentes añadiendo el prefijo a las variables. `aws:ssm` Por ejemplo: `{{ aws:ssm:/my/param }}`se resuelve en el valor del parámetro SSM. `/my/param` Esta función admite los siguientes tipos de parámetros de SSM: + Cadena: se asigna al tipo de TOE de AWS cadena. + StringList — Se asigna al TOE de AWS `stringList` tipo. + SecureString — Se asigna al tipo de TOE de AWS cadena. Para obtener más información sobre el almacén de parámetros, consulte el [almacén de AWS Systems Manager parámetros](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) en la *Guía del AWS Systems Manager usuario*. También puede hacer referencia a AWS Secrets Manager los secretos mediante un parámetro `SecureString` SSM. Por ejemplo: `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`. Para obtener más información, consulte Hacer [referencia a AWS Secrets Manager los secretos de los parámetros del almacén de parámetros](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html). **importante** Image Builder excluye la resolución de `SecureString` parámetros de sus registros. Sin embargo, también es responsable de garantizar que la información confidencial no se registre mediante los comandos incluidos en el documento del componente. Por ejemplo, si utiliza el `echo` comando con una cadena segura, el comando escribirá un valor de texto simple en el registro. ### Permisos de IAM necesarios Para usar los parámetros de Systems Manager en sus componentes, su rol de instancia debe tener el `ssm:GetParameter` permiso para el ARN del recurso de parámetros. Por ejemplo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" } ] } ``` ------ Para acceder a los valores cifrados, también necesitarás los siguientes permisos: + Agregue `kms:Decrypt` `SecureString` parámetros o AWS Secrets Manager valores cifrados con un administrador por el cliente AWS KMS key. + `secretsmanager:GetSecretValue`Añádelo si haces referencia a un secreto de Secrets Manager. ### Haga referencia a un parámetro SSM en un documento de componentes El siguiente ejemplo muestra cómo hacer referencia a un parámetro del almacén de parámetros de Systems Manager de los parámetros de Systems Manager de un 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 }}." ``` ### Resolución dinámica de variables de tiempo de ejecución para los parámetros de SSM AWSTOE proporciona la siguiente función integrada que puede utilizar en las referencias de variables para manipular o transformar valores en tiempo de ejecución. #### función de resolución La `resolve` función resuelve una referencia de variable dentro de otra referencia de variable, lo que permite hacer referencias dinámicas a nombres de variables. Esto resulta útil cuando se trabaja con parámetros de SSM, en los que parte de la ruta del parámetro puede ser variable y transferirse como parámetro del documento. La `resolve` función solo admite la resolución dinámica de la parte del nombre de un parámetro de SSM. ##### Sintaxis El `dynamic_variable` ejemplo siguiente representa el nombre de un parámetro SSM y debe ser uno de los siguientes: + Una referencia de parámetro SSM (por ejemplo,) `aws:ssm:/my/param` + Una referencia de parámetros de un documento de componentes (por ejemplo,`parameter-name`) ``` {{ aws:ssm:resolve(dynamic_variable) }} ``` ##### Ejemplo: resolver un parámetro SSM en tiempo de ejecución En el siguiente ejemplo, se muestra cómo utilizar la `resolve` función en un documento de componentes de 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) }}" ``` # Utilice construcciones condicionales en TOE de AWS Los constructos condicionales realizan diferentes acciones en el documento componente en función de si la expresión condicional especificada se evalúa como `true` o `false`. Puede utilizar el constructo `if` para controlar el flujo de ejecución del documento del componente. ## Constructo if Puede utilizar el constructo `if` para evaluar si un paso debe ejecutarse o no. De forma predeterminada, cuando la expresión condicional `if` se evalúa como `true`, TOE de AWS ejecuta el paso y cuando la condición se evalúa como `false`, TOE de AWS se salta el paso. Si se omite un paso, se considera un paso correcto cuando TOE de AWS evalúa si la fase y el documento se han ejecutado correctamente. **nota** Una instrucción `if` solo se evalúa una vez, incluso si el paso desencadena un reinicio. Si un paso se reinicia, reconoce que la instrucción `if` ya se ha evaluado y continúa donde la dejó. ### Sintaxis ``` if: - : [then: ] [else: ] ``` | Nombre de la clave | Obligatorio | Description (Descripción) | | --- | --- | --- | | expresión condicional | Sí | La expresión condicional puede contener exactamente uno de los siguientes tipos de operadores en el nivel superior. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/imagebuilder/latest/userguide/toe-conditional-constructs.html) Si la expresión debe cumplir varias condiciones, utilice un operador lógico para especificarlas. | | then | No | Define la acción que se debe realizar si la expresión condicional se evalúa como `true`. | | else | No | Define la acción que se debe realizar si la expresión condicional se evalúa como `false`. | | acción de paso | Condicional | Al utilizar `then` o `else`, debe especificar una de las siguientes acciones de pasos: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/imagebuilder/latest/userguide/toe-conditional-constructs.html) | **Ejemplo 1: instalación de un paquete** Los siguientes pasos de ejemplo de un documento de TOE de AWS componentes utilizan operadores lógicos para probar el valor de un parámetro y ejecutar los comandos del administrador de paquetes adecuados para instalar una aplicación si el paquete está descomprimido. ``` - 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 ``` **Ejemplo 2: omisión de un paso** El siguiente ejemplo muestra dos formas de omitir un paso. Una usa un operador lógico y la otra usa un operador de comparación con la acción del paso `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' ``` # Utilice operadores de comparación en los documentos TOE de AWS de componentes Puede utilizar los siguientes operadores de comparación con el módulo de acción **[Assert](toe-action-modules.md#action-modules-assertion)** y con las expresiones condicionales que utilizan [Constructo ifSintaxis](toe-conditional-constructs.md#toe-conditional-if). Un operador de comparación puede operar con un único valor, por ejemplo, `stringIsEmpty`, o puede comparar un valor de referencia con un segundo valor (valor variable) para determinar si la expresión condicional se evalúa como `true` o `false`. Si la comparación funciona con dos valores, el segundo valor puede ser una variable encadenante. Al comparar valores de un tipo diferente, se pueden producir las siguientes conversiones de valores antes de la comparación: + Para las comparaciones numéricas, si el valor de la variable es una cadena, TOE de AWS convierte la cadena en un número antes de la evaluación. Si la conversión no es posible, la comparación devuelve el resultado `false`. Por ejemplo, si el valor de la variable es `"1.0"`, la conversión funciona, pero si el valor de la variable es `"a10"`, la conversión falla. + Para las comparaciones de cadenas, si el valor de la variable es un número, lo TOE de AWS convierte en una cadena antes de la evaluación. ## Comparación de cadenas Los siguientes operadores de comparación funcionan con cadenas para comparar valores, comprobar si hay espacios o una cadena vacía, o para comparar un valor de entrada con un patrón de expresiones regulares. Las comparaciones de cadenas no distinguen entre mayúsculas y minúsculas y no recortan los espacios desde el principio o el final de las entradas de cadenas. **Operadores de comparación de cadenas** + [stringIsEmpty](#stringIsEmpty) + [stringIsWhitespace](#stringIsWhitespace) + [stringEquals](#stringEquals) + [stringLessThan](#stringLessThan) + [stringLessThanEquals](#stringLessThanEquals) + [stringGreaterThan](#stringGreaterThan) + [stringGreaterThanEquals](#stringGreaterThanEquals) + [patternMatches](#patternMatches) **stringIsEmpty** El operador `stringIsEmpty` devuelve `true` si la cadena especificada no contiene ningún carácter. Por ejemplo: ``` # Evaluates to true stringIsEmpty: "" # Evaluates to false stringIsEmpty: " " # Evaluates to false stringIsEmpty: "Hello." ``` **stringIsWhitespace** Comprueba si la cadena especificada para `stringIsWhitespace` contiene solo espacios. Por ejemplo: ``` # Evaluates to true stringIsWhitespace: " " # Evaluates to false stringIsWhitespace: "" # Evaluates to false stringIsWhitespace: " Hello?" ``` **stringEquals** Comprueba si la cadena especificada para `stringEquals` coincide exactamente con la cadena especificada en el parámetro `value`. Por ejemplo: ``` # 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** Comprueba si la cadena especificada para `stringLessThan` es inferior a la cadena especificada en el parámetro `value`. Por ejemplo: ``` # 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' ``` **stringLessThanEs igual a** Comprueba si la cadena especificada para `stringLessThanEquals` es inferior o igual a la cadena especificada en el parámetro `value`. Por ejemplo: ``` # 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** Comprueba si la cadena especificada para `stringGreaterThan` es superior a la cadena especificada en el parámetro `value`. Por ejemplo: ``` # 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' ``` **stringGreaterThanIguales** Comprueba si la cadena especificada para `stringGreaterThanEquals` es superior o igual a la cadena especificada en el parámetro `value`. Por ejemplo: ``` # 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** Comprueba si la cadena especificada en el parámetro `value` coincide con el patrón de expresiones regulares especificado para `patternMatches`. La comparación utiliza el [paquete de expresiones regulares de Golang](https://pkg.go.dev/regexp), que se ajusta a la sintaxis. RE2 Para obtener más información sobre RE2 las reglas, consulte el repositorio [google/](https://github.com/google/re2/wiki/Syntax) re2 en. *GitHub* En el siguiente ejemplo, se muestra una coincidencia de patrones que devuelve `true`: ``` patternMatches: '^[a-z]+$' value: 'ThisIsValue' ``` ## Comparación de números Los siguientes operadores de comparación funcionan con números. Los valores proporcionados para estos operadores deben ser de uno de los siguientes tipos, según la especificación YAML. La admisión de comparaciones numéricas utiliza el operador de comparación de paquetes grandes de Golang, por ejemplo: [func (\$1Float) Cmp](https://pkg.go.dev/math/big#Float.Cmp). + Entero + Float (basado en float64, admite números del -1,7e\$1308 al \$11,7e\$1308) + Cadena que coincide con el siguiente patrón de expresiones regulares: `^[-+]?([0-9]+[.])?[0-9]+$` **Operadores de comparación de números** + [numberEquals](#numberEquals) + [numberLessThan](#numberLessThan) + [numberLessThanEquals](#numberLessThanEquals) + [numberGreaterThan](#numberGreaterThan) + [numberGreaterThanEquals](#numberGreaterThanEquals) **numberEquals** Comprueba si el número especificado para `numberEquals` es igual al número especificado en el parámetro `value`. Todos los ejemplos de comparación siguientes devuelven `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** Comprueba si el número especificado para `numberLessThan` es inferior al número especificado en el parámetro `value`. Por ejemplo: ``` # Evaluates to true numberLessThan: 2 value: 1 # Evaluates to true numberLessThan: 2 value: 1.9 # Evaluates to false numberLessThan: 2 value: '2' ``` **numberLessThanEs igual a** Comprueba si el número especificado para `numberLessThanEquals` es inferior o igual al número especificado en el parámetro `value`. Por ejemplo: ``` # 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** Comprueba si el número especificado para `numberGreaterThan` es superior al número especificado en el parámetro `value`. Por ejemplo: ``` # Evaluates to true numberGreaterThan: 1 value: 2 # Evaluates to true numberGreaterThan: 1 value: 1.1 # Evaluates to false numberGreaterThan: 1 value: '1' ``` **numberGreaterThanIguales** Comprueba si el número especificado para `numberGreaterThanEquals` es superior o igual al número especificado en el parámetro `value`. Por ejemplo: ``` # 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 ``` ## Control de archivos Los siguientes operadores de comparación comprueban el hash del archivo o comprueban si existe un archivo o una carpeta. **Operadores de archivos y carpetas** + [binaryExists](#binaryExists) + [fileExists](#fileExists) + [folderExists](#folderExists) + [fileMD5Equals](#fileMD5Equals) + [fileSHA1Equals](#fileSHA1Equals) + [fileSHA256Equals](#fileSHA256Equals) + [fileSHA512Equals](#fileSHA512Equals) **binaryExists** Comprueba si una aplicación está disponible en la ruta actual. Por ejemplo: ``` binaryExists: 'foo' ``` En los sistemas Linux y macOS, para una aplicación llamada*foo*, esto funciona igual que el siguiente comando bash:**type *foo* >/dev/null 2>&1**, donde **\$1? == 0** indica que la comparación se ha realizado correctamente. En los sistemas Windows, para una aplicación denominada*foo*, funciona igual que el PowerShell comando que **\$1LASTEXITCODE = 0** indica que la comparación **& C:\$1Windows\$1System32\$1where.exe /Q *foo*** se ha realizado correctamente. **fileExists** Comprueba si un archivo existe en la ruta especificada. Puede proporcionar una ruta absoluta o relativa. Si la ubicación que especifique existe y es un archivo, la comparación se evaluará como `true`. Por ejemplo: ``` fileExists: '/path/to/file' ``` En los sistemas Linux y macOS, funciona igual que el siguiente comando bash: **-d */path/to/file***, donde **\$1? == 0** indica que la comparación se ha realizado correctamente. En los sistemas Windows, funciona igual que el PowerShell comando**Test-Path -Path '*C:\$1path\$1to\$1file*' -PathType 'Leaf'**. **folderExists** Comprueba si existe una carpeta en la ruta especificada. Puede proporcionar una ruta absoluta o relativa. Si la ubicación que especifique existe y es una carpeta, la comparación se evaluará como `true`. Por ejemplo: ``` folderExists: '/path/to/folder' ``` En los sistemas Linux y macOS, funciona igual que el siguiente comando bash: **-d */path/to/folder***, donde **\$1? == 0** indica que la comparación se ha realizado correctamente. En los sistemas Windows, funciona igual que el PowerShell comando**Test-Path -Path '*C:\$1path\$1to\$1folder*' -PathType 'Container'**. **el archivo MD5 es igual a** Comprueba si el MD5 hash de un archivo es igual a un valor especificado. Por ejemplo: ``` fileMD5Equals: '' path: '/path/to/file' ``` **el archivo SHA1 es igual a** Comprueba si el SHA1 hash de un archivo es igual a un valor especificado. Por ejemplo: ``` fileSHA1Equals: '' path: '/path/to/file' ``` **el archivo SHA256 es igual a** Comprueba si el SHA256 hash de un archivo es igual a un valor especificado. Por ejemplo: ``` fileSHA256Equals: '' path: '/path/to/file' ``` **el archivo SHA512 es igual a** Comprueba si el SHA512 hash de un archivo es igual a un valor especificado. Por ejemplo: ``` fileSHA512Equals: '' path: '/path/to/file' ``` # Utilice operadores lógicos en los documentos TOE de AWS de componentes Puede utilizar los siguientes operadores lógicos para añadir o modificar expresiones condicionales en el documento componente. TOE de AWS evalúa las expresiones condicionales en el orden en que se especifican las condiciones. Para obtener más información sobre los operadores de comparación de los documentos de componentes, consulte [Utilice operadores de comparación en los documentos TOE de AWS de componentes](toe-comparison-operators.md). **y** Con el operador `and`, puede evaluar dos o más comparaciones como una sola expresión. La expresión se evalúa como `true` cuando se cumplen todas las condiciones de la lista. De lo contrario, la expresión se evalúa como `false`. **Ejemplos:** En el siguiente ejemplo se realizan dos comparaciones: una cadena y un número. Ambas comparaciones son verdaderas, por lo que la expresión se evalúa como verdadera. ``` and: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 1 ``` En el siguiente ejemplo también se realizan dos comparaciones. La primera comparación es falsa, momento en el que se detiene la evaluación y se omite la segunda comparación. La expresión se evalúa como `false`. ``` and: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` **o bien** Con el operador `or`, puede evaluar dos o más comparaciones como una sola expresión. La expresión se evalúa como `true` cuando una de las comparaciones especificadas es verdadera. Si ninguna de las comparaciones especificadas se evalúa como `true`, la expresión se evalúa como `false`. **Ejemplos:** En el siguiente ejemplo se realizan dos comparaciones: una cadena y un número. La primera comparación es verdadera, por lo que la expresión se evalúa como `true` y se omite la segunda comparación. ``` or: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 3 ``` En el siguiente ejemplo también se realizan dos comparaciones. La primera comparación es falsa y la evaluación continúa. La segunda comparación es verdadera, por lo que la expresión se evalúa como `true`. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` En el último ejemplo, ambas comparaciones son falsas, por lo que la expresión se evalúa como `false`. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 3 ``` **not** Con el operador `not`, puede anular una sola comparación. La expresión se evalúa como `true` si la comparación es falsa. Si la comparación es verdadera, la expresión se evalúa como `false`. **Ejemplos:** En el siguiente ejemplo, se realiza una comparación de cadenas. La comparación es falsa, por lo que la expresión se evalúa como `true`. ``` not: - stringEquals: 'test_string' value: 'Hello world!' ``` En el siguiente ejemplo también se realiza una comparación de cadenas. La comparación es verdadera, por lo que la expresión se evalúa como `false`. ``` not: - stringEquals: 'test_string' value: 'test_string' ``` # Utilice construcciones en bucle en TOE de AWS En esta sección se proporciona información que le ayudará a crear constructos en bucle en TOE de AWS. Los constructos en bucle definen una secuencia repetida de instrucciones. Puede utilizar los siguientes tipos de constructos en bucle en TOE de AWS: + Constructos `for`: se repiten en iteraciones sobre una secuencia acotada de números enteros. + Constructos `forEach` + Bucle `forEach` con lista de entradas: se repite en iteraciones sobre una colección finita de cadenas. + Bucle `forEach` con lista delimitada: repite una colección finita de cadenas unidas por un delimitador. **nota** Los constructos en bucle solo admiten tipos de datos de cadena. **Topics** + [Variables de iteración de referencia](#toe-loop-iteration-variables) + [Tipos de constructos en bucle](#toe-loop-types) + [Campos de pasos](#toe-loop-step-fields) + [Salidas de paso e iteración](#toe-loop-step-output) ## Variables de iteración de referencia Para hacer referencia al índice y al valor de la variable de iteración actual, la expresión de referencia `{{ loop.* }}` debe usarse en el cuerpo de entrada de un paso que contenga un constructo en bucle. Esta expresión no se puede utilizar para hacer referencia a las variables de iteración del constructo en bucle de otro paso. La expresión de referencia consta de los siguientes miembros: + `{{ loop.index }}`: la posición ordinal de la iteración actual, que está indexada en `0`. + `{{ loop.value }}`: el valor asociado a la variable de iteración actual. ### Nombres de bucles Todos los constructos en bucle tienen un campo de nombre opcional para su identificación. Si se proporciona un nombre de bucle, este se puede utilizar para hacer referencia a las variables de iteración del cuerpo de entrada del paso. Para hacer referencia a los índices y valores de iteración de un bucle denominado, utilice `{{ .* }}` con `{{ loop.* }}` en el cuerpo de entrada del paso. Esta expresión no se puede utilizar para hacer referencia al constructo en bucle denominado de otro paso. La expresión de referencia consta de los siguientes miembros: + `{{ .index }}`: la posición ordinal de la iteración actual del bucle denominado, que está indexada en `0`. + `{{ .value }}` : el valor asociado a la variable de iteración actual del bucle denominado. ### Resolución de expresiones de referencia TOE de AWS Resuelve las expresiones de referencia de la siguiente manera: + `{{ .* }}`— TOE de AWS resuelve esta expresión mediante la siguiente lógica: + Si el bucle del paso que se está ejecutando actualmente coincide con el valor ``, la expresión de referencia se convierte en el constructo en bucle del paso que se está ejecutando actualmente. + `` se resuelve en el constructo de bucle denominado si aparece dentro del paso que se está ejecutando actualmente. + `{{ loop.* }}`— TOE de AWS resuelve la expresión mediante la construcción de bucle definida en el paso que se está ejecutando actualmente. Si se utilizan expresiones de referencia en un paso que no contiene un bucle, TOE de AWS no resuelve las expresiones y aparecen en el paso sin sustituirlas. **nota** Las expresiones de referencia deben estar entre comillas dobles para que el compilador YAML las interprete correctamente. ## Tipos de constructos en bucle Esta sección contiene información y ejemplos sobre los tipos de constructos en bucle que se pueden utilizar en TOE de AWS. **Topics** + [Bucle `for`](#toe-loop-types-for) + [Bucle `forEach` con lista de entradas](#toe-loop-types-foreach) + [Bucle `forEach` con lista delimitada](#toe-loop-types-foreach-delimited) ### Bucle `for` El bucle `for` itera en un rango de enteros especificado dentro de un límite delimitado por el inicio y el final de las variables. Los valores iterativos están en el conjunto `[start, end]` e incluyen los valores límite. TOE de AWS verifica los `updateBy` valores `start``end`, y para garantizar que la combinación no dé como resultado un bucle infinito. Esquema de bucle `for` ``` - name: "StepName" action: "ActionModule" loop: name: "string" for: start: int end: int updateBy: int inputs: ... ``` **Entrada de bucle `for`** | Campo | Description (Descripción) | Tipo | Obligatorio/a | Predeterminado | | --- | --- | --- | --- | --- | | `name` | Nombre único del bucle. Debe ser único en comparación con otros nombres de bucles de la misma fase. | Cadena | No | "" | | `start` | Valor inicial de la iteración. No acepta expresiones encadenadas. | Entero | Sí | n/a | | `end` | Valor final de la iteración. No acepta expresiones encadenadas. | Entero | Sí | n/a | | `updateBy` | Diferencia por la que un valor iterativo se actualiza mediante la adición. Debe ser un valor negativo o positivo distinto de cero. No acepta expresiones encadenadas. | Entero | Sí | n/a | Ejemplo de entrada de bucle `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 ``` ### Bucle `forEach` con lista de entradas El bucle `forEach` itera en una lista explícita de valores, que pueden ser cadenas y expresiones encadenadas. Bucle `forEach` con esquema de lista de entrada ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: - "string" inputs: ... ``` **Bucle `forEach` con entrada de lista de entrada** | Campo | Description (Descripción) | Tipo | Obligatorio/a | Predeterminado | | --- | --- | --- | --- | --- | | `name` | Nombre único del bucle. Debe ser único en comparación con otros nombres de bucles de la misma fase. | Cadena | No | "" | | Lista de cadenas de bucle `forEach` | Lista de cadenas para la iteración. Acepta expresiones encadenadas como cadenas en la lista. Las expresiones encadenadas deben estar entre comillas dobles para que el compilador YAML las interprete correctamente. | Lista de cadenas | Sí | n/a | Bucle `forEach` con lista de entradas (ejemplo 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 ``` Bucle `forEach` con lista de entradas (ejemplo 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 }}" ``` Bucle `forEach` con lista de entradas (ejemplo 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 }}" ``` ### Bucle `forEach` con lista delimitada El bucle itera sobre una cadena que contiene valores separados por un delimitador. Para recorrer en iteración los componentes de la cadena, TOE de AWS utiliza el delimitador para dividir la cadena en una matriz adecuada para la iteración. Bucle `forEach` con esquema de lista delimitada ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: list: "string" delimiter: ".,;:\n\t -_" inputs: ... ``` **Bucle `forEach` con entrada de lista delimitada** | Campo | Description (Descripción) | Tipo | Obligatorio/a | Predeterminado | | --- | --- | --- | --- | --- | | `name` | Nombre único del bucle. Debe ser único en comparación con otros nombres de bucles de la misma fase. | Cadena | No | "" | | `list` | Cadena compuesta por cadenas constitutivas unidas por un carácter delimitador común. También acepta expresiones encadenadas. En el caso de expresiones encadenadas, asegúrese de que estén entre comillas dobles para que el compilador de YAML las interprete correctamente. | Cadena | Sí | n/a | | `delimiter` | Carácter que se usa para separar las cadenas dentro de un bloque. El valor predeterminado es el carácter de coma. Solo se permite un carácter delimitador de la lista dada: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/imagebuilder/latest/userguide/toe-looping-constructs.html) No se pueden utilizar expresiones encadenadas. | Cadena | No | Coma: "," | **nota** El valor de `list` se trata como una cadena inmutable. Si la fuente de `list` se cambia durante el tiempo de ejecución, no se reflejará durante la ejecución. Bucle `forEach` con lista delimitada (ejemplo 1) Este ejemplo utiliza el siguiente patrón de expresión de encadenamiento para hacer referencia al resultado de otro paso: `..[inputs | outputs].`. ``` - name: "RunMSIs" action: "ExecuteBinary" loop: forEach: list: "{{ build.GetAllMSIPathsForInstallation.outputs.stdout }}" delimiter: "\n" inputs: commands: path: "{{ loop.value }}" ``` Bucle `forEach` con lista delimitada (ejemplo 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 pasos Los bucles son parte de un paso. Los campos relacionados con la ejecución de un paso no se aplican a las iteraciones individuales. Los campos de paso se aplican solo a nivel del paso, de la siguiente manera: + *timeoutSeconds*: todas las iteraciones del bucle deben ejecutarse dentro del período de tiempo especificado en este campo. Si se agota el tiempo de espera del bucle, TOE de AWS ejecuta la política de reintentos del paso y restablece el parámetro de tiempo de espera para cada nuevo intento. Si la ejecución del bucle supera el valor de tiempo de espera tras alcanzar el número máximo de reintentos, el mensaje de error del paso indica que se ha agotado el tiempo de espera de la ejecución del bucle. + *onFailure*: la administración de errores se aplica al paso de la siguiente manera: + Si *OnFailure* está establecido en`Abort`, TOE de AWS sale del bucle y vuelve a intentar el paso de acuerdo con la política de reintentos. Tras el número máximo de reintentos, TOE de AWS marca el paso actual como fallido y detiene la ejecución del proceso. TOE de AWS establece el código de estado de la fase principal y el documento en. `Failed` **nota** No se ejecutarán más pasos después del paso con errores. + Si *onFailure* está establecido como `Continue`, TOE de AWS sale del bucle y vuelve a intentar el paso de acuerdo con la política de reintentos. Tras el número máximo de reintentos, TOE de AWS marca el paso actual como fallido y continúa con el paso siguiente. TOE de AWS establece el código de estado de la fase principal y el documento en. `Failed` + Si *onFailure* está establecido como `Ignore`, TOE de AWS sale del bucle y vuelve a intentar el paso de acuerdo con la política de reintentos. Tras el número máximo de reintentos, TOE de AWS marca el paso actual como `IgnoredFailure` y continúa hasta ejecutar el paso siguiente. TOE de AWS establece el código de estado de la fase principal y el documento en. `SuccessWithIgnoredFailure` **nota** Esto sigue considerándose una ejecución correcta, pero incluye información que le permite saber que uno o más pasos tienen errores y se ignoraron. + *maxAttempts*: para cada reintento, todo el paso y todas las iteraciones se ejecutan desde el principio. + *status*: el estado general de la ejecución de un paso. `status` no representa el estado de las iteraciones individuales. El estado de un paso con bucles se determina de la siguiente manera: + Si no se puede ejecutar una sola iteración, el estado de un paso indica que se ha producido un error. + Si todas las iteraciones se realizan correctamente, el estado de un paso indica que se ha realizado correctamente. + *startTime*: hora de inicio general de la ejecución de un paso. No representa la hora de inicio de las iteraciones individuales. + *endTime*: la hora de finalización general de la ejecución de un paso. No representa la hora de finalización de las iteraciones individuales. + *failureMessage*: incluye los índices de iteración que fallaron en caso de errores sin tiempo de espera. En caso de errores de tiempo de espera, el mensaje indica que se produjo un error en la ejecución del bucle. No se proporcionan mensajes de error individuales para cada iteración para minimizar el tamaño de los mensajes de error. ## Salidas de paso e iteración Cada iteración contiene una salida. Al final de una ejecución en bucle, TOE de AWS consolida todos los resultados de la iteración correcta. `detailedOutput.json` Las salidas consolidadas son una recopilación de valores que pertenecen a las claves de salida correspondientes, como se define en el esquema de salida del módulo de acción. El siguiente ejemplo muestra cómo se consolidan las salidas: **Salida de `ExecuteBash` para la iteración 1** ``` { "stdout":"Hello" } ``` **Salida de `ExecuteBash` para la iteración 2** ``` { "stdout":"World" } ``` **Salida de `ExecuteBash` para el paso** ``` { "stdout":"Hello\nWorld" } ``` Por ejemplo, `ExecuteBash`, `ExecutePowerShell` y `ExecuteBinary` son módulos de acción que se devuelven `STDOUT` como salida del módulo de acción. Los mensajes `STDOUT` se unen con el carácter de la nueva línea para producir la salida general del paso en `detailedOutput.json`. TOE de AWS no consolidará los resultados de las iteraciones fallidas.