View a markdown version of this page

CloudFormation Unterstützung für Spracherweiterungen - AWS Serverless Application Model

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:

  1. Phase 1 (Spracherweiterungen) — Fn::ForEach Schleifen werden erweitert, intrinsische Funktionen werden nach Möglichkeit aufgelöst und die Vorlage wird in eine Standardvorlage umgewandelt CloudFormation.

  2. 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:

  1. CLI Fahne — Pass --language-extensions bei einem einzigen Aufruf:

    sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ...

    --no-language-extensions deaktiviert explizit und überschreibt beide samconfig.toml und die unten beschriebene Umgebungsvariable.

  2. 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 = true

    A) samconfig.toml Ein 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.

  3. Umgebungsvariable — gesetzt SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 um es für die aktuelle Shell zu aktivieren:

    export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction

    Wahrheitsgemäße Werte (ohne Berücksichtigung der Groß- und Kleinschreibung) sind 1, true, und yes. Alles andere, einschließlich der leeren Zeichenfolge, wird als aus behandelt. Die Umgebungsvariable wird nur konsultiert, wenn weder CLI Flagge noch samconfig.toml legt einen Wert fest.

Wichtig

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:

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

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).

Wichtig

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:

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

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:

  1. --parameter-overrides übergeben an AWS SAM CLI Befehl.

  2. Der Parameter ist Default Wert in der Vorlage.

Wichtig

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}/

&amp;{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:

Intrinsische Funktionen werden bei der Erweiterung der Spracherweiterungen lokal aufgelöst
Funktion Description

Fn::ForEach

Loop-Erweiterung.

Fn::Length

Gibt die Anzahl der Listenelemente zurück.

Fn::ToJsonString

Konvertiert einen Wert in einen JSON Zeichenfolge.

Fn::FindInMap

Kartensuche, einschließlich der optionalen DefaultValue.

Fn::If

Bedingte Wertauswahl.

Fn::Sub

Ersetzung von Zeichenketten.

Fn::Join

Verkettung von Zeichenketten.

Fn::Split

Aufteilen von Zeichenketten.

Fn::Select

Auswahl von Listenelementen.

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 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:

Bei der Erweiterung der Spracherweiterungen sind Validierungsfehler aufgetreten
Ursache Fehlermeldung

Das Fn::ForEach Der Wert ist falsch formatiert — keine Liste, hat nicht genau 3 Elemente oder hat einen Schleifenbezeichner, der keine Zeichenfolge ist.

Fn::ForEach::<key> layout is incorrect (erhöht als InvalidTemplateException).

Mehr als 5 Stufen von Fn::ForEach sind verschachtelt.

Fn::ForEach nesting depth of <N> 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. eine CommaDelimitedList Parameter mit Default: "").

Kein Fehler — die Schleife wird stillschweigend übersprungen und es werden keine Ressourcen ausgegeben.

Die !Ref in der Sammlung auf einen Parameter, der in der Vorlage nicht deklariert ist.

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::ForEach Sammlungen, die verwenden Fn::GetAtt, Fn::ImportValue, oder SSM/Secrets Dynamische Manager-Referenzen können nicht lokal erweitert werden. Verwenden Sie einen Parameter mit --parameter-overrides stattdessen.

  • Dynamische Artefaktzuordnungen werden zum Zeitpunkt des Paketes korrigiert. Wenn ein Fn::ForEach Eine Sammlung ist eine Parameterreferenz und der Loop-Körper verwendet eine dynamische Artefakteigenschaft (z. B. CodeUri: ./services/${Name}), das generierte SAM* Mappings enthalten nur Einträge für die Parameterwerte, die zum Zeitpunkt des Paketes aufgelöst wurden. Wenn Sie sich ändern --parameter-overrides Wenn 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 werden Fn::ForEach.

  • DeletionPolicy und UpdateReplacePolicy werden während der Erweiterung validiert und behoben. Sie unterstützen Ref zu Parametern, aber nicht zu anderen intrinsischen Funktionen.

  • Begrenzung der Verschachtelung. Bis zu 5 Stufen von Fn::ForEach kann verschachtelt sein, passend zu CloudFormation serverseitiges Limit.

  • Webfunktionen mit lokalem Code. Fn::ForEach kann kein generieren AWS::Serverless::WebFunction deren CodeUri ist ein lokaler Pfad. Definieren Sie die Web-Funktion draußen Fn::ForEach, oder stellen Sie ihre ein CodeUri zum 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 von sam package für dynamische Artefakteigenschaften. Sehen Sie sich das an Dynamische Artefakteigenschaften Tabelle.

    • SAMLayers — emittiert von sam build wenn ein Fn::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.