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.
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
AccessLogSettingpropriété d'uneAWS::ApiGateway::Stageressource. -
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
HEADERetAUTHORIZER.Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
ApiKeySourceTypepropriété d'uneAWS::ApiGateway::RestApiressource. -
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
BinaryMediaTypesd'uneAWS::ApiGateway::RestApiressource. 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
CachingEnabledsurtruesousMethodSettings.Type : valeur booléenne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
CacheClusterEnabledpropriété d'uneAWS::ApiGateway::Stageressource. -
CacheClusterSize -
Taille du cluster de cache de l'environnement.
Type : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
CacheClusterSizepropriété d'uneAWS::ApiGateway::Stageressource. -
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
CanarySettingpropriété d'uneAWS::ApiGateway::Stageressource. -
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
DefinitionBodyle 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, niDefinitionBodysont spécifiés, SAM générera unDefinitionBodypour 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::Includetransformation. 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
Bodyd'uneAWS::ApiGateway::RestApiressource. 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 unEventSourcede type Api activée pour uneAWS::Serverless::Functioncorrespondante. -
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, niDefinitionBodysont spécifiés, SAM générera unDefinitionBodypour 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 deployousam 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 laDefinitionBodyproprié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
BodyS3Locationd'uneAWS::ApiGateway::RestApiressource. 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
Descriptionpropriété d'uneAWS::ApiGateway::RestApiressource. -
DisableExecuteApiEndpoint -
Spécifie si les clients peuvent appeler votre API à l’aide du point de terminaison
execute-apipar défaut. Par défaut, les clients peuvent appeler votre API avec l'https://{api_id}.execute-api.{region}.amazonaws.com.rproxy.goskope.compar 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
DisableExecuteApiEndpointd'uneAWS::ApiGateway::RestApiressource. Il est transmis directement à la propriétédisableExecuteApiEndpointd'une extensionx-amazon-apigateway-endpoint-configuration, qui est ajoutée à la propriétéBodyd'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
EndpointConfigurationd'uneAWS::ApiGateway::RestApiressource. 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
FailOnWarningspropriété d'uneAWS::ApiGateway::RestApiressource. -
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
truepour le AWS SAM fusionner dans la ligne OpenAPI spécification définie dans votreAWS::Serverless::Apiressource. Spécifiez la valeurfalsepour ne pas fusionner.MergeDefinitionsnécessite la propriétéDefinitionBodypour queAWS::Serverless::Apisoit définie.MergeDefinitionsn'est pas compatible avec la propriétéDefinitionUripourAWS::Serverless::Api.Valeur par défaut :
falseType : 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
MethodSettingspropriété d'uneAWS::ApiGateway::Stageressource. -
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
MinimumCompressionSizepropriété d'uneAWS::ApiGateway::RestApiressource. -
Mode -
Cette propriété s'applique uniquement lorsque vous utilisez OpenAPI pour définir votre API REST. Le
Modedé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 :
overwriteoumergeType : chaîne
Obligatoire : non
AWS CloudFormation compatibilité : cette propriété est transmise directement à la
Modepropriété d'uneAWS::ApiGateway::RestApiressource. -
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
Namepropriété d'uneAWS::ApiGateway::RestApiressource. -
OpenApiVersion -
Version de OpenApi à utiliser. Cela peut être soit
2.0pour la spécification Swagger, soit pour l'une des versions OpenApi 3.0, comme.3.0.1Pour plus d'informations sur OpenAPI, consultez Spécification OpenAPI. Note
AWS SAM crée une étape appelée
Stagepar 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é
Tagsaux ressources AWS::Serverless::Api que vous avez générées. SpécifiezTruepour la propagation des balises dans vos ressources générées.Type : valeur booléenne
Obligatoire : non
Par défaut :
FalseAWS 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
<api-logical-id>.StageType : chaîne
Obligatoire : oui
AWS CloudFormation compatibilité : cette propriété est similaire à celle
StageNamed'uneAWS::ApiGateway::Stageressource. 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
Tagsd'uneAWS::ApiGateway::Stageressource. 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
TracingEnabledpropriété d'uneAWS::ApiGateway::Stageressource. -
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
Variablespropriété d'uneAWS::ApiGateway::Stageressource.
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}
