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::ForEachFn::Length,Fn::ToJsonString, e Fn::FindInMap comDefaultValue. Para obter informações de referência completas sobre essas construções, consulte AWS::LanguageExtensions transform 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 anteriorAWS::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 buildsam 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, consulteAtivando extensões de idioma.

A expansão acontece em duas fases quando ativada:

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:

Fã:: ForEach

Fn::ForEachgera 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 paraUsersFunction,, e OrdersFunctionProductsFunction, 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:

Para propriedades pontilhadas (por exemplo, Command.ScriptLocation on AWS::Glue::Job ou Code.ImageUri onAWS::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<LeafProperty><LoopName> (por exemplo, ou). SAMCodeUriServices SAMScriptLocationJobs

Por exemplo, depois desam 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 usoDefinitionUri), 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:

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 Ele os resolve quando processa o modelo, a partir de:

# 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::ForEachem 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::ForEachos 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:

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:

Limitações

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.