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.
# API HTTP API Gateway
Les API REST et les API HTTP sont toutes des produits d’API RESTful. Les API REST prennent en charge plus de fonctionnalités que les API HTTP, tandis que les API HTTP sont conçues avec un minimum de fonctionnalités afin de pouvoir être proposées à un prix inférieur. Pour de plus amples informations, consultez [Choisissez entre REST APIs et HTTP APIs](http-api-vs-rest.md).
Vous pouvez utiliser les API HTTP pour envoyer des demandes à des fonctions AWS Lambda ou à n’importe quel point de terminaison HTTP routable. Par exemple, vous pouvez créer une API HTTP qui s’intègre avec une fonction Lambda sur le backend. Lorsqu’un client appelle votre API, API Gateway envoie la demande à la fonction Lambda et renvoie la réponse de la fonction au client.
Les API HTTP prennent en charge [OpenID Connect](https://openid.net/developers/how-connect-works/) et l’autorisation [OAuth 2.0](https://oauth.net/2/). Ils sont fournis avec la prise en charge intégrée du partage de ressources d’origine croisée (CORS) et des déploiements automatiques.
Vous pouvez créer des API HTTP à l’aide de la console de gestion AWS, de l’AWS CLI, des API, de CloudFormation ou des SDK.
**Topics**
+ [
# Développement du protocole HTTP APIs dans API Gateway
](http-api-develop.md)
+ [
# Publication d’API HTTP invocables par les clients
](http-api-publish.md)
+ [
# Protection de vos API HTTP dans API Gateway
](http-api-protect.md)
+ [
# Surveiller le protocole HTTP APIs dans API Gateway
](http-api-monitor.md)
+ [
# Résolution des problèmes des API HTTP dans API Gateway
](http-api-troubleshooting.md)
# Développement du protocole HTTP APIs dans API Gateway
Cette section fournit des détails sur les fonctionnalités d'API Gateway dont vous avez besoin pour développer votre API Gateway APIs.
Au fur et à mesure que vous développez votre API API Gateway, vous décidez d’un certain nombre de caractéristiques de votre API. Ces caractéristiques dépendent du cas d’utilisation de votre API. Par exemple, vous pourriez vouloir autoriser uniquement certains clients à appeler votre API ou qu’elle soit disponible pour tout le monde. Vous pouvez souhaiter utiliser un appel d’API pour exécuter une fonction Lambda, créer une requête de base de données ou appeler une application.
**Topics**
+ [
## Création d’une API HTTP
](#http-api-examples)
+ [
# Création de routes pour HTTP APIs dans API Gateway
](http-api-develop-routes.md)
+ [
# Types d’adresses IP pour les API HTTP dans API Gateway
](http-api-ip-address-type.md)
+ [
# Contrôler et gérer l'accès au protocole HTTP APIs dans API Gateway
](http-api-access-control.md)
+ [
# Création d’intégrations pour les API HTTP dans API Gateway
](http-api-develop-integrations.md)
+ [
# Configurer CORS pour HTTP APIs dans API Gateway
](http-api-cors.md)
+ [
# Transformation des demandes et des réponses d’API HTTP dans API Gateway
](http-api-parameter-mapping.md)
+ [
# Utiliser les définitions OpenAPI pour HTTP APIs dans API Gateway
](http-api-open-api.md)
## Création d’une API HTTP
Pour créer une API fonctionnelle, vous devez disposer d’au moins une route, une intégration, une étape et un déploiement.
Les exemples suivants montrent comment créer une API avec une intégration AWS Lambda ou HTTP, une route et une étape par défaut configurée pour déployer automatiquement les modifications.
Ce guide suppose que vous connaissez déjà API Gateway et Lambda. Pour obtenir un guide plus détaillé, consultez [Mise en route avec API Gateway](getting-started.md).
**Topics**
+ [
### Créez une API HTTP à l'aide du AWS Management Console
](#apigateway-http-api-create.console)
+ [
### Création d'une API HTTP à l'aide de la AWS CLI
](#http-api-examples.cli.quick-create)
### Créez une API HTTP à l'aide du AWS Management Console
1. Ouvrez la [console API Gateway](https://console.aws.amazon.com/apigateway).
1. Sélectionnez **Create API (Créer une API)**.
1. Sous **API HTTP**, choisissez **Créer**.
1. Choisissez **Ajouter une intégration**, puis choisissez une fonction AWS Lambda ou entrez un point de terminaison HTTP.
1. Dans **Name (Nom)**, entrez le nom de votre API.
1. Choisissez **Review and create**.
1. Choisissez **Créer**.
Maintenant, votre API est prête à être appelée. Vous pouvez tester votre API en entrant son URL d'appel dans un navigateur, ou en utilisant Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
### Création d'une API HTTP à l'aide de la AWS CLI
Vous pouvez utiliser la création rapide pour créer une API avec une intégration Lambda ou HTTP, une route fourre-tout par défaut et une étape par défaut configurée pour déployer automatiquement les modifications. La commande [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) suivante utilise la création rapide pour créer une API qui s’intègre avec une fonction Lambda sur le backend.
**Note**
Pour appeler une intégration Lambda, API Gateway doit disposer des autorisations requises. Vous pouvez utiliser une politique basée sur les ressources ou un rôle IAM pour accorder des autorisations API Gateway permettant d’appeler une fonction Lambda. Pour en savoir plus, consultez la section [AWS Lambda Permissions](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) dans le *guide du AWS Lambda développeur*.
**Example**
```
aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name
```
Maintenant, votre API est prête à être appelée. Vous pouvez tester votre API en entrant son URL d'appel dans un navigateur, ou en utilisant Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
# Création de routes pour HTTP APIs dans API Gateway
Route les demandes d’API entrantes directes vers les ressources dorsales. Les routes se composent de deux parties : une méthode HTTP et un chemin de ressource (, par exemple, `GET /pets`. Vous pouvez définir des méthodes HTTP spécifiques pour votre route. Vous pouvez également utiliser la méthode `ANY` pour faire correspondre toutes les méthodes que vous n’avez pas définies pour une ressource. Vous pouvez créer une route `$default` qui agit comme un fourre-tout pour les demandes qui ne correspondent à aucune autre route.
**Note**
API Gateway décode les paramètres de demande encodés par URL avant de les transmettre à votre intégration backend.
## Utilisation des variables de chemin
Vous pouvez utiliser des variables de chemin dans les itinéraires des API HTTP.
Par exemple, la route `GET /pets/{petID}` attrape une demande `GET` qu’un client soumet à `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6`.
Une *variable de chemin gourmande* capture toutes les ressources enfants d’une route. Pour créer une variable de chemin gourmande, ajoutez `+` au nom de la variable (`{proxy+}`, par exemple). La variable de chemin gourmande doit se trouver à la fin du chemin de ressource.
## Utilisation des paramètres de chaîne de requête
Par défaut, API Gateway envoie les paramètres de chaîne de requête à votre intégration backend s’ils sont inclus dans une demande adressée à une API HTTP.
Par exemple, lorsqu’un client envoie une demande à `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`, les paramètres de chaîne de requête `?id=4&type=dog` sont envoyés à votre intégration.
## Utilisation de la route `$default`
La route `$default` attrape les demandes qui ne correspondent pas explicitement aux autres routes de votre API.
Lorsque la route `$default` reçoit une demande, API Gateway envoie le chemin de demande complet à l’intégration. Par exemple, vous pouvez créer une API avec seulement une route `$default` et l’intégrer à la méthode `ANY` avec le point de terminaison HTTP `https://petstore-demo-endpoint.execute-api.com`. Lorsque vous envoyez une demande à `https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`, API Gateway envoie une demande à `https://petstore-demo-endpoint.execute-api.com/store/checkout`.
Pour en savoir plus sur les intégrations HTTP, consultez [Création d'intégrations de proxy HTTP pour HTTP APIs](http-api-develop-integrations-http.md).
## Routage des demandes d'API
Lorsqu’un client envoie une demande d’API, API Gateway détermine d’abord à quelle [étape](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html) doit être acheminée la demande. Si la demande correspond explicitement à une étape, API Gateway envoie la demande à cette dernière. Si aucune étape ne correspond entièrement à la demande, API Gateway envoie la demande à l’étape `$default`. S'il n'y a pas d'`$default`étape, l'API revient `{"message":"Not Found"}` et ne génère pas de CloudWatch journaux.
Après avoir sélectionné une étape, API Gateway sélectionne une route. API Gateway sélectionne la route avec la correspondance la plus spécifique, en utilisant les priorités suivantes :
1. Correspondance complète pour une route et une méthode.
1. Correspondance pour une route et une méthode avec une variable de chemin gourmande (`{proxy+}`).
1. La route `$default`
Si aucune route ne correspond à une demande, API Gateway retourne `{"message":"Not Found"}` au client.
Par exemple, examinez une API avec une étape `$default` et les exemples de routes suivants :
1. `GET /pets/dog/1`
1. `GET /pets/dog/{id}`
1. `GET /pets/{proxy+}`
1. `ANY /{proxy+}`
1. `$default`
Le tableau suivant résume la façon dont API Gateway achemine les demandes vers les routes de l’exemple.
| Requête | Route sélectionnée | Explication |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | La demande correspond entièrement à cette route statique. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | La demande correspond entièrement à cette route. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | La demande ne correspond pas entièrement à une route. La route avec une méthode `GET` et une variable de chemin gourmande attrape cette requête. |
| `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | La méthode `ANY` correspond à toutes les méthodes que vous n’avez pas définies pour une route. Les routes avec des variables de chemin gourmandes ont une priorité plus élevée que la route `$default`. |
# Types d’adresses IP pour les API HTTP dans API Gateway
Lorsque vous créez une API, vous spécifiez le type d’adresses IP qui peut invoquer votre API. Vous avez le choix entre IPv4 (pour autoriser les adresses IPv4 à invoquer votre API) et Dualstack (pour autoriser les adresses IPv4 et IPv6 à invoquer votre API). Vous pouvez définir le type d’adresse IP sur Dualstack pour éviter l’épuisement de l’espace IP ou renforcer votre niveau de sécurité. Pour plus d’informations sur les avantages d’un type d’adresse IP à double pile, consultez [IPv6 sur AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considérations relatives aux types d’adresses IP
Les considérations suivantes peuvent avoir une incidence sur votre utilisation des types d’adresses IP :
+ Le type d’adresses IP par défaut pour toutes les API HTTP est IPv4.
+ Si vous remplacez le type d’adresse IP IPv4 d’une API existante par un type d’adresse IP à double pile, vérifiez que toutes les stratégies d’accès à vos API ont été mises à jour pour prendre en compte les appels IPv6. La modification du type d’adresse IP prend effet immédiatement.
+ Votre API peut être mappée à un nom de domaine personnalisé présentant un type d’adresse IP différent de celui de votre API. La désactivation du point de terminaison de votre API par défaut peut avoir une incidence sur la manière dont les appelants peuvent invoquer votre API.
## Modification du type d’adresse IP d’une API HTTP
Vous pouvez modifier le type d’adresse IP en mettant à jour la configuration de l’API. Vous pouvez mettre à jour la configuration de l’API à l’aide de la AWS Management Console, de l’AWS CLI, d’CloudFormation ou d’un kit SDK AWS. Si vous modifiez le type d’adresse IP de l’API, vous n’avez pas besoin de redéployer votre API pour que les modifications prennent effet.
------
#### [ AWS Management Console ]
**Pour modifier le type d’adresse IP d’une API HTTP**
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez une API HTTP.
1. Pour **Paramètres de l’API**, choisissez **Modifier**.
1. Pour Type d’adresse IP, choisissez **IPv4** ou **Dualstack**.
1. Choisissez **Save (Enregistrer)**.
La modification de la configuration de votre API prend effet immédiatement.
------
#### [ AWS CLI ]
La commande [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) suivante met à jour une API pour qu’elle possède le type d’adresse IP Dualstack :
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
Le résultat se présente comme suit :
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-HTTP-API",
"ProtocolType": "HTTP",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Contrôler et gérer l'accès au protocole HTTP APIs dans API Gateway
API Gateway prend en charge plusieurs mécanismes pour contrôler et gérer l’accès à votre API :
+ Les **autorisateurs Lambda utilisent** les fonctions Lambda pour contrôler l'accès à. APIs Pour de plus amples informations, veuillez consulter [Contrôlez l'accès au HTTP APIs avec des AWS Lambda autorisateurs](http-api-lambda-authorizer.md).
+ **Les autorisateurs JWT utilisent des** jetons Web JSON pour contrôler l'accès à. APIs Pour de plus amples informations, veuillez consulter [Contrôlez l'accès au HTTP APIs avec les autorisateurs JWT dans API Gateway](http-api-jwt-authorizer.md).
+ Les **rôles et politiques AWS IAM standard** offrent des contrôles d'accès flexibles et robustes. Vous pouvez utiliser les rôles et les politiques IAM pour contrôler qui peut les créer et les gérer APIs, ainsi que les personnes habilitées à les invoquer. Pour de plus amples informations, veuillez consulter [Contrôlez l'accès au HTTP APIs avec l'autorisation IAM dans API Gateway](http-api-access-control-iam.md).
Pour renforcer votre posture de sécurité, nous vous recommandons de configurer un mécanisme d’autorisation pour toutes les routes de votre API HTTP. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) dans le *Guide de l’utilisateur AWS Security Hub *.
# Contrôlez l'accès au HTTP APIs avec des AWS Lambda autorisateurs
Vous utilisez un mécanisme d’autorisation Lambda pour contrôler l’accès à votre API HTTP à l’aide d’une fonction Lambda. Ensuite, lorsqu’un client appelle votre API, API Gateway appelle votre fonction Lambda. API Gateway utilise la réponse de votre fonction Lambda pour déterminer si le client peut accéder à votre API.
## Version du format de charge utile
La version du format de charge utile de l’autorisation spécifie le format des données qu’API Gateway envoie à un mécanisme d’autorisation Lambda, et la façon dont API Gateway interprète la réponse de Lambda. Si vous ne spécifiez pas de version de format de charge utile, la dernière version est AWS Management Console utilisée par défaut. Si vous créez un autorisateur Lambda à l'aide du AWS CLI, ou d'un SDK CloudFormation, vous devez spécifier un. `authorizerPayloadFormatVersion` Les valeurs prises en charge sont `1.0` et `2.0`.
Si vous avez besoin de compatibilité avec REST APIs, utilisez la version`1.0`.
Les exemples suivants montrent la structure de chaque version de format de charge utile.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"header1": "value1",
"header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
------
## Format de réponse du mécanisme d’autorisation Lambda
La version du format de charge utile détermine également la structure de la réponse que vous devez renvoyer à partir de votre fonction Lambda.
### Réponse de la fonction Lambda pour le format 1.0
Si vous choisissez la version de format `1.0`, les mécanismes d’autorisation Lambda doivent renvoyer une politique IAM qui autorise ou refuse l’accès à votre route d’API. Vous pouvez utiliser la syntaxe de politique standard IAM dans la politique. Pour obtenir des exemples de politiques IAM, consultez [Contrôler l’accès pour l’appel d’une API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Vous pouvez transmettre des propriétés de contexte aux intégrations Lambda ou accéder aux journaux avec `$context.authorizer.property`. L’objet `context` est facultatif et `claims` est un espace réservé qui ne peut être utilisé comme objet contextuel. Pour en savoir plus, consultez la section [Personnalisation des journaux d’accès pour les API HTTP](http-api-logging-variables.md).
**Example**
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
### Réponse de la fonction Lambda pour le format 2.0
Si vous choisissez la version de format `2.0`, vous pouvez renvoyer une valeur booléenne ou une politique IAM qui utilise la syntaxe de politique IAM standard de votre fonction Lambda. Pour renvoyer une valeur booléenne, activez des réponses simples pour le mécanisme d’autorisation. Les exemples suivants montrent le format que vous devez coder pour retourner votre fonction Lambda. L’objet `context` est facultatif. Vous pouvez transmettre des propriétés de contexte aux intégrations Lambda ou accéder aux journaux avec `$context.authorizer.property`. Pour en savoir plus, consultez la section [Personnalisation des journaux d’accès pour les API HTTP](http-api-logging-variables.md).
------
#### [ Simple response ]
```
{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}
```
------
#### [ IAM policy ]
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
------
## Exemple de fonctions d’autorisation Lambda
Les exemples de fonction Lambda Node.js suivants illustrent les formats de réponse requis que vous devez renvoyer à partir de votre fonction Lambda pour la version du format de charge utile `2.0`.
------
#### [ Simple response - Node.js ]
```
export const handler = async(event) => {
let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
if (event.headers.authorization === "secretToken") {
console.log("allowed");
response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}
return response;
};
```
------
#### [ Simple response - Python ]
```
import json
def lambda_handler(event, context):
response = {
"isAuthorized": False,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
"isAuthorized": True,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
#### [ IAM policy - Node.js ]
```
export const handler = async(event) => {
if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};
```
------
#### [ IAM policy - Python ]
```
import json
def lambda_handler(event, context):
response = {
# The principal user identification associated with the token sent by
# the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
# The principal user identification associated with the token
# sent by the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
## Sources d’identité
Si vous le souhaitez, vous pouvez spécifier des sources d’identité pour un mécanisme d’autorisation Lambda. Les sources d’identité spécifient l’emplacement des données requises pour autoriser une demande. Par exemple, vous pouvez spécifier des valeurs d’en-tête ou de chaîne de requête en tant que sources d’identité. Si vous spécifiez des sources d’identité, les clients doivent les inclure dans la demande. Si la demande du client n’inclut pas les sources d’identité, API Gateway n’appelle pas votre mécanisme d’autorisation Lambda et le client reçoit une erreur `401`.
Le tableau suivant décrit les sources d’identité prises en charge pour un mécanisme d’autorisation Lambda.
| **Type** | **Exemple** | **Remarques** |
| --- | --- | --- |
| Valeur d'en-tête | \$1request.header. name | Les noms d'en-tête ne sont pas sensibles à la casse. |
| Valeur de chaîne de requête | \$1request.querystring. name | Les noms de chaîne de requête sont sensibles à la casse. |
| Variable de contexte | \$1contexte. variableName | Valeur d'une [variable de contexte](http-api-logging-variables.md) prise en charge. |
| Variable d'étape | \$1StageVariables. variableName | Valeur d'une [variable d'étape](http-api-stages.stage-variables.md). |
Vous pouvez également renvoyer directement ` {"errorMessage" : "Unauthorized"}` de votre fonction Lambda pour renvoyer une erreur `401` à vos clients. Si vous renvoyez directement une erreur `401` de votre fonction Lambda à vos clients, ne spécifiez aucune source d’identité lorsque vous créez votre mécanisme d’autorisation Lambda.
## Mise en cache des réponses du mécanisme d’autorisation
Vous pouvez activer la mise en cache pour un autorisateur Lambda en spécifiant un. [authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds) Lorsque la mise en cache est activée pour un mécanisme d’autorisation, API Gateway utilise les sources d’identité de ce mécanisme comme clé de cache. Si un client spécifie les mêmes paramètres dans les sources d’identité au sein de la TTL configurée, API Gateway utilise le résultat du mécanisme d’autorisation mis en cache, plutôt que d’appeler votre fonction Lambda.
Pour activer la mise en cache, votre mécanisme d’autorisation doit avoir au moins une source d’identité.
Si vous activez des réponses simples pour un mécanisme d’autorisation, la réponse de ce mécanisme autorise ou refuse totalement toutes les demandes d’API qui correspondent aux valeurs de source d’identité mises en cache. Pour obtenir des autorisations plus détaillées, désactivez les réponses simples et renvoyez une politique IAM. En fonction de votre mécanisme d’autorisation, votre politique IAM peut avoir besoin de contrôler l’accès à plusieurs éléments.
Par défaut, API Gateway utilise la réponse du mécanisme d’autorisation mise en cache pour toutes les routes d’une API utilisant le mécanisme d’autorisation. Pour mettre en cache les réponses par route, ajoutez `$context.routeKey` aux sources d’identité de votre mécanisme d’autorisation.
## Création d’un mécanisme d’autorisation Lambda
Lorsque vous créez un mécanisme d’autorisation Lambda, vous spécifiez la fonction Lambda qu’API Gateway doit utiliser. Vous devez accorder l’autorisation à API Gateway d’appeler la fonction Lambda à l’aide de la politique de ressources de la fonction ou d’un rôle IAM. La commande [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) suivante crée un mécanisme d’autorisation Lambda :
```
aws apigatewayv2 create-authorizer \
--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses
```
La commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) suivante met à jour la stratégie de ressources de la fonction Lambda afin qu’elle autorise API Gateway à invoquer la fonction. Si API Gateway n’a pas l’autorisation d’appeler votre fonction, les clients reçoivent un `500 Internal Server Error`.
```
aws lambda add-permission \
--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"
```
Une fois que vous avez créé un mécanisme d’autorisation et que vous avez accordé à API Gateway l’autorisation de l’appeler, mettez à jour votre route de manière à l’utiliser. La commande [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) suivante ajoute le mécanisme d’autorisation Lambda à la route. Si votre mécanisme d’autorisation Lambda utilise la mise en cache des stratégies, veillez à mettre à jour la politique afin qu’elle contrôle l’accès à la route supplémentaire.
```
aws apigatewayv2 update-route \
--api-id abcdef123 \
--route-id abc123 \
--authorization-type CUSTOM \
--authorizer-id def123
```
## Dépannage des autorisations Lambda
Si API Gateway ne peut pas appeler votre autorisation Lambda, ou si votre mécanisme d’autorisation Lambda renvoie une réponse dans un format non valide, les clients reçoivent un `500 Internal Server Error`.
Pour résoudre les erreurs, [activez la journalisation des accès](http-api-logging.md) pour votre étape d’API. Incluez la variable de journalisation `$context.authorizer.error` dans votre format de journal.
Si les journaux indiquent qu’API Gateway n’a pas l’autorisation d’appeler votre fonction, mettez à jour la politique de ressources de votre fonction ou fournissez un rôle IAM pour accorder à API Gateway l’autorisation d’appeler votre mécanisme d’autorisation.
Si les journaux indiquent que votre fonction Lambda renvoie une réponse non valide, vérifiez qu’elle renvoie une réponse dans le [format requis](#http-api-lambda-authorizer.payload-format-response).
# Contrôlez l'accès au HTTP APIs avec les autorisateurs JWT dans API Gateway
Vous pouvez utiliser des jetons Web JSON (JWTs) dans le cadre des frameworks [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) et [OAuth 2.0](https://oauth.net/2/) pour restreindre l'accès des clients à votre. APIs
Si vous configurez un autorisateur JWT pour un itinéraire de votre API, API Gateway valide les demandes d'API soumises par JWTs les clients. API Gateway autorise ou refuse les demandes basées sur la validation de jeton, et éventuellement, les étendues dans le jeton. Si vous configurez des étendues pour un routage, le jeton doit inclure au moins une des étendues du routage.
Vous pouvez configurer des autorisations distinctes pour chaque route d’une API ou utiliser le même mécanisme d’autorisation pour plusieurs routes.
**Note**
Il n'existe aucun mécanisme standard permettant de différencier les jetons d'accès JWT des autres types de jetons JWTs, tels que les jetons OpenID Connect ID. À moins que vous n’ayez besoin de jetons d’ID pour l’autorisation de l’API, nous vous recommandons de configurer vos routes pour qu’elles requièrent des étendues d’autorisation. Vous pouvez également configurer vos mécanismes d’autorisation JWT pour exiger des émetteurs ou des audiences que votre fournisseur d’identité utilise uniquement lors de l’émission de jetons d’accès JWT.
## Autorisation des demandes d’API avec un mécanisme d’autorisation JWT
API Gateway utilise le workflow général suivant pour autoriser les demandes de routes configurées pour utiliser un mécanisme d’autorisation JWT.
1. Vérifiez [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource) pour un jeton. `identitySource` peut inclure uniquement le jeton, ou le jeton préfixé avec `Bearer`.
1. Décodez le jeton.
1. Vérifiez l’algorithme et la signature du jeton en utilisant la clé publique récupérée auprès du `jwks_uri` de l’émetteur. Actuellement, seuls les algorithmes basés sur RSA sont pris en charge. API Gateway peut mettre en cache la clé publique pendant deux heures. Lorsque vous effectuez la rotation des clés, une bonne pratique consiste à prévoir un délai de grâce pendant lequel les anciennes et les nouvelles clés sont valides.
1. Validez les demandes. API Gateway évalue les demandes de jeton suivantes :
+ [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5) : le jeton doit avoir une demande d’en-tête qui correspond à la clé du `jwks_uri` ayant signé le jeton.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1) : doit correspondre à l’[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configuré pour le mécanisme d’autorisation.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) ou `client_id` : doit correspondre à l’une des entrées [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurées pour le mécanisme d’autorisation. API Gateway ne valide `client_id` que si `aud` n’est pas présent. Si `aud` et `client_id` sont présents, API Gateway évalue `aud`.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – doit être postérieure à l’heure actuelle (UTC).
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – doit être antérieure à l'heure actuelle(UTC).
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – doit être antérieure à l'heure actuelle(UTC).
+ [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) ou `scp` : le jeton doit inclure au moins une des portées dans les [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) de la route.
Si l’une de ces étapes échoue, API Gateway refuse la demande d’API.
Après avoir validé le JWT, API Gateway transmet les revendications du jeton à l’intégration de la route d’API. Les ressources backend, telles que les fonctions Lambda, peuvent accéder aux revendications JWT. Par exemple, si le JWT inclut une revendication d’identité `emailID`, elle est disponible pour une intégration Lambda dans `$event.requestContext.authorizer.jwt.claims.emailID`. Pour plus d’informations sur la charge utile qu’API Gateway envoie aux intégrations Lambda, consultez [Création d'intégrations de AWS Lambda proxy pour HTTP APIs dans API Gateway](http-api-develop-integrations-lambda.md).
## Créer un mécanisme d’autorisation JWT
Avant de créer un mécanisme d’autorisation JWT, vous devez enregistrer une application cliente auprès d’un fournisseur d’identité. Vous devez également avoir créé une API HTTP. Pour obtenir des exemples de création d'une API HTTP, veuillez consulter [Création d’une API HTTP](http-api-develop.md#http-api-examples).
### Création d’un mécanisme d’autorisation JWT à l’aide de la console
La procédure suivante montre comment créer un mécanisme d’autorisation JWT à l’aide de la console.
**Pour créer un mécanisme d’autorisation JWT à l’aide de la console**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API HTTP.
1. Dans le panneau de navigation principal, choisissez **Autorisation**.
1. Choisissez l’onglet **Gérer les mécanismes d’autorisation**.
1. Choisissez **Créer**.
1. Pour **Type du mécanisme d’autorisation**, choisissez **JWT**.
1. Configurez votre mécanisme d’autorisation JWT et spécifiez une **source d’identité** qui définit la source du jeton.
1. Choisissez **Créer**.
#### Créez un autorisateur JWT à l'aide du AWS CLI
La commande [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) suivante crée un mécanisme d’autorisation JWT. Pour `jwt-configuration`, spécifiez les paramètres `Audience` et `Issuer` pour votre fournisseur d’identité. Si vous utilisez Amazon Cognito comme fournisseur d’identité, `IssuerUrl` est `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`.
```
aws apigatewayv2 create-authorizer \
--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=IssuerUrl
```
##### Créez un autorisateur JWT en utilisant AWS CloudFormation
Le CloudFormation modèle suivant crée une API HTTP avec un autorisateur JWT qui utilise Amazon Cognito comme fournisseur d'identité.
La sortie du CloudFormation modèle est une URL pour une interface utilisateur hébergée par Amazon Cognito où les clients peuvent s'inscrire et se connecter pour recevoir un JWT. Une fois qu’un client s’est connecté, il est redirigé vers votre API HTTP avec un jeton d’accès dans l’URL. Pour invoquer l’API avec le jeton d’accès, remplacez le symbole `#` de l’URL par un `?` pour utiliser le jeton comme paramètre de chaîne de requête.
##### Exemple de CloudFormation modèle
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## Mise à jour d’une route pour utiliser un mécanisme d’autorisation JWT
Vous pouvez utiliser la console AWS CLI, le ou un AWS SDK pour mettre à jour un itinéraire afin d'utiliser un autorisateur JWT.
### Mise à jour d’une route pour utiliser un mécanisme d’autorisation JWT à l’aide de la console
La procédure suivante montre comment mettre à jour un mécanisme d’autorisation JWT à l’aide de la console.
**Pour créer un mécanisme d’autorisation JWT à l’aide de la console**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API HTTP.
1. Dans le panneau de navigation principal, choisissez **Autorisation**.
1. Choisissez une méthode, puis sélectionnez votre mécanisme d’autorisation dans le menu déroulant, puis choisissez **Attacher le mécanisme d’autorisation**.
#### Mettez à jour un itinéraire pour utiliser un autorisateur JWT à l'aide du AWS CLI
La commande [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) suivante met à jour une route de manière à ce qu’elle utilise un mécanisme d’autorisation JWT :
```
aws apigatewayv2 update-route \
--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.email
```
# Contrôlez l'accès au HTTP APIs avec l'autorisation IAM dans API Gateway
Vous pouvez activer l’autorisation IAM pour les routes des API HTTP. Lorsque l'autorisation IAM est activée, les clients doivent utiliser [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) pour signer leurs demandes avec AWS des informations d'identification. API Gateway n’appelle votre route API que si le client dispose de l’autorisation `execute-api` pour la route.
L'autorisation IAM pour HTTP APIs est similaire à celle pour [REST APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
**Note**
Les politiques relatives aux ressources ne sont actuellement pas prises en charge pour le protocole HTTP APIs.
Pour des exemples de politiques IAM qui accordent aux clients l'autorisation d'invoquer APIs, consultez[Contrôler l’accès pour l’appel d’une API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
## Activation d’une autorisation IAM pour une route
La commande [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) suivante active l’autorisation IAM pour une route d’API HTTP :
```
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM
```
# Création d’intégrations pour les API HTTP dans API Gateway
Les *intégrations* connectent une route aux ressources backend. Les API HTTP prennent en charge les intégrations de proxy Lambda, de service AWS et de proxy HTTP. Par exemple, vous pouvez configurer une demande `POST` sur la route `/signup` de votre API pour l’intégrer avec une fonction Lambda qui gère l’inscription des clients.
**Topics**
+ [
# Création d'intégrations de AWS Lambda proxy pour HTTP APIs dans API Gateway
](http-api-develop-integrations-lambda.md)
+ [
# Création d'intégrations de proxy HTTP pour HTTP APIs
](http-api-develop-integrations-http.md)
+ [
# Création d'intégrations de AWS services pour HTTP APIs dans API Gateway
](http-api-develop-integrations-aws-services.md)
+ [
# Création d'intégrations privées pour HTTP APIs dans API Gateway
](http-api-develop-integrations-private.md)
# Création d'intégrations de AWS Lambda proxy pour HTTP APIs dans API Gateway
Une intégration de proxy Lambda vous permet d’intégrer une route API avec une fonction Lambda. Lorsqu’un client appelle votre API, API Gateway envoie la demande à la fonction Lambda et renvoie la réponse de la fonction au client. Pour obtenir des exemples de création d'une API HTTP, veuillez consulter [Création d’une API HTTP](http-api-develop.md#http-api-examples).
## Version du format de charge utile
La version du format des données utiles spécifie le format de l’événement qu’API Gateway envoie à une intégration Lambda, et comment API Gateway interprète la réponse de Lambda. Si vous ne spécifiez pas de version de format de charge utile, la dernière version est AWS Management Console utilisée par défaut. Si vous créez une intégration Lambda à l'aide du AWS CLI CloudFormation, ou d'un SDK, vous devez spécifier un. `payloadFormatVersion` Les valeurs prises en charge sont `1.0` et `2.0`.
Pour plus d’informations sur la configuration de la valeur `payloadFormatVersion`, consultez [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). Pour plus d’informations sur la détermination de la valeur `payloadFormatVersion` d’une intégration existante, consultez [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html).
### Différences des formats de données utiles
La liste suivante indique les différences entre les versions de format de données utiles `1.0` et `2.0` :
+ Le format `2.0` n’a pas de champs `multiValueHeaders` ou `multiValueQueryStringParameters`. Les en-têtes dupliqués sont combinés avec des virgules et inclus dans le champ `headers`. Les chaînes de requête en double sont combinées avec des virgules et incluses dans le champ `queryStringParameters`.
+ Le format `2.0` inclut le champ `rawPath`. Si vous utilisez un mappage d’API pour connecter votre étape à un nom de domaine personnalisé, `rawPath` ne fournira pas la valeur du mappage d’API. Utilisez les formats `1.0` et `path` pour accéder au mappage d’API pour votre nom de domaine personnalisé.
+ Le format `2.0` inclut un nouveau champ `cookies`. Tous les en-têtes de cookie dans la demande sont combinés avec des virgules et ajoutés au champ `cookies`. Dans la réponse au client, chaque cookie devient un en-tête `set-cookie`.
### Structure des formats de données utiles
Les exemples suivants montrent la structure de chaque version de format de charge utile. Tous les noms d’en-tête sont en minuscules.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"header1": "value1",
"header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "192.0.2.1",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2"
},
"multiValueHeaders": {
"header1": [
"value1"
],
"header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "192.0.2.1",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
------
## Format de réponse de fonction Lambda
La version du format de charge utile détermine la structure de la réponse que votre fonction Lambda doit renvoyer.
### Réponse de la fonction Lambda pour le format 1.0
Avec la version de format `1.0`, les intégrations Lambda doivent renvoyer une réponse au format JSON suivant :
**Example**
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
```
### Réponse de la fonction Lambda pour le format 2.0
Avec la version de format `2.0`, API Gateway peut déduire le format de réponse pour vous. API Gateway fait les hypothèses suivantes si votre fonction Lambda renvoie JSON valide et ne renvoie pas un `statusCode`:
+ `isBase64Encoded` est `false`.
+ `statusCode` est `200`.
+ `content-type` est `application/json`.
+ `body` est la réponse de la fonction.
Les exemples suivants montrent la sortie d’une fonction Lambda et l’interprétation d’API Gateway.
| Sortie de la fonction Lambda | Interprétation d’API Gateway |
| --- | --- |
| "Hello from Lambda!"
| {
"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"content-type": "application/json"
}
} |
| { "message": "Hello from Lambda!" } | {
"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from Lambda!\" }",
"headers": {
"content-type": "application/json"
}
} |
Pour personnaliser la réponse, votre fonction Lambda doit renvoyer une réponse au format suivant.
```
{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"body": "Hello from Lambda!"
}
```
# Création d'intégrations de proxy HTTP pour HTTP APIs
Une intégration de proxy HTTP vous permet de connecter une route d’API à un point de terminaison HTTP routable publiquement. Avec ce type d’intégration, API Gateway passe l’intégralité de la demande et de la réponse entre le frontend et le backend.
Pour créer une intégration de proxy HTTP, fournissez l’URL d’un point de terminaison HTTP routable publiquement.
## Intégration de proxy HTTP avec les variables de chemin
Vous pouvez utiliser des variables de chemin dans les itinéraires des API HTTP.
Par exemple, la route `/pets/{petID}` attrape les demandes faites à `/pets/6`. Vous pouvez référencer des variables de chemin dans l’URI d’intégration pour envoyer le contenu de la variable à une intégration. Par exemple : `/pets/extendedpath/{petID}`.
Vous pouvez utiliser des variables de chemin gourmandes pour attraper toutes les ressources enfants d’une route. Pour créer une variable de chemin gourmande, ajoutez `+` au nom de la variable (`{proxy+}`, par exemple).
Pour configurer une route avec une intégration de proxy HTTP qui attrape toutes les demandes, créez une route d’API avec une variable de chemin gourmande (par exemple, `/parent/{proxy+}`). Intégrez la route avec un point de terminaison HTTP (par exemple, `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) sur la méthode `ANY`. La variable de chemin gourmande doit se trouver à la fin du chemin de ressource.
# Création d'intégrations de AWS services pour HTTP APIs dans API Gateway
Vous pouvez intégrer votre API HTTP à des AWS services en utilisant des *intégrations de premier ordre*. Une intégration de première classe connecte une route API HTTP à une API de service AWS . Lorsqu'un client invoque une route soutenue par une intégration de premier ordre, API Gateway invoque une API de AWS service pour vous. Par exemple, vous pouvez utiliser des intégrations de premier ordre pour envoyer un message à une file d'attente Amazon Simple Queue Service ou pour démarrer une machine à AWS Step Functions états. Pour connaître les actions de service prises en charge, consultez [Référence de sous-type d’intégration](http-api-develop-integrations-aws-services-reference.md).
## Paramètres de demande de mappage
Les intégrations de première classe ont des paramètres requis et des paramètres facultatifs. Vous devez configurer tous les paramètres requis pour créer une intégration. Vous pouvez utiliser des valeurs statiques ou des paramètres de mappage évalués de manière dynamique lors de l’exécution. Pour obtenir la liste complète des intégrations et des paramètres pris en charge, consultez [Référence de sous-type d’intégration](http-api-develop-integrations-aws-services-reference.md).
Le tableau suivant décrit les paramètres de demande de mappage pris en charge.
| Type | Exemple | Remarques |
| --- | --- | --- |
| Valeur d'en-tête | \$1request.header. name | Les noms d'en-tête ne sont pas sensibles à la casse. API Gateway combine plusieurs valeurs d'en-tête avec des virgules, par exemple "header1": "value1,value2". |
| Valeur de chaîne de requête | \$1request.querystring. name | Les noms de chaîne de requête sont sensibles à la casse. API Gateway combine plusieurs valeurs avec des virgules, par exemple "querystring1": "Value1,Value2". |
| Paramètre de chemin | \$1request.path. name | Valeur d'un paramètre de chemin dans la demande. Par exemple, si la route est /pets/\$1petId\$1, vous pouvez mapper le paramètre petId de la demande avec \$1request.path.petId. |
| Transmission de corps de demande | \$1request.body | API Gateway transmet l’ensemble du corps de la demande. |
| Corps de la demande | \$1request.body. name | [Expression de chemin JSON](https://goessner.net/articles/JsonPath/index.html#e2). La descente récursive (\$1request.body..name) et les expressions de filtre (?(expression)) ne sont pas prises en charge. Lorsque vous spécifiez un chemin JSON, API Gateway tronque le corps de la requête à 100 Ko, puis applique l'expression de sélection. Pour envoyer des charges utiles supérieures à 100 Ko, spécifiez `$request.body`. |
| Variable de contexte | \$1contexte. variableName | Valeur d'une [variable de contexte](http-api-logging-variables.md) prise en charge. |
| Variable d'étape | \$1StageVariables. variableName | Valeur d'une [variable d'étape](http-api-stages.stage-variables.md). |
| Valeur statique | string | Valeur constante. |
## Créer une intégration de première classe
Avant de créer une intégration de premier ordre, vous devez créer un rôle IAM qui accorde à API Gateway les autorisations nécessaires pour appeler l'action de AWS service à laquelle vous effectuez l'intégration. Pour en savoir plus, consultez [Création d’un rôle pour un service AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
Pour créer une intégration de premier ordre, choisissez une action de AWS service prise en charge, par exemple`SQS-SendMessage`, configurez les paramètres de demande et fournissez un rôle qui accorde à API Gateway les autorisations nécessaires pour appeler l'API du AWS service intégré. Selon le sous-type d’intégration, différents paramètres de demande sont requis. Pour en savoir plus, consultez la section [Référence de sous-type d’intégration](http-api-develop-integrations-aws-services-reference.md).
La commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante crée une intégration qui envoie un message Amazon SQS.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'
```
## Créez une intégration de premier ordre en utilisant CloudFormation
L'exemple suivant montre un CloudFormation extrait qui crée un `/{source}/{detailType}` itinéraire avec une intégration de premier ordre avec Amazon. EventBridge
Le paramètre `Source` est mappé au paramètre de chemin `{source}`, le paramètre `DetailType` au paramètre de chemin `{DetailType}` et le paramètre `Detail` au corps de la demande.
L’extrait n’affiche pas le bus d’événements ni le rôle IAM qui accorde à API Gateway les autorisations nécessaires pour invoquer l’action `PutEvents`.
```
Route:
Type: AWS::ApiGatewayV2::Route
Properties:
ApiId: !Ref HttpApi
AuthorizationType: None
RouteKey: 'POST /{source}/{detailType}'
Target: !Join
- /
- - integrations
- !Ref Integration
Integration:
Type: AWS::ApiGatewayV2::Integration
Properties:
ApiId: !Ref HttpApi
IntegrationType: AWS_PROXY
IntegrationSubtype: EventBridge-PutEvents
CredentialsArn: !GetAtt EventBridgeRole.Arn
RequestParameters:
Source: $request.path.source
DetailType: $request.path.detailType
Detail: $request.body
EventBusName: !GetAtt EventBus.Arn
PayloadFormatVersion: "1.0"
```
# Référence de sous-type d’intégration
Les [sous-types d’intégration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) suivants sont pris en charge pour les API HTTP.
**Topics**
+ [
## EventBridge-PutEvents 1.0
](#EventBridge-PutEvents)
+ [
## SQS-SendMessage 1.0
](#SQS-SendMessage)
+ [
## SQS-ReceiveMessage 1.0
](#SQS-ReceiveMessage)
+ [
## SQS-DeleteMessage 1.0
](#SQS-DeleteMessage)
+ [
## SQS-PurgeQueue 1.0
](#SQS-PurgeQueue)
+ [
## AppConfig-GetConfiguration 1.0
](#AppConfig-GetConfiguration)
+ [
## Kinesis-PutRecord 1.0
](#Kinesis-PutRecord)
+ [
## StepFunctions-StartExecution 1.0
](#StepFunctions-StartExecution)
+ [
## StepFunctions-StartSyncExecution 1.0
](#StepFunctions-StartSyncExecution)
+ [
## StepFunctions-StopExecution 1.0
](#StepFunctions-StopExecution)
## EventBridge-PutEvents 1.0
Envoie des événements personnalisés à Amazon EventBridge afin qu’ils puissent être mis en correspondance avec les règles.
| Paramètre | Obligatoire |
| --- | --- |
| Detail | Vrai |
| DetailType | Vrai |
| Source | Vrai |
| Heure | Faux |
| EventBusName | Faux |
| Ressources | Faux |
| Région | Faux |
| TraceHeader | Faux |
Pour en savoir plus, consultez [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) dans le document *Référence des API Amazon EventBridge*.
## SQS-SendMessage 1.0
Remet un message dans la file d’attente spécifiée.
| Paramètre | Obligatoire |
| --- | --- |
| QueueUrl | Vrai |
| MessageBody | Vrai |
| DelaySeconds | Faux |
| MessageAttributes | Faux |
| MessageDeduplicationId | Faux |
| MessageGroupId | Faux |
| MessageSystemAttributes | Faux |
| Région | Faux |
Pour en savoir plus, consultez [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) dans le document *Référence des API Amazon Simple Queue Service*.
## SQS-ReceiveMessage 1.0
Extrait un ou plusieurs messages (jusqu’à 10) de la file d’attente spécifiée.
| Paramètre | Obligatoire |
| --- | --- |
| QueueUrl | Vrai |
| AttributeNames | Faux |
| MaxNumberOfMessages | Faux |
| MessageAttributeNames | Faux |
| ReceiveRequestAttemptId | Faux |
| VisibilityTimeout | Faux |
| WaitTimeSeconds | Faux |
| Région | Faux |
Pour en savoir plus, consultez [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) dans le document *Référence des API Amazon Simple Queue Service*.
## SQS-DeleteMessage 1.0
Supprime le message spécifié de la file d’attente désignée.
| Paramètre | Obligatoire |
| --- | --- |
| ReceiptHandle | Vrai |
| QueueUrl | Vrai |
| Région | Faux |
Pour en savoir plus, consultez [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) dans le document *Référence des API Amazon Simple Queue Service*.
## SQS-PurgeQueue 1.0
Supprime tous les messages de la file d’attente spécifiée.
| Paramètre | Obligatoire |
| --- | --- |
| QueueUrl | Vrai |
| Région | Faux |
Pour en savoir plus, consultez [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) dans le document *Référence des API Amazon Simple Queue Service*.
## AppConfig-GetConfiguration 1.0
Reçoit des informations sur une configuration.
| Paramètre | Obligatoire |
| --- | --- |
| Application | Vrai |
| Environnement | Vrai |
| Configuration | Vrai |
| ClientId | Vrai |
| ClientConfigurationVersion | Faux |
| Région | Faux |
Pour en savoir plus, consultez [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) dans la *Référence de l’API AWS AppConfig*.
## Kinesis-PutRecord 1.0
Écrit un enregistrement de données unique dans Amazon Kinesis Data Stream.
| Paramètre | Obligatoire |
| --- | --- |
| StreamName | Vrai |
| non structurées | Vrai |
| PartitionKey | Vrai |
| SequenceNumberForOrdering | Faux |
| ExplicitHashKey | Faux |
| Région | Faux |
Pour en savoir plus, consultez [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) dans le document *Référence des API Amazon Kinesis Data Streams*.
## StepFunctions-StartExecution 1.0
Démarre l’exécution d’une machine d’état.
| Paramètre | Obligatoire |
| --- | --- |
| StateMachineArn | Vrai |
| Nom | Faux |
| Entrée | Faux |
| Région | Faux |
Pour en savoir plus, consultez [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) dans la *Référence de l’API AWS Step Functions*.
## StepFunctions-StartSyncExecution 1.0
Démarre une exécution de machine d’état synchrone.
| Paramètre | Obligatoire |
| --- | --- |
| StateMachineArn | Vrai |
| Nom | Faux |
| Entrée | Faux |
| Région | Faux |
| TraceHeader | Faux |
Pour en savoir plus, consultez [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) dans la *Référence de l’API AWS Step Functions*.
## StepFunctions-StopExecution 1.0
Arrête une exécution.
| Paramètre | Obligatoire |
| --- | --- |
| ExecutionArn | Vrai |
| Cause | Faux |
| Erreur | Faux |
| Région | Faux |
Pour en savoir plus, consultez [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) dans la *Référence de l’API AWS Step Functions*.
# Création d'intégrations privées pour HTTP APIs dans API Gateway
Les intégrations privées vous permettent de créer des intégrations d’API avec des ressources privées dans un VPC, telles que des équilibreurs Application Load Balancer ou des applications basées sur un conteneur Amazon ECS.
Vous pouvez exposer vos ressources dans un VPC pour que des clients puissent y accéder en dehors du VPC à l’aide d’intégrations privées. Vous pouvez contrôler l’accès à votre API à l’aide de n’importe quelle [méthode d’autorisation](http-api-access-control.md) prise en charge par API Gateway.
**Note**
Pour créer une intégration privée, vous devez d’abord créer un lien VPC. Les liens VPC V2 sont désormais pris en charge à la fois pour HTTP et REST. APIs Pour en savoir plus sur les liens VPC V2, consultez. [Configuration des liens VPC V2 dans API Gateway](apigateway-vpc-links-v2.md)
Après avoir créé un lien VPC V2, vous pouvez configurer des intégrations privées qui se connectent à un Application Load Balancer, à un Network Load Balancer ou à des ressources enregistrées auprès d'un service. AWS Cloud Map
## Considérations
Les considérations suivantes peuvent avoir un impact sur votre utilisation des intégrations privées :
+ Toutes les ressources doivent être détenues par la même personne Compte AWS. Cela inclut l'équilibreur de charge ou le AWS Cloud Map service, le lien VPC et l'API HTTP.
+ Par défaut, le trafic d’intégration privée utilise le protocole HTTP. Pour utiliser le protocole HTTPS, spécifiez un [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html). Pour ce faire AWS Management Console, lorsque vous créez votre intégration privée, choisissez **Paramètres avancés**, puis entrez un nom de serveur sécurisé.
+ Pour les intégrations privées, API Gateway inclut la partie de l’[étape](http-api-stages.md) du point de terminaison d’API dans la demande adressée à vos ressources backend. Par exemple, une demande à l’étape `test` d’une API inclut `test/route-path` dans la demande à votre intégration privée. Pour supprimer le nom de l’étape de la demande pour vos ressources backend, utilisez le [mappage de paramètres](http-api-parameter-mapping.md) pour écraser le chemin d’accès à la requête vers `$request.path`.
## Créer une intégration privée à l’aide d’Application Load Balancer ou de Network Load Balancer
Avant de créer une intégration privée, vous devez créer un lien VPC V2. Pour en savoir plus sur les liens VPC V2, consultez. [Configuration des liens VPC V2 dans API Gateway](apigateway-vpc-links-v2.md)
Pour créer une intégration privée avec un équilibreur Application Load Balancer ou un équilibreur Network Load Balancer, créez une intégration de proxy HTTP, spécifiez le lien VPC à utiliser et fournissez l’ARN de l’écouteur de l’équilibreur de charge.
Utilisez la commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante pour créer une intégration privée qui se connecte à un équilibreur de charge à l’aide d’un lien VPC :
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0
```
## Création d'une intégration privée à l'aide de la découverte AWS Cloud Map de services
Avant de créer une intégration privée, vous devez créer un lien VPC V2. Pour de plus amples informations sur les liens VPC, veuillez consulter [Configuration des liens VPC V2 dans API Gateway](apigateway-vpc-links-v2.md).
Pour les intégrations avec AWS Cloud Map, API Gateway les utilise `DiscoverInstances` pour identifier les ressources. Vous pouvez utiliser des paramètres de requête pour cibler des ressources spécifiques. Les attributs des ressources enregistrées doivent inclure les adresses IP et les ports. API Gateway distribue les demandes entre les ressources saines qui sont renvoyées à partir de `DiscoverInstances`. Pour en savoir plus, consultez [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html)le Guide de référence des AWS Cloud Map API.
**Note**
Si vous utilisez Amazon ECS pour renseigner les entrées AWS Cloud Map, vous devez configurer votre tâche Amazon ECS pour utiliser les enregistrements SRV avec Amazon ECS Service Discovery ou activer Amazon ECS Service Connect. Pour en savoir plus, consultez [Interconnexion des services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) dans le Guide du développeur Amazon Elastic Container Service.
Pour créer une intégration privée avec AWS Cloud Map, créez une intégration de proxy HTTP, spécifiez le lien VPC à utiliser et fournissez l'ARN du AWS Cloud Map service.
La commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante crée une intégration privée qui utilise la découverte de AWS Cloud Map services pour identifier les ressources :
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment
--payload-format-version 1.0
```
# Configurer CORS pour HTTP APIs dans API Gateway
Le [partage des ressources entre origines multiples (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) est une fonctionnalité de sécurité des navigateurs qui restreint les demandes HTTP lancées à partir de scripts s’exécutant dans le navigateur. Si vous ne parvenez pas à accéder à votre API et que vous recevez un message d'erreur contenant `Cross-Origin Request Blocked`, vous devrez peut-être activer CORS. Pour plus d’informations, consultez [What is CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)
CORS est généralement nécessaire pour créer des applications Web dont l'accès est APIs hébergé sur un domaine ou une origine différent. Vous pouvez activer CORS pour autoriser les demandes à votre API à partir d’une application Web hébergée sur un autre domaine. Par exemple, si votre API est hébergée sur `https://{api_id}.execute-api.{region}.amazonaws.com/` et que vous souhaitez appeler votre API à partir d’une application Web hébergée sur `example.com`, votre API doit prendre en charge CORS.
Si vous configurez CORS pour une API, API Gateway envoie automatiquement une réponse aux demandes OPTIONS en amont, même s’il n’y a pas de route OPTIONS configurée pour votre API. Pour une demande CORS, API Gateway ajoute les en-têtes CORS configurés à la réponse d’une intégration.
**Note**
Si vous configurez CORS pour une API, API Gateway ignore les en-têtes CORS renvoyés par votre intégration backend.
Vous pouvez spécifier les paramètres suivants dans une configuration CORS. Pour ajouter ces paramètres à l’aide de la console API HTTP API Gateway, choisissez **Ajouter** après avoir entré votre valeur.
| En-têtes CORS | Propriété de configuration CORS | Exemples de valeur |
| --- | --- | --- |
| Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/http-api-cors.html) |
| Access-Control-Allow-Credentials | allowCredentials | true |
| Access-Control-Expose-Headers | exposeHeaders | date x-api-id, \$1 |
| Access-Control-Max-Age | maxAge | 300 |
| Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE , \$1 |
| Access-Control-Allow-Headers | allowHeaders | authorization, \$1 |
Pour renvoyer des en-têtes CORS, votre demande doit contenir un en-tête `origin`. Pour la méthode `OPTIONS`, votre demande doit contenir un en-tête `origin` et un en-tête `Access-Control-Request-Method`.
Votre configuration CORS peut s’apparenter à ce qui suit :
![\[Configuration CORS pour HTTP APIs\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/http-cors-console.png)
## Configuration de CORS pour une API HTTP avec une route `$default` et un mécanisme d’autorisation
Vous pouvez activer CORS et configurer l’autorisation pour n’importe quelle route d’une API HTTP. Lorsque vous activez CORS et l’autorisation pour la route [https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default), certaines considérations particulières sont à prendre en compte. La route `$default` attrape les demandes pour toutes les méthodes et routes que vous n’avez pas explicitement définies, y compris les demandes `OPTIONS`. Pour prendre en charge les demandes `OPTIONS` non autorisées, ajoutez une route `OPTIONS /{proxy+}` à votre API qui ne nécessite pas d’autorisation et attachez une intégration à la route. La priorité de la route `OPTIONS /{proxy+}` est supérieure à celle de la route `$default`. Par conséquent, il permet aux clients de soumettre des demandes `OPTIONS` à votre API sans autorisation. Pour plus d’informations sur les priorités de routage, consultez [Routage des demandes d'API](http-api-develop-routes.md#http-api-develop-routes.evaluation).
## Configurer CORS pour une API HTTP à l'aide de la CLI AWS
La commande [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) suivante active les demandes CORS de `https://www.example.com` :
**Example**
```
aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com"
```
Pour plus d’informations, consultez [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors) dans le document Référence des API Amazon API Gateway Version 2.
# Transformation des demandes et des réponses d’API HTTP dans API Gateway
Vous pouvez modifier les demandes d’API des clients avant qu’elles n’atteignent vos intégrations backend. Vous pouvez également modifier la réponse des intégrations avant qu’API Gateway ne la renvoie aux clients. Le *mappage de paramètres* vous permet de modifier les demandes et les réponses d’API pour les API HTTP. Pour utiliser le mappage de paramètres, spécifiez les paramètres de demande ou de réponse d’API à modifier, et indiquez comment modifier ces paramètres.
## Transformation des demandes d’API
Les paramètres de demande vous permettent de modifier les demandes avant qu’elles n’atteignent vos intégrations backend. Vous pouvez modifier les en-têtes, les chaînes de la demande ou le chemin de la demande.
Les paramètres de demande sont représentés par un mappage clé-valeur. La clé identifie l'emplacement du paramètre de demande à modifier, ainsi que la façon de le modifier. La valeur spécifie les nouvelles données pour le paramètre.
Le tableau suivant présente les clés prises en charge.
| Type | Syntaxe |
| --- | --- |
| En-tête | append\$1overwrite\$1remove:header.headername |
| Chaîne de requête | append\$1overwrite\$1remove:querystring.querystring-name |
| Chemin | overwrite:path |
Le tableau suivant présente les valeurs prises en charge que vous pouvez mapper aux paramètres.
| Type | Syntaxe | Remarques |
| --- | --- | --- |
| Valeur d'en-tête | \$1request.header.name ou \$1\$1request.header.name\$1 | Les noms d'en-tête ne sont pas sensibles à la casse. API Gateway combine plusieurs valeurs d'en-tête avec des virgules, par exemple "header1": "value1,value2". Certains en-têtes sont réservés. Pour en savoir plus, consultez la section [En-têtes réservés](#http-api-mapping-reserved-headers). |
| Valeur de chaîne de requête | \$1request.querystring.name ou \$1\$1request.querystring.name\$1 | Les noms de chaîne de requête sont sensibles à la casse. API Gateway combine plusieurs valeurs avec des virgules, par exemple "querystring1" "Value1,Value2". |
| Corps de la demande | \$1request.body.name ou \$1\$1request.body.name\$1 | Expression de chemin JSON. La descente récursive (\$1request.body..name) et les expressions de filtre (?(expression)) ne sont pas prises en charge. Lorsque vous spécifiez un chemin JSON, API Gateway tronque le corps de la requête à 100 Ko, puis applique l'expression de sélection. Pour envoyer des charges utiles supérieures à 100 Ko, spécifiez `$request.body`. |
| Chemin de la demande. | \$1request.path ou \$1\$1request.path\$1 | Chemin de la demande, sans le nom de l’étape. |
| Paramètre de chemin | \$1request.path.name ou \$1\$1request.path.name\$1 | Valeur d'un paramètre de chemin dans la demande. Par exemple, si la route est /pets/\$1petId\$1, vous pouvez mapper le paramètre petId de la demande avec \$1request.path.petId. |
| Variable de contexte | \$1context.variableName ou \$1\$1context.variableName\$1 | Valeur d’une [variable de contexte](http-api-logging-variables.md). Seuls les caractères spéciaux `.` et `_` sont pris en charge. |
| Variable d'étape | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | Valeur d'une [variable d'étape](http-api-stages.stage-variables.md). |
| Valeur statique | string | Valeur constante. |
**Note**
Pour utiliser plusieurs variables dans une expression de sélection, placez la variable entre crochets. Par exemple, `${request.path.name} ${request.path.id}`.
## Transformation des réponses d’API
Les paramètres de réponse vous permettent de transformer la réponse HTTP à partir d’une intégration backend avant de retourner la réponse aux clients. Vous pouvez modifier les en-têtes ou le code de statut d’une réponse avant qu’API Gateway ne renvoie la réponse aux clients.
Vous configurez les paramètres de réponse pour chaque code de statut renvoyé par votre intégration. Les paramètres de réponse sont représentés par un mappage clé-valeur. La clé identifie l'emplacement du paramètre de demande à modifier, ainsi que la façon de le modifier. La valeur spécifie les nouvelles données pour le paramètre.
Le tableau suivant présente les clés prises en charge.
| Type | Syntaxe |
| --- | --- |
| En-tête | append\$1overwrite\$1remove:header.headername |
| Code de statut | overwrite:statuscode |
Le tableau suivant présente les valeurs prises en charge que vous pouvez mapper aux paramètres.
| Type | Syntaxe | Remarques |
| --- | --- | --- |
| Valeur d'en-tête | \$1response.header.nom ou \$1\$1response.header.nom\$1 | Les noms d'en-tête ne sont pas sensibles à la casse. API Gateway combine plusieurs valeurs d'en-tête avec des virgules, par exemple "header1": "value1,value2". Certains en-têtes sont réservés. Pour en savoir plus, consultez la section [En-têtes réservés](#http-api-mapping-reserved-headers). |
| Corps de la réponse | \$1response.body.name ou \$1\$1response.body.name\$1 | Expression de chemin JSON. La descente récursive (\$1response.body..name) et les expressions de filtre (?(expression)) ne sont pas prises en charge. Lorsque vous spécifiez un chemin JSON, API Gateway tronque le corps de la réponse à 100 Ko, puis applique l’expression de sélection. Pour envoyer des charges utiles supérieures à 100 Ko, spécifiez `$response.body`. |
| Variable de contexte | \$1context.variableName ou \$1\$1context.variableName\$1 | Valeur d'une [variable de contexte](http-api-logging-variables.md) prise en charge. |
| Variable d'étape | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | Valeur d'une [variable d'étape](http-api-stages.stage-variables.md). |
| Valeur statique | string | Valeur constante. |
**Note**
Pour utiliser plusieurs variables dans une expression de sélection, placez la variable entre crochets. Par exemple, `${request.path.name} ${request.path.id}`.
## En-têtes réservés
Les en-têtes suivants sont réservés. Vous ne pouvez pas configurer les mappages de demande ou de réponse pour ces en-têtes.
+ access-control-\$1
+ apigw-\$1
+ Autorisation
+ Connection
+ Encodage-Contenu
+ Content-Length
+ Content-Location
+ Forwarded
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via
## Exemples
Les exemples AWS CLI suivants configurent les mappages de paramètres. Pour des exemples de modèles CloudFormation, consultez [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).
### Ajouter un en-tête à une demande d’API
La commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante ajoute un en-tête nommé `header1` à une demande d’API avant que celle-ci n’atteigne votre intégration backend. API Gateway remplit l’en-tête avec l’ID de demande.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### Renommer un en-tête de demande
La commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante renomme un en-tête de requête `header1` en `header2` :
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### Modifier la réponse d’une intégration
La commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante configure les paramètres de réponse pour une intégration. Lorsque les intégrations renvoient un code de statut 500, API Gateway modifie le code de statut en 403 et ajoute `header1`1 à la réponse. Lorsque l’intégration renvoie un code de statut 404, API Gateway ajoute un en-tête `error` à la réponse.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### Supprimer les mappages de paramètres configurés
La commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante supprime les paramètres de requête précédemment configurés pour `append:header.header1`. Il supprime également les paramètres de réponse précédemment configurés pour un code de statut 200.
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```
# Utiliser les définitions OpenAPI pour HTTP APIs dans API Gateway
Vous pouvez définir votre API HTTP à l’aide d’un fichier de définition OpenAPI 3.0. Ensuite, vous pouvez importer la définition dans API Gateway pour créer une API. Pour en savoir plus sur les extensions API Gateway vers OpenAPI, consultez [Extensions OpenAPI pour API Gateway](api-gateway-swagger-extensions.md).
## Importation d'une API HTTP
Vous pouvez créer une API HTTP en important un fichier de définition OpenAPI 3.0.
Pour migrer d’une API REST vers une API HTTP, vous pouvez exporter votre API REST en tant que fichier de définition OpenAPI 3.0. Ensuite, importez la définition de l’API en tant qu’API HTTP. Pour en savoir plus sur l’exportation d’une API REST, consultez [Exportation d’une API REST à partir d’API Gateway](api-gateway-export-api.md).
**Note**
Le protocole HTTP APIs prend en charge les mêmes AWS variables que le protocole REST APIs. Pour en savoir plus, consultez la section [AWS variables pour l'importation d'OpenAPI](import-api-aws-variables.md).
### Importer des informations de validation
Lorsque vous importez une API, API Gateway fournit trois catégories d’informations de validation.
**Info (Infos)**
Une propriété est valide selon la spécification OpenAPI, mais elle n'est pas prise en charge pour le protocole HTTP. APIs
Par exemple, l'extrait OpenAPI 3.0 suivant produit des informations lors de l'importation, car le protocole HTTP APIs ne prend pas en charge la validation des demandes. API Gateway ignore les champs `requestBody` et `schema`.
```
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
```
**Avertissement**
Une propriété ou une structure n’est pas valide selon la spécification OpenAPI, mais elle ne bloque pas la création d’API. Vous pouvez spécifier si API Gateway doit ignorer ces avertissements et continuer à créer l’API, ou arrêter de créer l’API sur les avertissements.
Le document OpenAPI 3.0 suivant génère des avertissements lors de l'importation, car HTTP ne prend en APIs charge que les intégrations de proxy Lambda et de proxy HTTP.
```
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
```
**Erreur**
La spécification OpenAPI n’est pas valide ou mal formée. API Gateway ne peut pas créer de ressources à partir du document mal formé. Vous devez corriger les erreurs, puis réessayer.
La définition d'API suivante génère des erreurs lors de l'importation car le protocole HTTP ne APIs prend en charge que la spécification OpenAPI 3.0.
```
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
```
Autre exemple, alors qu’OpenAPI permet aux utilisateurs de définir une API avec plusieurs exigences en matière de sécurité liées à une opération particulière, API Gateway ne prend pas en charge cette fonctionnalité. Chaque opération ne peut avoir qu’un seul des éléments suivants : autorisation IAM, mécanisme d’autorisation Lambda ou mécanisme d’autorisation JWT. Tenter de modéliser plusieurs exigences de sécurité entraîne une erreur.
### Importez une API à l'aide du AWS CLI
La commande [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) suivante importe le fichier de définition OpenAPI 3.0 `api-definition.json` en tant qu’API HTTP :
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
Vous pouvez importer l’exemple suivant de définition OpenAPI 3.0 pour créer une API HTTP.
```
{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"
},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}
```
# Exporter le protocole HTTP APIs depuis API Gateway
Après avoir créé une API HTTP, vous pouvez exporter une définition OpenAPI 3.0 de votre API à partir d’API Gateway. Vous pouvez choisir une étape à exporter ou exporter la dernière configuration de votre API. Vous pouvez également importer une définition d’API exportée dans API Gateway pour créer une autre API identique. Pour plus d’informations sur l’importation de définitions d’API, consultez [Importation d'une API HTTP](http-api-open-api.md#http-api-import).
## Exporter une définition OpenAPI 3.0 d'une étape à l'aide de la CLI AWS
La commande [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) suivante exporte une définition OpenAPI d’une étape d’API nommée `prod` dans un fichier YAML nommé `stage-definition.yaml`. Le fichier de définition exporté inclut les [extensions API Gateway](api-gateway-swagger-extensions.md) par défaut.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## Exportez une définition OpenAPI 3.0 des dernières modifications de votre API à l'aide de la CLI AWS
La commande [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) suivante exporte une définition OpenAPI d’une API HTTP vers un fichier JSON nommé `latest-api-definition.json`. Étant donné que la commande ne spécifie pas d’étape, API Gateway exporte la dernière configuration de votre API, qu’elle ait été déployée ou non sur une étape. Le fichier de définition exporté n’inclut pas les [extensions API Gateway](api-gateway-swagger-extensions.md).
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
Pour plus d’informations, consultez [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) dans le document *Référence des API Amazon API Gateway Version 2*.
## Exportation d’une définition OpenAPI 3.0 à l’aide de la console API Gateway
La procédure suivante illustre comment exporter une définition OpenAPI d’une API HTTP.
**Pour exporter une définition OpenAPI 3.0 à l’aide de la console API Gateway**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API HTTP.
1. Dans le panneau de navigation principal, sous **Développer**, choisissez **Exporter**.
1. Sélectionnez l’une des options suivantes pour exporter votre API :
![\[Options d'exportation pour HTTP APIs.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/export-http-api.png)
1. Pour **Source**, sélectionnez une source pour la définition OpenAPI 3.0. Vous pouvez choisir une étape à exporter ou exporter la dernière configuration de votre API.
1. Activez l’option **Inclure les extensions API Gateway** pour inclure les [extensions API Gateway](api-gateway-swagger-extensions.md).
1. Pour **Format de sortie**, sélectionnez un format de sortie.
1. Choisissez **Téléchargement**.
# Publication d’API HTTP invocables par les clients
Vous pouvez utiliser des étapes et des noms de domaine personnalisés pour publier l’API que les clients peuvent appeler.
Une étape d'API est une référence logique à un état du cycle de vie de votre API (par exemple, `dev`, `prod`, `beta` ou `v2`). Chaque étape est une référence nommée à un déploiement de l'API et elle est mise à la disposition des applications clientes à appeler. Vous pouvez configurer différentes intégrations et divers paramètres pour chaque étape d’une API.
Vous pouvez utiliser des noms de domaine personnalisés pour fournir aux clients une URL plus simple et plus intuitive pour appeler votre API que l’URL par défaut, `https://api-id.execute-api.region.amazonaws.com/stage`.
**Note**
Pour renforcer la sécurité de vos API API Gateway, le domaine `execute-api.{region}.amazonaws.com` est enregistré dans la [liste des suffixes publics (PSL](https://publicsuffix.org/)). Pour plus de sécurité, nous vous recommandons d’utiliser des cookies avec un préfixe `__Host-` si vous devez définir des cookies sensibles dans le nom de domaine par défaut de vos API API Gateway. Cette pratique vous aidera à protéger votre domaine contre les tentatives de falsification de requêtes intersites (CSRF). Pour plus d’informations, consultez la page [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) du Mozilla Developer Network.
**Topics**
+ [
# Étapes du protocole HTTP APIs dans API Gateway
](http-api-stages.md)
+ [
# Politique de sécurité pour le protocole HTTP APIs dans API Gateway
](http-api-ciphers.md)
+ [
# Noms de domaine personnalisés pour les API HTTP dans API Gateway
](http-api-custom-domain-names.md)
# Étapes du protocole HTTP APIs dans API Gateway
Une étape d’API est une référence logique à un état du cycle de vie de votre API (par exemple, `dev`, `prod`, `beta` ou `v2`). Les étapes API sont identifiées par leur ID d’API et leur nom d’étape, et elles sont incluses dans l’URL que vous utilisez pour appeler l’API. Chaque étape est une référence nommée à un déploiement de l'API et elle est mise à la disposition des applications clientes à appeler.
Vous pouvez créer une étape `$default` qui est servie à partir de la base de l’URL de votre API, par exemple `https://{api_id}.execute-api.{region}.amazonaws.com/`. Vous utilisez cette URL pour appeler une étape d’API.
Un déploiement est un instantané de la configuration de votre API. Après que vous avez déployé une API dans une étape, les clients peuvent l’appeler. Vous devez déployer une API pour que les modifications prennent effet. Si vous activez les déploiements automatiques, les modifications apportées à une API sont automatiquement libérées pour vous.
# Utiliser des variables d'étape pour le protocole HTTP APIs dans API Gateway
Les variables d’étape sont des paires clé-valeur que vous pouvez définir pour une étape d’une API HTTP. Elles se comportent comme les variables d’environnement et peuvent être utilisées dans votre configuration d’API.
Les variables d’étape ne sont pas destinées à être utilisées pour des données sensibles, telles que les informations d’identification. Pour transmettre des données sensibles aux intégrations, utilisez un AWS Lambda autorisateur. Vous pouvez transmettre des données sensibles aux intégrations dans la sortie du mécanisme d’autorisation Lambda. Pour en savoir plus, consultez la section [Format de réponse du mécanisme d’autorisation Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
## Exemple : utilisation d’une variable d’étape pour personnaliser le point de terminaison d’intégration HTTP
Par exemple, vous pouvez définir une variable d’étape, puis définir sa valeur en tant que point de terminaison HTTP pour une intégration de proxy HTTP. Par la suite, vous pouvez référencer le point de terminaison à l’aide du nom de la variable d’étape associée. Ce faisant, vous pouvez utiliser la même configuration d’API avec un point de terminaison différent à chaque étape. De même, vous pouvez utiliser des variables d'étape pour spécifier une intégration de AWS Lambda fonction différente pour chaque étape de votre API.
Pour utiliser une variable d’étape afin de personnaliser le point de terminaison d’intégration HTTP, vous devez d’abord définir le nom et la valeur de la variable stage (par exemple, `url`) avec la valeur `example.com`. Ensuite, configurez une intégration de proxy HTTP. Au lieu d’entrer l’URL du point de terminaison, vous pouvez demander à API Gateway d’utiliser la valeur de la variable d’étape, **http://\$1\$1stageVariables.url\$1**. Cette valeur demande à API Gateway de remplacer votre variable d’étape `${}` au moment de l’exécution, en fonction de l’étape à laquelle se trouve votre API.
Vous pouvez référencer les variables d'étape de la même manière pour spécifier un nom de fonction Lambda ou un AWS ARN de rôle.
Lorsque vous spécifiez un nom de fonction Lambda en tant que valeur de variable d’étape, vous devez configurer les autorisations sur cette fonction Lambda manuellement. La commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) suivante configure l’autorisation pour la fonction Lambda :
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
# Référence des variables de stage API Gateway pour HTTP APIs dans API Gateway
Vous pouvez utiliser les variables d'étape API Gateway pour HTTP APIs dans les cas suivants.
## Intégration HTTP URIs
Une variable d’étape peut être utilisée dans une URI d’intégration HTTP, comme illustré dans les exemples suivants.
+ URI complet sans protocole – `http://${stageVariables.}`
+ Domaine complet – `http://${stageVariables.}/resource/operation`
+ Sous-domaine – `http://${stageVariables.}.example.com/resource/operation`
+ Chemin – `http://example.com/${stageVariables.}/bar`
+ Chaîne de requête – `http://example.com/foo?q=${stageVariables.}`
## Fonctions Lambda
Vous pouvez utiliser une variable d’étape à la place d’un nom d’intégration ou d’un alias de fonction Lambda, comme illustré dans les exemples suivants.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Note**
Pour utiliser une variable d’étape pour une fonction Lambda, la fonction doit se trouver dans le même compte que l’API. Les variables d’étape ne prennent pas en charge les fonctions Lambda inter-comptes.
## AWS informations d'identification d'intégration
Vous pouvez utiliser une variable d'étape dans le cadre de l'ARN d'identification AWS d'un utilisateur ou d'un rôle, comme illustré dans l'exemple suivant.
+ `arn:aws:iam:::${stageVariables.}`
# Politique de sécurité pour le protocole HTTP APIs dans API Gateway
API Gateway applique une politique de sécurité `TLS_1_2` pour tous les points de terminaison des API HTTP.
Une *politique de sécurité* est une combinaison prédéfinie d’une version minimale du protocole TLS et de suites de chiffrement offerte par Amazon API Gateway. Le protocole TLS résout les problèmes de sécurité de réseau tels que la falsification et le risque d’écoute illicite entre un client et un serveur. Lorsque vos clients établissent une liaison TLS vers votre API via le domaine personnalisé, la politique de sécurité applique les options de version TLS et de suite de chiffrement que vos clients peuvent choisir d’utiliser. Cette politique de sécurité accepte le trafic TLS 1.2 et TLS 1.3 et rejette le trafic TLS 1.0.
## Protocoles et chiffrements TLS pris en charge pour HTTP APIs
Le tableau suivant décrit les protocoles TLS pris en charge pour le protocole HTTP APIs.
| **Protocoles TLS** | **Politique de sécurité TLS\$11\$12** |
| --- | --- |
| TLSv13. | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| TLSv12. | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
Le tableau suivant décrit les chiffrements TLS disponibles pour la politique de sécurité TLS 1\$12 pour HTTP. APIs
| **Chiffrements TLS** | **Politique de sécurité TLS\$11\$12** |
| --- | --- |
| TLS-AES-128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| TLS-AES-256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| TLS- CHACHA20 - - POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-ECDSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/success_icon.svg) Oui |
## Noms de chiffrement OpenSSL et RFC
OpenSSL et IETF RFC 5246 utilisent des noms différents pour les mêmes chiffrements. Pour obtenir la liste des noms de chiffrement, consultez [Noms de chiffrement OpenSSL et RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informations sur REST APIs et WebSocket APIs
Pour plus d'informations sur REST APIs et WebSocket APIs, voir [Choisissez une politique de sécurité pour votre domaine personnalisé dans API Gateway](apigateway-custom-domain-tls-version.md) et[Politique de sécurité pour WebSocket APIs in API Gateway](websocket-api-ciphers.md).
# Noms de domaine personnalisés pour les API HTTP dans API Gateway
Les *noms de domaine personnalisés* sont des URL plus simples et plus intuitives que vous pouvez fournir à vos utilisateurs d’API.
Après avoir déployé votre API, vous (et vos clients) pouvez appeler cette API à l’aide de l’URL de base par défaut au format suivant :
```
https://api-id.execute-api.region.amazonaws.com/stage
```
où *api-id* est généré par API Gateway, *region* est la région AWS et *stage* est spécifié par vous lors du déploiement de l’API.
La partie nom d’hôte de l’URL, `api-id.execute-api.region.amazonaws.com`, fait référence à un point de terminaison de l’API. Le nom par défaut du point de terminaison de l’API est généré de manière aléatoire, difficile à mémoriser et peu convivial.
Avec des noms de domaine personnalisés, vous pouvez configurer le nom d’hôte de votre API et choisir un chemin de base (par exemple, `myservice`) pour mapper l’URL alternative à votre API. Par exemple, une URL de base de l’API plus conviviale peut devenir :
```
https://api.example.com/myservice
```
## Considérations
Les considérations suivantes peuvent avoir une incidence sur votre utilisation d’un nom de domaine personnalisé.
+ Un nom de domaine personnalisé régional peut être associé à des API REST et HTTP. Vous pouvez utiliser les API API Gateway version 2 pour créer et gérer des noms de domaine personnalisés régionaux pour les API REST.
+ Pour la version TLS minimale, seule la version TLS 1.2 est prise en charge.
+ Vous devez créer ou mettre à jour l’enregistrement de ressource de votre fournisseur DNS pour le mapper au point de terminaison de votre API. Sans ce mappage, les demandes d’API destinées au nom de domaine personnalisé ne peuvent pas atteindre API Gateway.
+ Vous pouvez prendre en charge un nombre presque infini de noms de domaine sans dépasser le quota par défaut en utilisant un certificat générique. Pour de plus amples informations, consultez [Noms de domaine personnalisés génériques](#http-wildcard-custom-domain-names).
## Prérequis
Les conditions suivantes sont requises pour créer un nom de domaine personnalisé.
### Enregistrement d’un nom de domaine
Pour pouvoir configurer des noms de domaine personnalisés pour vos API, vous devez avoir enregistré un nom de domaine Internet. Vous pouvez enregistrer votre nom de domaine Internet avec [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou utiliser un bureau d’enregistrement de domaine tiers de votre choix. Votre nom de domaine personnalisé peut être le nom d’un sous-domaine ou le domaine racine (également nommé « zone apex ») d’un domaine Internet enregistré.
Votre nom de domaine doit respecter la spécification [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) et peut comporter un maximum de 63 octets par étiquette et 255 octets au total.
### Certificats pour les noms de domaine personnalisés
Avant de configurer un nom de domaine personnalisé pour une API, vous devez avoir un certificat SSL/TLS prêt dans ACM. Si ACM n’est pas disponible dans la région AWS où vous créez votre nom de domaine personnalisé, vous devez importer un certificat dans API Gateway dans cette région.
Pour importer un certificat SSL/TLS, vous devez fournir le corps du certificat SSL/TLS au format PEM, sa clé privée, ainsi que la chaîne de certificats du nom de domaine personnalisé.
Chaque certificat stocké dans ACM est identifié par son ARN. Avec les certificats émis par ACM, vous n’avez pas à vous inquiéter d’une éventuelle exposition des informations sensibles du certificat, par exemple sa clé privée. Pour utiliser un certificat géré par AWS pour un nom de domaine, indiquez simplement son ARN.
Si votre application utilise l’épinglage de certificat, parfois appelé épinglage SSL, pour épingler un certificat ACM, l’application ne pourra peut-être pas se connecter à votre domaine une fois qu’AWS aura renouvelé le certificat. Pour plus d’informations, consultez la section [Problèmes d’épinglage de certificat](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) dans le *Guide de l’utilisateur AWS Certificate Manager*.
## Noms de domaine personnalisés génériques
Avec les noms de domaine personnalisés génériques, vous pouvez prendre en charge un nombre presque infini de noms de domaine sans dépasser le [quota par défaut](limits.md). Par exemple, vous pouvez donner à chacun de vos clients son propre nom de domaine, `customername.api.example.com`.
Pour créer un nom de domaine personnalisé générique, vous pouvez spécifier un caractère générique (`*`) comme premier sous-domaine d’un domaine personnalisé qui représente tous les sous-domaines possibles d’un domaine racine.
Par exemple, le nom de domaine personnalisé générique `*.example.com` se traduit par des sous-domaines tels que `a.example.com`, `b.example.com` et `c.example.com`, qui effectuent tous un routage vers le même domaine.
Les noms de domaine personnalisés génériques prennent en charge des configurations distinctes des noms de domaine personnalisés standard d’API Gateway. Par exemple, dans un seul compte AWS, vous pouvez configurer `*.example.com` et `a.example.com` pour qu'ils se comportent différemment.
Pour créer un nom de domaine personnalisé générique, vous devez fournir un certificat émis par ACM qui a été validé à l'aide du DNS ou de la méthode de validation par e-mail.
**Note**
Vous ne pouvez pas créer un nom de domaine personnalisé générique si un autre compte AWS a créé un nom de domaine personnalisé en conflit avec ce nom. Par exemple, si le compte A a créé `a.example.com`, le compte B ne peut pas créer le nom de domaine personnalisé générique `*.example.com`.
Si les comptes A et B ont le même propriétaire, vous pouvez contacter le [AWSCentre de support](https://console.aws.amazon.com/support/home#/) pour demander une exception.
## Étapes suivantes pour les noms de domaine personnalisés
Pour configurer un nom de domaine personnalisé pour une API HTTP, utilisez la documentation de la section API REST du Guide du développeur API Gateway.
D’abord, spécifiez un certificat pour votre nom de domaine personnalisé. Pour de plus amples informations, consultez [Préparez les certificats dans AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Ensuite, créez un nom de domaine personnalisé régional. Pour de plus amples informations, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
# Mappage des étapes d’API à un nom de domaine personnalisé pour les API HTTP
Les mappages d’API vous permettent de connecter des étapes d’API à un nom de domaine personnalisé. Après avoir créé un nom de domaine et configuré les enregistrements DNS, vous pouvez utiliser les mappages d’API pour envoyer le trafic vers vos API via votre nom de domaine personnalisé.
Un mappage d’API spécifie une API, une étape et éventuellement un chemin à utiliser pour le mappage. Par exemple, vous pouvez mapper l’étape `production` d’une API à `https://api.example.com/orders`.
Vous pouvez mapper les étapes d’API HTTP et REST au même nom de domaine personnalisé.
Avant de créer un mappage d’API, vous devez disposer d’une API, d’une étape et d’un nom de domaine personnalisé. Pour plus d’informations sur la création d’un nom de domaine personnalisé, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
## Routage des demandes d’API
Vous pouvez configurer des mappages d’API à plusieurs niveaux, par exemple `orders/v1/items` et `orders/v2/items`.
Pour les mappages d’API à plusieurs niveaux, API Gateway achemine les demandes vers le mappage d’API dont le chemin d’accès est le plus long. API Gateway prend uniquement en compte les chemins configurés pour les mappages d’API, et non les routes d’API, pour sélectionner l’API à appeler. Si aucun chemin ne correspond à la demande, API Gateway envoie celle-ci à l’API que vous avez mappée au chemin vide `(none)`.
Pour les noms de domaine personnalisés qui utilisent les mappages d’API à plusieurs niveaux, API Gateway achemine les demandes vers le mappage d’API doté du préfixe correspondant le plus long.
Par exemple, imaginons un nom de domaine personnalisé `https://api.example.com` doté des mappages d’API suivants :
1. `(none)` mappé à l’API 1.
1. `orders` mappé à l’API 2.
1. `orders/v1/items` mappé à l’API 3.
1. `orders/v2/items` mappé à l’API 4.
1. `orders/v2/items/categories` mappé à l’API 5.
| Requête | API sélectionnée | Explication |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | La demande correspond exactement à ce mappage d’API. |
| `https://api.example.com/orders/v1/items` | `API 3` | La demande correspond exactement à ce mappage d’API. |
| `https://api.example.com/orders/v2/items` | `API 4` | La demande correspond exactement à ce mappage d’API. |
| `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway choisit le mappage d’API dont le chemin d’accès est le plus long. La présence de `123` à la fin de la demande n’affecte pas la sélection. |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway choisit le mappage d’API dont le chemin d’accès est le plus long. |
| `https://api.example.com/customers` | `API 1` | API Gateway utilise le mappage vide comme fourre-tout. |
| `https://api.example.com/ordersandmore` | `API 2` | API Gateway choisit le mappage d’API doté du préfixe correspondant le plus long. Pour un nom de domaine personnalisé configuré avec des mappages à un seul niveau, tels que `https://api.example.com/orders` et `https://api.example.com/` uniquement, API Gateway choisirait `API 1`, car il n’y a pas de chemin correspondant avec `ordersandmore`. |
## Restrictions
+ Dans un mappage d’API, le nom de domaine personnalisé et les API mappées doivent se trouver sur le même compte AWS.
+ Les mappages d’API ne doivent contenir que des lettres, des chiffres et les caractères suivants : `$-_.+!*'()/`.
+ La longueur maximale du chemin d’un mappage d’API est de 300 caractères.
+ Vous pouvez disposer de 200 mappages d’API à plusieurs niveaux pour chaque nom de domaine. Cette limite n’inclut pas les mappages d’API à un niveau tels que `/prod`.
+ Vous ne pouvez mapper les API HTTP à un nom de domaine personnalisé régional qu’à l’aide de la politique de sécurité TLS 1.2.
+ Vous ne pouvez pas mapper les API WebSocket au même nom de domaine personnalisé qu’une API HTTP ou une API REST.
+ Si vous créez un mappage d’API à plusieurs niveaux, API Gateway convertit tous les noms d’en-tête en minuscules.
## Création d’un mappage d’API
Pour créer un mappage d’API, vous devez d’abord créer un nom de domaine personnalisé, une API et une étape. Pour plus d’informations sur la création d’un nom de domaine personnalisé, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
Pour accéder à des exemples de modèles AWS Serverless Application Model qui créent toutes les ressources, consultez [Séances avec SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) sur GitHub.
------
#### [ AWS Management Console ]
**Pour créer un mappage d’API**
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez **Noms de domaine personnalisés**.
1. Sélectionnez un nom de domaine personnalisé que vous avez déjà créé.
1. Choisissez **Mappages d’API**.
1. Choisissez **Configurer les mappages d’API**.
1. Choisissez **Ajouter un nouveau mappage**.
1. Entrez une **API**, une **Étape** et, éventuellement, un **Chemin d’accès**.
1. Choisissez **Save (Enregistrer)**.
------
#### [ AWS CLI ]
La commande [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) suivante crée un mappage d’API. Dans cet exemple, API Gateway envoie des demandes `api.example.com/v1/orders` à l’API et à l’étape spécifiés.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
L’exemple CloudFormation suivant crée un mappage d’API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Désactivation du point de terminaison par défaut pour une API HTTP
Par défaut, les clients peuvent appeler votre API en utilisant le point de terminaison `execute-api` généré par API Gateway pour votre API. Pour vous assurer que les clients peuvent accéder à votre API en utilisant uniquement un nom de domaine personnalisé, désactivez le point de terminaison par défaut `execute-api`. Lorsque vous désactivez le point de terminaison par défaut, toutes les étapes d’une API sont affectées.
La procédure suivante explique comment désactiver le point de terminaison par défaut pour une API HTTP.
------
#### [ AWS Management Console ]
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez une API HTTP.
1. Choisissez l’ID de votre API pour ouvrir la page **Détails de l’API**.
1. Dans l’onglet **Détails de l’API**, choisissez **Modifier**.
1. Pour **Point de terminaison par défaut**, sélectionnez **Désactiver**.
1. Choisissez **Save (Enregistrer)**.
Si vous activez les déploiements automatiques pour votre étape, vous n’avez pas besoin de redéployer votre API pour que la modification prenne effet. Sinon, vous devez redéployer votre API.
1. (Facultatif) Choisissez **Déployer**, puis redéployez votre API ou créez une étape pour que la modification prenne effet.
------
#### [ AWS CLI ]
La commande [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) suivante désactive le point de terminaison par défaut pour une API HTTP :
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Après avoir désactivé le point de terminaison par défaut, vous devez déployer votre API pour que la modification prenne effet, sauf si les déploiements automatiques sont activés.
La commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) suivante crée un déploiement :
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Types d’adresses IP des noms de domaine personnalisés pour les API HTTP
Lorsque vous créez une API, vous spécifiez le type d’adresses IP qui peut invoquer votre domaine. Vous avez le choix entre IPv4 (pour autoriser les adresses IPv4 à invoquer votre domaine) et Dualstack (pour autoriser les adresses IPv4 et IPv6 à invoquer votre domaine). Nous vous recommandons de définir le type d’adresse IP sur Dualstack pour éviter l’épuisement de l’espace IP ou renforcer votre niveau de sécurité. Pour plus d’informations sur les avantages d’un type d’adresse IP à double pile, consultez [IPv6 sur AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considérations relatives aux types d’adresses IP
Les considérations suivantes peuvent avoir une incidence sur votre utilisation des types d’adresses IP.
+ Le type d’adresse IP par défaut des noms de domaine personnalisés API Gateway est IPv4.
+ Il n’est pas nécessaire que votre nom de domaine personnalisé possède le même type d’adresse IP pour toutes les API qui y sont mappées. La désactivation du point de terminaison de votre API par défaut peut avoir une incidence sur la manière dont les appelants peuvent invoquer votre API.
## Modification du type d’adresse IP d’un nom de domaine personnalisé
Vous pouvez modifier le type d’adresse IP en mettant à jour la configuration de point de terminaison du domaine. Vous pouvez mettre à jour la configuration du point de terminaison du domaine à l’aide de la AWS Management Console, de l’AWS CLI, d’CloudFormation ou d’un kit SDK AWS.
------
#### [ AWS Management Console ]
**Pour modifier le type d’adresse IP d’un nom de domaine personnalisé**
1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choisissez un nom de domaine personnalisé public.
1. Sélectionnez **Configuration du point de terminaison**.
1. Pour Type d’adresse IP, choisissez **IPv4** ou **Dualstack**.
1. Choisissez **Save (Enregistrer)**.
------
#### [ AWS CLI ]
La commande [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) suivante met à jour une API pour qu’elle possède le type d’adresse IP Dualstack :
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
Le résultat se présente comme suit :
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Protection de vos API HTTP dans API Gateway
API Gateway fournit un certain nombre de façons de protéger votre API contre certaines menaces, comme les utilisateurs malveillants ou les pics de trafic. Vous pouvez protéger votre API à l’aide de politiques telles que la définition de limitations et l’activation de l’authentification TLS mutuelle. Dans cette section, vous pouvez apprendre à activer ces fonctionnalités à l’aide d’API Gateway.
**Topics**
+ [
# Limitez les requêtes adressées à votre HTTP APIs pour un meilleur débit dans API Gateway
](http-api-throttling.md)
+ [
# Comment activer l'authentification TLS mutuelle pour votre protocole HTTP APIs dans API Gateway
](http-api-mutual-tls.md)
# Limitez les requêtes adressées à votre HTTP APIs pour un meilleur débit dans API Gateway
Vous pouvez configurer la régulation pour éviter qu'ils ne soient submergés par un trop grand nombre de demandes. APIs Les limitations sont appliquées dans la mesure du possible et doivent être considérées comme des cibles plutôt que des plafonds de demandes garantis.
API Gateway régule les demandes de limitations soumises à votre API à l’aide de l’algorithme de compartiment de jetons, où un jeton compte pour une demande. Plus précisément, API Gateway examine le taux et le nombre de demandes soumises par rapport APIs à l'ensemble de votre compte, par région. Dans l’algorithme de compartiment de jetons, une rafale peut permettre un dépassement prédéfini de ces limites, mais d’autres facteurs peuvent également entraîner le dépassement des limites dans certains cas.
Lorsque les soumissions de demandes dépassent les limites de taux régulier et en mode rafale des demandes, API Gateway commence à limiter les demandes. Les clients peuvent recevoir des réponses aux erreurs `429 Too Many Requests` à ce stade. Lors de la capture de ces exceptions, le client peut renvoyer les demandes en échec de façon à limiter le débit tout en respectant les limitations.
En tant que développeur d'API, vous pouvez définir les limites cibles pour les différentes étapes ou itinéraires d'API afin d'améliorer les APIs performances globales de l'ensemble de votre compte.
## Limitation au niveau du compte par région
Par défaut, API Gateway limite le nombre de demandes stables par seconde (RPS) sur l'ensemble APIs d'un AWS compte, par région. Cela limite également la rafale (c'est-à-dire la taille maximale du bucket) sur l'ensemble APIs du AWS compte, par région. Dans API Gateway, la limite en mode rafale correspond au nombre maximal d’envois de demandes simultanés qu’API Gateway peut traiter à tout moment sans renvoyer de réponses d’erreur `429 Too Many Requests`. Pour plus d’informations sur les quotas de limitation, consultez [Quotas Amazon API Gateway](limits.md).
Les limites par compte sont appliquées à tous les APIs membres d'un compte dans une région spécifiée. La limite de débit au niveau du compte peut être augmentée sur demande. Des limites plus élevées sont possibles avec APIs des délais d'attente plus courts et des charges utiles plus faibles. Pour demander une augmentation des limitations au niveau du compte par Région, contactez le [Centre de support AWS](https://console.aws.amazon.com/support/home#/). Pour de plus amples informations, veuillez consulter [Quotas Amazon API Gateway](limits.md). Notez que ces limites ne peuvent pas être supérieures aux limites d' AWS étranglement.
## Limitation au niveau de l’acheminement
Vous pouvez définir une limitation au niveau des acheminements, afin de remplacer les limitations de requêtes au niveau du compte pour une étape spécifique ou pour des acheminements particuliers de votre API. Les limites de limitation d’acheminement par défaut ne peuvent pas dépasser les limites de débit au niveau du compte.
Vous pouvez configurer la limitation au niveau des acheminements à l’aide de AWS CLI. La commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) suivante configure une limitation personnalisée pour l’étape et la route spécifiées d’une API :
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Comment activer l'authentification TLS mutuelle pour votre protocole HTTP APIs dans API Gateway
L’authentification TLS mutuelle nécessite une authentification bidirectionnelle entre le client et le serveur. Avec l’authentification TLS mutuelle, les clients doivent présenter des certificats X.509 pour vérifier leur identité afin d’accéder à votre API. Le protocole TLS mutuel est une exigence courante pour l'Internet des objets (IoT) et business-to-business les applications.
Vous pouvez utiliser l’authentification TLS mutuelle avec d’autres [opérations d’autorisation et d’authentification](apigateway-control-access-to-api.md) prises en charge par API Gateway. API Gateway transmet les certificats que les clients fournissent aux mécanismes d’autorisation Lambda et aux intégrations de backend.
**Important**
Par défaut, les clients peuvent appeler votre API en utilisant le point de terminaison `execute-api` généré par API Gateway pour votre API. Pour vous assurer que les clients peuvent accéder à votre API en utilisant uniquement un nom de domaine personnalisé avec authentification TLS mutuelle, désactivez le point de terminaison par défaut `execute-api`. Pour en savoir plus, consultez la section [Désactivation du point de terminaison par défaut pour une API HTTP](http-api-disable-default-endpoint.md).
## Conditions préalables pour l’authentification TLS mutuelle
Pour configurer des authentifications TLS mutuelles, vous avez besoin des éléments suivants :
+ Un nom de domaine personnalisé
+ Au moins un certificat configuré AWS Certificate Manager pour votre nom de domaine personnalisé
+ Un magasin de confiance configuré et chargé vers Amazon S3
### noms de domaine personnalisés
Pour activer l’authentification TLS mutuelle pour une API HTTP, vous devez configurer un nom de domaine personnalisé pour votre API. Vous pouvez activer l’authentification TLS mutuelle pour un nom de domaine personnalisé, puis fournir le nom de domaine personnalisé aux clients. Pour accéder à une API à l’aide d’un nom de domaine personnalisé sur lequel l’authentification TLS mutuelle est activée, les clients doivent présenter des certificats approuvés dans les demandes d’API. Vous trouverez plus d’informations dans [Noms de domaine personnalisés pour les API HTTP dans API Gateway](http-api-custom-domain-names.md).
### Utilisation de certificats AWS Certificate Manager émis
Vous pouvez demander un certificat approuvé publiquement directement à partir d’ACM ou importer des certificats publics ou auto-signés. Pour configurer un certificat dans ACM, accédez à [ACM](https://console.aws.amazon.com/acm/). Si vous souhaitez importer un certificat, poursuivez votre lecture dans la section suivante.
### Utilisation d'un AWS Autorité de certification privée certificat ou d'un produit importé
Pour utiliser un certificat importé dans ACM ou un certificat provenant AWS Autorité de certification privée d'un protocole TLS mutuel, API Gateway a besoin d'un certificat `ownershipVerificationCertificate` émis par ACM. Ce certificat de propriété est utilisé uniquement pour vérifier que vous disposez des autorisations nécessaires pour utiliser le nom de domaine. Il n’est pas utilisé pour la poignée de main TLS. Si vous n'en avez pas encore`ownershipVerificationCertificate`, rendez-vous sur [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/)pour en créer un.
Vous devrez conserver ce certificat valide pendant toute la durée de vie de votre nom de domaine. Si un certificat expire et que le renouvellement automatique échoue, toutes les mises à jour du nom de domaine seront verrouillées. Vous devrez mettre à jour le `ownershipVerificationCertificateArn`avec un `ownershipVerificationCertificate` valide avant de pouvoir effectuer d’autres modifications. Le `ownershipVerificationCertificate` ne peut pas être utilisé comme certificat de serveur pour un autre domaine TLS mutuel dans API Gateway. Si un certificat est directement réimporté dans ACM, le diffuseur doit rester le même.
### Configuration de votre magasin de confiance
Les magasins de confiance sont des fichiers texte avec une `.pem` extension de fichier. Il s’agit d’une liste de certificats approuvés provenant des autorités de certification. Pour utiliser l’authentification TLS mutuelle, créez un magasin de confiance de certificats X.509 auxquels vous faites confiance pour accéder à votre API.
Vous devez inclure la chaîne de confiance complète à partir du certificat de l’autorité de certification émettrice jusqu’au certificat de l’autorité de certification racine, dans votre magasin de confiance. API Gateway accepte les certificats clients émis par toute autorité de certification présente dans la chaîne de confiance. Les certificats peuvent être délivrés par des autorités de certification publiques ou privées. Les certificats peuvent avoir une longueur de chaîne maximale de quatre. Vous pouvez également fournir des certificats auto-signés. Les algorithmes de hachage suivants sont pris en charge dans le magasin de confiance :
+ SHA-256 ou plus
+ RSA-2048 ou plus
+ ECDSA-256 ou plus
API Gateway valide un certain nombre de propriétés de certificat. Vous pouvez utiliser des mécanismes d’autorisation Lambda pour effectuer des vérifications supplémentaires lorsqu’un client appelle une API, notamment pour vérifier si un certificat a été révoqué. API Gateway valide les propriétés suivantes :
| Validation | Description |
| --- | --- |
| Syntaxe X.509 | Le certificat doit répondre aux exigences de syntaxe X.509. |
| Intégrité | Le contenu du certificat ne doit pas avoir été modifié par rapport à celui signé par l’autorité de certification à partir du magasin de confiance. |
| Validité | La période de validité du certificat doit en cours. |
| Chaînage de noms / chaînage de clés | Les noms et les objets des certificats doivent former une chaîne ininterrompue. Les certificats peuvent avoir une longueur de chaîne maximale de quatre. |
### Chargement du magasin de confiance dans un fichier unique d’un compartiment Amazon S3
**Example certificates.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
La AWS CLI commande [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) suivante est chargée dans `certificates.pem` votre compartiment Amazon S3 :
```
aws s3 cp certificates.pem s3://bucket-name
```
## Configuration de l’authentification TLS mutuelle pour un nom de domaine personnalisé
Pour configurer l’authentification TLS mutuelle pour une API HTTP, vous devez utiliser un nom de domaine personnalisé régional pour votre API, avec une version minimale TLS 1.2. Pour plus d’informations sur la création et la configuration d’un nom de domaine personnalisé, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
**Note**
Le protocole TLS mutuel n'est pas pris en charge pour le mode privé APIs.
Une fois que vous avez chargé votre magasin de confiance dans Amazon S3, vous pouvez configurer votre nom de domaine personnalisé pour utiliser l’authentification TLS mutuelle. Ce qui suit [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html)crée un nom de domaine personnalisé avec le protocole TLS mutuel :
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
Après avoir créé le nom de domaine, vous devrez configurer des enregistrements DNS et des mappages de chemin de base pour les opérations API. Pour en savoir plus, consultez la section [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
## Appeler une API à l’aide d’un nom de domaine personnalisé qui nécessite une authentification TLS mutuelle
Pour appeler une API avec l’authentification TLS mutuelle activée, les clients doivent présenter un certificat approuvé dans la demande d’API. Lorsqu’un client tente d’appeler votre API, API Gateway recherche le diffuseur du certificat client dans votre magasin de confiance. Pour que l’API Gateway puisse poursuivre la demande, le diffuseur du certificat et la chaîne de confiance complète jusqu’au certificat d’autorité de certification racine doivent se trouver dans votre magasin de confiance.
L’exemple de commande `curl` suivant envoie à `api.example.com,` une demande qui inclut `my-cert.pem` dans la demande. `my-key.key` est la clé privée du certificat.
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
Votre API est appelée uniquement si votre magasin de confiance approuve le certificat. Les conditions suivantes provoqueront l’échec de la poignée de main de l’API Gateway avec TLS et le refus de la demande d’un code de statut `403`. Si votre certificat :
+ n’est pas approuvé
+ a expiré
+ n’utilise pas d’algorithme pris en charge
**Note**
L’API Gateway ne vérifie pas si un certificat a été révoqué.
## Mise à jour de votre magasin de confiance
Pour mettre à jour les certificats dans votre magasin de confiance, chargez un nouveau lot de certificats dans Amazon S3. Vous pourrez ensuite mettre à jour votre nom de domaine personnalisé de manière à utiliser le certificat mis à jour.
Utilisez la [gestion des versions Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) pour gérer plusieurs versions de votre magasin de confiance. Lorsque vous mettez à jour votre nom de domaine personnalisé de manière à utiliser une nouvelle version du magasin de confiance, API Gateway renvoie des avertissements si les certificats ne sont pas valides.
API Gateway ne génère des avertissements de certificat que lorsque vous mettez à jour votre nom de domaine. API Gateway ne vous avertit pas si un certificat précédemment chargé arrive à expiration.
La [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)commande suivante met à jour un nom de domaine personnalisé afin d'utiliser une nouvelle version de Truststore :
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## Désactiver l’authentification TLS mutuelle
Pour désactiver l’authentification TLS mutuelle pour un nom de domaine personnalisé, supprimez le magasin de confiance de votre nom de domaine personnalisé, comme indiqué dans la commande suivante.
La [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)commande suivante met à jour un nom de domaine personnalisé afin de supprimer le truststore de votre nom de domaine personnalisé :
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## Résolution des problèmes d’authentification TLS mutuelle pour votre API HTTP
Les rubriques suivantes fournissent des conseils de dépannage pour les erreurs et problèmes que vous pouvez rencontrer lorsque vous activez l’authentification TLS mutuelle.
### Résolution des problèmes liés aux avertissements de certificat
Lors de la création d’un nom de domaine personnalisé avec authentification TLS mutuelle, API Gateway renvoie des avertissements si les certificats du magasin de confiance ne sont pas valides. Cela peut également se produire lors de la mise à jour d’un nom de domaine personnalisé de manière à utiliser un nouveau magasin de confiance. Les avertissements indiquent le problème lié au certificat et l’objet du certificat ayant produit l’avertissement. L’authentification TLS mutuelle reste activée pour votre API, mais certains clients risquent de ne pas être en mesure d’accéder à votre API.
Vous devrez décoder les certificats de votre magasin de confiance pour identifier le certificat ayant émis l’avertissement. Vous pouvez utiliser des outils tels que `openssl` pour décoder les certificats et identifier leur objet.
La commande suivante affiche le contenu d’un certificat, y compris son objet.
```
openssl x509 -in certificate.crt -text -noout
```
Mettez à jour ou supprimez les certificats ayant produit des avertissements, puis chargez un nouveau magasin de confiance dans Amazon S3. Après avoir chargé le nouveau magasin de confiance, mettez à jour votre nom de domaine personnalisé de manière à utiliser le nouveau magasin de confiance.
### Résolution des conflits de noms de domaine
L’erreur `"The certificate subject conflicts with an existing certificate from a different issuer."` signifie que plusieurs autorités de certification ont émis un certificat pour ce domaine. Pour chaque sujet du certificat, il ne peut y avoir qu’un seul diffuseur dans API Gateway pour les domaines TLS mutuels. Vous devrez obtenir tous vos certificats pour ce sujet par l’intermédiaire d’un seul diffuseur. Si le problème est dû à un certificat dont vous n’avez pas le contrôle, mais pour lequel vous pouvez prouver la propriété du nom de domaine, [contactez Support](https://console.aws.amazon.com/support/cases#/create) pour ouvrir un ticket.
### Dépannage des messages d’état des noms de domaine
`PENDING_CERTIFICATE_REIMPORT`: Cela signifie que vous avez réimporté un certificat dans ACM et que sa validation a échoué car le nouveau certificat possède un SAN (nom alternatif du sujet) qui n'est pas couvert par le `ownershipVerificationCertificate` ou le sujet ou SANs le certificat ne couvre pas le nom de domaine. Quelque chose peut être configuré de manière incorrecte ou un certificat non valide a été importé. Vous devez réimporter un certificat valide dans ACM. Pour en savoir plus sur la validation, consultez [Validation de la propriété de domaine](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html).
`PENDING_OWNERSHIP_VERIFICATION` : cela signifie que votre certificat précédemment vérifié a expiré et qu’ACM n’a pas pu le renouveler automatiquement. Vous devrez renouveler le certificat ou demander un nouveau certificat. Pour en savoir plus sur le renouvellement du certificat, vous trouverez des informations supplémentaires dans le guide : [Résolution des problèmes liés au renouvellement des certificats gérés par ACM](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html).
# Surveiller le protocole HTTP APIs dans API Gateway
Vous pouvez utiliser CloudWatch les métriques et les CloudWatch journaux pour surveiller le protocole HTTP APIs. En combinant les journaux et les métriques, vous pouvez enregistrer les erreurs et surveiller les performances de votre API.
**Note**
API Gateway peut ne pas générer de journaux et de métriques dans les cas suivants :
Nombre d’erreurs de demande d’entité 413 trop important
Nombre d’erreurs de demande 429 trop important
Erreurs de la série 400 provenant de demandes envoyées à un domaine personnalisé qui n’a pas de mappage d’API
Erreurs de la série 500 causées par des défaillances internes
**Topics**
+ [
# Surveillance des métriques CloudWatch pour les API HTTP dans API Gateway
](http-api-metrics.md)
+ [
# Configuration de la journalisation pour HTTP APIs dans API Gateway
](http-api-logging.md)
# Surveillance des métriques CloudWatch pour les API HTTP dans API Gateway
Vous pouvez surveiller l’exécution de l’API avec CloudWatch, qui recueille les données brutes d’API Gateway et les traite en métriques lisibles et disponibles presque en temps réel. Ces statistiques sont enregistrées pour une durée de 15 mois et, par conséquent, vous pouvez accéder aux informations historiques et acquérir un meilleur point de vue de la façon dont votre service ou application web s’exécute. Par défaut, les données des métriques API Gateway sont automatiquement envoyées à CloudWatch toutes les minutes. Pour surveiller vos métriques, créez un tableau de bord CloudWatch pour votre API. Pour plus d’informations sur la façon de créer un tableau de bord CloudWatch, consultez [Création d’un tableau de bord CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html) dans le *Guide de l’utilisateur Amazon CloudWatch*. Pour plus d’informations, consultez la rubrique [Qu’est-ce qu’Amazon CloudWatch ?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) du *Guide de l’utilisateur Amazon CloudWatch*.
Les métriques suivantes sont prises en charge pour les API HTTP. Vous pouvez également activer des métriques détaillées pour écrire des métriques de niveau route sur Amazon CloudWatch.
| Métrique | Description |
| --- | --- |
| 4xx | Nombre d’erreurs côté client capturées dans une période donnée. |
| 5xx | Nombre d’erreurs côté serveur capturées dans une période donnée. |
| Nombre | Nombre total de demandes d’API sur une période donnée. |
| IntegrationLatency | Délai entre le moment de la transmission de la demande au backend par API Gateway et celui de la réception de la réponse du backend. |
| Latence | Délai entre le moment de la réception par API Gateway d’une demande d’un client et celui du renvoi de la réponse au client. La latence prend en compte la latence d’intégration et autres surcharges d’API Gateway. |
| Données traitées | Quantité de données traitées en octets. |
Vous pouvez utiliser les dimensions du tableau suivant pour filtrer les métriques API Gateway.
| Dimension | Description |
| --- | --- |
| ApiId | Filtre les métriques API Gateway pour une API avec l’ID d’API spécifié. |
| ApiId, Stage | Filtre les métriques API Gateway pour trouver une étape d’API portant l’ID d’API et l’ID d’étape spécifiés. |
| ApiId, Method, Resource, Stage | Filtre les métriques API Gateway pour trouver une méthode d’API portant l’ID d’API, l’ID d’étape, le chemin de ressource et l’ID de routage spécifiés. API Gateway n’envoie pas ces métriques à moins que vous n’ayez explicitement activé les métriques CloudWatch détaillées. Pour ce faire, appelez l’action [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) de l’API REST d’API Gateway V2 pour mettre à jour la propriété `detailedMetricsEnabled` sur `true`. Sinon, vous pouvez appeler la commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) de l’AWS CLI pour mettre à jour la propriété `DetailedMetricsEnabled` sur `true`. L’activation de ces métriques implique des frais supplémentaires pour votre compte. Pour plus d’informations, consultez [Tarification Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/). |
# Configuration de la journalisation pour HTTP APIs dans API Gateway
Vous pouvez activer la journalisation pour écrire des CloudWatch journaux dans Logs. Vous pouvez utiliser des [variables de journalisation](http-api-logging-variables.md) pour personnaliser le contenu de vos journaux.
Pour améliorer votre niveau de sécurité, nous vous recommandons d'écrire des journaux dans CloudWatch Logs pour toutes les étapes de votre API HTTP. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) dans le *Guide de l’utilisateur AWS Security Hub *.
Pour activer la journalisation pour une API HTTP, vous devez effectuer les opérations suivantes.
1. Vérifiez que votre utilisateur dispose des autorisations nécessaires pour activer la journalisation.
1. Créez un groupe de CloudWatch journaux Logs.
1. Indiquez l'ARN du groupe de CloudWatch journaux Logs pour une étape de votre API.
## Autorisations pour activer la journalisation
Pour activer la journalisation pour une API, votre utilisateur doit disposer des autorisations suivantes.
**Example**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}
```
## Création d'un groupe de journaux et activation de la journalisation pour HTTP APIs
Vous pouvez créer un groupe de journaux et activer la journalisation des accès à l'aide du AWS Management Console ou du AWS CLI.
------
#### [ AWS Management Console ]
1. Créez un groupe de journaux .
Pour savoir comment créer un groupe de journaux à l'aide de la console, consultez [Créer un groupe de CloudWatch journaux dans le guide de l'utilisateur d'Amazon Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API HTTP.
1. Sous l’onglet **Monitor** (Surveiller) du panneau de navigation principal, choisissez **Logging** (Journalisation).
1. Sélectionnez une étape pour activer la journalisation, puis choisissez **Select** (Sélectionner).
1. Choisissez **Edit** (Modifier) pour activer la journalisation des accès.
1. Activez la **journalisation des accès**, entrez un CloudWatch journal et sélectionnez un format de journal.
1. Choisissez **Enregistrer**.
------
#### [ AWS CLI ]
La [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html)commande suivante crée un groupe de journaux :
```
aws logs create-log-group --log-group-name my-log-group
```
Vous avez besoin de l’Amazon Resource Name (ARN) de votre groupe de journaux pour activer la journalisation. Le format ARN est arn:aws:logs : ::log-group :. *region* *account-id* *log-group-name*
La commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) suivante active la journalisation pour l’étape `$default` d’une API HTTP :
```
aws apigatewayv2 update-stage --api-id abcdef \
--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```
------
## Exemples de format de journal
Des exemples de format de journal utilisé couramment sont disponibles dans la console API Gateway et répertoriés ci-dessous.
+ `CLF` ([Format de journal commun](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
```
+ `XML`:
```
$context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId
```
+ `CSV` (valeurs séparées par des virgules) :
```
$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
# Personnalisation des journaux d’accès pour les API HTTP
Vous pouvez utiliser les variables suivantes pour personnaliser les journaux d’accès des API HTTP. Pour en savoir plus sur les journaux d'accès pour HTTP APIs, consultez[Configuration de la journalisation pour HTTP APIs dans API Gateway](http-api-logging.md).
| Paramètre | Description |
| --- | --- |
| \$1context.accountId | ID de AWS compte du propriétaire de l'API. |
| \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. |
| \$1context.authorizer.claims.property | Propriété des requêtes renvoyées depuis le jeton JWT (JSON Web Token) une fois que l’appelant de la méthode a été authentifié avec succès, par exemple `$context.authorizer.claims.username`. Pour de plus amples informations, veuillez consulter [Contrôlez l'accès au HTTP APIs avec les autorisateurs JWT dans API Gateway](http-api-jwt-authorizer.md). L’appel de `$context.authorizer.claims` renvoie la valeur null. |
| \$1context.authorizer.error | Message d’erreur renvoyé par un mécanisme d’autorisation. |
| \$1context.authorizer.property | Valeur de la paire clé-valeur spécifiée du mappage `context` renvoyé par une fonction API Gateway du mécanisme d’autorisation Lambda. Par exemple, si le mécanisme d’autorisation retourne le mappage `context` suivant : "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} l’appel `$context.authorizer.key` renvoie la chaîne `"value"`, l’appel `$context.authorizer.numKey` renvoie `1` et l’appel `$context.authorizer.boolKey` renvoie `true`. |
| \$1context.awsEndpointRequestId | L'ID de demande du AWS point de terminaison indiqué dans l'`x-amzn-requestId`en-tête `x-amz-request-id` ou. |
| \$1context.awsEndpointRequestId2 | L'ID de demande du AWS point de terminaison indiqué dans l'`x-amz-id-2`en-tête. |
| \$1context.customDomain.basePathMatched | Chemin d’accès d’un mappage d’API correspondant à une demande entrante. Applicable lorsqu’un client utilise un nom de domaine personnalisé pour accéder à une API. Par exemple, si un client envoie une demande à `https://api.example.com/v1/orders/1234` et que cette demande correspond au mappage d’API dont le chemin d’accès est `v1/orders`, la valeur est `v1/orders`. Pour en savoir plus, consultez la section [Mappage des étapes d’API à un nom de domaine personnalisé pour les API HTTP](http-api-mappings.md). |
| \$1context.dataProcessed | Quantité de données traitées en octets. |
| \$1context.domainName | Nom de domaine complet utilisé pour invoquer l’API. Il doit être identique à l’en-tête `Host` entrant. |
| \$1context.domainPrefix | Première étiquette de `$context.domainName`. |
| \$1context.error.message | Chaîne contenant un message d’erreur API Gateway. |
| \$1context.error.messageString | La valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". |
| \$1context.error.responseType | Type de `GatewayResponse`. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.extendedRequestId | Équivalent à \$1context.requestId. |
| \$1context.httpMethod | Méthode HTTP utilisée. Les valeurs valides sont les suivantes : `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` et `PUT`. |
| \$1context.identity.accountId | L'ID de AWS compte associé à la demande. Pris en charge pour les routes qui utilisent l'autorisation IAM. |
| \$1context.identity.caller | Identifiant principal de l’appelant qui a signé la demande. Pris en charge pour les routes qui utilisent l’autorisation IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Liste séparée par des virgules de tous les fournisseurs d’authentification Amazon Cognito utilisés par l’appelant à l’origine de la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Par exemple, pour une identité provenant d’un groupe d’utilisateurs Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Pour plus d’informations sur les fournisseurs d’authentification Amazon Cognito disponibles, consultez [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) dans le *Guide du développeur Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Type d’authentification Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Les valeurs possibles incluent `authenticated` pour les identités authentifiées et `unauthenticated` pour les identités non authentifiées. |
| \$1context.identity.cognitoIdentityId | ID d’identité Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID de groupe d’identités Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID d’organisation AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Pris en charge pour les routes qui utilisent l'autorisation IAM. |
| \$1context.identity.clientCert.clientCertPem | Certificat client codé PEM présenté par le client lors de l’authentification TLS mutuelle. Présent lorsqu'un client accède à une API à l'aide d'un nom de domaine personnalisé pour lequel l'authentification TLS mutuelle est activée. |
| \$1context.identity.clientCert.subjectDN | Nom distinctif de l’objet du certificat présenté par un client. Présent lorsqu'un client accède à une API à l'aide d'un nom de domaine personnalisé pour lequel l'authentification TLS mutuelle est activée. |
| \$1context.identity.clientCert.issuerDN | Nom distinctif de l’émetteur du certificat présenté par un client. Présent lorsqu'un client accède à une API à l'aide d'un nom de domaine personnalisé pour lequel l'authentification TLS mutuelle est activée. |
| \$1context.identity.clientCert.serialNumber | Numéro de série du certificat. Présent lorsqu'un client accède à une API à l'aide d'un nom de domaine personnalisé pour lequel l'authentification TLS mutuelle est activée. |
| \$1context.identity.clientCert.validity.notBefore | Date avant laquelle le certificat n’est pas valide. Présent lorsqu'un client accède à une API à l'aide d'un nom de domaine personnalisé pour lequel l'authentification TLS mutuelle est activée. |
| \$1context.identity.clientCert.validity.notAfter | Date après laquelle le certificat n’est pas valide. Présent lorsqu'un client accède à une API à l'aide d'un nom de domaine personnalisé pour lequel l'authentification TLS mutuelle est activée. |
| \$1context.identity.sourceIp | L’adresse IP source de la connexion TCP envoyant la demande au point de terminaison de l’API Gateway. |
| \$1context.identity.user | Identifiant principal de l’utilisateur qui sera autorisé à accéder aux ressources. Pris en charge pour les routes qui utilisent l'autorisation IAM. |
| \$1context.identity.userAgent | En-tête [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) de l’appelant d’API. |
| \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. Pris en charge pour les routes qui utilisent l'autorisation IAM. Pour de plus amples informations, veuillez consulter [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.integration.error | Message d’erreur renvoyé à partir d’une intégration. Équivalent à \$1context.integrationErrorMessage. |
| \$1context.integration.integrationStatus | Pour l'intégration du proxy Lambda, le code d'état est renvoyé par le code de fonction Lambda principal AWS Lambda, et non par le code de fonction Lambda principal. |
| \$1context.integration.latency | Latence d’intégration en millisecondes (ms). Équivalent à \$1context.integrationLatency. |
| \$1context.integration.requestId | ID de demande du AWS point de terminaison. Équivalent à \$1context.awsEndpointRequestId. |
| \$1context.integration.status | Code de statut renvoyé à partir d’une intégration. Pour les intégrations de proxy Lambda, code de statut que votre code de fonction Lambda renvoie. |
| \$1context.integrationErrorMessage | Chaîne contenant un message d’erreur d’intégration. |
| \$1context.integrationLatency | Latence d'intégration en millisecondes (ms). |
| \$1context.integrationStatus | Pour l'intégration du proxy Lambda, ce paramètre représente le code d'état renvoyé par la fonction Lambda principale AWS Lambda, et non par celle-ci. |
| \$1context.path | Chemin d’accès de la demande. Par exemple, /\$1stage\$1/root/child. |
| \$1context.protocol | Protocole de demande, par exemple, HTTP/1.1. API Gateway APIs peut accepter les requêtes HTTP/2, mais API Gateway envoie des demandes aux intégrations de backend à l'aide du protocole HTTP/1.1. Par conséquent, le protocole de requête est enregistré comme HTTP/1.1 même si un client envoie une requête qui utilise HTTP/2. |
| \$1context.requestId | ID attribué par API Gateway à la demande d’API. |
| \$1context.requestTime | Durée des demandes au format [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Durée des demandes au format [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.responseLatency | Latence de la réponse en millisecondes (ms). |
| \$1context.responseLength | La longueur de la charge utile de la réponse en octets. |
| \$1context.routeKey | La clé de routage de la demande d’API, par exemple `/pets`. |
| \$1context.stage | Étape de déploiement de la demande d’API (par exemple, `beta` ou `prod`). |
| \$1context.status | Statut de la réponse de la méthode. |
# Résolution des problèmes des API HTTP dans API Gateway
Les rubriques suivantes fournissent des conseils de dépannage pour les erreurs et problèmes que vous pouvez rencontrer en utilisant des API HTTP.
**Topics**
+ [
# Résolution des problèmes liés aux intégrations Lambda d’API HTTP
](http-api-troubleshooting-lambda.md)
+ [
# Résolution des problèmes liés aux mécanismes d’autorisation JWT pour les API HTTP
](http-api-troubleshooting-jwt.md)
# Résolution des problèmes liés aux intégrations Lambda d’API HTTP
Vous trouverez ci-dessous des conseils de résolution des erreurs et des problèmes que vous pourriez rencontrer lors de l'utilisation [AWS Lambda intégrations](http-api-develop-integrations-lambda.md) du protocole HTTP APIs.
## Problème : Mon API avec une intégration Lambda renvoie `{"message":"Internal Server Error"}`
Pour résoudre l’erreur interne du serveur, ajoutez la [variable de journalisation](http-api-logging-variables.md) `$context.integrationErrorMessage` à votre format de journal et affichez vos journaux d’API HTTP. Pour ce faire, procédez comme suit :
**Pour créer un groupe de journaux à l'aide du AWS Management Console**
1. Ouvrez la CloudWatch console à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Groupes de journaux**.
1. Sélectionnez **Créer un groupe de journaux**.
1. Saisissez un nom de groupe de journaux, puis choisissez **Créer**.
1. Notez l’Amazon Resource Name (ARN) de votre groupe de journaux. Le format ARN est arn:aws:logs : ::log-group :. *region* *account-id* *log-group-name* Vous avez besoin de l’ARN du groupe de journaux pour activer la journalisation de l’accès pour votre API HTTP.
**Pour ajouter la variable de journalisation `$context.integrationErrorMessage`**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez votre API HTTP.
1. Sous **Moniteur**, choisissez **Journalisation**.
1. Sélectionnez une étape de votre API.
1. Choisissez **Modifier**, puis activez la journalisation des accès.
1. Pour **Destination du journal**, saisissez l’ARN du groupe de journaux que vous avez créé à l’étape précédente.
1. Pour **Format de journal**, choisissez **CLF**. API Gateway crée un exemple de format de journal.
1. Ajouter `$context.integrationErrorMessage` à la fin du format de journal.
1. Choisissez **Enregistrer**.
**Pour afficher les journaux de votre API**
1. Génération de journaux Utilisez un navigateur ou `curl` pour appeler votre API.
```
$curl https://api-id.execute-api.us-west-2.amazonaws.com/route
```
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez votre API HTTP.
1. Sous **Moniteur**, choisissez **Journalisation**.
1. Sélectionnez l’étape de votre API pour laquelle vous avez activé la journalisation.
1. Choisissez **Afficher les connexions CloudWatch**.
1. Choisissez le dernier flux de journaux pour afficher vos journaux d’API HTTP.
1. Votre entrée de journal doit ressembler à la suivante :
![\[CloudWatch Enregistre une entrée du journal indiquant le message d'erreur d'intégration envoyé par Lambda.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png)
Comme nous avons ajouté `$context.integrationErrorMessage` au format de journal, nous voyons un message d’erreur dans nos journaux qui résume le problème.
Vos journaux peuvent inclure un autre message d’erreur indiquant l’existence d’un problème avec votre code de fonction Lambda. Dans ce cas, vérifiez votre code de fonction Lambda et assurez-vous que votre fonction Lambda renvoie une réponse au [format requis](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response). Si vos journaux n’incluent pas de message d’erreur, ajoutez `$context.error.message` et `$context.error.responseType` à votre format de journal pour plus d’informations pour vous aider à résoudre les problèmes.
Si c’est le cas, les journaux montrent qu’API Gateway ne disposait pas des autorisations requises pour appeler la fonction Lambda.
Lorsque vous créez une intégration Lambda dans la console API Gateway, API Gateway configure automatiquement les autorisations pour appeler la fonction Lambda. Lorsque vous créez une intégration Lambda à l'aide du AWS CLI CloudFormation, ou d'un SDK, vous devez autoriser API Gateway à appeler la fonction. Les commandes [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) suivantes autorisent différentes routes d’API HTTP à invoquer une fonction Lambda.
**Example Exemple : pour l’étape `$default` et la route `$default` d’une API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"
```
**Example Exemple : pour l’étape `prod` et la route `test` d’une API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test"
```
[Vérifiez la politique de fonction](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html) dans l’onglet **Permissions (Autorisations)** de la console Lambda.
Essayez à nouveau d’appeler votre API. Vous devriez voir la réponse de votre fonction Lambda.
# Résolution des problèmes liés aux mécanismes d’autorisation JWT pour les API HTTP
Vous trouverez ci-dessous des conseils de résolution des erreurs et des problèmes que vous pourriez rencontrer lors de l'utilisation des autorisateurs JSON Web Token (JWT) avec HTTP. APIs
## Problème : Mon API renvoie `401 {"message":"Unauthorized"}`
Vérifiez l’en-tête `www-authenticate` dans la réponse de l’API.
La commande suivante utilise `curl` pour envoyer une demande à une API avec un mécanisme d’autorisation JWT qui utilise `$request.header.Authorization` comme source d’identité.
```
$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route
```
La réponse de l’API inclut un en-tête `www-authenticate`.
```
...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}
```
Dans ce cas, l’en-tête `www-authenticate` indique que le jeton n’a pas été émis pour un public ciblé approprié. Pour qu’API Gateway autorise une demande, la demande `aud` ou `client_id` de JWT doit correspondre à l’une des entrées de public ciblé configurées pour le mécanisme d’autorisation. API Gateway ne valide `client_id` que si `aud` n’est pas présent. Si `aud` et `client_id` sont présents, API Gateway évalue `aud`.
Vous pouvez également décoder un JWT et vérifier qu’il correspond à l’émetteur, au public ciblé et aux portées dont votre API a besoin. Le site Web [jwt.io](https://jwt.io/) peut être JWTs débogué dans le navigateur. L'OpenID Foundation tient à jour une [liste de bibliothèques avec lesquelles travailler](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/). JWTs
Pour plus d’informations sur les mécanismes d’autorisation JWT, consultez [Contrôlez l'accès au HTTP APIs avec les autorisateurs JWT dans API Gateway](http-api-jwt-authorizer.md).