翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CloudFormation 言語拡張機能のサポート

は AWS SAM CLI、、、Fn::ForEach、および Fn::LengthFn::ToJsonStringFn::FindInMapを含む AWS::LanguageExtensions変換を使用するテンプレートをサポートしますDefaultValue。これらのコンストラクトに関する完全なリファレンス情報については、「 AWS CloudFormation ユーザーガイド」の「AWS::LanguageExtensions transform」を参照してください。

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 packagesam deploy、、sam sync、sam validate、sam local invoke、および sam local start-lambdaはsam local start-api、これらのコンストラクトを使用するテンプレートを操作できます。

ローカル処理はデフォルトでオフになっています。オフにすると AWS SAM CLI、 はテンプレートを変更せずに渡し、デプロイ時にAWS::LanguageExtensions変換サーバー側 CloudFormation を処理します。アクティベーション方法については、「」を参照してください言語拡張機能の有効化。

拡張は、有効にすると 2 つのフェーズで行われます。

はAWS::LanguageExtensions変換サーバー側 CloudFormation を処理するため、元のテンプレート (Fn::ForEachそのまま) は CloudFormation デプロイ用に保持されます。

言語拡張機能の有効化

のローカル処理AWS::LanguageExtensionsは、コマンドごとにオプトインされます。優先度順にリストされた 3 つの同等のアクティベーション方法があります。

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}

を実行すると、これを UsersFunction、OrdersFunction、および にsam build拡張しProductsFunction、それぞれがそれぞれのソースディレクトリから構築されます。

動的アーティファクトプロパティ

パッケージ化可能なプロパティがループ変数 ( など./services/${Name}) を使用する場合、 は CloudFormation Mappings各コレクション値を Amazon S3 にマッピングするセクション AWS SAM CLIを生成しますURI。Fn::ForEach 本文は を使用するように書き換えられるFn::FindInMapため、 はデプロイ時に正しいアーティファクトを解決 CloudFormation できます。

認識されたアーティファクトプロパティは、今日書きsam package換えられたものと同じです。これには、以下が含まれます。

点線プロパティ ( Command.ScriptLocationAWS::Glue::Jobまたは などAWS::Lambda::Function) Code.ImageUriの場合、値はリソース上のネストされた場所で読み書きされます。生成されたマッピング名は、プロパティパスのリーフセグメントのみを使用します。

プロパティがループテンプレートの場合、マッピング名は です 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 本文ごとに複数のリソース

1 つの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本文内の 2 つのリソースが同じ動的アーティファクトプロパティを宣言する場合 (たとえば、 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) の がサポートされています。は親スタックの AWS SAM CLIParametersプロパティを子テンプレート拡張に渡すため、親が指定したパラメータを参照する子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セクション内で展開されるため、コレクション値ごとに 1 つの出力を出力できます。

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

条件と DependsOn

によって出力されるリソースFn::ForEachは、他のリソースDependsOnと同様に Conditionおよび を実行できます。条件または依存関係は、生成された各リソースにレプリケートされます。

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 変換を実行する前に、次のテンプレートの問題がローカルで検出されます。

制限事項

テレメトリ

は、 --language-extensions (または同等の環境変数) AWS SAM CLIでコマンドが呼び出され、テンプレートがAWS::LanguageExtensions変換を宣言すると、CFNLanguageExtensionsテレメトリイベントを発行します。イベントは呼び出しごとに 1 回発生し、テンプレートコンテンツは送信されません。ローカル処理がオフ (デフォルト) の場合、イベントは発生しません。