

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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) 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](#sam-specification-language-extensions-enabling).

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.

1. **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
<a name="sam-specification-language-extensions-enabling"></a>

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.

1. **`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.

1. **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
<a name="sam-specification-language-extensions-foreach"></a>

`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
<a name="sam-specification-language-extensions-dynamic-artifacts"></a>

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](#sam-specification-language-extensions-limitations).

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
<a name="sam-specification-language-extensions-multiple-resources"></a>

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
<a name="sam-specification-language-extensions-mapping-collisions"></a>

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
<a name="sam-specification-language-extensions-parameter-collections"></a>

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](#sam-specification-language-extensions-dynamic-artifacts). Los resuelve cuando procesa la plantilla, desde:

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

1. 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
<a name="sam-specification-language-extensions-nested-stacks"></a>

`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
<a name="sam-specification-language-extensions-nested-foreach"></a>

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
<a name="sam-specification-language-extensions-foreach-outputs"></a>

`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
<a name="sam-specification-language-extensions-conditions-dependson"></a>

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}
<a name="sam-specification-language-extensions-identifier-syntax"></a>

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
<a name="sam-specification-language-extensions-supported-functions"></a>

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
<a name="sam-specification-language-extensions-validation-errors"></a>

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
<a name="sam-specification-language-extensions-limitations"></a>
+ **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](#sam-specification-language-extensions-dynamic-artifacts) mesa.
  + `SAMLayers` — emitido por `sam build` cuando un `Fn::ForEach`La 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
<a name="sam-specification-language-extensions-telemetry"></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.