Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

CloudFormation prise en charge des extensions linguistiques

Les modèles de AWS SAMCLI support qui utilisent la AWS::LanguageExtensions transformation, y compris Fn::ForEachFn::Length,Fn::ToJsonString, et Fn::FindInMap avecDefaultValue. Pour obtenir des informations de référence complètes sur ces constructions, voir AWS::LanguageExtensions transformation dans le guide de l'AWS CloudFormation utilisateur.

Pour utiliser des extensions de langue dans un AWS SAM modèle, AWS::LanguageExtensions listez-les dans la Transform section précédente AWS::Serverless-2016-10-31 :

Transform:
  - AWS::LanguageExtensions
  - AWS::Serverless-2016-10-31

Lorsque la Transform section d'un modèle est AWS SAMCLI détectée AWS::LanguageExtensions et que vous avez opté pour le traitement local, les structures d'extension de langue s'étendent localement avant d'exécuter les AWS SAM transformations. Cela permet à sam buildsam package,sam deploy,sam sync,sam validate,sam local invoke,sam local start-api, et sam local start-lambda de travailler avec des modèles qui utilisent ces constructions.

Le traitement local est désactivé par défaut. Lorsque cette option est désactivée AWS SAMCLI, le modèle est transmis tel quel et CloudFormation traite la AWS::LanguageExtensions transformation côté serveur au moment du déploiement. Pour les méthodes d'activation, voirActivation des extensions de langue.

L'extension s'effectue en deux phases lorsqu'elle est activée :

Le modèle d'origine (Fn::ForEachintact) est conservé pour CloudFormation le déploiement, car il CloudFormation traite la AWS::LanguageExtensions transformation côté serveur.

Activation des extensions de langue

Le traitement local de AWS::LanguageExtensions est activé par commande. Il existe trois méthodes d'activation équivalentes, répertoriées par ordre de priorité :

Ventilateur : ForEach

Fn::ForEachgénère plusieurs ressources, conditions ou sorties à partir d'une seule définition de modèle :

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'exécution sam build étend cela àUsersFunction,OrdersFunction, etProductsFunction, chacun construit à partir de son répertoire source respectif.

Propriétés dynamiques des artefacts

Lorsqu'une propriété packageable utilise une variable de boucle (par exemple,./services/${Name}), elle AWS SAMCLI génère une CloudFormation Mappings section qui fait correspondre la valeur de chaque collection à son Amazon S3. URI Le Fn::ForEach corps est réécrit pour être utilisé Fn::FindInMap afin de CloudFormation pouvoir résoudre le bon artefact au moment du déploiement.

Les propriétés reconnues des artefacts sont les mêmes que celles qui sont sam package réécrites aujourd'hui. Cela inclut :

Pour les propriétés en pointillés (par exemple, Command.ScriptLocation on AWS::Glue::Job ou Code.ImageUri onAWS::Lambda::Function), la valeur est lue et écrite à l'emplacement imbriqué sur la ressource. Le nom de mappage généré utilise uniquement le segment de feuille du chemin de propriété.

Lorsque la propriété est modélisée en boucle, le nom du mappage est SAM<LeafProperty><LoopName> (par exemple, SAMCodeUriServices ou). SAMScriptLocationJobs

Par exemple, après 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]

Plusieurs ressources par ForEach organisme

Un seul Fn::ForEach corps peut émettre plusieurs ressources par itération. Chaque ressource est générée pour chaque valeur de collection :

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

Résolution des collisions entre noms de mappage

Lorsque deux ressources du même Fn::ForEach corps déclarent la même propriété d'artefact dynamique (par exemple, un Api et un StateMachine usageDefinitionUri), un suffixe extrait de la partie statique du modèle Logical-ID de ressource est AWS SAMCLI ajouté pour que les noms de mappage restent uniques :

En l'absence de collision, le nom de base (par exemple,SAMDefinitionUriServices) est utilisé.

Parameter-based collections

Lorsque la Fn::ForEach collection est une référence de paramètre (par exemple,!Ref ServiceNames) et que le corps de la boucle utilise une propriété d'artefact dynamique (par exemple,CodeUri: ./services/${Name}), elle AWS SAMCLI a besoin des valeurs de collection pour générer les SAM* mappages décrits dans. Propriétés dynamiques des artefacts Il les résout lorsqu'il traite le modèle, à 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"

Piles imbriquées

Fn::ForEachdans les modèles de pile imbriqués (AWS::CloudFormation::Stack) est pris en charge. Transmet AWS SAMCLI la Parameters propriété de la pile parent à l'extension du modèle enfant, de sorte que les Fn::ForEach collections enfants qui font référence à des paramètres fournis par le parent soient résolues correctement.

# parent.yaml
Resources:
  ChildStack:
    Type: AWS::CloudFormation::Stack
    Properties:
      TemplateURL: ./child.yaml
      Parameters:
        ServiceNames: "Users,Orders,Products"

Ventilateur imbriqué : ForEach

Jusqu'à 5 niveaux d'imbrication sont pris en charge, conformément à la 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 dans Sorties

Fn::ForEachles blocs sont également développés à l'intérieur de la Outputs section, de sorte que vous pouvez émettre une sortie par valeur de collection :

Outputs:
  Fn::ForEach::FunctionArns:
    - Name
    - [alpha, beta]
    - ${Name}FunctionArn:
        Value: !GetAtt
          - !Sub "${Name}Function"
          - Arn

Conditions et DependsOn

Les ressources émises par Fn::ForEach can carry Condition and DependsOn like n'importe quelle autre ressource. La condition ou la dépendance est répliquée sur chaque ressource générée :

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

&syntaxe {identifier}

La &{identifier} syntaxe supprime les caractères non alphanumériques de la valeur substituée, ce qui est utile pour générer des identifiants logiques valides à partir de valeurs telles que les adresses IP :

Fn::ForEach::Hosts:
  - IP
  - ["10.0.0.1", "10.0.0.2"]
  - Host&{IP}:
      Type: AWS::EC2::Instance
      # Expands to Host10001, Host10002

Fonctions intrinsèques prises en charge

Les fonctions intrinsèques suivantes sont résolues localement lors de l'expansion :

Les fonctions qui nécessitent des ressources déployées (Fn::GetAttFn::ImportValue,,Fn::GetAZs) sont conservées CloudFormation pour être résolues au moment du déploiement.

Erreurs de validation

Les problèmes de modèle suivants sont détectés localement avant l'exécution de la AWS SAM transformation :

Limitations

Télémétrie

Le AWS SAMCLI émet un événement de CFNLanguageExtensions télémétrie lorsqu'une commande est invoquée avec --language-extensions (ou son équivalent en variable d'environnement) et que le modèle déclare la transformation. AWS::LanguageExtensions L'événement se déclenche une fois par invocation et aucun contenu du modèle n'est transmis. Lorsque le traitement local est désactivé (par défaut), aucun événement ne se déclenche.