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 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 définies dans le modèle qui ne font pas référence à une ressource AWS::Serverless::Api.
Une AWS::Serverless::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 AWS 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 AWS CloudFormation des hooks, consultez la section Enregistrement des hooks dans le guide de l'utilisateur de la AWS CloudFormation CLI et dans le apigw-enforce-authorizer
Pour plus d'informations sur l'utilisation de politiques IAM, veuillez consulter Exiger que les routes d'API disposent d'une autorisation 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 AWS CloudFormation ressources. Pour de plus amples informations, veuillez consulter AWS CloudFormation Ressources générées pour AWS SAM.
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:
AccessLogSetting
AlwaysDeploy:Boolean
ApiKeySourceType:String
Auth:ApiAuth
BinaryMediaTypes:List
CacheClusterEnabled:Boolean
CacheClusterSize:String
CanarySetting:CanarySetting
Cors:String | CorsConfiguration
DefinitionBody:JSON
DefinitionUri:String | ApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:DomainConfiguration
EndpointConfiguration:EndpointConfiguration
FailOnWarnings:Boolean
GatewayResponses:Map
MergeDefinitions:Boolean
MethodSettings:MethodSettings
MinimumCompressionSize:Integer
Mode:String
Models:Map
Name:String
OpenApiVersion:String
PropagateTags:Boolean
StageName:String
Tags:Map
TracingEnabled:Boolean
Variables:Map
Propriétés
-
AccessLogSetting
-
Configure les réglages d'accès au journal pour une étape.
Type : AccessLogSetting
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
AccessLogSetting
propriété d'uneAWS::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
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS 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
etAUTHORIZER
.Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
ApiKeySourceType
propriété d'uneAWS::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 deContrôlez l'accès aux API avec votre AWS SAM modèle. Pour un exemple montrant comment remplacer un autorisateur global, voir. Remplacer un mécanisme d'autorisation global pour votre API REST Amazon API Gateway
Type : ApiAuth
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
BinaryMediaTypes
-
Liste des types MIME que votre API pourrait renvoyer. Utilisez-le pour activer le support binaire pourAPIs. Utilisez ~1 au lieu de / dans les types mime.
Type: liste
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est similaire à celle
BinaryMediaTypes
d'uneAWS::ApiGateway::RestApi
ressource. La liste des BinaryMediaTypes est ajoutée à la fois à la AWS 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
surtrue
sousMethodSettings
.Type : valeur booléenne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
CacheClusterEnabled
propriété d'uneAWS::ApiGateway::Stage
ressource. -
CacheClusterSize
-
Taille du cluster de cache de l'environnement.
Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
CacheClusterSize
propriété d'uneAWS::ApiGateway::Stage
ressource. -
CanarySetting
-
Configurez un paramètre Canary à une étape d'un déploiement régulier.
Type : CanarySetting
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
CanarySetting
propriété d'uneAWS::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.
Note
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 dans le Guide du développeur API Gateway.
Type : Chaîne | CorsConfiguration
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
DefinitionBody
-
Spécification OpenAPI qui décrit votre API. Si ni
DefinitionUri
, niDefinitionBody
sont spécifiés, SAM générera unDefinitionBody
pour vous en fonction de la configuration de votre modèle.Pour référencer un local OpenAPI fichier qui définit votre API, utilisez la
AWS::Include
transformation. Pour en savoir plus, consultez Comment AWS SAM télécharge les fichiers locaux.Type : JSON
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est similaire à celle
Body
d'uneAWS::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 unAuth
,BinaryMediaTypes
,Cors
,GatewayResponses
,Models
, et unEventSource
de type Api activée pour uneAWS::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
, niDefinitionBody
sont spécifiés, SAM générera unDefinitionBody
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
ousam 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 laDefinitionBody
propriété avec la transformation Include pour importer une OpenApi définition dans le modèle.Type : Chaîne | ApiDefinition
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est similaire à celle
BodyS3Location
d'uneAWS::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
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
Description
propriété d'uneAWS::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écifiezTrue
.Type : valeur booléenne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est similaire à celle
DisableExecuteApiEndpoint
d'uneAWS::ApiGateway::RestApi
ressource. Il est transmis directement à la propriétédisableExecuteApiEndpoint
d'une extensionx-amazon-apigateway-endpoint-configuration
, qui est ajoutée à la propriétéBody
d'une ressourceAWS::ApiGateway::RestApi
. -
Domain
-
Configure un domaine personnalisé pour cette API Gateway.
Type : DomainConfiguration
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
EndpointConfiguration
-
Type de point de terminaison d'une API REST.
Type : EndpointConfiguration
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est similaire à celle
EndpointConfiguration
d'uneAWS::ApiGateway::RestApi
ressource. Les propriétés de configuration imbriquées sont nommées différemment. -
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 estfalse
.Type : valeur booléenne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
FailOnWarnings
propriété d'uneAWS::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.
Type: carte (map)
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
MergeDefinitions
-
AWS SAM génère un OpenAPI spécification provenant de la source d'événements de votre API. Spécifiez
true
pour le AWS SAM fusionner dans la ligne OpenAPI spécification définie dans votreAWS::Serverless::Api
ressource. Spécifiez la valeurfalse
pour ne pas fusionner.MergeDefinitions
nécessite la propriétéDefinitionBody
pour queAWS::Serverless::Api
soit définie.MergeDefinitions
n'est pas compatible avec la propriétéDefinitionUri
pourAWS::Serverless::Api
.Valeur par défaut :
false
Type : valeur booléenne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS 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
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
MethodSettings
propriété d'uneAWS::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
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
MinimumCompressionSize
propriété d'uneAWS::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 section Propriété Mode du AWS::ApiGateway::RestApiType de ressource .Valeurs valides :
overwrite
oumerge
Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
Mode
propriété d'uneAWS::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
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
Name
-
Nom de la RestApi ressource API Gateway
Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
Name
propriété d'uneAWS::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. Note
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'étapeStage
.Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
Indiquez s'il faut ou non transmettre les balises de la propriété
Tags
aux ressources AWS::Serverless::Api que vous avez générées. SpécifiezTrue
pour la propagation des balises dans vos ressources générées.Type : valeur booléenne
Obligatoire : non
Par défaut :
False
AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.
-
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
. Pour plus d'informations sur le référencement des ressources générées lorsqu'une AWS::Serverless::Api est spécifiée, consultez AWS CloudFormation ressources générées lorsque AWS::Serverless::Api est spécifié. Pour des informations générales sur les AWS CloudFormation ressources générées, consultezAWS CloudFormation Ressources générées pour AWS SAM.<api-logical-id>
.StageType : chaîne
Obligatoire : oui
AWS CloudFormation compatibilité : cette propriété est similaire à celle
StageName
d'uneAWS::ApiGateway::Stage
ressource. Elle est requise dans SAM, mais pas dans API GatewayInformations complémentaires : l'API implicite a un nom d'étape « Prod ».
-
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 dans le Guide de l'utilisateur AWS CloudFormation .
Type: carte (map)
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est similaire à celle
Tags
d'uneAWS::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 dans le guide du développeur d'API Gateway.
Type : valeur booléenne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
TracingEnabled
propriété d'uneAWS::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
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
Variables
propriété d'uneAWS::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 Ref
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 Fn::GetAtt
dans le Guide de l'utilisateur AWS CloudFormation .
RootResourceId
-
ID de ressource racine d'une ressource
RestApi
, commea0bc123d4e
.
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 s'agit simplement d'une partie d'un fichier AWS SAM modèle présentant une AWS::Serverless::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 s'agit simplement d'une partie d'un fichier AWS SAM modèle présentant une AWS::Serverless::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 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é 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}