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 API HTTP Amazon API Gateway, qui vous permet de créer RESTful APIs avec une latence et des coûts inférieurs à ceux de REST APIs. Pour plus d'informations, consultez la section [Working with HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) dans le *guide du développeur d'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 autorisateurs afin de contrôler l'accès à celles-ci.
Pour plus d'informations sur l'utilisation CloudFormation des hooks, consultez la section [Enregistrement des hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) dans le *guide de l'utilisateur de la CloudFormation CLI* et dans le [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/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](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) 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 CloudFormation ressources. Pour de plus amples informations, veuillez consulter [CloudFormation Ressources générées pour AWS SAM](sam-specification-generated-resources.md).
## 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](#sam-httpapi-accesslogsettings): [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
[Auth](#sam-httpapi-auth): HttpApiAuth
[CorsConfiguration](#sam-httpapi-corsconfiguration): String | HttpApiCorsConfiguration
[DefaultRouteSettings](#sam-httpapi-defaultroutesettings): [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
[DefinitionBody](#sam-httpapi-definitionbody): JSON
[DefinitionUri](#sam-httpapi-definitionuri): String | HttpApiDefinition
[Description](#sam-httpapi-description): String
[DisableExecuteApiEndpoint](#sam-httpapi-disableexecuteapiendpoint): Boolean
[Domain](#sam-httpapi-domain): HttpApiDomainConfiguration
[FailOnWarnings](#sam-httpapi-failonwarnings): Boolean
Name: String
PropagateTags: Boolean
[RouteSettings](#sam-httpapi-routesettings): [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
[StageName](#sam-httpapi-stagename): String
[StageVariables](#sam-httpapi-stagevariables): [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
[Tags](#sam-httpapi-tags): Map
```
## Propriétés
`AccessLogSettings`
Les paramètres pour la journalisation des accès dans une étape.
*Type :* [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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 la section [Contrôle de l'accès au protocole HTTP APIs avec les autorisateurs JWT](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) dans le guide du *développeur d'API Gateway*.
*Type :* [HttpApiAuth](sam-property-httpapi-httpapiauth.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`CorsConfiguration`
Gère le partage de ressources entre origines (CORS) pour tous vos API Gateway HTTP. APIs 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html) dans le *Guide du développeur API Gateway*.
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 \$1 [HttpApiCorsConfiguration](sam-property-httpapi-httpapicorsconfiguration.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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 a`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 à celle `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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 à 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érence`DefinitionUri`. Pour importer une OpenApi définition dans le modèle, utilisez la `DefinitionBody` propriété avec la [transformation Include](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html).
*Type* : Chaîne \$1 [HttpApiDefinition](sam-property-httpapi-httpapidefinition.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est similaire à celle `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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écifiez`Description`, 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
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' 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
*CloudFormation compatibilité* : cette propriété est similaire à celle `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` d'une `AWS::ApiGatewayV2::Api` ressource. Il est transmis directement à la propriété `disableExecuteApiEndpoint` d'une extension `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)`, qui est ajoutée à la propriété ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` d'une ressource `AWS::ApiGatewayV2::Api`.
`Domain`
Configure un domaine personnalisé pour cette API HTTP API Gateway.
*Type :* [HttpApiDomainConfiguration](sam-property-httpapi-httpapidomainconfiguration.md)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' 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 à la `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-failonwarnings)` propriété d'une `AWS::ApiGatewayV2::Api` ressource.
`Name`
Nom de la ressource d'API HTTP.
Lorsque vous le spécifiez`Name`, 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
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.
`PropagateTags`
Indiquez s'il faut ou non transmettre les balises de la propriété `Tags` aux ressources [AWS::Serverless::HttpApi](sam-specification-generated-resources-httpapi.md) 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 d' CloudFormation équivalent.
`RouteSettings`
Les paramètres d'acheminement par acheminement pour cette API HTTP. Pour plus d'informations, consultez la section [Travailler avec des routes pour le protocole HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html) dans le *guide du développeur d'API Gateway*.
*Type :* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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* : \$1default
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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-.\$1\$1 :/ ? \$1&=,] \$1.
*Type* : [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
*Obligatoire* : non
*CloudFormation compatibilité* : cette propriété est transmise directement à la `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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
*CloudFormation compatibilité* : cette propriété est unique AWS SAM et n'a pas d' 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 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) 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"
```
### HttpApi avec 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
```