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::ForEach``Fn::Length`,`Fn::ToJsonString`, et `Fn::FindInMap` avec`DefaultValue`. Pour obtenir des informations de référence complètes sur ces constructions, voir [AWS::LanguageExtensions transformation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) 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 build``sam 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, voir[Activation des extensions de langue](#sam-specification-language-extensions-enabling). L'extension s'effectue en deux phases lorsqu'elle est activée : 1. **Phase 1 (extensions de langage)** : les `Fn::ForEach` boucles sont étendues, les fonctions intrinsèques sont résolues dans la mesure du possible et le modèle est converti en standard CloudFormation. 1. **Phase 2 (AWS SAM transformation)** — Le modèle développé est traité par le AWS SAM traducteur comme d'habitude. Le modèle d'origine (`Fn::ForEach`intact) 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é : 1. **CLIdrapeau** — `--language-extensions` transmettre une seule invocation : ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions`désactive explicitement, en remplaçant les deux variables `samconfig.toml` ainsi que la variable d'environnement décrite ci-dessous. 1. **`samconfig.toml`**— conserver le choix par projet : ``` [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 ``` Une `samconfig.toml` entrée est chargée par défaut pour la commande. Elle prend donc effet comme si l'indicateur était passé, et l'emporte donc sur la variable d'environnement. 1. **Variable d'environnement** — définie `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` pour être activée pour le shell actuel : ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` Les valeurs véridiques (sans distinction majuscules/majuscules) sont`1`, et`true`. `yes` Tout le reste, y compris la chaîne vide, est considéré comme non activé. La variable d'environnement n'est consultée que lorsque ni l'CLIindicateur ni `samconfig.toml` la valeur ne sont définis. **Important** Chaque commande nécessite sa propre activation. Le passage `--language-extensions` à `sam build` ne se propage pas à une version ultérieure `sam local invoke` : le traitement local est décidé par appel de commande. Utilisez la variable d'environnement ou une `samconfig.toml` entrée pour activer toutes les commandes sans répéter l'indicateur. ## Ventilateur : ForEach `Fn::ForEach`gé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`, et`ProductsFunction`, 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 : **Propriétés dynamiques des artefacts reconnues par le AWS SAM INTERFACE DE LIGNE DE COMMANDE (CLI)** | Type de ressource | Propriété | | --- | --- | | `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` | Pour les propriétés en pointillés (par exemple, `Command.ScriptLocation` on `AWS::Glue::Job` ou `Code.ImageUri` on`AWS::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` (par exemple, `SAMCodeUriServices` ou). `SAMScriptLocationJobs` **Important** Customer-authored les mappages ne doivent pas commencer par ces `SAM*` préfixes ; ils sont réservés au. AWS SAMCLI Consultez [Limitations](#sam-specification-language-extensions-limitations). 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` usage`DefinitionUri`), 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 : **Exemple de mappage de noms avec des suffixes de collision** | Modèle de ressource | Propriété | Nom du mappage | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | 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](#sam-specification-language-extensions-dynamic-artifacts) Il les résout lorsqu'il traite le modèle, à partir de : 1. `--parameter-overrides`passé à la AWS SAMCLI commande. 1. La `Default` valeur du paramètre dans le modèle. **Important** Comme les `SAM*` mappages sont intégrés au moment du package, vous devez les reconditionner chaque fois que vous modifiez la valeur du paramètre (par exemple, lors de l'ajout d'un nouveau service) afin que les mappages incluent des entrées pour les nouvelles valeurs. Cela s'applique uniquement lorsque le paramètre entraîne une boucle d'artefact dynamique ; les autres remplacements de paramètres peuvent être modifiés au moment du déploiement, comme d'habitude. ``` # 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::ForEach`dans 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::ForEach`les 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 : **Fonctions intrinsèques résolues localement lors de l'extension des extensions linguistiques** | Fonction | Description | | --- | --- | | `Fn::ForEach` | Expansion de la boucle. | | `Fn::Length` | Renvoie le nombre d'éléments de la liste. | | `Fn::ToJsonString` | Convertit une valeur en JSON chaîne. | | `Fn::FindInMap` | Recherche cartographique, y compris l'option facultative`DefaultValue`. | | `Fn::If` | Sélection de valeur conditionnelle. | | `Fn::Sub` | Substitution de chaînes. | | `Fn::Join` | Concaténation de chaînes. | | `Fn::Split` | Fendage de cordes. | | `Fn::Select` | Sélection d'éléments de liste. | | `Fn::Base64` | Encodage Base64. | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | Évaluation de l'état. | | `Ref` | Références de paramètres et de pseudo-paramètres. | Les fonctions qui nécessitent des ressources déployées (`Fn::GetAtt``Fn::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 : **Erreurs de validation survenues lors de l'extension des extensions linguistiques** | Cause | Message d’erreur | | --- | --- | | La `Fn::ForEach` valeur est mal formée : il ne s'agit pas d'une liste, ne comporte pas exactement 3 éléments ou possède un identifiant de boucle autre qu'une chaîne de caractères. | `Fn::ForEach:: layout is incorrect`(élevé comme`InvalidTemplateException`). | | Plus de 5 niveaux `Fn::ForEach` sont imbriqués. | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | La collection se résout en une liste vide (par exemple, un `CommaDelimitedList` paramètre avec`Default: ""`). | Aucune erreur : la boucle est ignorée en silence et aucune ressource n'est émise. | | La `!Ref` collection pointe vers un paramètre qui n'est pas déclaré dans le modèle. | Aucune erreur : la référence non résolue est conservée dans le modèle. Au moment du déploiement, le problème CloudFormation sera résolu côté serveur. | ## Limitations + **Les collections doivent pouvoir être résolues à un build/package moment donné.** `Fn::ForEach`les collections qui utilisent ou `Fn::GetAtt` `Fn::ImportValue` les références dynamiques SSM/Secrets du gestionnaire ne peuvent pas être étendues localement. Utilisez `--parameter-overrides` plutôt un paramètre avec. + **Les mappages d'artefacts dynamiques sont corrigés au moment du package.** Lorsqu'une `Fn::ForEach` collection est une référence de paramètre et que le corps de la boucle utilise une propriété d'artefact dynamique (par exemple,`CodeUri: ./services/${Name}`), les `SAM*` mappages générés contiennent uniquement des entrées pour les valeurs des paramètres qui ont été résolues au moment du package. Si vous modifiez `--parameter-overrides` ce paramètre au moment du déploiement sans reconditionner, les nouvelles valeurs ne comporteront pas d'entrées de mappage et le déploiement échouera. Cela ne s'applique pas aux paramètres qui ne sont pas utilisés pour piloter un artefact `Fn::ForEach` dynamique. + **`DeletionPolicy`et `UpdateReplacePolicy`** sont validés et résolus lors de l'extension. Ils prennent en charge `Ref` les paramètres mais pas les autres fonctions intrinsèques. + **Limite de nidification.** Jusqu'à 5 niveaux `Fn::ForEach` peuvent être imbriqués, correspondant à la limite CloudFormation côté serveur. + **Noms de mappage réservés.** Les noms de mappage commençant par l'un des suivants sont réservés aux AWS SAMCLI : ne créez pas vos propres mappages avec ces préfixes : + `SAMCodeUri`,`SAMImageUri`,`SAMContentUri`,`SAMDefinitionUri`,,`SAMSchemaUri`,`SAMBodyS3Location`,`SAMDefinitionS3Location`, `SAMTemplateURL``SAMCode`, `SAMContent` — émis par `sam package` pour les propriétés dynamiques des artefacts. Voir le [Propriétés dynamiques des artefacts](#sam-specification-language-extensions-dynamic-artifacts) tableau. + `SAMLayers`— émis `sam build` lorsqu'une fonction `Fn::ForEach` générée récupère des références de couche de dépendance générées automatiquement (couches AWS SAMCLI Lambda intégrées dans une pile imbriquée). Ce préfixe n'a aucune propriété correspondante créée par l'utilisateur ; il est ajouté automatiquement. ## 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.