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
Die AWS SAM CLI unterstützt Vorlagen, die das verwenden AWS::LanguageExtensions transformieren, einschließlich Fn::ForEach, Fn::Length, Fn::ToJsonString, und Fn::FindInMap mit DefaultValue. Vollständige Referenzinformationen zu diesen Konstrukten finden Sie unter AWS::LanguageExtensions transformieren in der AWS CloudFormation Benutzerleitfaden.
Um Spracherweiterungen in einem zu verwenden AWS SAM Vorlage, Liste AWS::LanguageExtensions in der Transform Abschnitt vor AWS::Serverless-2016-10-31:
Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31
Wann der AWS SAM CLI erkennt AWS::LanguageExtensions in einer Vorlage Transform Abschnitt und Sie haben sich für die lokale Verarbeitung entschieden, sie erweitert die Konstrukte der Spracherweiterungen lokal, bevor sie ausgeführt wird AWS SAM transformiert. Das ermöglicht sam build, sam package, sam deploy, sam sync, sam validate, sam local invoke, sam local start-api, und sam local start-lambda um mit Vorlagen zu arbeiten, die diese Konstrukte verwenden.
Die lokale Verarbeitung ist standardmäßig deaktiviert. Wenn diese Option ausgeschaltet ist, AWS SAM CLI leitet das Template unverändert durch und CloudFormation verarbeitet die AWS::LanguageExtensions transformiert serverseitig zum Zeitpunkt der Bereitstellung. Informationen zu Aktivierungsmethoden finden Sie unter Spracherweiterungen aktivieren.
Die Erweiterung erfolgt in zwei Phasen, wenn sie aktiviert ist:
-
Phase 1 (Spracherweiterungen) —
Fn::ForEachSchleifen werden erweitert, intrinsische Funktionen werden nach Möglichkeit aufgelöst und die Vorlage wird in eine Standardvorlage umgewandelt CloudFormation. -
Phase 2 (AWS SAM Transformieren) — Die erweiterte Vorlage wird von der verarbeitet AWS SAM Übersetzer wie gewohnt.
Die ursprüngliche Vorlage (mit Fn::ForEach intakt) bleibt erhalten für CloudFormation Einsatz, seit CloudFormation verarbeitet die AWS::LanguageExtensions transformiert serverseitig.
Spracherweiterungen aktivieren
Lokale Verarbeitung von AWS::LanguageExtensions ist Opt-In per Befehl. Es gibt drei gleichwertige Aktivierungsmethoden, die in der Reihenfolge ihrer Priorität aufgeführt sind:
-
CLI Fahne — Pass
--language-extensionsbei einem einzigen Aufruf:sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ...--no-language-extensionsdeaktiviert explizit und überschreibt beidesamconfig.tomlund die unten beschriebene Umgebungsvariable. -
samconfig.toml— Behalten Sie 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 = trueA)
samconfig.tomlEin Eintrag wird standardmäßig für den Befehl geladen, sodass er wirksam wird, als ob das Flag übergeben worden wäre — und gewinnt somit über die Umgebungsvariable. -
Umgebungsvariable — gesetzt
SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1um es für die aktuelle Shell zu aktivieren:export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunctionWahrheitsgemäße Werte (ohne Berücksichtigung der Groß- und Kleinschreibung) sind
1,true, undyes. Alles andere, einschließlich der leeren Zeichenfolge, wird als aus behandelt. Die Umgebungsvariable wird nur konsultiert, wenn weder CLI Flagge nochsamconfig.tomllegt einen Wert fest.
Jeder Befehl benötigt eine eigene Aktivierung. Passieren --language-extensions zu sam build wird nicht auf einen späteren übertragen sam local invoke — Die lokale Verarbeitung wird per Befehlsaufruf entschieden. Verwenden Sie die Umgebungsvariable oder 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}
Läuft sam build erweitert das zu UsersFunction, OrdersFunction, und ProductsFunction, die jeweils aus ihrem jeweiligen Quellverzeichnis erstellt wurden.
Dynamische Artefakteigenschaften
Wenn eine paketierbare Eigenschaft eine Schleifenvariable verwendet (z. B. ./services/${Name}), das AWS SAM CLI generiert eine CloudFormation Mappings Abschnitt, der jeden Sammlungswert seinem Amazon S3 zuordnet URI. Das Fn::ForEach Der Körper wurde für den Gebrauch umgeschrieben Fn::FindInMap so CloudFormation kann das richtige Artefakt zum Zeitpunkt der Bereitstellung auflösen.
Die erkannten Artefakteigenschaften sind dieselben sam package schreibt heute um. Das beinhaltet:
| Ressourcentyp | Eigenschaft |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Für gepunktete Eigenschaften (zum Beispiel Command.ScriptLocation auf AWS::Glue::Job oder Code.ImageUri auf AWS::Lambda::Function), wird der Wert an der verschachtelten Stelle auf der Ressource gelesen und geschrieben. Der generierte Mapping-Name verwendet nur das Blattsegment des Eigenschaftspfads.
Wenn es sich bei der Eigenschaft um eine Loop-Vorlage handelt, lautet der Mapping-Name SAM<LeafProperty><LoopName> (zum Beispiel SAMCodeUriServices oder SAMScriptLocationJobs).
Customer-authored Zuordnungen sollten nicht mit diesen beginnen SAM* Präfixe — sie sind reserviert für AWS SAM CLI. Siehe Einschränkungen.
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 einziger Fn::ForEach Ein Körper kann mehr als eine Ressource pro Iteration ausgeben. 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
Name der Abbildung, Kollisionsauflösung
Wenn sich zwei Ressourcen in derselben befinden Fn::ForEach body deklariert dieselbe dynamische Artefakteigenschaft (z. B. beide Api und ein StateMachine benutzen DefinitionUri), das AWS SAM CLI hängt ein Suffix an, das aus dem statischen Teil der Logical-ID-Vorlage der Ressource stammt, um die Mapping-Namen eindeutig zu halten:
| Vorlage für Ressourcen | Eigenschaft | Name der Zuordnung |
|---|---|---|
|
|
|
|
|
|
Wenn es keine Kollision gibt, der Basisname (z. B. SAMDefinitionUriServices) wird verwendet.
Parameter-based Kollektionen
Wann die Fn::ForEach Sammlung ist eine Parameterreferenz (zum Beispiel !Ref ServiceNames) und der Loop-Körper verwendet eine dynamische Artefakteigenschaft (zum Beispiel CodeUri: ./services/${Name}), der AWS SAM CLI benötigt die Sammlungswerte, um die zu generieren SAM* Zuordnungen, beschrieben in Dynamische Artefakteigenschaften. Es löst sie auf, wenn es die Vorlage verarbeitet, und zwar aus:
-
--parameter-overridesübergeben an AWS SAM CLI Befehl. -
Der Parameter ist
DefaultWert in der Vorlage.
Weil der SAM* Mappings werden beim Paketieren eingebrannt. Sie müssen jedes Mal neu packen, wenn Sie den Parameterwert ändern (z. B. wenn Sie einen neuen Dienst hinzufügen), sodass 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 zur Bereitstellungszeit 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 verschachtelten Stack-Vorlagen (AWS::CloudFormation::Stack) wird unterstützt. Das AWS SAM CLI übergibt die des übergeordneten Stapels Parameters Eigenschaft an die Erweiterung der untergeordneten Vorlage, also untergeordnet Fn::ForEach Sammlungen, die auf übergeordnete Parameter verweisen, werden korrekt aufgelöst.
# parent.yaml Resources: ChildStack: Type: AWS::CloudFormation::Stack Properties: TemplateURL: ./child.yaml Parameters: ServiceNames: "Users,Orders,Products"
Verschachtelter Fn:ForEach
Es werden bis zu 5 Verschachtelungsebenen unterstützt, die dem entsprechen CloudFormation Grenze:
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 Ausgängen
Fn::ForEach Blöcke werden auch innerhalb von erweitert Outputs Abschnitt, damit Sie eine Ausgabe pro Sammlungswert ausgeben können:
Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn
Bedingungen und DependsOn
Ressourcen, die emittiert werden von Fn::ForEach kann 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} Die Syntax entfernt nicht-alphanumerische Zeichen aus dem ersetzten Wert, was für die Generierung gültiger logischer IDs aus Werten wie IP-Adressen nützlich ist:
Fn::ForEach::Hosts: - IP - ["10.0.0.1", "10.0.0.2"] - Host&{IP}: Type: AWS::EC2::Instance # Expands to Host10001, Host10002
Unterstützte intrinsische Funktionen
Die folgenden intrinsischen Funktionen werden während der Erweiterung lokal aufgelöst:
| Funktion | Description |
|---|---|
|
Loop-Erweiterung. |
|
Gibt die Anzahl der Listenelemente zurück. |
|
Konvertiert einen Wert in einen JSON Zeichenfolge. |
|
Kartensuche, einschließlich der optionalen |
|
Bedingte Wertauswahl. |
|
Ersetzung von Zeichenketten. |
|
Verkettung von Zeichenketten. |
|
Aufteilen von Zeichenketten. |
|
Auswahl von Listenelementen. |
|
Base64-Kodierung. |
|
Bewertung des Zustands. |
|
Parameter- und Pseudo-Parameter-Referenzen. |
Funktionen, die bereitgestellte Ressourcen benötigen (Fn::GetAtt, Fn::ImportValue, Fn::GetAZs) werden aufbewahrt für CloudFormation zum Zeitpunkt der Bereitstellung zu lösen.
Validierungsfehler
Die folgenden Vorlagenprobleme werden lokal behoben, bevor AWS SAM Die Transformation wird ausgeführt:
| Ursache | Fehlermeldung |
|---|---|
Das |
|
Mehr als 5 Stufen von |
|
Die Sammlung wird in eine leere Liste aufgelöst (z. B. eine |
Kein Fehler — die Schleife wird stillschweigend übersprungen und es werden keine Ressourcen ausgegeben. |
Die |
Kein Fehler — die ungelöste Referenz bleibt in der Vorlage erhalten. Zum Zeitpunkt der Bereitstellung CloudFormation wird es serverseitig lösen. |
Einschränkungen
-
Sammlungen müssen auflösbar sein unter build/package Zeit.
Fn::ForEachSammlungen, die verwendenFn::GetAtt,Fn::ImportValue, oder SSM/Secrets Dynamische Manager-Referenzen können nicht lokal erweitert werden. Verwenden Sie einen Parameter mit--parameter-overridesstattdessen. -
Dynamische Artefaktzuordnungen werden zum Zeitpunkt des Paketes korrigiert. Wenn ein
Fn::ForEachEine Sammlung ist eine Parameterreferenz und der Loop-Körper verwendet eine dynamische Artefakteigenschaft (z. B.CodeUri: ./services/${Name}), das generierteSAM*Mappings enthalten nur Einträge für die Parameterwerte, die zum Zeitpunkt des Paketes aufgelöst wurden. Wenn Sie sich ändern--parameter-overridesWenn Sie diesen Parameter bei der Bereitstellung ohne erneutes Packen verwenden, enthalten die neuen Werte keine Zuordnungseinträge und die Bereitstellung schlägt fehl. Dies gilt nicht für Parameter, die nicht zur Steuerung eines dynamischen Artefakts verwendet werdenFn::ForEach. -
DeletionPolicyundUpdateReplacePolicywerden während der Erweiterung validiert und behoben. Sie unterstützenRefzu Parametern, aber nicht zu anderen intrinsischen Funktionen. -
Begrenzung der Verschachtelung. Bis zu 5 Stufen von
Fn::ForEachkann verschachtelt sein, passend zu CloudFormation serverseitiges Limit. -
Webfunktionen mit lokalem Code.
Fn::ForEachkann kein generierenAWS::Serverless::WebFunctionderenCodeUriist ein lokaler Pfad. Definieren Sie die Web-Funktion draußenFn::ForEach, oder stellen Sie ihre einCodeUrizum Code, der bereits in Amazon S3 enthalten ist. -
Reservierte Zuordnungsnamen. Zuordnungsnamen, die mit einem der folgenden Zeichen beginnen, sind reserviert für AWS SAM CLI — verfassen Sie keine eigenen Mappings mit diesen Präfixen:
-
SAMCodeUri,SAMImageUri,SAMContentUri,SAMDefinitionUri,SAMSchemaUri,SAMBodyS3Location,SAMDefinitionS3Location,SAMTemplateURL,SAMCode,SAMContent— emittiert vonsam packagefür dynamische Artefakteigenschaften. Sehen Sie sich das an Dynamische Artefakteigenschaften Tabelle. -
SAMLayers— emittiert vonsam buildwenn einFn::ForEach-generierte Funktion nimmt automatisch generierte Referenzen auf Abhängigkeitsschichten auf (Lambda-Layers AWS SAM CLI baut in einen verschachtelten Stapel ein). Dieses Präfix hat keine entsprechende, vom Benutzer verfasste Eigenschaft; es wird automatisch hinzugefügt.
-
Telemetrie
Das AWS SAM CLI emittiert ein CFNLanguageExtensions Telemetrieereignis, wenn ein Befehl aufgerufen wird mit --language-extensions (oder das entsprechende Äquivalent zur Umgebungsvariablen) und die Vorlage deklariert die AWS::LanguageExtensions transformieren. 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.