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 soporte de extensiones de idioma
El AWS SAM CLI admite plantillas que utilizan el AWS::LanguageExtensions transformar, incluyendo Fn::ForEach, Fn::Length, Fn::ToJsonString, y Fn::FindInMap con DefaultValue. Para obtener información de referencia completa sobre estas construcciones, consulte AWS::LanguageExtensions transformar en el AWS CloudFormation Guía del usuario.
Para usar extensiones de idioma en un AWS SAM plantilla, lista AWS::LanguageExtensions en el Transform sección delante de AWS::Serverless-2016-10-31:
Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31
Cuando el AWS SAM CLI detecta AWS::LanguageExtensions en la de una plantilla Transform sección y ha optado por el procesamiento local, amplía las construcciones de las extensiones del lenguaje localmente antes de ejecutarse AWS SAM transforma. Esto permite sam build, sam package, sam deploy, sam sync, sam validate, sam local invoke, sam local start-api, y sam local start-lambda para trabajar con plantillas que utilizan estas construcciones.
El procesamiento local está desactivado de forma predeterminada. Cuando está desactivado, el AWS SAM CLI pasa la plantilla sin cambios y CloudFormation procesa el AWS::LanguageExtensions transforme el lado del servidor en el momento de la implementación. Para conocer los métodos de activación, consulte Habilitar las extensiones de idioma.
La expansión se produce en dos fases cuando está habilitada:
-
Fase 1 (extensiones de idioma) —
Fn::ForEachlos bucles se expanden, las funciones intrínsecas se resuelven siempre que es posible y la plantilla se convierte en estándar CloudFormation. -
Fase 2 (AWS SAM Transformar) — La plantilla expandida es procesada por AWS SAM Traductor, como de costumbre.
La plantilla original (con Fn::ForEach intacta) se conserva durante CloudFormation despliegue, ya que CloudFormation procesa el AWS::LanguageExtensions transforma el lado del servidor.
Habilitar las extensiones de idioma
Procesamiento local de AWS::LanguageExtensions es opcional por comando. Hay tres métodos de activación equivalentes, que se enumeran por orden de prioridad:
-
CLI marcar — pase
--language-extensionsen una sola invocación:sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ...--no-language-extensionsdeshabilita explícitamente, anulando ambassamconfig.tomly la variable de entorno que se describe a continuación. -
samconfig.toml— persistir en 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 = trueA
samconfig.tomlla 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, triunfa sobre la variable de entorno. -
Variable de entorno — establecido
SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1para habilitarlo en el shell actual:export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunctionLos valores verdaderos (sin distinción entre mayúsculas y minúsculas) son
1,true, yyes. Cualquier otra cosa, incluida la cadena vacía, se considera desactivada. La variable de entorno se consulta solo cuando ni el CLI marcar nisamconfig.tomlestablece un valor.
Cada comando necesita su propia activación. Pasando --language-extensions a sam build no se propaga a una posterior sam local invoke — el procesamiento local se decide por cada invocación de comando. Utilice la variable de entorno o un samconfig.toml entrada para habilitar todos los comandos sin repetir la marca.
Diversión::ForEach
Fn::ForEach genera múltiples recursos, condiciones o salidas 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}
En ejecución sam build expande esto en UsersFunction, OrdersFunction, y ProductsFunction, cada uno creado a partir de su directorio fuente respectivo.
Propiedades dinámicas de los artefactos
Cuando una propiedad empaquetable usa una variable de bucle (por ejemplo, ./services/${Name}), el AWS SAM CLI genera un CloudFormation Mappings sección que asigna cada valor de colección a su Amazon S3 URI. El Fn::ForEach el cuerpo se reescribe para usarlo Fn::FindInMap así que CloudFormation puede resolver el artefacto correcto en el momento de la implementación.
Las propiedades del artefacto reconocido son las mismas sam package reescribe hoy. Esto incluye:
| Tipo de recurso | Propiedad |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Para las propiedades punteadas (por ejemplo, Command.ScriptLocation en AWS::Glue::Job o Code.ImageUri en 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 de la asignación es SAM<LeafProperty><LoopName> (por ejemplo, SAMCodeUriServices o SAMScriptLocationJobs).
Customer-authored los mapeos no deberían empezar con estos SAM* prefijos: están reservados para AWS SAM CLI. Consulte Limitaciones.
Por ejemplo, después 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 cuerpo
Un solo Fn::ForEach el 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
Nombre del mapeo: resolución de colisiones
Cuando hay dos recursos en el mismo Fn::ForEach body declara la misma propiedad de artefacto dinámico (por ejemplo, tanto un Api y un StateMachine utilizar DefinitionUri), el AWS SAM CLI añade un sufijo tomado de la parte estática de la plantilla Logical-ID del recurso para mantener la exclusividad de los nombres de mapeo:
| Plantilla de recursos | Propiedad | Nombre de mapeo |
|---|---|---|
|
|
|
|
|
|
Cuando no hay ninguna colisión, el nombre base (por ejemplo, SAMDefinitionUriServices) se usa.
Parameter-based colecciones
Cuando el Fn::ForEach la colección es una referencia de parámetros (por ejemplo, !Ref ServiceNames) y el cuerpo del bucle usa una propiedad de artefacto dinámica (por ejemplo, CodeUri: ./services/${Name}), el AWS SAM CLI necesita los valores de la colección para generar el SAM* Los mapeos descritos en Propiedades dinámicas de los artefactos. Los resuelve cuando procesa la plantilla, desde:
-
--parameter-overridespasó a la AWS SAM CLI comando. -
El parámetro es
Defaultvalor de la plantilla.
Porque el SAM* Las asignaciones se incorporan en el momento del paquete, por lo que debe volver a empaquetarlas cada vez que cambie el valor del parámetro (por ejemplo, al agregar un nuevo servicio) para que las asignaciones incluyan entradas para los nuevos valores. Esto solo se aplica cuando el parámetro impulsa 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 plantillas de pila anidadas (AWS::CloudFormation::Stack) es compatible. El AWS SAM CLI pasa la pila principal Parameters propiedad de la expansión de la plantilla secundaria, por lo que es secundaria Fn::ForEach las colecciones que hacen referencia a parámetros proporcionados por los padres se resuelven 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 anidamiento, que coincidan con CloudFormation límite:
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 del Outputs sección, por lo que puede emitir una salida por valor de colección:
Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn
Condiciones y DependsOn
Recursos emitidos por Fn::ForEach puede 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 de {identifier}
La &{identifier} la 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:
| Función | Description (Descripción) |
|---|---|
|
Expansión del bucle. |
|
Devuelve el recuento de los elementos de la lista. |
|
Convierte un valor en JSON cadena. |
|
Búsqueda de mapas, incluida la opcional |
|
Selección de valores condicionales. |
|
Sustitución de cadenas. |
|
Concatenación de cadenas. |
|
División de cadenas. |
|
Selección de elementos de lista. |
|
Codificación Base64. |
|
Evaluación del estado. |
|
Referencias de parámetros y pseudoparámetros. |
Funciones que requieren recursos desplegados (Fn::GetAtt, Fn::ImportValue, Fn::GetAZs) se conservan durante CloudFormation para que se resuelvan en el momento de la implementación.
Errores de validación
Los siguientes problemas de plantilla se detectan localmente antes de AWS SAM la transformación se ejecuta:
| Causa | Mensaje de error |
|---|---|
El |
|
Más de 5 niveles de |
|
La colección se convierte en una lista vacía (por ejemplo, una |
Sin error: el ciclo se omite silenciosamente y no se emite ningún recurso. |
El |
Sin error: la referencia sin resolver se conserva en la plantilla. En el momento de la implementación, CloudFormation lo resolverá desde el lado del servidor. |
Limitaciones
-
Las colecciones deben poder resolverse en build/package hora.
Fn::ForEachcolecciones que utilizanFn::GetAtt,Fn::ImportValue, o SSM/Secrets Las referencias dinámicas del administrador no se pueden expandir localmente. Utilice un parámetro con--parameter-overridesen su lugar. -
Los mapeos dinámicos de artefactos se fijan a la hora del paquete. Cuando un
Fn::ForEachla colección es una referencia de parámetros y el cuerpo del bucle usa una propiedad de artefacto dinámica (por ejemplo,CodeUri: ./services/${Name}), el generadoSAM*Las asignaciones solo contienen entradas para los valores de los parámetros que se resolvieron en el momento del paquete. Si cambias--parameter-overridespara ese parámetro en el momento de la implementación sin volver a empaquetarlo, los nuevos valores no tendrán entradas de mapeo y la implementación fallará. Esto no se aplica a los parámetros que no se utilizan para controlar un artefacto dinámicoFn::ForEach. -
DeletionPolicyyUpdateReplacePolicyse validan y resuelven durante la expansión. ApoyanRefa los parámetros pero no a otras funciones intrínsecas. -
límite de anidación. Hasta 5 niveles de
Fn::ForEachpuede estar anidado, coincidiendo con CloudFormation límite del lado del servidor. -
Funciones web con código local.
Fn::ForEachno puede generar unAWS::Serverless::WebFunctioncuyoCodeUries un camino local. Defina la función web desde fueraFn::ForEach, o defina suCodeUrial código que ya está en Amazon S3. -
Nombres de mapeo reservados. Los nombres de mapeo que comiencen por cualquiera de los siguientes están reservados para AWS SAM CLI — no cree sus propios mapeos con estos prefijos:
-
SAMCodeUri,SAMImageUri,SAMContentUri,SAMDefinitionUri,SAMSchemaUri,SAMBodyS3Location,SAMDefinitionS3Location,SAMTemplateURL,SAMCode,SAMContent— emitido porsam packagepara propiedades dinámicas de artefactos. Consulte el Propiedades dinámicas de los artefactos mesa. -
SAMLayers— emitido porsam buildcuando unFn::ForEachLa función generada recoge las referencias de la capa de dependencia generadas automáticamente (capas Lambda, las AWS SAM CLI se convierte en una pila anidada). Este prefijo no tiene ninguna propiedad correspondiente creada por el usuario; se agrega automáticamente.
-
Telemetría
El AWS SAM CLI emite un CFNLanguageExtensions evento de telemetría cuando se invoca un comando con --language-extensions (o su equivalente en la variable de entorno) y la plantilla declara el AWS::LanguageExtensions transformar. 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.