AWS::Serverless::Api - AWS Serverless Application Model
SyntaxePropriétésValeurs renvoyéesExemples

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 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.

Note

Lorsque vous déployez vers AWS CloudFormation, vos AWS SAM ressources sont AWS SAM transformées en AWS CloudFormation ressources. Pour plus d’informations, consultez 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.

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'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

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 et AUTHORIZER.

Type : chaîne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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 deContrôlez API l'accès avec votre AWS SAM modèle.

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 ceci pour activer la prise en charge binaire pour les API. Utilisez ~1 au lieu de / dans les types mime.

Type: liste

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est similaire à celle BinaryMediaTypes d'une AWS::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 sur true sous MethodSettings.

Type : valeur booléenne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la CacheClusterEnabled propriété d'une AWS::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'une AWS::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'une AWS::ApiGateway::Stage ressource.

Cors

Gérer le partage des ressources cross-origin (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 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, 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 Chargement de fichiers locaux lors du déploiement.

Type : JSON

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est similaire à celle 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 parDefinitionUri. Utilisez plutôt la DefinitionBody 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'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

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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

AWS CloudFormation compatibilité : cette propriété est similaire à celle DisableExecuteApiEndpoint d'une 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

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'une AWS::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 est false.

Type : valeur booléenne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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.

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 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

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'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

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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 du type de ressource AWS::ApiGateway::RestApi.

Valeurs valides : overwrite ou merge

Type : chaîne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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

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'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.

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'étape Stage.

Type : chaîne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS 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

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 <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 AWS CloudFormation ressources générées lorsque cela 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.

Type : chaîne

Obligatoire : oui

AWS CloudFormation compatibilité : cette propriété est similaire à celle 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 dans le Guide de l'utilisateur AWS CloudFormation .

Type: carte (map)

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est similaire à celle 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 Suivi des demandes utilisateur vers les API REST à l'aide de X-Ray dans le Guide du développeur API Gateway.

Type : valeur booléenne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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

AWS CloudFormation compatibilité : cette propriété est transmise directement à la 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 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 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}