本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

CloudFormation 語言延伸支援

AWS SAM CLI 支援使用AWS::LanguageExtensions轉換的範本，包括 Fn::ForEach、Fn::ToJsonString、 Fn::Length和 Fn::FindInMap與 DefaultValue。如需這些建構模組的完整參考資訊，請參閱AWS CloudFormation 《 使用者指南》中的 AWS：：LanguageExtensions 轉換。

若要在 AWS SAM 範本中使用語言延伸，請在 之前的 Transform區段AWS::LanguageExtensions中列出 AWS::Serverless-2016-10-31：

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

當 在 AWS SAM CLI範本的 Transform區段AWS::LanguageExtensions中偵測到 ，且您已選擇加入本機處理時，它會在執行 AWS SAM 轉換之前於本機擴展語言延伸建構。這可讓 sam build、sam package、sam deploy、sam sync、sam validate、sam local start-api、 和 sam local invokesam local start-lambda使用使用這些建構的範本。

本機處理預設為關閉。關閉時， AWS SAM CLI會傳遞範本，並在部署時間 CloudFormation 處理AWS::LanguageExtensions轉換伺服器端。如需啟用方法，請參閱 啟用語言延伸模組。

啟用時，擴展會分兩個階段進行：

原始範本 (Fn::ForEach完整） 會保留供 CloudFormation 部署使用，因為 會 CloudFormation 處理AWS::LanguageExtensions轉換伺服器端。

啟用語言延伸模組

的本機處理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}

執行 會將此項目sam build擴展至 OrdersFunction、 UsersFunction和 ProductsFunction，每個項目都是從其個別來源目錄建置。

動態成品屬性

當可封裝屬性使用迴圈變數 （例如 ./services/${Name}) 時， AWS SAM CLI會產生區段 CloudFormation Mappings，將每個集合值映射至其 Amazon S3URI。內Fn::ForEach文會重寫為使用 Fn::FindInMap，以便在部署時 CloudFormation 解析正確的成品。

辨識的成品屬性與今天sam package重新寫入的成品屬性相同。這包括：

對於虛線屬性 （例如Command.ScriptLocation，在 上AWS::Glue::Job或在 Code.ImageUri上AWS::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) 時， AWS SAM CLI會附加從資源邏輯 ID 範本的靜態部分取得的尾碼，以保持映射名稱是唯一的：

沒有碰撞時，會使用基本名稱 （例如 SAMDefinitionUriServices)。

參數型集合

當Fn::ForEach集合是參數參考 （例如 !Ref ServiceNames) 且迴圈內文使用動態成品屬性 （例如 CodeUri: ./services/${Name}) 時， AWS SAM CLI需要集合值才能產生 中所述的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 屬性 AWS SAM CLI傳遞至子範本擴展，以便參考父系提供的參數的子Fn::ForEach集合正確解析。

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

巢狀 Fn：：ForEach

最多支援 5 個巢狀層級，符合 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} 語法

&{identifier} 語法會從取代的值中去除非英數字元，這對於從 IP 地址等值產生有效的邏輯 IDs 非常有用：

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) 的函數會在部署時保留 CloudFormation 供 解析。

驗證錯誤

在 AWS SAM 轉換執行之前，會在本機發現下列範本問題：

限制

遙測

當 AWS SAM CLI使用 --language-extensions（或其環境變數對等項目） 叫用命令，且範本宣告AWS::LanguageExtensions轉換時， 會發出CFNLanguageExtensions遙測事件。事件會在每次叫用時觸發一次，而且不會傳輸任何範本內容。當本機處理關閉 （預設值） 時，不會觸發事件。