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.
# 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**.