As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # CloudFormation suporte a extensões de linguagem O AWS SAMCLI suporta modelos que usam a `AWS::LanguageExtensions` transformação, incluindo `Fn::ForEach``Fn::Length`,`Fn::ToJsonString`, e `Fn::FindInMap` com`DefaultValue`. Para obter informações de referência completas sobre essas construções, consulte [AWS::LanguageExtensions transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) no *Guia do AWS CloudFormation usuário*. Para usar extensões de linguagem em um AWS SAM modelo, liste `AWS::LanguageExtensions` na `Transform` seção *anterior*`AWS::Serverless-2016-10-31`: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 ``` Quando é AWS SAMCLI detectado `AWS::LanguageExtensions` na `Transform` seção de um modelo *e* você opta pelo processamento local, ele expande as construções de extensão de linguagem localmente antes de executar as transformações. AWS SAM Isso permite que `sam build``sam package`,`sam deploy`,`sam sync`,`sam validate`,`sam local invoke`,`sam local start-api`, e `sam local start-lambda` trabalhe com modelos que usam essas construções. O processamento local está desativado por padrão. Quando desativado, AWS SAMCLI ele passa o modelo inalterado e CloudFormation processa a `AWS::LanguageExtensions` transformação no lado do servidor no momento da implantação. Para métodos de ativação, consulte[Ativando extensões de idioma](#sam-specification-language-extensions-enabling). A expansão acontece em duas fases quando ativada: 1. **Fase 1 (extensões de linguagem)** — os `Fn::ForEach` loops são expandidos, as funções intrínsecas são resolvidas sempre que possível e o modelo é convertido em padrão. CloudFormation 1. **Fase 2 (AWS SAM Transformação)** — O modelo expandido é processado pelo AWS SAM Tradutor como de costume. O modelo original (com o modelo `Fn::ForEach` intacto) é preservado para CloudFormation implantação, pois CloudFormation processa a `AWS::LanguageExtensions` transformação no lado do servidor. ## Ativando extensões de idioma O processamento local do `AWS::LanguageExtensions` é opcional por comando. Há três métodos de ativação equivalentes, listados em ordem de prioridade: 1. **CLIbandeira** — `--language-extensions` transmita uma única invocação: ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions`desativa explicitamente, substituindo ambas `samconfig.toml` e a variável de ambiente descrita abaixo. 1. **`samconfig.toml`**— persistir na escolha por projeto: ``` [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 ``` Uma `samconfig.toml` entrada é carregada como padrão para o comando, então ela entra em vigor como se o sinalizador tivesse sido passado — e, portanto, supera a variável de ambiente. 1. **Variável de ambiente** — definida como `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` habilitada para o shell atual: ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` Valores verdadeiros (sem distinção entre maiúsculas e minúsculas) são`1`, e. `true` `yes` Qualquer outra coisa, incluindo a string vazia, é tratada como desativada. A variável de ambiente é consultada somente quando nem o CLI sinalizador nem `samconfig.toml` define um valor. **Importante** Cada comando precisa de sua própria ativação. Passar `--language-extensions` para `sam build` não se propaga para um posterior `sam local invoke` — o processamento local é decidido por invocação de comando. Use a variável de ambiente ou uma `samconfig.toml` entrada para habilitar vários comandos sem repetir o sinalizador. ## Fã:: ForEach `Fn::ForEach`gera vários recursos, condições ou saídas a partir de uma única definição de modelo: ``` 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} ``` A execução `sam build` expande isso para`UsersFunction`,, e `OrdersFunction``ProductsFunction`, cada um criado a partir de seu respectivo diretório de origem. ### Propriedades dinâmicas do artefato Quando uma propriedade empacotável usa uma variável de loop (por exemplo,`./services/${Name}`), ela AWS SAMCLI gera uma CloudFormation `Mappings` seção que mapeia cada valor de coleção para seu Amazon S3. URI O `Fn::ForEach` corpo é reescrito para ser usado para `Fn::FindInMap` que CloudFormation possa resolver o artefato correto no momento da implantação. As propriedades reconhecidas do artefato são as mesmas que são `sam package` reescritas atualmente. Isso inclui: **Propriedades dinâmicas de artefatos reconhecidas pelo AWS SAM CLI** | Tipo de atributo | Propriedade | | --- | --- | | `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` | Para propriedades pontilhadas (por exemplo, `Command.ScriptLocation` on `AWS::Glue::Job` ou `Code.ImageUri` on`AWS::Lambda::Function`), o valor é lido e gravado no local aninhado no recurso. O nome de mapeamento gerado usa somente o segmento de folha do caminho da propriedade. Quando a propriedade é modelada em loop, o nome do mapeamento é `SAM` (por exemplo, ou). `SAMCodeUriServices` `SAMScriptLocationJobs` **Importante** Customer-authored os mapeamentos não devem começar com esses `SAM*` prefixos — eles são reservados para o. AWS SAMCLI Consulte [Limitações](#sam-specification-language-extensions-limitations). Por exemplo, depois de`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] ``` ### Vários recursos por ForEach corpo Um único `Fn::ForEach` corpo pode emitir mais de um recurso por iteração. Cada recurso é gerado para cada valor da coleção: ``` 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 ``` ### Resolução de colisão de nomes de mapeamento Quando dois recursos no mesmo `Fn::ForEach` corpo declaram a mesma propriedade de artefato dinâmico (por exemplo, um `Api` e um `StateMachine` uso`DefinitionUri`), eles AWS SAMCLI acrescentam um sufixo retirado da parte estática do modelo de ID lógica do recurso para manter os nomes de mapeamento exclusivos: **Exemplo de mapeamento de nomes com sufixos de colisão** | Modelo de recurso | Propriedade | Nome do mapeamento | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | Quando não há colisão, o nome base (por exemplo,`SAMDefinitionUriServices`) é usado. ### Parameter-based coleções Quando a `Fn::ForEach` coleção é uma referência de parâmetro (por exemplo,`!Ref ServiceNames`) e o corpo do loop usa uma propriedade de artefato dinâmico (por exemplo,`CodeUri: ./services/${Name}`), ele AWS SAMCLI precisa dos valores da coleção para gerar os `SAM*` mapeamentos descritos em. [Propriedades dinâmicas do artefato](#sam-specification-language-extensions-dynamic-artifacts) Ele os resolve quando processa o modelo, a partir de: 1. `--parameter-overrides`passado para o AWS SAMCLI comando. 1. O `Default` valor do parâmetro no modelo. **Importante** Como os `SAM*` mapeamentos são incorporados no momento do pacote, você deve reempacotar sempre que alterar o valor do parâmetro (por exemplo, ao adicionar um novo serviço) para que os mapeamentos incluam entradas para os novos valores. Isso se aplica somente quando o parâmetro aciona um loop dinâmico de artefatos; outras substituições de parâmetros podem ser alteradas no momento da implantação, como de costume. ``` # 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" ``` ### Pilhas aninhadas `Fn::ForEach`em modelos de pilha aninhados (`AWS::CloudFormation::Stack`) é suportado. O AWS SAMCLI passa a `Parameters` propriedade da pilha principal para a expansão do modelo filho, para que as `Fn::ForEach` coleções secundárias que fazem referência aos parâmetros fornecidos pelos pais sejam resolvidas corretamente. ``` # parent.yaml Resources: ChildStack: Type: AWS::CloudFormation::Stack Properties: TemplateURL: ./child.yaml Parameters: ServiceNames: "Users,Orders,Products" ``` ### Ventilador aninhado:: ForEach Até 5 níveis de aninhamento são suportados, correspondendo ao CloudFormation limite: ``` 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 em saídas `Fn::ForEach`os blocos também são expandidos dentro da `Outputs` seção, para que você possa emitir uma saída por valor de coleção: ``` Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn ``` ### Condições e DependsOn Os recursos emitidos por `Fn::ForEach` can carry `Condition` and `DependsOn` like any other resource. A condição ou dependência é replicada em cada recurso gerado: ``` 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}/ ``` ### &sintaxe {identifier} A `&{identifier}` sintaxe retira caracteres não alfanuméricos do valor substituído, o que é útil para gerar IDs lógicos válidos a partir de valores como endereços IP: ``` Fn::ForEach::Hosts: - IP - ["10.0.0.1", "10.0.0.2"] - Host&{IP}: Type: AWS::EC2::Instance # Expands to Host10001, Host10002 ``` ## Funções intrínsecas suportadas As seguintes funções intrínsecas são resolvidas localmente durante a expansão: **Funções intrínsecas resolvidas localmente durante a expansão das extensões de linguagem** | Função | Description | | --- | --- | | `Fn::ForEach` | Expansão em loop. | | `Fn::Length` | Retorna a contagem dos elementos da lista. | | `Fn::ToJsonString` | Converte um valor em uma JSON string. | | `Fn::FindInMap` | Pesquisa de mapa, incluindo o opcional`DefaultValue`. | | `Fn::If` | Seleção de valor condicional. | | `Fn::Sub` | Substituição de strings. | | `Fn::Join` | Concatenação de strings. | | `Fn::Split` | Divisão de cordas. | | `Fn::Select` | Seleção de elementos da lista. | | `Fn::Base64` | Codificação Base64. | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | Avaliação da condição. | | `Ref` | Referências de parâmetros e pseudoparâmetros. | As funções que exigem recursos implantados (`Fn::GetAtt`,`Fn::ImportValue`,`Fn::GetAZs`) são preservadas CloudFormation para serem resolvidas no momento da implantação. ## Erros de validação Os seguintes problemas de modelo são detectados localmente antes da execução da AWS SAM transformação: **Erros de validação gerados durante a expansão das extensões de linguagem** | Causa | Mensagem de erro | | --- | --- | | O `Fn::ForEach` valor está malformado — não é uma lista, não tem exatamente 3 elementos ou tem um identificador de loop que não seja de string. | `Fn::ForEach:: layout is incorrect`(criado como`InvalidTemplateException`). | | Mais de 5 níveis de `Fn::ForEach` estão aninhados. | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | A coleção é resolvida em uma lista vazia (por exemplo, um `CommaDelimitedList` parâmetro com`Default: ""`). | Sem erro — o loop é ignorado silenciosamente e nenhum recurso é emitido. | | O `!Ref` nos pontos de coleta em um parâmetro que não está declarado no modelo. | Sem erro — a referência não resolvida é preservada no modelo. No momento da implantação, CloudFormation resolverá o problema no lado do servidor. | ## Limitações + **As coleções devem ser resolvidas a qualquer momento build/package .** `Fn::ForEach`coleções que usam `Fn::GetAtt``Fn::ImportValue`, ou SSM/Secrets Gerenciam referências dinâmicas não podem ser expandidas localmente. `--parameter-overrides`Em vez disso, use um parâmetro com. + **Os mapeamentos dinâmicos de artefatos são corrigidos no momento do pacote.** Quando uma `Fn::ForEach` coleção é uma referência de parâmetro e o corpo do loop usa uma propriedade de artefato dinâmico (por exemplo,`CodeUri: ./services/${Name}`), os `SAM*` mapeamentos gerados contêm somente entradas para os valores dos parâmetros que foram resolvidos no momento do pacote. Se você alterar `--parameter-overrides` esse parâmetro no momento da implantação sem reempacotar, os novos valores não terão entradas de mapeamento e a implantação falhará. Isso não se aplica aos parâmetros que não são usados para acionar um artefato `Fn::ForEach` dinâmico. + **`DeletionPolicy`e `UpdateReplacePolicy`** são validados e resolvidos durante a expansão. Eles oferecem suporte `Ref` a parâmetros, mas não a outras funções intrínsecas. + **Limite de nidificação.** Até 5 níveis de `Fn::ForEach` podem ser aninhados, correspondendo ao limite do lado do CloudFormation servidor. + **Nomes de mapeamento reservados.** Os nomes de mapeamento que começam com qualquer um dos seguintes são reservados para AWS SAMCLI — não crie seus próprios mapeamentos com esses prefixos: + `SAMCodeUri`,`SAMImageUri`,`SAMContentUri`,,`SAMDefinitionUri`,`SAMSchemaUri`,`SAMBodyS3Location`, `SAMDefinitionS3Location` `SAMTemplateURL``SAMCode`, `SAMContent` — emitido por `sam package` para propriedades dinâmicas do artefato. Veja a [Propriedades dinâmicas do artefato](#sam-specification-language-extensions-dynamic-artifacts) tabela. + `SAMLayers`— emitido `sam build` quando uma função `Fn::ForEach` gerada pega referências de camada de dependência geradas automaticamente (o Lambda coloca as compilações em uma pilha aninhada). AWS SAMCLI Esse prefixo não tem nenhuma propriedade correspondente de autoria do usuário; ele é adicionado automaticamente. ## Telemetria *O AWS SAMCLI emite um evento de `CFNLanguageExtensions` telemetria quando um comando é invocado com `--language-extensions` (ou seu equivalente em variável de ambiente) e o modelo declara a transformação.* `AWS::LanguageExtensions` O evento é acionado uma vez por invocação e nenhum conteúdo do modelo é transmitido. Quando o processamento local está desativado (o padrão), nenhum evento é acionado.