View a markdown version of this page

AWS::Serverless::Api - AWS Serverless Application Model

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.

Un AWS::Serverless::Api il n'est pas nécessaire d'ajouter explicitement une ressource à AWS Modèle de définition d'application 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::Fonction définies dans le modèle qui ne font pas référence à une ressource AWS::Serverless::Api.

Un AWS::Serverless::Api la ressource doit être utilisée pour définir et documenter l'API à l'aide OpenApi, 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 autorisations permettant d'en contrôler l'accès.

Pour plus d'informations sur l'utilisation CloudFormation crochets, voir Enregistrement des hooks dans le CloudFormation Guide de l'utilisateur CLI et le autorisateur 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 dans le Guide du développeur API Gateway.

Cette ressource soutient également le Connectors ressource Attribute. Pour plus d’informations, consultez Gérer les autorisations relatives aux ressources avec AWS SAM connectors.

Note

Lorsque vous effectuez un déploiement sur AWS CloudFormation, AWS SAM transforme votre AWS SAM ressources dans CloudFormation ressources. Pour plus d’informations, consultez Générées CloudFormation ressources pour AWS SAM.

Syntaxe

Pour déclarer cette entité dans votre AWS Serverless Application Model (AWS SAM) modèle, utilisez la syntaxe suivante.

Propriétés

AccessLogSetting

Configure les réglages d'accès au journal pour une étape.

Type : AccessLogSetting

Obligatoire : non

CloudFormation compatibilité: Cette propriété est transmise directement au AccessLogSetting propriété d'un 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 de 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 au ApiKeySourceType propriété d'un 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'aide de AWS SAM voir Contrô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

CloudFormation compatibilité: Cette propriété est unique à AWS SAM et n'a pas de CloudFormation équivalent.

BinaryMediaTypes

Liste des types MIME que votre API pourrait renvoyer. Utilisez ceci pour activer la prise en charge binaire pour les API.

Type : liste

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la BinaryMediaTypes propriété d'un AWS::ApiGateway::RestApi ressource. La liste des BinaryMediaTypes est ajouté à la fois au CloudFormation ressource et le 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 au CacheClusterEnabled propriété d'un 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 au CacheClusterSize propriété d'un AWS::ApiGateway::Stage ressource.

CanarySetting

Configurez un paramètre Canary à une étape d'un déploiement régulier.

Type : CanarySetting

Obligatoire : non

CloudFormation compatibilité: Cette propriété est transmise directement au CanarySetting propriété d'un AWS::ApiGateway::Stage ressource.

Cors

Gérez Cross-origin partage de ressources (CORS) pour toutes vos API API Gateway. 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 pour modifier votre définition d'OpenAPI. Créez une définition OpenAPI en ligne dans le DefinitionBody 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.

Tapez: Chaîne | CorsConfiguration

Obligatoire : non

CloudFormation compatibilité: Cette propriété est unique à AWS SAM et n'a pas de 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, consultez Comment AWS SAM télécharge les fichiers locaux.

Type : JSON

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la Body propriété d'un AWS::ApiGateway::RestApi ressource. Si certaines propriétés sont fournies, le contenu peut être inséré ou modifié dans 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 en externe OpenApi fichiers référencés par DefinitionUri. Utilisez plutôt le DefinitionBody propriété avec Inclure Transform pour importer un OpenApi définition dans le modèle.

Tapez: Chaîne | ApiDefinition

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la BodyS3Location propriété d'un 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 au Description propriété d'un 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 à la DisableExecuteApiEndpoint propriété d'un AWS::ApiGateway::RestApi ressource. Il est transmis directement à la propriété disableExecuteApiEndpoint d'une extension x-amazon-apigateway-endpoint-configuration, qui est ajoutée à la propriété Body d'une ressource AWS::ApiGateway::RestApi.

Domain

Configure un domaine personnalisé pour cette API Gateway.

Type : DomainConfiguration

Obligatoire : non

CloudFormation compatibilité: Cette propriété est unique à AWS SAM et n'a pas de CloudFormation équivalent.

EndpointConfiguration

Type de point de terminaison d'une API REST.

Type : EndpointConfiguration

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la EndpointConfiguration propriété d'un 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 au EndpointAccessMode propriété d'un 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 au FailOnWarnings propriété d'un 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 du Passerelle Api OpenApi extension pour Gateway Responses.

Type: carte (map)

Obligatoire : non

CloudFormation compatibilité: Cette propriété est unique à AWS SAM et n'a pas de CloudFormation équivalent.

MergeDefinitions

AWS SAM génère un OpenAPI spécification à partir de la source d'événements de votre API. Spécifiez true avoir AWS SAM fusionnez-le dans l'inline OpenAPI spécification 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 de 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

CloudFormation compatibilité: Cette propriété est transmise directement au MethodSettings propriété d'un AWS::ApiGateway::Stage ressource.

MinimumCompressionSize

Autoriser la compression des corps de réponse en fonction de ceux du client Accept-Encoding en-tête. 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 au MinimumCompressionSize propriété d'un 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 du type de ressource AWS::ApiGateway::RestApi.

Valeurs valides : overwrite ou merge

Type : chaîne

Obligatoire : non

CloudFormation compatibilité: Cette propriété est transmise directement au Mode propriété d'un 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 de CloudFormation équivalent.

Name

Un nom pour la passerelle API RestApi ressource

Type : chaîne

Obligatoire : non

CloudFormation compatibilité: Cette propriété est transmise directement au Name propriété d'un AWS::ApiGateway::RestApi ressource.

OpenApiVersion

Version de OpenApi à utiliser. Cela peut être soit 2.0 pour la spécification Swagger, ou l'une des OpenApi versions 3.0, comme 3.0.1. Pour plus d'informations sur OpenAPI, consultez Spécification OpenAPI.

Note

AWS SAM crée une scène 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 de CloudFormation équivalent.

PropagateTags

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é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 de CloudFormation équivalent.

Policy

Un 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 au Politique propriété d'un 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éfinirEndpointAccessMode.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité: Cette propriété est transmise directement au SecurityPolicy propriété d'un 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 <api-logical-id>.Stage. 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 CloudFormation ressources générées lorsque cela AWS::Serverless::Api est spécifié. Pour des informations générales sur les produits générés CloudFormation ressources, voir Générées CloudFormation ressources pour AWS SAM.

Type : chaîne

Obligatoire : oui

CloudFormation compatibilité: Cette propriété est similaire à la StageName propriété d'un 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 dans le Guide de l'utilisateur AWS CloudFormation .

Type: carte (map)

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la Tags propriété d'un AWS::ApiGateway::Stage ressource. La propriété Tags dans SAM se compose de Key:Value paires ; en CloudFormation il se compose d'une liste d'objets Tag.

TracingEnabled

Indique si le traçage est actif avec X-Ray est activé pour la scène. Pour plus d'informations sur X-Ray, voir Traçage des demandes des utilisateurs vers les API REST à l'aide de X-Ray dans le Guide du développeur d'API Gateway.

Type : valeur booléenne

Obligatoire : non

CloudFormation compatibilité: Cette propriété est transmise directement au TracingEnabled propriété d'un 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 au Variables propriété d'un 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 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, comme a0bc123d4e.

Exemples

SimpleApiExample

Un monde bonjour AWS SAM fichier modèle contenant une fonction événementielle Lambda avec un point de terminaison d'API. Il s'agit d'un livre complet AWS SAM fichier modèle 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 AWS SAM extrait de 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 AWS SAM fichier modèle affichant un 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

Un AWS SAM extrait de 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 AWS SAM fichier modèle affichant un 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

Un AWS SAM extrait de modèle avec une API qui inclut un schéma de modèles. Il ne s'agit que d'une partie d'un AWS SAM fichier modèle, affichant un AWS::Serverless::Api définition avec deux schémas modèles.

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 monde bonjour AWS SAM fichier modèle contenant 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}

Exemple de domaine personnalisé avec une API privée

Un monde bonjour AWS SAM fichier modèle contenant 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, voir Noms de domaine personnalisés pour les API privées dans API Gateway.

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