Syntaxe Propriétés Valeurs renvoyées Exemples

AWS::Serverless::HttpApi

Crée une Amazon API Gateway API HTTP, qui vous permet de créer des API RESTful avec une latence inférieure et un coût inférieur aux API REST. Pour plus d'informations sur les API HTTP, consultez Utilisation des API HTTP dans le Guide du développeur API Gateway.

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.

Syntaxe

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

YAML


Type: AWS::Serverless::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: JSON
  DefinitionUri: String | HttpApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  Name: String
  PropagateTags: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Propriétés

AccessLogSettings

Les paramètres pour la journalisation des accès dans une étape.

Type : AccessLogSettings

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la AccessLogSettings propriété d'une AWS::ApiGatewayV2::Stage ressource.

Auth

Configure l'autorisation pour le contrôle de l'accès à votre API HTTP API Gateway.

Pour plus d'informations, consultez Contrôle de l'accès aux API HTTP avec les mécanismes d'autorisation JWT dans le Guide du développeur API Gateway.

Type : HttpApiAuth

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.

CorsConfiguration

Gère le partage des ressources cross-origin (CORS) pour toutes vos API HTTP API Gateway. Spécifiez le domaine à autoriser en tant que chaîne ou spécifiez un objet HttpApiCorsConfiguration. Notez que CORS nécessite AWS SAM de modifier votre définition OpenAPI. CORS ne fonctionne donc que si DefinitionBody la propriété est spécifiée.

Pour plus d'informations, consultez la Configuration CORS pour une API HTTP dans le Guide du développeur API Gateway.

Note

Il CorsConfiguration est défini à la fois dans une définition OpenAPI et au niveau de la propriété, puis AWS SAM fusionne les deux sources de configuration avec les propriétés prioritaires. Si cette propriété est définie sur true, alors toutes les origines sont autorisées.

Type : Chaîne | HttpApiCorsConfiguration

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.

DefaultRouteSettings

Les paramètres d'acheminement par défaut pour cette API HTTP. Ces paramètres s'appliquent à tous les acheminements sauf s'ils sont remplacés par le paramètre RouteSettings pour certains acheminements.

Type : RouteSettings

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la RouteSettings propriété d'une AWS::ApiGatewayV2::Stage ressource.

DefinitionBody

La définition OpenAPI qui décrit votre API HTTP. Si vous ne spécifiez pas a DefinitionUri ou aDefinitionBody, AWS SAM génère un DefinitionBody pour vous en fonction de la configuration de votre modèle.

Type : JSON

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est similaire à celle Body d'une AWS::ApiGatewayV2::Api ressource. Si certaines propriétés sont fournies, vous AWS SAM pouvez y insérer du contenu ou le modifier DefinitionBody avant qu'il ne soit transmis à AWS CloudFormation. Les propriétés incluent le type Auth et le type EventSource HttpApi de la AWS::Serverless::Function ressource correspondante.

DefinitionUri

L'URI Amazon Simple Storage Service (Amazon S3), le chemin d'accès au fichier local ou l'objet d'emplacement de la définition OpenAPI qui définit l'API HTTP. L'objet Amazon S3 auquel cette propriété fait référence doit être un fichier de définition OpenAPI valide. Si vous ne spécifiez pas a DefinitionUri ou n'DefinitionBodyêtes pas spécifié, AWS SAM génère un DefinitionBody pour vous en fonction de la configuration de votre modèle.

Si vous fournissez un chemin d'accès au fichier local, le modèle doit passer par le flux de travail qui inclut le fichier sam deploy ou la commande sam package pour que la définition soit correctement transformée.

Les fonctions intrinsèques ne sont pas prises en charge dans les fichiers de OpenApi définition externes auxquels vous faites référenceDefinitionUri. Pour importer une OpenApi définition dans le modèle, utilisez la DefinitionBody propriété avec la transformation Include.

Type : Chaîne | HttpApiDefinition

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est similaire à celle BodyS3Location d'une AWS::ApiGatewayV2::Api ressource. Les propriétés imbriquées d'Amazon S3 sont nommées différemment.

Description

Description de la ressource d'API HTTP.

Lorsque vous spécifiezDescription, la OpenApi définition de la ressource d'API HTTP AWS SAM sera modifiée en définissant le description champ. Les scénarios suivants entraînent une erreur :

La DefinitionBody propriété est spécifiée avec le description champ défini dans la définition de l'API ouverte. Cela entraîne un conflit de description champ qui AWS SAM ne sera pas résolu.
La DefinitionUri propriété est spécifiée : elle AWS SAM ne modifiera pas une définition d'API ouverte extraite d'Amazon S3.

Type : chaîne

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.

DisableExecuteApiEndpoint

Spécifie si les clients peuvent appeler votre API à l'aide du point de terminaison execute-api par défaut https://{api_id}.execute-api.{region}.amazonaws.com. Par défaut, les clients peuvent appeler votre API avec le point de terminaison par défaut. Pour exiger que les clients utilisent uniquement un nom de domaine personnalisé pour appeler votre API, désactivez le point de terminaison par défaut.

Pour utiliser cette propriété, vous devez spécifier la DefinitionBody propriété au lieu de la DefinitionUri propriété ou définir x-amazon-apigateway-endpoint-configuration avec disableExecuteApiEndpoint dans votre définition OpenAPI.

Type : valeur booléenne

Obligatoire : non

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

Domain

Configure un domaine personnalisé pour cette API HTTP API Gateway.

Type : HttpApiDomainConfiguration

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.

FailOnWarnings

Spécifie si la création d'API HTTP 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::ApiGatewayV2::Api ressource.

Name

Nom de la ressource d'API HTTP.

Lorsque vous le spécifiezName, AWS SAM il modifiera la définition OpenAPI de la ressource d'API HTTP en définissant le title champ. Les scénarios suivants entraînent une erreur :

La DefinitionBody propriété est spécifiée avec le title champ défini dans la définition de l'API ouverte. Cela entraîne un conflit de title champ qui AWS SAM ne sera pas résolu.
La DefinitionUri propriété est spécifiée : elle AWS SAM ne modifiera pas une définition d'API ouverte extraite d'Amazon S3.

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

RouteSettings

Les paramètres d'acheminement par acheminement pour cette API HTTP. Pour plus d'informations, consultez Utilisation des acheminements pour API HTTP dans le Guide du développeur API Gateway.

Type : RouteSettings

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la RouteSettings propriété d'une AWS::ApiGatewayV2::Stage ressource.

StageName

Le nom de l'étape d'API. Si aucun nom n'est spécifié, AWS SAM utilise le $default stage d'API Gateway.

Type : chaîne

Obligatoire : non

Par défaut : $default

AWS CloudFormation compatibilité : cette propriété est transmise directement à la StageName propriété d'une AWS::ApiGatewayV2::Stage ressource.

StageVariables

Mappage qui définit les variables de l'étape. Les noms de variables peuvent comporter des caractères alphanumériques et des caractères de soulignement. Les valeurs doivent correspondre à [A-Za-Z0-9-._~ :/ ? #&=,] +.

Type : Json

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est transmise directement à la StageVariables propriété d'une AWS::ApiGatewayV2::Stage ressource.

Tags

Un mappage (chaîne à chaîne) qui spécifie les balises à ajouter à cette étape API Gateway. Les clés peuvent comporter de 1 à 128 caractères Unicode de longueur et ne peuvent pas être précédée du préfixe aws:. Les caractères suivants sont acceptés : l'ensemble des lettres Unicode, les chiffres, les espaces, _, ., /, =, + et -. Les valeurs de balise doivent comporter de 1 à 256 caractères Unicode en longueur.

Type: carte (map)

Obligatoire : non

AWS CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' AWS CloudFormation équivalent.

Remarques supplémentaires : La Tags propriété nécessite de AWS SAM modifier votre définition OpenAPI, de sorte que les balises ne sont ajoutées que si la DefinitionBody propriété est spécifiée ; aucune balise n'est ajoutée si la propriété est spécifiée. DefinitionUri AWS SAM ajoute automatiquement un httpapi:createdBy:SAM tag. Les balises sont également ajoutées à la ressource AWS::ApiGatewayV2::Stage et à la ressource AWS::ApiGatewayV2::DomainName (si le DomainName est spécifié).

Valeurs renvoyées

Réf

Lorsque vous transmettez l'ID logique de cette ressource à la fonction intrinsèque Ref, Ref renvoie l'ID API de la ressource sous-jacente AWS::ApiGatewayV2::Api, par exemple, a1bcdef2gh.

Pour plus d'informations sur l'utilisation de la fonction Ref, consultez Ref dans le Guide de l'utilisateur AWS CloudFormation .

Exemples

Simple HttpApi

L'exemple suivant montre le minimum nécessaire pour configurer un point de terminaison d'API HTTP soutenu par une fonction Lambda. Cet exemple utilise l'API HTTP par défaut qui AWS SAM crée.

YAML


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS SAM template with a simple API definition
Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: HttpApi
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Runtime: python3.7
Transform: AWS::Serverless-2016-10-31

HttpApi avec Auth

L'exemple suivant montre comment configurer l'autorisation sur les points de terminaison d'API HTTP.

YAML


Properties:
  FailOnWarnings: true
  Auth:
    DefaultAuthorizer: OAuth2
    Authorizers:
      OAuth2:
        AuthorizationScopes:
          - scope4
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oauth2"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

HttpApiavec définition OpenAPI

L'exemple suivant montre comment ajouter une définition OpenAPI au modèle.

Notez que toutes AWS SAM les intégrations Lambda manquantes sont renseignées pour les HttpApi événements faisant référence à cette API HTTP. AWS SAM ajoute également tous les chemins manquants auxquels les HttpApi événements font référence.

YAML


Properties:
  FailOnWarnings: true
  DefinitionBody:
    info:
      version: '1.0'
      title:
        Ref: AWS::StackName
    paths:
      "/":
        get:
          security:
          - OpenIdAuth:
            - scope1
            - scope2
          responses: {}
    openapi: 3.0.1
    securitySchemes:
      OpenIdAuth:
        type: openIdConnect
        x-amazon-apigateway-authorizer:
          identitySource: "$request.querystring.param"
          type: jwt
          jwtConfiguration:
            audience:
            - MyApi
            issuer: https://www.example.com/v1/connect/oidc
          openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

HttpApi avec paramètres de configuration

L'exemple suivant montre comment ajouter des configurations d'API HTTP et des configurations d'étape au modèle.

YAML


AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
  StageName:
    Type: String
    Default: Prod
    
Resources:
  HttpApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
          def handler(event, context):
              import json
              return {
                  "statusCode": 200,
                  "body": json.dumps(event),
              }
      Handler: index.handler
      Runtime: python3.7
      Events:
        ExplicitApi: # warning: creates a public endpoint
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: GET
            Path: /path
            TimeoutInMillis: 15000
            PayloadFormatVersion: "2.0"
            RouteSettings:
              ThrottlingBurstLimit: 600

  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      Tags:
        Tag: Value
      AccessLogSettings:
        DestinationArn: !GetAtt AccessLogs.Arn
        Format: $context.requestId
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
      RouteSettings:
        "GET /path":
          ThrottlingBurstLimit: 500 # overridden in HttpApi Event
      StageVariables:
        StageVar: Value
      FailOnWarnings: true

  AccessLogs:
    Type: AWS::Logs::LogGroup

Outputs:
  HttpApiUrl:
    Description: URL of your API endpoint
    Value:
      Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/'
  HttpApiId:
    Description: Api id of HttpApi
    Value:
      Ref: HttpApi

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Environnement d’exécution

HttpApiAuth