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. # CloudFormation compatibilidad con extensiones de idioma AWS SAMCLIAdmite plantillas que utilizan la `AWS::LanguageExtensions` transformación, incluidas`Fn::ForEach`, `Fn::Length``Fn::ToJsonString`, y `Fn::FindInMap` con`DefaultValue`. Para obtener información de referencia completa sobre estas construcciones, consulte la [AWS::LanguageExtensions transformación](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) en la *Guía del AWS CloudFormation usuario*. Para usar extensiones de idioma en una AWS SAM plantilla, enumere `AWS::LanguageExtensions` en la `Transform` sección *anterior*`AWS::Serverless-2016-10-31`: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 ``` Cuando se AWS SAMCLI detecta `AWS::LanguageExtensions` en la `Transform` sección de una plantilla *y* se ha optado por el procesamiento local, se expanden las construcciones de extensiones de idioma de forma local antes de ejecutar las AWS SAM transformaciones. Esto permite`sam build`, `sam package``sam deploy`,`sam sync`,`sam validate`, `sam local invoke``sam local start-api`, y `sam local start-lambda` trabajar con plantillas que utilizan estas construcciones. El procesamiento local está desactivado de forma predeterminada. Cuando está desactivada, AWS SAMCLI transfiere la plantilla sin cambios y CloudFormation procesa la `AWS::LanguageExtensions` transformación del lado del servidor en el momento de la implementación. Para conocer los métodos de activación, consulte. [Habilitar las extensiones de idioma](#sam-specification-language-extensions-enabling) La expansión se produce en dos fases cuando está habilitada: 1. **Fase 1 (extensiones de idioma)**: los `Fn::ForEach` bucles se expanden, las funciones intrínsecas se resuelven siempre que es posible y la plantilla se convierte en estándar CloudFormation. 1. **Fase 2 (AWS SAM transformación)**: el AWS SAM traductor procesa la plantilla expandida como de costumbre. La plantilla original (`Fn::ForEach`intacta) se conserva para su CloudFormation implementación, ya que CloudFormation procesa la `AWS::LanguageExtensions` transformación en el servidor. ## Habilitar las extensiones de idioma El procesamiento local de `AWS::LanguageExtensions` es opcional para cada comando. Hay tres métodos de activación equivalentes, enumerados por orden de prioridad: 1. **CLIbandera**: transmite una `--language-extensions` sola invocación: ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions`deshabilita explícitamente, anulando tanto `samconfig.toml` la variable de entorno como la que se describe a continuación. 1. **`samconfig.toml`**— conservar la elección por proyecto: ``` [default.build.parameters] language_extensions = true [default.package.parameters] language_extensions = true [default.deploy.parameters] language_extensions = true [default.sync.parameters] language_extensions = true [default.local_invoke.parameters] language_extensions = true [default.local_start_api.parameters] language_extensions = true [default.local_start_lambda.parameters] language_extensions = true [default.validate.parameters] language_extensions = true ``` La `samconfig.toml` entrada se carga de forma predeterminada para el comando, por lo que surte efecto como si se hubiera pasado la bandera y, por lo tanto, prevalece sobre la variable de entorno. 1. **Variable de entorno**: configurada `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` para habilitarla en el shell actual: ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` Los valores verdaderos (no distinguen mayúsculas de minúsculas) son`1`, y`true`. `yes` Todo lo demás, incluida la cadena vacía, se considera desactivado. La variable de entorno solo se consulta cuando ni la CLI marca ni `samconfig.toml` establece un valor. **importante** Cada comando necesita su propia activación. La transferencia `--language-extensions` a `sam build` no se propaga a otra versión posterior`sam local invoke`: el procesamiento local se decide en función de la invocación del comando. Utilice la variable de entorno o una `samconfig.toml` entrada para activar todos los comandos sin repetir la marca. ## Ventilador: ForEach `Fn::ForEach`genera múltiples recursos, condiciones o resultados a partir de una única definición de plantilla: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 Parameters: ServiceNames: Type: CommaDelimitedList Default: "Users,Orders,Products" Resources: Fn::ForEach::Services: - Name - !Ref ServiceNames - ${Name}Function: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: python3.12 CodeUri: ./services/${Name} ``` Al `sam build` ejecutarlo, se expande y `UsersFunction` `OrdersFunction``ProductsFunction`, cada uno se crea a partir de su directorio fuente respectivo. ### Propiedades de los artefactos dinámicos Cuando una propiedad empaquetable utiliza una variable de bucle (por ejemplo,`./services/${Name}`), AWS SAMCLI genera una CloudFormation `Mappings` sección que asigna cada valor de colección a su Amazon S3. URI El `Fn::ForEach` cuerpo se ha reescrito para usarlo de forma que se `Fn::FindInMap` CloudFormation pueda resolver el artefacto correcto en el momento de la implementación. Las propiedades de los artefactos reconocidas son las mismas que se reescriben en la actualidad. `sam package` Esto incluye: **Propiedades de artefactos dinámicos reconocidas por el AWS SAM CLI** | Tipo de recurso | Propiedad | | --- | --- | | `AWS::Serverless::Function` | `CodeUri`, `ImageUri` | | `AWS::Serverless::LayerVersion` | `ContentUri` | | `AWS::Serverless::Api` | `DefinitionUri` | | `AWS::Serverless::HttpApi` | `DefinitionUri` | | `AWS::Serverless::StateMachine` | `DefinitionUri` | | `AWS::Serverless::GraphQLApi` | `SchemaUri`, `CodeUri` | | `AWS::Serverless::Application` | `Location` | | `AWS::Lambda::Function` | `Code`, `Code.ImageUri` | | `AWS::Lambda::LayerVersion` | `Content` | | `AWS::ApiGateway::RestApi` | `BodyS3Location` | | `AWS::ApiGatewayV2::Api` | `BodyS3Location` | | `AWS::AppSync::GraphQLSchema` | `DefinitionS3Location` | | `AWS::AppSync::Resolver` | `RequestMappingTemplateS3Location`, `ResponseMappingTemplateS3Location`, `CodeS3Location` | | `AWS::AppSync::FunctionConfiguration` | `RequestMappingTemplateS3Location`, `ResponseMappingTemplateS3Location`, `CodeS3Location` | | `AWS::StepFunctions::StateMachine` | `DefinitionS3Location` | | `AWS::ElasticBeanstalk::ApplicationVersion` | `SourceBundle` | | `AWS::Glue::Job` | `Command.ScriptLocation` | | `AWS::CloudFormation::Stack` | `TemplateURL` | | `AWS::CloudFormation::StackSet` | `TemplateURL` | | `AWS::CloudFormation::ModuleVersion` | `ModulePackage` | | `AWS::CloudFormation::ResourceVersion` | `SchemaHandlerPackage` | En el caso de las propiedades punteadas (por ejemplo, `Command.ScriptLocation` `Code.ImageUri` activadas `AWS::Glue::Job` o activadas`AWS::Lambda::Function`), el valor se lee y escribe en la ubicación anidada del recurso. El nombre de mapeo generado usa solo el segmento de hoja de la ruta de la propiedad. Cuando la propiedad tiene una plantilla de bucle, el nombre del mapeo es `SAM` (por ejemplo, o). `SAMCodeUriServices` `SAMScriptLocationJobs` **importante** Customer-authored las asignaciones no deben empezar con estos `SAM*` prefijos, sino que están reservadas para. AWS SAMCLI Consulte [Limitaciones](#sam-specification-language-extensions-limitations). Por ejemplo, después de: `sam package` ``` Mappings: SAMCodeUriServices: Users: CodeUri: s3://my-bucket/abc123 Orders: CodeUri: s3://my-bucket/def456 Products: CodeUri: s3://my-bucket/ghi789 Resources: Fn::ForEach::Services: - Name - !Ref ServiceNames - ${Name}Function: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: python3.12 CodeUri: !FindInMap [SAMCodeUriServices, !Ref Name, CodeUri] ``` ### Múltiples recursos por ForEach organismo Un solo `Fn::ForEach` cuerpo puede emitir más de un recurso por iteración. Cada recurso se genera para cada valor de colección: ``` Resources: Fn::ForEach::Tables: - TableName - [Users, Orders, Products] - ${TableName}Table: Type: AWS::DynamoDB::Table Properties: TableName: !Sub "${AWS::StackName}-${TableName}" # ... ${TableName}StreamProcessor: Type: AWS::Serverless::Function Properties: CodeUri: stream-processors/${TableName}/ Events: DDBStream: Type: DynamoDB Properties: Stream: !GetAtt - !Sub "${TableName}Table" - StreamArn ``` ### Mapeo: nombre, resolución de colisiones Cuando dos recursos del mismo `Fn::ForEach` cuerpo declaran la misma propiedad de artefacto dinámico (por ejemplo, un artefacto dinámico `Api` y un `StateMachine` uso`DefinitionUri`), se AWS SAMCLI añade un sufijo tomado de la parte estática de la plantilla de ID lógico del recurso para mantener la exclusividad de los nombres de los mapas: **Ejemplo de mapeo de nombres con sufijos de colisión** | Plantilla de recursos | Propiedad | Nombre de mapeo | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | Cuando no hay colisión, se utiliza el nombre base (por ejemplo,`SAMDefinitionUriServices`). ### Parameter-based colecciones Cuando la `Fn::ForEach` colección es una referencia de parámetros (por ejemplo`!Ref ServiceNames`) y el cuerpo del bucle utiliza una propiedad de artefacto dinámico (por ejemplo,`CodeUri: ./services/${Name}`), AWS SAMCLI necesita los valores de la colección para generar `SAM*` las asignaciones descritas en. [Propiedades de los artefactos dinámicos](#sam-specification-language-extensions-dynamic-artifacts) Los resuelve cuando procesa la plantilla, a partir de: 1. `--parameter-overrides`pasados al AWS SAMCLI comando. 1. El `Default` valor del parámetro en la plantilla. **importante** Como `SAM*` las asignaciones se incorporan al empaquetar, debe volver a empaquetarlas siempre que cambie el valor del parámetro (por ejemplo, al añadir un nuevo servicio) para que las asignaciones incluyan entradas para los nuevos valores. Esto solo se aplica cuando el parámetro genera un bucle de artefactos dinámico; otras anulaciones de parámetros se pueden cambiar en el momento de la implementación, como de costumbre. ``` # Package with the values you intend to deploy with sam package --language-extensions --parameter-overrides ServiceNames="Users,Orders,Products" # Deploy with the same values sam deploy --language-extensions --parameter-overrides ServiceNames="Users,Orders,Products" ``` ### Pilas anidadas `Fn::ForEach`en pilas anidadas, se admiten plantillas (`AWS::CloudFormation::Stack`). AWS SAMCLIPasa la `Parameters` propiedad de la pila principal a la expansión de la plantilla secundaria, de modo que `Fn::ForEach` las colecciones secundarias que hacen referencia a los parámetros proporcionados por la matriz se resuelvan correctamente. ``` # parent.yaml Resources: ChildStack: Type: AWS::CloudFormation::Stack Properties: TemplateURL: ./child.yaml Parameters: ServiceNames: "Users,Orders,Products" ``` ### Ventilador anidado: ForEach Se admiten hasta 5 niveles de anidación, igualando el límite: CloudFormation ``` Resources: Fn::ForEach::Envs: - Env - [Dev, Staging, Prod] - Fn::ForEach::Services: - Svc - [Users, Orders] - ${Env}${Svc}Function: Type: AWS::Serverless::Function Properties: CodeUri: ./services/${Svc} Environment: Variables: STAGE: ${Env} ``` ### ForEach en salidas `Fn::ForEach`los bloques también se expanden dentro de la `Outputs` sección, por lo que puedes emitir una salida por cada valor de colección: ``` Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn ``` ### Condiciones y DependsOn Los recursos emitidos por `Fn::ForEach` pueden transportar `Condition` y `DependsOn` como cualquier otro recurso. La condición o dependencia se replica en cada recurso generado: ``` Conditions: IsProd: !Equals [!Ref Environment, prod] Resources: SharedTable: Type: AWS::DynamoDB::Table # ... Fn::ForEach::Functions: - Name - [api, worker] - ${Name}Function: Type: AWS::Serverless::Function Condition: IsProd DependsOn: SharedTable Properties: Handler: main.handler CodeUri: functions/${Name}/ ``` ### &Sintaxis {identifier} La `&{identifier}` sintaxis elimina los caracteres no alfanuméricos del valor sustituido, lo que resulta útil para generar identificadores lógicos válidos a partir de valores como las direcciones IP: ``` Fn::ForEach::Hosts: - IP - ["10.0.0.1", "10.0.0.2"] - Host&{IP}: Type: AWS::EC2::Instance # Expands to Host10001, Host10002 ``` ## Funciones intrínsecas compatibles Las siguientes funciones intrínsecas se resuelven localmente durante la expansión: **Las funciones intrínsecas se resolvieron localmente durante la expansión de las extensiones de lenguaje** | Función | Description (Descripción) | | --- | --- | | `Fn::ForEach` | Expansión de bucles. | | `Fn::Length` | Devuelve el recuento de elementos de la lista. | | `Fn::ToJsonString` | Convierte un valor en una JSON cadena. | | `Fn::FindInMap` | Búsqueda de mapas, incluida la opcional`DefaultValue`. | | `Fn::If` | Selección de valores condicionales. | | `Fn::Sub` | Sustitución de cadenas. | | `Fn::Join` | Concatenación de cadenas. | | `Fn::Split` | División de cadenas. | | `Fn::Select` | Selección de elementos de lista. | | `Fn::Base64` | Codificación Base64. | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | Evaluación del estado. | | `Ref` | Referencias de parámetros y pseudoparámetros. | Las funciones que requieren recursos desplegados (`Fn::GetAtt`,`Fn::ImportValue`,`Fn::GetAZs`) se conservan para que se resuelvan en CloudFormation el momento de la implementación. ## Errores de validación Los siguientes problemas de plantilla se detectan localmente antes de que se ejecute la AWS SAM transformación: **Se producen errores de validación durante la expansión de las extensiones de idioma** | Causa | Mensaje de error | | --- | --- | | El `Fn::ForEach` valor tiene un formato incorrecto: no es una lista, no tiene exactamente 3 elementos o tiene un identificador de bucle que no es una cadena. | `Fn::ForEach:: layout is incorrect`(planteado como`InvalidTemplateException`). | | `Fn::ForEach`Están anidados más de 5 niveles. | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | La colección se resuelve en una lista vacía (por ejemplo, un `CommaDelimitedList` parámetro con`Default: ""`). | Sin error: el ciclo se omite silenciosamente y no se emite ningún recurso. | | El `!Ref` elemento de la colección apunta a un parámetro que no está declarado en la plantilla. | Sin error: la referencia no resuelta se conserva en la plantilla. En el momento de la implementación, lo CloudFormation resolverá del lado del servidor. | ## Limitaciones + **Las colecciones deben poder resolverse en el momento. build/package ** `Fn::ForEach`Las colecciones que utilizan `Fn::GetAtt` referencias dinámicas de SSM/Secrets Manager o Manager no se pueden expandir localmente. `Fn::ImportValue` En su `--parameter-overrides` lugar, utilice un parámetro con. + **Los mapeos dinámicos de artefactos se fijan en el momento del paquete.** Cuando una `Fn::ForEach` colección es una referencia de parámetro y el cuerpo del bucle utiliza una propiedad de artefacto dinámico (por ejemplo,`CodeUri: ./services/${Name}`), las `SAM*` asignaciones generadas solo contienen entradas para los valores de los parámetros que se resolvieron en el momento del paquete. Si `--parameter-overrides` cambias ese parámetro en el momento del despliegue sin volver a empaquetarlo, los nuevos valores no tendrán entradas de mapeo y el despliegue fallará. Esto no se aplica a los parámetros que no se utilizan para controlar un artefacto `Fn::ForEach` dinámico. + **`DeletionPolicy`y `UpdateReplacePolicy`** se validan y resuelven durante la expansión. Son compatibles con `Ref` los parámetros, pero no con otras funciones intrínsecas. + **Límite de anidación.** Se `Fn::ForEach` pueden anidar hasta 5 niveles de, lo que coincide con el límite del lado del CloudFormation servidor. + **Nombres de mapeo reservados.** Los nombres de mapeo que comiencen con alguno de los siguientes están reservados para el AWS SAMCLI; no cree sus propios mapeos con estos prefijos: + `SAMCodeUri`,`SAMImageUri`,,`SAMContentUri`,`SAMDefinitionUri`,`SAMSchemaUri`,,`SAMBodyS3Location`, `SAMDefinitionS3Location` `SAMTemplateURL``SAMCode`, `SAMContent` — emitido por `sam package` para propiedades de artefactos dinámicos. Consulte la [Propiedades de los artefactos dinámicos](#sam-specification-language-extensions-dynamic-artifacts) tabla. + `SAMLayers`— emitido `sam build` cuando una función `Fn::ForEach` generada recoge referencias de capa de dependencia generadas automáticamente (Lambda coloca las compilaciones en capas AWS SAMCLI en una pila anidada). Este prefijo no tiene ninguna propiedad correspondiente creada por el usuario; se añade automáticamente. ## Telemetría AWS SAMCLI*Emite un evento de `CFNLanguageExtensions` telemetría cuando se invoca un comando con `--language-extensions` (o su equivalente en una variable de entorno) y la plantilla declara la transformación.* `AWS::LanguageExtensions` El evento se activa una vez por invocación y no se transmite el contenido de la plantilla. Cuando el procesamiento local está desactivado (opción predeterminada), no se desencadena ningún evento.