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
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.
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.
YAML
Type: AWS::Serverless::HttpApi Properties: AccessLogSettings:AccessLogSettingsAuth:HttpApiAuthCorsConfiguration:String | HttpApiCorsConfigurationDefaultRouteSettings:RouteSettingsDefinitionBody:JSONDefinitionUri:String | HttpApiDefinitionDescription:StringDisableExecuteApiEndpoint:BooleanDomain:HttpApiDomainConfigurationFailOnWarnings:BooleanName:StringPropagateTags:BooleanRouteSettings:RouteSettingsStageName:StringStageVariables:JsonTags:Map
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
AccessLogSettingspropriété d'unAWS::ApiGatewayV2::Stageressource. -
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 siDefinitionBodyla 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.
NoteSi
CorsConfigurationest 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 surtrue, 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
RouteSettingspour certains acheminements.Type : RouteSettings
Obligatoire : non
CloudFormation compatibilité: Cette propriété est transmise directement au
RouteSettingspropriété d'unAWS::ApiGatewayV2::Stageressource. -
DefinitionBody -
La définition OpenAPI qui décrit votre API HTTP. Si vous ne spécifiez pas de
DefinitionUriou unDefinitionBody, AWS SAM génère unDefinitionBodypour vous en fonction de la configuration de votre modèle.Type : JSON
Obligatoire : non
CloudFormation compatibilité: Cette propriété est similaire à la
Bodypropriété d'unAWS::ApiGatewayV2::Apiressource. Si certaines propriétés sont fournies, AWS SAM peut insérer du contenu dans ou modifier leDefinitionBodyavant qu'il ne soit transmis à CloudFormation. Les propriétés incluentAuthet unEventSourcede type HttpApi pour un correspondantAWS::Serverless::Functionressource. -
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
DefinitionUriou unDefinitionBodysont spécifiés, AWS SAM génère unDefinitionBodypour 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 deployou la commandesam packagepour 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 leDefinitionBodypropriété avec Inclure la transformation.Tapez: Chaîne | HttpApiDefinition
Obligatoire : non
CloudFormation compatibilité: Cette propriété est similaire à la
BodyS3Locationpropriété d'unAWS::ApiGatewayV2::Apiressource. 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églantdescriptionchamp. Les scénarios suivants entraînent une erreur :-
Le
DefinitionBodyla propriété est spécifiée avecdescriptionchamp défini dans la définition de l'API ouverte — Cela entraîne un conflit entredescriptionchamp qui AWS SAM ne se résoudra pas. -
Le
DefinitionUrila 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-apipar défauthttps://{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
DefinitionBodypropriété au lieu deDefinitionUripropriété ou définitionx-amazon-apigateway-endpoint-configurationavecdisableExecuteApiEndpointdans votre définition OpenAPI.Type : valeur booléenne
Obligatoire : non
CloudFormation compatibilité: Cette propriété est similaire à la
DisableExecuteApiEndpointpropriété d'unAWS::ApiGatewayV2::Apiressource. Il est transmis directement à la propriétédisableExecuteApiEndpointd'une extensionx-amazon-apigateway-endpoint-configuration, qui est ajoutée à la propriétéBodyd'une ressourceAWS::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 estfalse.Type : valeur booléenne
Obligatoire : non
CloudFormation compatibilité: Cette propriété est transmise directement au
FailOnWarningspropriété d'unAWS::ApiGatewayV2::Apiressource. 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éfinissanttitlechamp. Les scénarios suivants entraînent une erreur :-
Le
DefinitionBodyla propriété est spécifiée avectitlechamp défini dans la définition de l'API ouverte — Cela entraîne un conflit entretitlechamp qui AWS SAM ne se résoudra pas. -
Le
DefinitionUrila 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.
-
-
Indiquez s'il faut ou non transmettre les balises de la propriété
Tagsaux ressources AWS::Serverless::HttpApi 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 :
FalseCloudFormation 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
RouteSettingspropriété d'unAWS::ApiGatewayV2::Stageressource. -
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
StageNamepropriété d'unAWS::ApiGatewayV2::Stageressource. -
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
StageVariablespropriété d'unAWS::ApiGatewayV2::Stageressource. -
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
Tagsla propriété nécessite AWS SAM pour modifier votre définition OpenAPI, afin que les balises ne soient ajoutées que siDefinitionBodyla propriété est spécifiée : aucune balise n'est ajoutée siDefinitionUrila propriété est spécifiée. AWS SAM ajoute automatiquement unhttpapi:createdBy:SAMétiquette. Les balises sont également ajoutées à la ressourceAWS::ApiGatewayV2::Stageet à la ressourceAWS::ApiGatewayV2::DomainName(si leDomainNameest 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