View a markdown version of this page

AWS::Serverless::HttpApi - 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::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 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

AccessLogSettings

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

Type : AccessLogSettings

Obligatoire : non

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

CloudFormation compatibilité: Cette propriété est unique à AWS SAM et n'a pas de 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 pour modifier votre définition d'OpenAPI, afin que CORS ne fonctionne 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

Si 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, les propriétés étant prioritaires. Si cette propriété est définie sur true, alors toutes les origines sont autorisées.

Tapez: Chaîne | HttpApiCorsConfiguration

Obligatoire : non

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

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

DefinitionBody

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

Type : JSON

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la Body propriété d'un AWS::ApiGatewayV2::Api ressource. Si certaines propriétés sont fournies, AWS SAM peut insérer du contenu dans ou modifier le DefinitionBody avant qu'il ne soit transmis à CloudFormation. Les propriétés incluent Auth et un EventSource de type HttpApi pour un correspondant AWS::Serverless::Function ressource.

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 de DefinitionUri ou un DefinitionBody sont spécifiés, 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 en externe OpenApi fichiers de définition auxquels vous faites référence DefinitionUri. Pour importer un OpenApi définition dans le modèle, utilisez le DefinitionBody propriété avec Inclure la transformation.

Tapez: Chaîne | HttpApiDefinition

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la BodyS3Location propriété d'un 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écifiez Description, AWS SAM modifiera les ressources de l'API HTTP OpenApi définition en réglant description champ. Les scénarios suivants entraînent une erreur :

  • Le DefinitionBody la propriété est spécifiée avec description champ défini dans la définition de l'API ouverte — Cela entraîne un conflit entre description champ qui AWS SAM ne se résoudra pas.

  • Le DefinitionUri la propriété est spécifiée — AWS SAM ne modifiera pas une définition d'API ouverte extraite d'Amazon S3.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité: Cette propriété est unique à AWS SAM et n'a pas de 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 DefinitionBody propriété au lieu de DefinitionUri propriété ou définition x-amazon-apigateway-endpoint-configuration avec disableExecuteApiEndpoint dans votre définition OpenAPI.

Type : valeur booléenne

Obligatoire : non

CloudFormation compatibilité: Cette propriété est similaire à la DisableExecuteApiEndpoint propriété d'un 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

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

CloudFormation compatibilité: Cette propriété est transmise directement au FailOnWarnings propriété d'un AWS::ApiGatewayV2::Api ressource.

Name

Nom de la ressource d'API HTTP.

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

  • Le DefinitionBody la propriété est spécifiée avec title champ défini dans la définition de l'API ouverte — Cela entraîne un conflit entre title champ qui AWS SAM ne se résoudra pas.

  • Le DefinitionUri la propriété est spécifiée — AWS SAM ne modifiera pas une définition d'API ouverte extraite d'Amazon S3.

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

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

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

StageName

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

Type : chaîne

Obligatoire : non

Par défaut : $default

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

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

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

Remarques supplémentaires: Les Tags la propriété nécessite AWS SAM pour modifier votre définition OpenAPI, afin que les balises ne soient ajoutées que si DefinitionBody la propriété est spécifiée : aucune balise n'est ajoutée si DefinitionUri la propriété est spécifiée. AWS SAM ajoute automatiquement un httpapi:createdBy:SAM étiquette. 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 requis pour configurer un point de terminaison d'API HTTP soutenu par une fonction événementielle 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"

HttpApi avec définition OpenAPI

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

Notez que AWS SAM remplit toutes les intégrations Lambda manquantes pour HttpApi événements qui font référence à cette API HTTP. AWS SAM ajoute également tous les chemins manquants qui HttpApi référence des événements.

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