Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon CloudFormation 语言扩展支持

Amazon SAMCLI支持使用AWS::LanguageExtensions变换的模板，包括Fn::ForEachFn::Length、Fn::ToJsonString、Fn::FindInMap和DefaultValue。有关这些构造的完整参考信息，请参阅《Amazon CloudFormation 用户指南》中的 t AWS::LanguageExtensions r ansform。

要在 Amazon SAM 模板中使用语言扩展名，请在之前的Transform部分AWS::LanguageExtensions中列出AWS::Serverless-2016-10-31：

Transform:
  - AWS::LanguageExtensions
  - AWS::Serverless-2016-10-31

当在模板的Transform部分AWS::LanguageExtensions中 Amazon SAMCLI检测到并且您选择了本地处理时，它会在运行 Amazon SAM 转换之前在本地扩展语言扩展结构。这使sam build得sam package、sam deploy、sam sync、sam validate、sam local invoke、sam local start-api、和sam local start-lambda能够使用使用这些构造的模板。

默认情况下，本地处理处于关闭状态。禁用后， Amazon SAMCLI会将模板保持不变，并在部署时 Amazon CloudFormation 处理服务器端的AWS::LanguageExtensions转换。有关激活方法，请参阅启用语言扩展。

启用后，扩展分两个阶段进行：

由于在服务器端 Amazon CloudFormation 处理了AWS::LanguageExtensions转换，因此保留了原始模板（Fn::ForEach完好无损）以供 Amazon CloudFormation 部署。

启用语言扩展

按命令选择AWS::LanguageExtensions进行本地处理。有三种等效的激活方法，按优先级顺序列出：

Fn:: ForEach

Fn::ForEach根据单个模板定义生成多个资源、条件或输出：

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}

Run sam build ning 将其扩展为UsersFunctionOrdersFunctionProductsFunction、和，每个都从其各自的源目录构建。

动态构件属性

当可打包属性使用循环变量（例如./services/${Name}）时， Amazon SAMCLI会生成一个将每个集合值映射到其 Amazon S3 的 Amazon CloudFormation Mappings部分。URI正Fn::ForEach文被重写为使用，Fn::FindInMap因此 Amazon CloudFormation 可以在部署时解析正确的工件。

已识别的工件属性与当今sam package重写的属性相同。这包括：

对于点状属性（例如，Command.ScriptLocationon AWS::Glue::Job 或 Code.ImageUri onAWS::Lambda::Function），将在资源上的嵌套位置读取和写入该值。生成的映射名称仅使用属性路径的叶段。

当属性采用循环模板化时，映射名称为SAM<LeafProperty><LoopName>（例如，SAMCodeUriServices或）。SAMScriptLocationJobs

例如，之后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]

每个 ForEach 机构有多种资源

单个Fn::ForEach主体每次迭代可以发射多个资源。每个资源都是为每个集合值生成的：

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

映射名称冲突解决方案

当同一个Fn::ForEach主体中的两个资源声明相同的动态构件属性（例如，一个Api和一个StateMachine用途DefinitionUri）时，会 Amazon SAMCLI附加一个取自资源 Logical-ID 模板静态部分的后缀，以保持映射名称的唯一性：

如果没有碰撞，则使用基本名称（例如SAMDefinitionUriServices）。

Parameter-based 集合

如果Fn::ForEach集合是参数引用（例如!Ref ServiceNames），而循环体使用动态构件属性（例如CodeUri: ./services/${Name}），则 Amazon SAMCLI需要集合值来生成中所动态构件属性述的SAM*映射。它在处理模板时会解析它们，来自：

# 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"

嵌套堆栈

Fn::ForEach支持嵌套堆栈模板 (AWS::CloudFormation::Stack)。将父堆栈的Parameters属性 Amazon SAMCLI传递给子模板扩展，因此引用父级提供的参数的子Fn::ForEach集合可以正确解析。

# parent.yaml
Resources:
  ChildStack:
    Type: AWS::CloudFormation::Stack
    Properties:
      TemplateURL: ./child.yaml
      Parameters:
        ServiceNames: "Users,Orders,Products"

嵌套 Fn:: ForEach

最多支持 5 个嵌套级别，符合 Amazon 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 在输出中

Fn::ForEach区块也会在该Outputs部分内展开，因此你可以为每个集合值发出一个输出：

Outputs:
  Fn::ForEach::FunctionArns:
    - Name
    - [alpha, beta]
    - ${Name}FunctionArn:
        Value: !GetAtt
          - !Sub "${Name}Function"
          - Arn

条件和 DependsOn

发出的资源Fn::ForEach可以携带，Condition并且可以DependsOn像任何其他资源一样携带。条件或依赖关系会复制到每个生成的资源上：

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

&{标识符} 语法

该&{identifier}语法从替换值中去除非字母数字字符，这对于从 IP 地址等值生成有效的逻辑 ID 非常有用：

Fn::ForEach::Hosts:
  - IP
  - ["10.0.0.1", "10.0.0.2"]
  - Host&{IP}:
      Type: AWS::EC2::Instance
      # Expands to Host10001, Host10002

支持的内部函数

在扩展过程中，以下内部函数将在本地解析：

需要部署资源（Fn::GetAtt、Fn::ImportValue、Fn::GetAZs）的函数会被保留， Amazon CloudFormation 以便在部署时解析。

验证错误

在 Amazon SAM 转换运行之前，会在本地捕获以下模板问题：

限制

遥测

当使用--language-extensions（或 Amazon SAMCLI其等效环境变量）调用命令并且模板声明转换时，会发出CFNLanguageExtensions遥测事件。AWS::LanguageExtensions该事件每次调用都会触发一次，并且不会传输任何模板内容。本地处理处于关闭状态（默认）时，不会触发任何事件。