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.
# AWS::Serverless::Api
Crée un ensemble de ressources et de méthodes Amazon API Gateway qui peuvent être appelées via les points de terminaison HTTPS.
Il n'est pas nécessaire d'ajouter explicitement une [AWS::Serverless::Api](#sam-resource-api) ressource à un modèle de définition d'application AWS sans serveur. Une ressource de ce type est implicitement créée à partir de l'union des événements Api définis su les ressources [AWS::Serverless::Function](sam-resource-function.md) définies dans le modèle qui ne font pas référence à une ressource [AWS::Serverless::Api](#sam-resource-api).
Une [AWS::Serverless::Api](#sam-resource-api) ressource doit être utilisée pour définir et documenter l'API utilisée OpenApi, ce qui permet de mieux configurer les ressources Amazon API Gateway sous-jacentes.
Nous vous recommandons d'utiliser CloudFormation des hooks ou des politiques IAM pour vérifier que les ressources API Gateway sont associées à des autorisateurs afin de contrôler l'accès à celles-ci.
Pour plus d'informations sur l'utilisation CloudFormation des hooks, consultez la section [Enregistrement des hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) dans le *guide de l'utilisateur de la CloudFormation CLI* et dans le [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub référentiel.
Pour plus d'informations sur l'utilisation de politiques IAM, veuillez consulter [Exiger que les routes d'API disposent d'une autorisation](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) dans le *Guide du développeur API Gateway*.
**Note**
Lorsque vous déployez vers AWS CloudFormation, vos AWS SAM ressources sont AWS SAM transformées en CloudFormation ressources. Pour de plus amples informations, veuillez consulter [CloudFormation Ressources générées pour AWS SAM](sam-specification-generated-resources.md).
## Syntaxe
Pour déclarer cette entité dans votre modèle AWS Serverless Application Model (AWS SAM), utilisez la syntaxe suivante.
### YAML
```
Type: AWS::Serverless::Api
Properties:
[AccessLogSetting](#sam-api-accesslogsetting): {{[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)}}
AlwaysDeploy: {{Boolean}}
[ApiKeySourceType](#sam-api-apikeysourcetype): {{String}}
[Auth](#sam-api-auth): {{ApiAuth}}
[BinaryMediaTypes](#sam-api-binarymediatypes): {{List}}
[CacheClusterEnabled](#sam-api-cacheclusterenabled): {{Boolean}}
[CacheClusterSize](#sam-api-cacheclustersize): {{String}}
[CanarySetting](#sam-api-canarysetting): {{[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)}}
[Cors](#sam-api-cors): {{String | CorsConfiguration}}
[DefinitionBody](#sam-api-definitionbody): {{JSON}}
[DefinitionUri](#sam-api-definitionuri): {{String | ApiDefinition}}
[Description](#sam-api-description): {{String}}
[DisableExecuteApiEndpoint](#sam-api-disableexecuteapiendpoint): {{Boolean}}
[Domain](#sam-api-domain): {{DomainConfiguration}}
[EndpointAccessMode](#sam-api-endpointaccessmode): {{String}}
[EndpointConfiguration](#sam-api-endpointconfiguration): {{EndpointConfiguration}}
[FailOnWarnings](#sam-api-failonwarnings): {{Boolean}}
[GatewayResponses](#sam-api-gatewayresponses): {{Map}}
MergeDefinitions: {{Boolean}}
[MethodSettings](#sam-api-methodsettings): {{MethodSettings}}
[MinimumCompressionSize](#sam-api-minimumcompressionsize): {{Integer}}
[Mode](#sam-api-mode): {{String}}
[Models](#sam-api-models): {{Map}}
[Name](#sam-api-name): {{String}}
[OpenApiVersion](#sam-api-openapiversion): {{String}}
PropagateTags: {{Boolean}}
[Policy](#sam-api-policy): {{JSON}}
[SecurityPolicy](#sam-api-securitypolicy): {{String}}
[StageName](#sam-api-stagename): {{String}}
[Tags](#sam-api-tags): {{Map}}
[TracingEnabled](#sam-api-tracingenabled): {{Boolean}}
[Variables](#sam-api-variables): {{Map}}
```
## Propriétés
`AccessLogSetting`
Configure les réglages d'accès au journal pour une étape.
*Type :* [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)` propriété d'une `AWS::ApiGateway::Stage` ressource.
`AlwaysDeploy`
Déploie toujours l'API, même si aucune modification n'a été détectée.
*Type* : valeur booléenne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`ApiKeySourceType`
Source de la clé API pour les demandes de relevé en fonction d'un plan d'utilisation. Les valeurs valides sont `HEADER` et `AUTHORIZER`.
*Type* : chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[ApiKeySourceType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-apikeysourcetype)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`Auth`
Configurez le mécanisme d'autorisation utilisé pour contrôler l'accès à votre API API Gateway.
Pour plus d'informations sur la configuration de l'accès à l' AWS SAM aide de[Contrôlez l'accès aux API avec votre AWS SAM modèle](serverless-controlling-access-to-apis.md). Pour un exemple montrant comment remplacer un autorisateur global, voir. [Remplacer un mécanisme d'autorisation global pour votre API REST Amazon API Gateway](sam-property-function-apifunctionauth.md#sam-property-function-apifunctionauth--examples--override)
*Type :* [ApiAuth](sam-property-api-apiauth.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`BinaryMediaTypes`
Liste des types MIME que votre API pourrait renvoyer. Utilisez-le pour activer le support binaire pourAPIs.
*Type* : liste
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes)` d'une `AWS::ApiGateway::RestApi` ressource. La liste des BinaryMediaTypes est ajoutée à la fois à la CloudFormation ressource et au document OpenAPI.
`CacheClusterEnabled`
Indique si la mise en cache est activée pour l'étape. Pour mettre en cache les réponses, vous devez également définir `CachingEnabled` sur `true` sous `MethodSettings`.
*Type* : valeur booléenne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)` propriété d'une `AWS::ApiGateway::Stage` ressource.
`CacheClusterSize`
Taille du cluster de cache de l'environnement.
*Type* : chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize)` propriété d'une `AWS::ApiGateway::Stage` ressource.
`CanarySetting`
Configurez un paramètre Canary à une étape d'un déploiement régulier.
*Type :* [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)` propriété d'une `AWS::ApiGateway::Stage` ressource.
`Cors`
Gérez le partage de ressources entre origines (CORS) pour l'ensemble de votre API Gateway. APIs Spécifiez le domaine à autoriser en tant que chaîne ou spécifiez un dictionnaire avec une configuration Cors supplémentaire.
CORS nécessite AWS SAM de modifier votre définition OpenAPI. Créez une définition OpenAPI intégrée dans `DefinitionBody` le pour activer CORS.
Pour plus d'informations, consultez [Activation de CORS pour une ressource API REST dans API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html) dans le *Guide du développeur API Gateway*.
*Type* : Chaîne \| [CorsConfiguration](sam-property-api-corsconfiguration.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`DefinitionBody`
Spécification OpenAPI qui décrit votre API. Si ni `DefinitionUri`, ni `DefinitionBody` sont spécifiés, SAM générera un `DefinitionBody` pour vous en fonction de la configuration de votre modèle.
Pour faire référence à un fichier OpenAPI local qui définit votre API, utilisez la macro `AWS::Include` transform. Pour en savoir plus, veuillez consulter la section [Comment AWS SAM télécharge les fichiers locaux](deploy-upload-local-files.md).
*Type* : JSON
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` d'une `AWS::ApiGateway::RestApi` ressource. Si certaines propriétés sont fournies, le contenu peut être inséré ou modifié dans le DefinitionBody avant d'être transmis à CloudFormation. Les propriétés comprennent un `Auth`, `BinaryMediaTypes`, `Cors`, `GatewayResponses`, `Models`, et un `EventSource` de type Api activée pour une `AWS::Serverless::Function` correspondante.
`DefinitionUri`
Amazon S3 Uri, chemin d'accès au fichier local ou objet d'emplacement du document OpenAPI définissant l'API. L'objet Amazon S3 référencé par cette propriété doit être un fichier OpenAPI valide. Si ni `DefinitionUri`, ni `DefinitionBody` sont spécifiés, SAM générera un `DefinitionBody` pour vous en fonction de la configuration de votre modèle.
Si un chemin d'accès de fichier local est fourni, le modèle doit passer par le flux comprenant la propriété `sam deploy` ou `sam package`, afin que la définition soit correctement transformée.
Les fonctions intrinsèques ne sont pas prises en charge dans OpenApi les fichiers externes référencés par`DefinitionUri`. Utilisez plutôt la `DefinitionBody` propriété avec la [transformation Include](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html) pour importer une OpenApi définition dans le modèle.
*Type* : Chaîne \| [ApiDefinition](sam-property-api-apidefinition.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-bodys3location)` d'une `AWS::ApiGateway::RestApi` ressource. Les propriétés imbriquées d'Amazon S3 sont nommées différemment.
`Description`
Une description de la ressource API.
*Type* : chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-description)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`DisableExecuteApiEndpoint`
Spécifie si les clients peuvent appeler votre API à l’aide du point de terminaison `execute-api` par défaut. Par défaut, les clients peuvent appeler votre API avec l'`https://{api_id}.execute-api.{region}.amazonaws.com` par défaut. Pour obliger les clients à utiliser un nom de domaine personnalisé pour appeler votre API, spécifiez `True`.
*Type* : valeur booléenne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)` d'une `AWS::ApiGateway::RestApi` ressource. Il est transmis directement à la propriété `disableExecuteApiEndpoint` d'une extension `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)`, qui est ajoutée à la propriété ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` d'une ressource `AWS::ApiGateway::RestApi`.
`Domain`
Configure un domaine personnalisé pour cette API Gateway.
*Type :* [DomainConfiguration](sam-property-api-domainconfiguration.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`EndpointConfiguration`
Type de point de terminaison d'une API REST.
*Type :* [EndpointConfiguration](sam-property-api-endpointconfiguration.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration)` d'une `AWS::ApiGateway::RestApi` ressource. Les propriétés de configuration imbriquées sont nommées différemment.
`EndpointAccessMode`
Mode d'accès pour le point de terminaison de l'API REST. Obligatoire lors de l'utilisation de politiques de sécurité renforcées (celles préfixées par`SecurityPolicy_`).
*Valeurs valides* : `STRICT` ou `BASIC`
*Type :* chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[EndpointAccessMode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointaccessmode)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`FailOnWarnings`
Indique si la création d'API doit être annulée (`true`) ou non (`false`) lorsqu'un avertissement est rencontré. La valeur par défaut est `false`.
*Type* : valeur booléenne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-failonwarnings)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`GatewayResponses`
Configure les réponses de passerelle pour une API. Les réponses de passerelle sont des réponses renvoyées par API Gateway, directement ou via l'utilisation des mécanismes d'autorisation Lambda. Pour plus d'informations, consultez la documentation de l'[ OpenApi extension Api Gateway pour Gateway Responses](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html).
*Type*: carte (map)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`MergeDefinitions`
AWS SAM génère une OpenAPI spécification à partir de la source d'événements de votre API. Spécifiez `true` de le AWS SAM fusionner dans la OpenAPI spécification en ligne définie dans votre `AWS::Serverless::Api` ressource. Spécifiez la valeur `false` pour ne pas fusionner.
`MergeDefinitions` nécessite la propriété `DefinitionBody` pour que `AWS::Serverless::Api` soit définie. `MergeDefinitions` n'est pas compatible avec la propriété `DefinitionUri` pour `AWS::Serverless::Api`.
*Valeur par défaut* : `false`
*Type* : valeur booléenne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`MethodSettings`
Configure tous les paramètres de l'étape API, y compris la journalisation, les métriques, le CacheTL, la limitation.
*Type* : liste de propriétés [ MethodSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-methodsetting.html)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings)` propriété d'une `AWS::ApiGateway::Stage` ressource.
`MinimumCompressionSize`
Autoriser la compression des corps de réponse en fonction de l'en-tête Accept-Encoding du client. La compression est déclenchée lorsque la taille du corps de la réponse est supérieure ou égale au seuil configuré. Le seuil de taille maximale du corps est de 10 Mo (10 485 760 octets). - Les types de compression suivants sont pris en charge : gzip, deflate et identity.
*Type* : entier
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`Mode`
Cette propriété s'applique uniquement lorsque vous utilisez OpenAPI pour définir votre API REST. Le `Mode` détermine comment API Gateway gère les mises à jour des ressources. Pour plus d'informations, consultez la propriété [Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode) du type de ressource [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html).
*Valeurs valides* : `overwrite` ou `merge`
*Type :* chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`Models`
Les schémas à utiliser par vos méthodes d'API. Ces schémas peuvent être décrits avec JSON ou YAML. Consultez la section Exemples au bas de cette page pour obtenir des exemples de modèles.
*Type*: carte (map)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`Name`
Nom de la RestApi ressource API Gateway
*Type* : chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`OpenApiVersion`
Version de OpenApi à utiliser. Cela peut être soit `2.0` pour la spécification Swagger, soit pour l'une des versions OpenApi 3.0, comme. `3.0.1` Pour plus d'informations sur OpenAPI, consultez [Spécification OpenAPI](https://swagger.io/specification/).
AWS SAM crée une étape appelée `Stage` par défaut. La définition de cette propriété sur n'importe quelle valeur valide empêchera la création de l'étape `Stage`.
*Type* : chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`PropagateTags`
Indiquez s'il faut ou non transmettre les balises de la propriété `Tags` aux ressources [AWS::Serverless::Api](sam-specification-generated-resources-api.md) que vous avez générées. Spécifiez `True` pour la propagation des balises dans vos ressources générées.
*Type* : valeur booléenne
*Obligatoire* : non
*Par défaut* : `False`
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`Policy`
Document de politique qui contient les autorisations pour l'API. Pour définir l'ARN de la politique, utilisez la fonction `!Join` intrinsèque avec `""` comme délimiteur et les valeurs `"execute-api:/"` et `"*"`.
*Type* : JSON
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la propriété [Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) d'une `AWS::ApiGateway::RestApi` ressource.
`SecurityPolicy`
La version TLS et la suite de chiffrement pour l'API REST. Lorsque vous utilisez des politiques de sécurité renforcées (celles préfixées par`SecurityPolicy>`), vous devez également définir le`EndpointAccessMode`.
*Type* : chaîne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-securitypolicy)` propriété d'une `AWS::ApiGateway::RestApi` ressource.
`StageName`
Le nom de l'étape qu'API Gateway utilise en tant que premier segment de chemin d'accès dans l'identificateur de ressource uniforme (URI) appelé.
Pour référencer la ressource de l'étape, utilisez `{{}}.Stage`. Pour plus d'informations sur le référencement des ressources générées lorsqu'une [AWS::Serverless::Api](#sam-resource-api) est spécifiée, consultez [CloudFormation ressources générées lorsque cela AWS::Serverless::Api est spécifié](sam-specification-generated-resources-api.md). Pour des informations générales sur les CloudFormation ressources générées, consultez[CloudFormation Ressources générées pour AWS SAM](sam-specification-generated-resources.md).
*Type* : chaîne
*Obligatoire* : oui
*CloudFormation compatibilité* : cette propriété est similaire à celle `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-stagename)` d'une `AWS::ApiGateway::Stage` ressource. Elle est requise dans SAM, mais pas dans API Gateway
*Informations complémentaires* : l'API implicite a un nom d'étape « Prod ».
`Tags`
Un mappage (chaîne à chaîne) qui spécifie les balises à ajouter à cette étape API Gateway. Pour plus de détails sur les clés et les valeurs valides pour les étiquettes, voir l'[étiquette Ressource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) dans le *Guide de l'utilisateur AWS CloudFormation *.
*Type*: carte (map)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tags)` d'une `AWS::ApiGateway::Stage` ressource. La propriété Tags dans SAM se compose de paires Key:Value ; CloudFormation elle consiste en une liste d'objets Tag.
`TracingEnabled`
Indique si le suivi actif avec X-Ray est activé pour cette étape. Pour plus d'informations sur X-Ray, consultez la section [Suivi des demandes des utilisateurs vers REST à APIs l'aide de X-Ray](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html) dans le *guide du développeur d'API Gateway*.
*Type* : valeur booléenne
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tracingenabled)` propriété d'une `AWS::ApiGateway::Stage` ressource.
`Variables`
Un mappage (chaîne à chaîne) qui définit les variables de l'étape, où le nom de la variable correspond à la clé et où la valeur de la variable correspond à la valeur. Les noms de variables peuvent uniquement utiliser des caractères alphanumériques. Les valeurs doivent respecter l'expression régulière suivante : `[A-Za-z0-9._~:/?#&=,-]+`.
*Type*: carte (map)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables)` propriété d'une `AWS::ApiGateway::Stage` ressource.
## Valeurs renvoyées
### Réf
Lorsque l'ID logique de cette ressource est fournie à la fonction intrinsèque `Ref`, elle renvoie l'ID de l'API API Gateway sous-jacente.
Pour plus d'informations sur l'utilisation de la fonction `Ref`, consultez [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) dans le *Guide de l'utilisateur AWS CloudFormation *.
### Ventilateur : GetAtt
`Fn::GetAtt` renvoie une valeur pour un attribut de ce type indiqué. Voici les attributs disponibles et des exemples de valeurs de retour.
Pour plus d'informations sur l'utilisation de `Fn::GetAtt`, consultez [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html) dans le *Guide de l'utilisateur AWS CloudFormation *.
`RootResourceId`
ID de ressource racine d'une ressource `RestApi`, comme `a0bc123d4e`.
## Exemples
### SimpleApiExample
Un fichier AWS SAM modèle Hello World qui contient une fonction Lambda avec un point de terminaison d'API. Il s'agit d'un fichier AWS SAM modèle complet pour une application sans serveur fonctionnelle.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
ApiFunction: # Adds a GET method at the root resource via an Api event
Type: AWS::Serverless::Function
Properties:
Events:
ApiEvent:
Type: Api
Properties:
Path: /
Method: get
RestApiId:
Ref: ApiGatewayApi
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
### ApiCorsExample
Un extrait de AWS SAM modèle avec une API définie dans un fichier Swagger externe, ainsi que des intégrations Lambda et des configurations CORS. Il ne s'agit que d'une partie d'un fichier AWS SAM modèle présentant une [AWS::Serverless::Api](#sam-resource-api) définition.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
# Allows www.example.com to call these APIs
# SAM will automatically add AllowMethods with a list of methods for this API
Cors: "'www.example.com'"
DefinitionBody: # Pull in an OpenApi definition from S3
'Fn::Transform':
Name: 'AWS::Include'
# Replace "bucket" with your bucket name
Parameters:
Location: s3://bucket/swagger.yaml
```
### ApiCognitoAuthExample
Extrait de AWS SAM modèle avec une API qui utilise Amazon Cognito pour autoriser les requêtes adressées à l'API. Il ne s'agit que d'une partie d'un fichier AWS SAM modèle présentant une [AWS::Serverless::Api](#sam-resource-api) définition.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Cors: "'*'"
Auth:
DefaultAuthorizer: MyCognitoAuthorizer
Authorizers:
MyCognitoAuthorizer:
UserPoolArn:
Fn::GetAtt: [MyCognitoUserPool, Arn]
```
### ApiModelsExample
Extrait AWS SAM de modèle avec une API qui inclut un schéma Models. Il ne s'agit que d'une partie d'un fichier AWS SAM modèle présentant une [AWS::Serverless::Api](#sam-resource-api) définition avec deux schémas de modèle.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Models:
User:
type: object
required:
- username
- employee_id
properties:
username:
type: string
employee_id:
type: integer
department:
type: string
Item:
type: object
properties:
count:
type: integer
category:
type: string
price:
type: integer
```
### Exemple de mise en cache
Un fichier AWS SAM modèle Hello World qui contient une fonction Lambda avec un point de terminaison d'API. La mise en cache de l'API est activée pour une ressource et une méthode. Pour plus d'informations sur la mise en cache, veuillez consulter [Activation de la mise en cache des API pour améliorer la réactivité](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html) dans le *Guide du développeur API Gateway*.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition with caching turned on
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
CacheClusterEnabled: true
CacheClusterSize: '0.5'
MethodSettings:
- ResourcePath: /
HttpMethod: GET
CachingEnabled: true
CacheTtlInSeconds: 300
Tags:
CacheMethods: All
ApiFunction: # Adds a GET method at the root resource via an Api event
Type: AWS::Serverless::Function
Properties:
Events:
ApiEvent:
Type: Api
Properties:
Path: /
Method: get
RestApiId:
Ref: ApiGatewayApi
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
### Exemple de domaine personnalisé avec une API privée
Un fichier AWS SAM modèle Hello World qui contient une fonction Lambda avec un point de terminaison d'API mappé à un domaine privé. Le modèle crée une association d'accès au domaine entre un point de terminaison VPC et le domaine privé. Pour plus d'informations, consultez la section [Noms de domaine personnalisés pour le domaine privé APIs dans API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html).
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template configured with a custom domain using a private API
Parameters:
DomainName:
Type: String
Default: mydomain.example.com
CertificateArn:
Type: String
HostedZoneId:
Type: String
VpcEndpointId:
Type: String
VpcEndpointDomainName:
Type: String
VpcEndpointHostedZoneId:
Type: String
Resources:
MyFunction:
Type: AWS::Serverless::Function
Properties:
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
Handler: index.handler
Runtime: python3.13
Events:
Fetch:
Type: Api
Properties:
RestApiId:
Ref: MyApi
Method: Get
Path: /get
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
EndpointConfiguration:
Type: PRIVATE
VPCEndpointIds:
- !Ref VpcEndpointId
Policy:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
- Effect: Deny
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
Condition:
StringNotEquals:
aws:SourceVpce: !Ref VpcEndpointId
Domain:
DomainName: !Ref DomainName
CertificateArn: !Ref CertificateArn
EndpointConfiguration: PRIVATE
BasePath:
- /
Route53:
HostedZoneId: !Ref HostedZoneId
VpcEndpointDomainName: !Ref VpcEndpointDomainName
VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
AccessAssociation:
VpcEndpointId: !Ref VpcEndpointId
Policy:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
- Effect: Deny
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
Condition:
StringNotEquals:
aws:SourceVpce: !Ref VpcEndpointId
```