View a markdown version of this page

CloudFormation soporte de extensiones de idioma - AWS Serverless Application Model

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:

  1. Fase 1 (extensiones de idioma) — Fn::ForEach los bucles se expanden, las funciones intrínsecas se resuelven siempre que es posible y la plantilla se convierte en estándar CloudFormation.

  2. 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:

  1. CLI marcar — pase --language-extensions en una sola invocación:

    sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ...

    --no-language-extensions deshabilita explícitamente, anulando ambas samconfig.toml y la variable de entorno que se describe a continuación.

  2. 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 = true

    A samconfig.toml la 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.

  3. Variable de entorno — establecido SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 para habilitarlo en el shell actual:

    export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction

    Los valores verdaderos (sin distinción entre mayúsculas y minúsculas) son 1, true, y yes. Cualquier otra cosa, incluida la cadena vacía, se considera desactivada. La variable de entorno se consulta solo cuando ni el CLI marcar ni samconfig.toml establece un valor.

importante

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:

Propiedades dinámicas de los artefactos 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

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).

importante

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:

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 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:

  1. --parameter-overrides pasó a la AWS SAM CLI comando.

  2. El parámetro es Default valor de la plantilla.

importante

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}/

&amp;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:

Las funciones intrínsecas se resolvieron localmente durante la expansión de las extensiones del lenguaje
Función Description (Descripción)

Fn::ForEach

Expansión del bucle.

Fn::Length

Devuelve el recuento de los elementos de la lista.

Fn::ToJsonString

Convierte un valor en 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.

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:

Se produjeron errores de validación durante la expansión de las extensiones de idioma
Causa Mensaje de error

El Fn::ForEach el valor está mal formado: no es una lista, no tiene exactamente 3 elementos o tiene un identificador de bucle que no es una cadena.

Fn::ForEach::<key> layout is incorrect (planteado como InvalidTemplateException).

Más de 5 niveles de Fn::ForEach están anidados.

Fn::ForEach nesting depth of <N> exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.

La colección se convierte en una lista vacía (por ejemplo, una CommaDelimitedList parámetro con Default: "").

Sin error: el ciclo se omite silenciosamente y no se emite ningún recurso.

El !Ref en la colección apunta a un parámetro que no está declarado en la plantilla.

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::ForEach colecciones que utilizan Fn::GetAtt, Fn::ImportValue, o SSM/Secrets Las referencias dinámicas del administrador no se pueden expandir localmente. Utilice un parámetro con --parameter-overrides en su lugar.

  • Los mapeos dinámicos de artefactos se fijan a la hora del paquete. Cuando un Fn::ForEach la 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 generado SAM* Las asignaciones solo contienen entradas para los valores de los parámetros que se resolvieron en el momento del paquete. Si cambias --parameter-overrides para 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ámico Fn::ForEach.

  • DeletionPolicy y UpdateReplacePolicy se validan y resuelven durante la expansión. Apoyan Ref a los parámetros pero no a otras funciones intrínsecas.

  • límite de anidación. Hasta 5 niveles de Fn::ForEach puede estar anidado, coincidiendo con CloudFormation límite del lado del servidor.

  • Funciones web con código local. Fn::ForEach no puede generar un AWS::Serverless::WebFunction cuyo CodeUri es un camino local. Defina la función web desde fuera Fn::ForEach, o defina su CodeUri al 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 por sam package para propiedades dinámicas de artefactos. Consulte el Propiedades dinámicas de los artefactos mesa.

    • SAMLayers — emitido por sam build cuando un Fn::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.