Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # CloudFormation Unterstützung für Spracherweiterungen Das AWS SAMCLI unterstützt Vorlagen, die die `AWS::LanguageExtensions` Transformation verwenden`Fn::ForEach`, einschließlich`Fn::Length`,`Fn::ToJsonString`, und `Fn::FindInMap` with`DefaultValue`. Vollständige Referenzinformationen zu diesen Konstrukten finden Sie unter [AWS::LanguageExtensions Transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) im *AWS CloudFormation Benutzerhandbuch*. Informationen zur Verwendung von Spracherweiterungen in einer AWS SAM Vorlage finden Sie `AWS::LanguageExtensions` im *vorherigen `Transform`* `AWS::Serverless-2016-10-31` Abschnitt: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 ``` Wenn der `AWS::LanguageExtensions` im `Transform` Abschnitt einer Vorlage AWS SAMCLI erkannt wird *und* Sie sich für die lokale Verarbeitung entschieden haben, werden die Konstrukte der Spracherweiterungen lokal erweitert, bevor AWS SAM Transformationen ausgeführt werden. Dadurch kann`sam build`,`sam package`,`sam deploy`,`sam sync`, `sam validate``sam local invoke`, und mit Vorlagen arbeiten `sam local start-api``sam local start-lambda`, die diese Konstrukte verwenden. Die lokale Verarbeitung ist standardmäßig deaktiviert. Wenn diese Option deaktiviert ist, AWS SAMCLI leitet der die Vorlage unverändert weiter und CloudFormation verarbeitet die `AWS::LanguageExtensions` Transformation serverseitig bei der Bereitstellung. Informationen zu Aktivierungsmethoden finden Sie unter[Spracherweiterungen werden aktiviert](#sam-specification-language-extensions-enabling). Die Erweiterung erfolgt in zwei Phasen, wenn sie aktiviert ist: 1. **Phase 1 (Spracherweiterungen)** — `Fn::ForEach` Schleifen werden erweitert, systeminterne Funktionen werden soweit möglich aufgelöst und die Vorlage wird in den Standard umgewandelt. CloudFormation 1. **Phase 2 (AWS SAM Transformation)** — Die erweiterte Vorlage wird vom AWS SAM Übersetzer wie gewohnt verarbeitet. Die ursprüngliche Vorlage (mit `Fn::ForEach` intakter Vorlage) wird für die CloudFormation Bereitstellung beibehalten, da die `AWS::LanguageExtensions` Transformation serverseitig CloudFormation verarbeitet wird. ## Spracherweiterungen werden aktiviert Die lokale Verarbeitung von `AWS::LanguageExtensions` erfolgt per Opt-In pro Befehl. Es gibt drei äquivalente Aktivierungsmethoden, die in der Reihenfolge ihrer Priorität aufgeführt sind: 1. **CLIflag** — einen einzigen Aufruf `--language-extensions` weiterleiten: ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions`deaktiviert explizit und überschreibt beide `samconfig.toml` sowie die unten beschriebene Umgebungsvariable. 1. **`samconfig.toml`**— Behält die Auswahl pro Projekt bei: ``` [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 ``` Ein `samconfig.toml` Eintrag wird standardmäßig für den Befehl geladen, sodass er so wirkt, als ob das Flag übergeben worden wäre — und hat somit Vorrang vor der Umgebungsvariablen. 1. **Umgebungsvariable** — so gesetzt`SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1`, dass sie für die aktuelle Shell aktiviert wird: ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` Wahrheitsgemäße Werte (ohne Berücksichtigung von Groß- und Kleinschreibung) sind`1`, und`true`. `yes` Alles andere, einschließlich der leeren Zeichenfolge, wird als ausgeschaltet behandelt. Die Umgebungsvariable wird nur dann konsultiert, wenn weder das CLI Flag noch einen Wert `samconfig.toml` festlegt. **Wichtig** Jeder Befehl benötigt seine eigene Aktivierung. Die Übergabe `--language-extensions` an `sam build` wird nicht auf einen späteren Zeitpunkt übertragen `sam local invoke` — die lokale Verarbeitung wird pro Befehlsaufruf entschieden. Verwenden Sie die Umgebungsvariable oder einen `samconfig.toml` Eintrag, um Across-Befehle zu aktivieren, ohne das Flag zu wiederholen. ## Fn:: ForEach `Fn::ForEach`generiert mehrere Ressourcen, Bedingungen oder Ausgaben aus einer einzigen Vorlagendefinition: ``` 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} ``` Beim Ausführen wird dies auf`UsersFunction`, und`OrdersFunction`, `sam build` erweitert`ProductsFunction`, die jeweils aus ihrem jeweiligen Quellverzeichnis erstellt wurden. ### Dynamische Artefakteigenschaften Wenn eine paketierbare Eigenschaft eine Schleifenvariable verwendet (z. B.`./services/${Name}`), AWS SAMCLI generiert sie einen CloudFormation `Mappings` Abschnitt, der jeden Sammlungswert seinem Amazon S3 zuordnet. URI Der `Fn::ForEach` Text wird so umgeschrieben, dass er verwendet werden CloudFormation kann, `Fn::FindInMap` damit er bei der Bereitstellung das richtige Artefakt auflösen kann. Bei den erkannten Artefakteigenschaften handelt es sich um dieselben, die heute neu geschrieben wurden. `sam package` Das beinhaltet: **Dynamische Artefakteigenschaften, erkannt von AWS SAM CLI** | Ressourcentyp | Eigenschaft | | --- | --- | | `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` | Bei Eigenschaften mit Punkten (z. B. `Command.ScriptLocation` on `AWS::Glue::Job` oder `Code.ImageUri` on`AWS::Lambda::Function`) wird der Wert an der verschachtelten Position auf der Ressource gelesen und geschrieben. Der generierte Mapping-Name verwendet nur das Blattsegment des Eigenschaftenpfads. Wenn es sich bei der Eigenschaft um eine Loop-Vorlage handelt, lautet der Mapping-Name `SAM` (zum Beispiel oder). `SAMCodeUriServices` `SAMScriptLocationJobs` **Wichtig** Customer-authored Zuordnungen sollten nicht mit diesen `SAM*` Präfixen beginnen — sie sind reserviert für. AWS SAMCLI Siehe [Einschränkungen](#sam-specification-language-extensions-limitations). Zum Beispiel nach: `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] ``` ### Mehrere Ressourcen pro ForEach Körper Ein einzelner `Fn::ForEach` Körper kann mehr als eine Ressource pro Iteration emittieren. Jede Ressource wird für jeden Sammlungswert generiert: ``` 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 ``` ### Zuordnung, Name, Kollision, Auflösung Wenn zwei Ressourcen im selben `Fn::ForEach` Hauptteil dieselbe dynamische Artefakteigenschaft deklarieren (z. B. sowohl an als auch als `StateMachine` use`DefinitionUri`), wird ein `Api` Suffix AWS SAMCLI angehängt, das aus dem statischen Teil der Vorlage für die logische ID der Ressource übernommen wurde, um die Zuordnungsnamen eindeutig zu halten: **Beispiel für die Zuordnung von Namen mit Kollisionssuffixen** | Vorlage für Ressourcen | Eigenschaft | Name der Zuordnung | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | Liegt keine Kollision vor, wird der Basisname (z. B.`SAMDefinitionUriServices`) verwendet. ### Parameter-based Sammlungen Wenn es sich bei der `Fn::ForEach` Sammlung um eine Parameterreferenz handelt (z. B.`!Ref ServiceNames`) und der Schleifenkörper eine dynamische Artefakteigenschaft verwendet (z. B.`CodeUri: ./services/${Name}`), AWS SAMCLI benötigt er die Sammlungswerte, um die unter beschriebenen `SAM*` Zuordnungen zu generieren. [Dynamische Artefakteigenschaften](#sam-specification-language-extensions-dynamic-artifacts) Sie werden bei der Verarbeitung der Vorlage wie folgt aufgelöst: 1. `--parameter-overrides`an den AWS SAMCLI Befehl übergeben. 1. Der `Default` Wert des Parameters in der Vorlage. **Wichtig** Da die `SAM*` Mappings zum Zeitpunkt des Paketes integriert werden, müssen Sie jedes Mal, wenn Sie den Parameterwert ändern (z. B. wenn Sie einen neuen Dienst hinzufügen), neu verpacken, damit die Mappings Einträge für die neuen Werte enthalten. Dies gilt nur, wenn der Parameter eine dynamische Artefaktschleife steuert. Andere Parameterüberschreibungen können wie gewohnt bei der Bereitstellung geändert werden. ``` # 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" ``` ### Verschachtelte Stacks `Fn::ForEach`in Nested Stack wird Templates (`AWS::CloudFormation::Stack`) unterstützt. Der AWS SAMCLI übergibt die `Parameters` Eigenschaft des übergeordneten Stacks an die Erweiterung der untergeordneten Vorlage, sodass untergeordnete `Fn::ForEach` Sammlungen, die auf vom Elternteil bereitgestellte Parameter verweisen, korrekt aufgelöst werden. ``` # parent.yaml Resources: ChildStack: Type: AWS::CloudFormation::Stack Properties: TemplateURL: ./child.yaml Parameters: ServiceNames: "Users,Orders,Products" ``` ### Verschachteltes Fn: ForEach Es werden bis zu 5 Verschachtelungsebenen unterstützt, die dem CloudFormation Limit entsprechen: ``` 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 in den Ausgängen `Fn::ForEach`Blöcke werden auch innerhalb des `Outputs` Abschnitts erweitert, sodass Sie pro Sammlungswert eine Ausgabe ausgeben können: ``` Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn ``` ### Bedingungen und DependsOn Ressourcen, die von `Fn::ForEach` can emittiert werden, tragen `Condition` und `DependsOn` wie jede andere Ressource. Die Bedingung oder Abhängigkeit wird auf jede generierte Ressource repliziert: ``` 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} -Syntax Die `&{identifier}` Syntax entfernt nicht-alphanumerische Zeichen aus dem ersetzten Wert, was nützlich ist, um gültige logische IDs aus Werten wie IP-Adressen zu generieren: ``` Fn::ForEach::Hosts: - IP - ["10.0.0.1", "10.0.0.2"] - Host&{IP}: Type: AWS::EC2::Instance # Expands to Host10001, Host10002 ``` ## Unterstützte systeminterne Funktionen Die folgenden systemeigenen Funktionen werden während der Erweiterung lokal gelöst: **Systeminterne Funktionen wurden bei der Erweiterung der Spracherweiterungen lokal behoben** | Funktion | Description | | --- | --- | | `Fn::ForEach` | Loop-Erweiterung. | | `Fn::Length` | Gibt die Anzahl der Listenelemente zurück. | | `Fn::ToJsonString` | Konvertiert einen Wert in eine JSON Zeichenfolge. | | `Fn::FindInMap` | Kartensuche, einschließlich der optionalen`DefaultValue`. | | `Fn::If` | Bedingte Auswahl von Werten. | | `Fn::Sub` | Ersetzung von Zeichenketten. | | `Fn::Join` | Verkettung von Zeichenketten. | | `Fn::Split` | Aufteilen von Zeichenketten. | | `Fn::Select` | Elementauswahl auflisten. | | `Fn::Base64` | Base64-Kodierung. | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | Bewertung des Zustands. | | `Ref` | Parameter- und Pseudo-Parameter-Referenzen. | Funktionen, die bereitgestellte Ressourcen (`Fn::GetAtt`,,`Fn::GetAZs`) benötigen`Fn::ImportValue`, werden beibehalten, CloudFormation damit sie bei der Bereitstellung behoben werden können. ## Validierungsfehler Die folgenden Vorlagenprobleme werden lokal erkannt, bevor die AWS SAM Transformation ausgeführt wird: **Bei der Erweiterung der Spracherweiterungen sind Validierungsfehler aufgetreten** | Ursache | Fehlermeldung | | --- | --- | | Der `Fn::ForEach` Wert ist falsch formatiert — es handelt sich nicht um eine Liste, er hat nicht genau 3 Elemente oder er hat einen Schleifenbezeichner, der keine Zeichenfolge ist. | `Fn::ForEach:: layout is incorrect`(ausgelöst als`InvalidTemplateException`). | | Mehr als 5 Ebenen von `Fn::ForEach` sind verschachtelt. | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | Die Sammlung wird in eine leere Liste aufgelöst (z. B. ein `CommaDelimitedList` Parameter mit`Default: ""`). | Kein Fehler — die Schleife wird stillschweigend übersprungen und es werden keine Ressourcen ausgegeben. | | Die Punkte `!Ref` in der Sammlung befinden sich auf einem Parameter, der nicht in der Vorlage deklariert ist. | Kein Fehler — die ungelöste Referenz wird in der Vorlage beibehalten. CloudFormation Wird das Problem bei der Bereitstellung serverseitig lösen. | ## Einschränkungen + **Sammlungen müssen zu einem bestimmten Zeitpunkt build/package auflösbar sein.** `Fn::ForEach`Sammlungen, `Fn::GetAtt``Fn::ImportValue`, oder dynamische SSM/Secrets Manager-Verweise verwenden, können nicht lokal erweitert werden. Verwenden Sie `--parameter-overrides` stattdessen einen Parameter mit. + **Dynamische Artefaktzuordnungen werden zur Paketzeit behoben.** Wenn es sich bei einer `Fn::ForEach` Sammlung um eine Parameterreferenz handelt und der Loop-Body eine dynamische Artefakteigenschaft verwendet (z. B.`CodeUri: ./services/${Name}`), enthalten die generierten `SAM*` Mappings nur Einträge für die Parameterwerte, die zur Paketzeit aufgelöst wurden. Wenn Sie diesen Parameter bei der Bereitstellung ändern`--parameter-overrides`, ohne das Paket neu zu verpacken, enthalten die neuen Werte keine Mapping-Einträge und die Bereitstellung schlägt fehl. Dies gilt nicht für Parameter, die nicht zur Steuerung eines dynamischen `Fn::ForEach` Artefakts verwendet werden. + **`DeletionPolicy`und `UpdateReplacePolicy`** werden während der Erweiterung validiert und behoben. Sie unterstützen zwei Parameter`Ref`, aber keine anderen systemeigenen Funktionen. + **Verschachtelungslimit.** `Fn::ForEach`Es können bis zu 5 Ebenen verschachtelt werden, was dem CloudFormation serverseitigen Limit entspricht. + **Reservierte Zuordnungsnamen.** Mapping-Namen, die mit einem der folgenden Zeichen beginnen, sind für die reserviert AWS SAMCLI — erstellen Sie keine eigenen Mappings mit diesen Präfixen: + `SAMCodeUri`,`SAMImageUri`,,`SAMContentUri`,`SAMDefinitionUri`,`SAMSchemaUri`,, `SAMBodyS3Location` `SAMDefinitionS3Location` `SAMTemplateURL``SAMCode`, `SAMContent` — wird von `sam package` für dynamische Artefakteigenschaften ausgegeben. Sehen Sie sich die [Dynamische Artefakteigenschaften](#sam-specification-language-extensions-dynamic-artifacts) Tabelle an. + `SAMLayers`— wird ausgegeben`sam build`, wenn eine `Fn::ForEach` -generierte Funktion automatisch generierte Referenzen auf Abhängigkeitsebenen aufnimmt (Lambda überlagert die Builds in einen verschachtelten Stapel). AWS SAMCLI Dieses Präfix hat keine entsprechende vom Benutzer verfasste Eigenschaft; es wird automatisch hinzugefügt. ## Telemetrie *Das AWS SAMCLI gibt ein `CFNLanguageExtensions` Telemetrieereignis aus, wenn ein Befehl mit `--language-extensions` (oder einer entsprechenden Umgebungsvariablen) aufgerufen wird und die Vorlage die Transformation deklariert.* `AWS::LanguageExtensions` Das Ereignis wird einmal pro Aufruf ausgelöst und es wird kein Vorlageninhalt übertragen. Wenn die lokale Verarbeitung ausgeschaltet ist (Standardeinstellung), wird kein Ereignis ausgelöst.