Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # CloudFormation supporto per le estensioni linguistiche AWS SAMCLISupporta modelli che utilizzano la `AWS::LanguageExtensions` trasformazione, tra cui `Fn::ForEach``Fn::Length`,`Fn::ToJsonString`, e `Fn::FindInMap` with`DefaultValue`. Per informazioni di riferimento complete su questi costrutti, vedete [AWS::LanguageExtensions transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) nella *Guida per l'AWS CloudFormation utente*. Per utilizzare le estensioni linguistiche in un AWS SAM modello, elenca `AWS::LanguageExtensions` nella `Transform` sezione *precedente*`AWS::Serverless-2016-10-31`: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 ``` Quando i AWS SAMCLI rilevamenti vengono rilevati `AWS::LanguageExtensions` nella `Transform` sezione di un modello *e* avete optato per l'elaborazione locale, espande localmente i costrutti delle estensioni linguistiche prima di eseguire le trasformazioni. AWS SAM Ciò consente`sam build`,,`sam package`,,`sam deploy`, `sam sync` `sam validate` `sam local invoke``sam local start-api`, e di lavorare con modelli `sam local start-lambda` che utilizzano questi costrutti. L'elaborazione locale è disattivata per impostazione predefinita. Quando è disattivata, AWS SAMCLI passa il modello invariato ed CloudFormation elabora la `AWS::LanguageExtensions` trasformazione sul lato server al momento della distribuzione. Per i metodi di attivazione, vedere. [Abilitazione delle estensioni linguistiche](#sam-specification-language-extensions-enabling) L'espansione avviene in due fasi quando abilitata: 1. **Fase 1 (estensioni del linguaggio)**: i `Fn::ForEach` loop vengono espansi, le funzioni intrinseche vengono risolte ove possibile e il modello viene convertito in standard. CloudFormation 1. **Fase 2 (AWS SAM Trasformazione)**: il modello espanso viene elaborato dal AWS SAM Translator come di consueto. Il modello originale (rimasto `Fn::ForEach` intatto) viene preservato per la CloudFormation distribuzione, poiché CloudFormation elabora la `AWS::LanguageExtensions` trasformazione lato server. ## Abilitazione delle estensioni linguistiche L'elaborazione locale di `AWS::LanguageExtensions` è facoltativa per comando. Esistono tre metodi di attivazione equivalenti, elencati in ordine di priorità: 1. **CLIflag** — trasmette `--language-extensions` una singola invocazione: ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions`disabilita esplicitamente, sovrascrivendo sia la variabile di ambiente descritta `samconfig.toml` di seguito. 1. **`samconfig.toml`**— persiste la scelta per progetto: ``` [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 ``` Una `samconfig.toml` voce viene caricata di default per il comando, quindi ha effetto come se il flag fosse stato passato e quindi prevale sulla variabile di ambiente. 1. **Variabile d'ambiente**: impostata `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` per essere abilitata per la shell corrente: ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` I valori veritieri (senza distinzione tra maiuscole e minuscole) sono`1`, e. `true` `yes` Qualsiasi altra cosa, inclusa la stringa vuota, viene considerata disattivata. La variabile di ambiente viene consultata solo quando né il CLI flag né `samconfig.toml` imposta un valore. **Importante** Ogni comando necessita di una propria attivazione. Il passaggio `--language-extensions` a `sam build` non si propaga a un comando successivo`sam local invoke`: l'elaborazione locale viene decisa in base alla chiamata del comando. Utilizzate la variabile di ambiente o una `samconfig.toml` voce per abilitare più comandi senza ripetere il flag. ## Fn:: ForEach `Fn::ForEach`genera più risorse, condizioni o output da un'unica definizione di modello: ``` 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} ``` Running lo `sam build` espande in `UsersFunction``OrdersFunction`, e`ProductsFunction`, ciascuno creato dalla rispettiva directory di origine. ### Proprietà dinamiche degli artefatti Quando una proprietà impacchettabile utilizza una variabile di ciclo (ad esempio`./services/${Name}`), AWS SAMCLI genera una CloudFormation `Mappings` sezione che mappa ogni valore della raccolta sul relativo Amazon S3. URI Il `Fn::ForEach` corpo viene riscritto per essere utilizzato in `Fn::FindInMap` modo da CloudFormation poter risolvere l'artefatto corretto al momento della distribuzione. Le proprietà degli artefatti riconosciute sono le stesse riscritte oggi. `sam package` Ciò include: **Proprietà dinamiche degli artefatti riconosciute da AWS SAM CLI** | Tipo di risorsa | Proprietà | | --- | --- | | `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` | Per le proprietà punteggiate (ad esempio, `Command.ScriptLocation` attivate `AWS::Glue::Job` o `Code.ImageUri` attivate`AWS::Lambda::Function`), il valore viene letto e scritto nella posizione annidata sulla risorsa. Il nome di mappatura generato utilizza solo il segmento fogliare del percorso della proprietà. Quando la proprietà è basata su un modello di loop, il nome della mappatura è `SAM` (ad esempio, o). `SAMCodeUriServices` `SAMScriptLocationJobs` **Importante** Customer-authored le mappature non devono iniziare con questi prefissi, in quanto sono `SAM*` riservate a. AWS SAMCLI Per informazioni, consulta [Limitazioni](#sam-specification-language-extensions-limitations). Ad esempio, dopo: `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] ``` ### Risorse multiple per ForEach corpo Un singolo `Fn::ForEach` corpo può emettere più di una risorsa per iterazione. Ogni risorsa viene generata per ogni valore di raccolta: ``` 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 ``` ### Risoluzione delle collisioni tra nomi di mappatura Quando due risorse nello stesso `Fn::ForEach` corpo dichiarano la stessa proprietà dinamica dell'artefatto (ad esempio, sia an `Api` che `StateMachine` use`DefinitionUri`), AWS SAMCLI aggiunge un suffisso tratto dalla parte statica del modello Logical-ID della risorsa per mantenere unici i nomi di mappatura: **Esempio di mappatura di nomi con suffissi di collisione** | Modello di risorse | Proprietà | Nome della mappatura | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | In assenza di collisione, viene utilizzato il nome di base (ad esempio,`SAMDefinitionUriServices`). ### Parameter-based collezioni Quando la `Fn::ForEach` raccolta è un riferimento a un parametro (ad esempio`!Ref ServiceNames`) e il corpo del ciclo utilizza una proprietà di artefatto dinamica (ad esempio,`CodeUri: ./services/${Name}`), AWS SAMCLI ha bisogno dei valori della raccolta per generare le `SAM*` mappature descritte in. [Proprietà dinamiche degli artefatti](#sam-specification-language-extensions-dynamic-artifacts) Li risolve quando elabora il modello, da: 1. `--parameter-overrides`passato al comando. AWS SAMCLI 1. Il `Default` valore del parametro nel modello. **Importante** Poiché i `SAM*` mapping vengono inseriti al momento del pacchetto, è necessario reimballarli ogni volta che si modifica il valore del parametro (ad esempio, quando si aggiunge un nuovo servizio) in modo che i mapping includano le voci per i nuovi valori. Ciò si applica solo quando il parametro guida un ciclo dinamico di artefatti; le altre sostituzioni dei parametri possono essere modificate al momento della distribuzione, come di consueto. ``` # 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" ``` ### Stack nidificati `Fn::ForEach`nei modelli di stack annidati () è supportato. `AWS::CloudFormation::Stack` AWS SAMCLIPassa la `Parameters` proprietà dello stack principale all'espansione del modello secondario, in modo che le `Fn::ForEach` raccolte secondarie che fanno riferimento ai parametri forniti dal padre vengano risolte correttamente. ``` # parent.yaml Resources: ChildStack: Type: AWS::CloudFormation::Stack Properties: TemplateURL: ./child.yaml Parameters: ServiceNames: "Users,Orders,Products" ``` ### Fn annidato: ForEach Sono supportati fino a 5 livelli di nidificazione, corrispondenti al limite: 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 in Uscite `Fn::ForEach`i blocchi vengono inoltre espansi all'interno della `Outputs` sezione, quindi puoi emettere un output per valore di raccolta: ``` Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn ``` ### Condizioni e DependsOn Le risorse emesse da `Fn::ForEach` possono trasportare `Condition` e sono `DependsOn` simili a qualsiasi altra risorsa. La condizione o dipendenza viene replicata su ogni risorsa generata: ``` 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}/ ``` ### &sintassi {identifier} La `&{identifier}` sintassi elimina i caratteri non alfanumerici dal valore sostituito, utile per generare ID logici validi a partire da valori come gli indirizzi IP: ``` Fn::ForEach::Hosts: - IP - ["10.0.0.1", "10.0.0.2"] - Host&{IP}: Type: AWS::EC2::Instance # Expands to Host10001, Host10002 ``` ## Funzioni intrinseche supportate Le seguenti funzioni intrinseche vengono risolte localmente durante l'espansione: **Funzioni intrinseche risolte localmente durante l'espansione delle estensioni linguistiche** | Funzione | Description | | --- | --- | | `Fn::ForEach` | Espansione del ciclo. | | `Fn::Length` | Restituisce il conteggio degli elementi della lista. | | `Fn::ToJsonString` | Converte un valore in una JSON stringa. | | `Fn::FindInMap` | Ricerca sulla mappa, inclusa quella opzionale. `DefaultValue` | | `Fn::If` | Selezione condizionale del valore. | | `Fn::Sub` | Sostituzione di stringhe. | | `Fn::Join` | Concatenazione di stringhe. | | `Fn::Split` | Divisione di stringhe. | | `Fn::Select` | Selezione degli elementi dell'elenco. | | `Fn::Base64` | Codifica Base64. | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | Valutazione delle condizioni. | | `Ref` | Riferimenti a parametri e pseudoparametri. | Le funzioni che richiedono risorse distribuite (`Fn::GetAtt`,`Fn::ImportValue`,`Fn::GetAZs`) vengono conservate per essere risolte CloudFormation al momento della distribuzione. ## Errori di convalida I seguenti problemi relativi ai modelli vengono rilevati localmente prima dell'esecuzione della AWS SAM trasformazione: **Errori di convalida generati durante l'espansione delle estensioni del linguaggio** | Causa | Messaggio di errore | | --- | --- | | Il `Fn::ForEach` valore non è valido: non è un elenco, non ha esattamente 3 elementi o ha un identificatore di loop diverso da una stringa. | `Fn::ForEach:: layout is incorrect`(sollevato come). `InvalidTemplateException` | | `Fn::ForEach`Sono annidati più di 5 livelli. | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | La raccolta si risolve in un elenco vuoto (ad esempio, un `CommaDelimitedList` parametro con). `Default: ""` | Nessun errore: il ciclo viene saltato silenziosamente e non viene emessa alcuna risorsa. | | `!Ref`Nella raccolta punta a un parametro che non è dichiarato nel modello. | Nessun errore: il riferimento non risolto viene mantenuto nel modello. Al momento della distribuzione, lo CloudFormation risolverà sul lato server. | ## Limitazioni + **Le raccolte devono essere risolvibili in qualsiasi momento. build/package ** `Fn::ForEach`le raccolte che utilizzano `Fn::GetAtt` riferimenti dinamici o SSM/Secrets Manager non possono essere espanse localmente. `Fn::ImportValue` Utilizzate `--parameter-overrides` invece un parametro con. + **Le mappature dinamiche degli artefatti vengono corrette al momento del pacchetto.** Quando una `Fn::ForEach` raccolta è un riferimento a un parametro e il corpo del ciclo utilizza una proprietà di artefatto dinamica (ad esempio,`CodeUri: ./services/${Name}`), i `SAM*` mapping generati contengono solo voci per i valori dei parametri che sono stati risolti al momento del pacchetto. Se si modifica `--parameter-overrides` tale parametro al momento della distribuzione senza riconfezionare i nuovi valori, non verranno inserite le voci Mapping e la distribuzione avrà esito negativo. Questo non si applica ai parametri che non vengono utilizzati per guidare un artefatto dinamico. `Fn::ForEach` + **`DeletionPolicy`e `UpdateReplacePolicy`** vengono convalidati e risolti durante l'espansione. Supportano solo `Ref` i parametri ma non altre funzioni intrinseche. + **Limite di nidificazione.** È `Fn::ForEach` possibile annidare fino a 5 livelli, corrispondenti al limite sul CloudFormation lato server. + **Nomi di mappatura riservati.** I nomi di mappatura che iniziano con uno dei seguenti prefissi sono riservati a AWS SAMCLI: non creare mappature personalizzate con questi prefissi: + `SAMCodeUri`,,`SAMImageUri`,,`SAMContentUri`,,`SAMDefinitionUri`,, `SAMSchemaUri` `SAMBodyS3Location` `SAMDefinitionS3Location``SAMTemplateURL`, `SAMContent` — emesso da per le `SAMCode` proprietà dinamiche degli artefatti. `sam package` Vedi la tabella. [Proprietà dinamiche degli artefatti](#sam-specification-language-extensions-dynamic-artifacts) + `SAMLayers`— emesso da `sam build` quando una funzione `Fn::ForEach` generata raccoglie riferimenti al livello di dipendenza generati automaticamente (livelli Lambda che si accumulano in uno stack annidato). AWS SAMCLI Questo prefisso non ha alcuna proprietà creata dall'utente corrispondente; viene aggiunto automaticamente. ## Telemetria AWS SAMCLI*Emette un evento di `CFNLanguageExtensions` telemetria quando viene richiamato un comando con `--language-extensions` (o il suo equivalente in una variabile di ambiente) e il modello dichiara la trasformazione.* `AWS::LanguageExtensions` L'evento si attiva una volta per chiamata e non viene trasmesso alcun contenuto del modello. Quando l'elaborazione locale è disattivata (impostazione predefinita), non viene generato alcun evento.