翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # CloudFormation 言語拡張機能のサポート は AWS SAM CLI、、、`Fn::ForEach`、および `Fn::Length``Fn::ToJsonString``Fn::FindInMap`を含む `AWS::LanguageExtensions`変換を使用するテンプレートをサポートします`DefaultValue`。これらのコンストラクトに関する完全なリファレンス情報については、「 *AWS CloudFormation ユーザーガイド*」の[「AWS::LanguageExtensions transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html)」を参照してください。 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 invoke`、および `sam local start-lambda`は`sam local start-api`、これらのコンストラクトを使用するテンプレートを操作できます。 ローカル処理はデフォルトでオフになっています。オフにすると AWS SAM CLI、 はテンプレートを変更せずに渡し、デプロイ時に`AWS::LanguageExtensions`変換サーバー側 CloudFormation を処理します。アクティベーション方法については、「」を参照してください[言語拡張機能の有効化](#sam-specification-language-extensions-enabling)。 拡張は、有効にすると 2 つのフェーズで行われます。 1. **フェーズ 1 (言語拡張)** — `Fn::ForEach`ループが展開され、組み込み関数が可能な限り解決され、テンプレートが標準に変換されます CloudFormation。 1. **フェーズ 2 (AWS SAM 変換)** — 展開されたテンプレートは、通常どおり AWS SAM Translator によって処理されます。 は`AWS::LanguageExtensions`変換サーバー側 CloudFormation を処理するため、元のテンプレート (`Fn::ForEach`そのまま) は CloudFormation デプロイ用に保持されます。 ## 言語拡張機能の有効化 のローカル処理`AWS::LanguageExtensions`は、コマンドごとにオプトインされます。優先度順にリストされた 3 つの同等のアクティベーション方法があります。 1. **CLI フラグ** — 1 回の呼び出し`--language-extensions`で渡します。 ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions` は明示的に無効に`samconfig.toml`し、以下で説明する環境変数と の両方を上書きします。 1. **`samconfig.toml`** — プロジェクトごとに選択肢を保持します。 ``` [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 ``` `samconfig.toml` エントリはコマンドのデフォルトとしてロードされるため、フラグが渡されたかのように有効になり、環境変数を優先します。 1. **環境変数** — 現在のシェルに対して を有効にする`SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1`ように設定されます。 ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` Truthy 値 (大文字と小文字を区別しない) は `1`、`true`、および です`yes`。空の文字列を含む他のものはオフとして扱われます。環境変数は、 CLIフラグも 値も`samconfig.toml`設定されていない場合にのみ参照されます。 **重要** 各コマンドには独自のアクティベーションが必要です。`--language-extensions` に渡すと、後で に伝達`sam build`されません`sam local invoke`。ローカル処理はコマンドの呼び出しごとに決定されます。環境変数または`samconfig.toml`エントリを使用して、 フラグを繰り返すことなくコマンド間で を有効にします。 ## 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`換えられたものと同じです。これには、以下が含まれます。 **によって認識される動的アーティファクトプロパティ AWS SAM CLI** | リソースタイプ | プロパティ | | --- | --- | | `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` | 点線プロパティ ( `Command.ScriptLocation``AWS::Glue::Job`または など`AWS::Lambda::Function`) `Code.ImageUri`の場合、値はリソース上のネストされた場所で読み書きされます。生成されたマッピング名は、プロパティパスのリーフセグメントのみを使用します。 プロパティがループテンプレートの場合、マッピング名は です `SAM` (例: `SAMCodeUriServices`または `SAMScriptLocationJobs`)。 **重要** お客様が作成したマッピングは、これらの`SAM*`プレフィックスで開始しないでください。 用に予約されています AWS SAM CLI。「[制限事項](#sam-specification-language-extensions-limitations)」を参照してください。 たとえば、 の後`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 テンプレートの静的部分から取得したサフィックスを追加して、マッピング名を一意に保ちます。 **衝突サフィックスを使用して名前をマッピングする例** | リソーステンプレート | プロパティ | マッピング名 | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | 衝突がない場合、ベース名 ( など`SAMDefinitionUriServices`) が使用されます。 ### パラメータベースのコレクション `Fn::ForEach` コレクションがパラメータリファレンス ( など`!Ref ServiceNames`) であり、ループ本文が動的アーティファクトプロパティ ( など`CodeUri: ./services/${Name}`) を使用する場合、 AWS SAM CLIで説明されている`SAM*`マッピングを生成するにはコレクション値が必要です[動的アーティファクトプロパティ](#sam-specification-language-extensions-dynamic-artifacts)。テンプレートを処理するときに、以下から解決されます。 1. `--parameter-overrides` コマンドに渡されます AWS SAM CLI。 1. テンプレート内のパラメータ`Default`の値。 **重要** `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 CLI`Parameters`プロパティを子テンプレート拡張に渡すため、親が指定したパラメータを参照する子`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::ForEach` | ループ拡張。 | | `Fn::Length` | リスト要素の数を返します。 | | `Fn::ToJsonString` | 値をJSON文字列に変換します。 | | `Fn::FindInMap` | オプションの を含むマップルックアップ`DefaultValue`。 | | `Fn::If` | 条件付き値の選択。 | | `Fn::Sub` | 文字列の置換。 | | `Fn::Join` | 文字列連結。 | | `Fn::Split` | 文字列の分割。 | | `Fn::Select` | 要素の選択を一覧表示します。 | | `Fn::Base64` | Base64 エンコーディング。 | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | 条件評価。 | | `Ref` | パラメータと擬似パラメータの参照。 | デプロイされたリソース (`Fn::GetAtt`、`Fn::ImportValue`、`Fn::GetAZs`) を必要とする関数は、デプロイ時に が解決 CloudFormation できるように保持されます。 ## 検証エラー AWS SAM 変換を実行する前に、次のテンプレートの問題がローカルで検出されます。 **言語拡張機能の拡張中に発生した検証エラー** | 原因 | エラーメッセージ | | --- | --- | | `Fn::ForEach` 値が形式が正しくありません。リストではない、要素が 3 つしかない、または文字列以外のループ識別子があります。 | `Fn::ForEach:: layout is incorrect` ( として引き上げ)`InvalidTemplateException`。 | | 5 レベル以上の `Fn::ForEach`がネストされています。 | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | コレクションは空のリスト ( を含む`CommaDelimitedList`パラメータなど`Default: ""`) に解決されます。 | エラーなし — ループはサイレントにスキップされ、リソースは出力されません。 | | コレクション`!Ref`内の は、テンプレートで宣言されていないパラメータを指します。 | エラーなし — 未解決のリファレンスはテンプレートに保持されます。デプロイ時に、 CloudFormation はサーバー側で解決します。 | ## 制限事項 + **コレクションはビルド/パッケージ時に解決可能である必要があります。**`Fn::GetAtt`、`Fn::ImportValue`、または SSM/Secrets Manager の動的参照を使用する`Fn::ForEach`コレクションをローカルで展開することはできません。`--parameter-overrides` 代わりに で パラメータを使用します。 + **動的アーティファクトマッピングはパッケージ時に固定されます。**`Fn::ForEach` コレクションがパラメータリファレンスであり、ループ本文が動的アーティファクトプロパティ ( など`CodeUri: ./services/${Name}`) を使用する場合、生成された`SAM*`マッピングには、パッケージ時に解決されたパラメータ値のエントリのみが含まれます。再パッケージ化せずにデプロイ時にそのパラメータ`--parameter-overrides`を変更した場合、新しい値には Mapping エントリがなく、デプロイは失敗します。これは、動的アーティファクトの駆動に使用されていないパラメータには適用されません`Fn::ForEach`。 + **`DeletionPolicy` と `UpdateReplacePolicy`** は、拡張中に検証および解決されます。これらは パラメータをサポートしていますが`Ref`、他の組み込み関数はサポートしていません。 + **ネスト制限。** CloudFormation サーバー側の制限に合わせて、最大 5 レベルの をネスト`Fn::ForEach`できます。 + **予約済みマッピング名。**次のいずれかで始まるマッピング名は AWS SAM CLI用に予約されています。これらのプレフィックスを使用して独自のマッピングを作成しないでください。 + `SAMCodeUri`、`SAMImageUri`、`SAMContentUri`、`SAMDefinitionUri`、、`SAMSchemaUri`、`SAMCode`、、 `SAMContent` — 動的アーティファクトプロパティ`sam package`用に `SAMBodyS3Location` `SAMDefinitionS3Location` `SAMTemplateURL`によって出力されます。[動的アーティファクトプロパティ](#sam-specification-language-extensions-dynamic-artifacts) 表を参照してください。 + `SAMLayers` — `Fn::ForEach`が生成した関数が自動生成された依存関係レイヤー参照 ( が AWS SAM CLIネストされたスタックに構築する Lambda レイヤー) を取得する`sam build`と、 によって出力されます。このプレフィックスには、対応するユーザー作成プロパティはなく、自動的に追加されます。 ## テレメトリ は、 `--language-extensions` (または同等の環境変数) AWS SAM CLIでコマンドが呼び出*され*、テンプレートが`AWS::LanguageExtensions`変換を宣言すると、`CFNLanguageExtensions`テレメトリイベントを発行します。イベントは呼び出しごとに 1 回発生し、テンプレートコンテンツは送信されません。ローカル処理がオフ (デフォルト) の場合、イベントは発生しません。