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éveloppez REST APIs dans API Gateway
Dans Amazon API Gateway, vous créez une API REST sous la forme d’un ensemble d’entités programmables, appelées [ressources](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html). Par exemple, vous utilisez une [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource pour représenter une API qui peut contenir un ensemble d'entités [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html).
Chaque entité `Resource` peut disposer d’une ou de plusieurs ressources [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). Une `Method` est une demande entrante soumise par le client, qui peut contenir les paramètres de demande suivants : un paramètre de chemin, un en-tête ou un paramètre de chaîne de requête. En outre, selon la méthode HTTP, la demande peut contenir un corps. Votre méthode définit la manière dont le client accède à la `Resource` exposée. Pour intégrer la `Method` avec un point de terminaison de backend, également appelé point de terminaison d’intégration, vous allez créer une ressource [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Cette opération transmet la demande entrante à un URI de point de terminaison d’intégration spécifié. Si nécessaire, vous pouvez transformer les paramètres ou le corps de la demande afin de répondre aux exigences du backend, ou vous pouvez créer une intégration de proxy, dans laquelle API Gateway envoie la demande complète dans un format normalisé à l’URI du point de terminaison d’intégration, puis envoie directement la réponse au client.
Pour les réponses, vous pouvez créer une [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)ressource pour représenter une réponse reçue par le client et vous créer une [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)ressource pour représenter la réponse renvoyée par le backend. Utilisez une réponse d’intégration pour transformer les données de la réponse du backend avant de les renvoyer au client, ou pour transmettre la réponse du backend telle quelle au client.
## Exemple de ressource pour une API REST
Le schéma suivant montre comment API Gateway implémente ce request/response modèle pour un proxy HTTP et une intégration HTTP sans proxy pour la `GET /pets` ressource. Le client envoie l’en-tête `x-version:beta` à API Gateway, qui envoie le code d’état `204` au client.
Dans une intégration sans proxy, API Gateway transforme les données pour répondre aux exigences du backend en modifiant la demande d’intégration et la réponse d’intégration. Dans une intégration sans proxy, vous accédez au corps dans la demande de méthode, mais vous le transformez dans la demande d’intégration. Lorsque le point de terminaison d’intégration renvoie une réponse avec un corps, vous y accédez et vous le transformez dans la réponse d’intégration. Vous ne pouvez pas modifier le corps dans la réponse de méthode.
Dans une intégration de proxy, le point de terminaison d’intégration modifie la demande et la réponse. API Gateway ne modifie ni la demande d’intégration ni la réponse d’intégration, et envoie la demande entrante au backend telle quelle.
Quel que soit le type d’intégration, le client envoie une demande à API Gateway, qui y répond de manière synchrone.
------
#### [ Non-proxy integration ]
![\[Schéma d’une intégration sans proxy d’API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/develop-non-proxy.png)
------
#### [ Proxy integration ]
![\[Schéma d’une intégration de proxy API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/develop-proxy.png)
------
Les exemples de journaux d’exécution suivants montrent ce qu’API Gateway enregistrerait dans l’exemple précédent. Pour plus de clarté, certaines valeurs et certains journaux initiaux ont été supprimés :
------
#### [ Non-proxy integration ]
```
Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678
Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets
Wed Feb 12 23:56:44 UTC 2025 : Method request path: {}
Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {}
Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta}
Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations:
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta}
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations:
Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms
Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT}
Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations:
Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null)
Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345}
Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution
Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204
```
------
#### [ Proxy integration ]
```
Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678
Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets
Wed Feb 12 23:59:42 UTC 2025 : Method request path: {}
Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {}
Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta}
Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations:
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta}
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations:
Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms
Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT}
Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations:
Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations:
Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT}
Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution
Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204
```
------
Pour importer une API similaire et la tester dans le AWS Management Console, consultez l'[exemple d'API](api-gateway-create-api-from-example.md).
## Autres fonctionnalités pour le développement des API REST
API Gateway prend en charge d’autres fonctionnalités pour le développement de votre API REST. Par exemple, pour aider vos clients à comprendre votre API, vous pouvez fournir une documentation sur l’API. Pour ce faire, ajoutez une ressource [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) pour une entité d'API prise en charge.
Pour contrôler la manière dont les clients appellent une API, utilisez des [autorisations IAM](permissions.md), un [mécanisme d'autorisation Lambda](apigateway-use-lambda-authorizer.md) ou un [groupe d'utilisateurs Amazon Cognito](apigateway-integrate-with-cognito.md). Pour mesurer l’utilisation de votre API, configurez des [plans d’utilisation](api-gateway-api-usage-plans.md) pour limiter les demandes d’API. Vous pouvez les activer lors de la création ou de la mise à jour de l’API.
Le schéma suivant montre les fonctionnalités disponibles pour le développement d’API REST et indique où ces fonctionnalités sont configurées dans le modèle de demande/réponse.
![\[Schéma des fonctionnalités d’API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/develop-features.png)
Pour une introduction à la création d’une API, consultez [Didacticiel : création d’une API REST avec une intégration de proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Pour en savoir plus sur les fonctionnalités d’API Gateway que vous pouvez utiliser lors du développement d’une API REST, consultez les rubriques suivantes. Ces rubriques contiennent des informations conceptuelles et des procédures que vous pouvez exécuter à l'aide de la console API Gateway, de l'API REST API Gateway AWS CLI, de ou de l'une des AWS SDKs.
**Topics**
+ [
## Exemple de ressource pour une API REST
](#rest-api-develop-example)
+ [
## Autres fonctionnalités pour le développement des API REST
](#rest-api-develop-details)
+ [
# Types de points de terminaison d'API pour REST APIs dans API Gateway
](api-gateway-api-endpoint-types.md)
+ [
# Politiques de sécurité pour REST APIs dans API Gateway
](apigateway-security-policies.md)
+ [
# Types d’adresses IP pour les API REST dans API Gateway
](api-gateway-ip-address-type.md)
+ [
# Méthodes pour REST APIs dans API Gateway
](how-to-method-settings.md)
+ [
# Contrôler et gérer l'accès à REST APIs dans API Gateway
](apigateway-control-access-to-api.md)
+ [
# Intégrations pour REST APIs dans API Gateway
](how-to-integration-settings.md)
+ [
# Demande de validation pour REST APIs dans API Gateway
](api-gateway-method-request-validation.md)
+ [
# Transformations de données pour REST APIs dans API Gateway
](rest-api-data-transformations.md)
+ [
# Réponses de passerelle pour REST APIs dans API Gateway
](api-gateway-gatewayResponse-definition.md)
+ [
# CORS pour REST APIs dans API Gateway
](how-to-cors.md)
+ [
# Types de médias binaires pour REST APIs dans API Gateway
](api-gateway-payload-encodings.md)
+ [
# Invocation d’une API REST dans API Gateway
](how-to-call-api.md)
+ [
# Développez REST APIs à l'aide d'OpenAPI dans API Gateway
](api-gateway-import-api.md)
# Types de points de terminaison d'API pour REST APIs dans API Gateway
Un type de *[point de terminaison d'API](api-gateway-basic-concept.md#apigateway-definition-api-endpoints) * fait référence au nom d'hôte de l'API. Le type de point de terminaison de l’API peut être *optimisé pour la périphérie*, *régional* ou *privé*, selon la provenance de la majorité du trafic de votre API.
## Points de terminaison d’API optimisés pour la périphérie
Un point de *[terminaison d'API optimisé](api-gateway-basic-concept.md#apigateway-definition-edge-optimized-api-endpoint)* pour les périphériques achemine généralement les demandes vers le CloudFront point de présence (POP) le plus proche, ce qui peut être utile dans les cas où vos clients sont répartis géographiquement. Il s'agit du type de point de terminaison par défaut pour API Gateway REST APIs.
Optimisé pour les bords, mettez en APIs majuscule les noms des [en-têtes HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (par exemple,). `Cookie`
CloudFront trie les cookies HTTP dans l'ordre naturel par nom de cookie avant de transmettre la demande à votre source. Pour plus d'informations sur la manière dont les cookies CloudFront sont traités, consultez la section [Mise en cache du contenu basé sur les cookies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html).
Un nom de domaine personnalisé que vous utilisez pour une API optimisée pour la périphérie s’applique à toutes les régions.
## Points de terminaison d’API régional
Un *[point de terminaison d’API régional](api-gateway-basic-concept.md#apigateway-definition-regional-api-endpoint)* est destiné aux clients situés dans la même région. Lorsqu’un client s’exécutant sur une instance EC2 appelle une API de la même région, ou lorsqu’une API est destinée à servir un petit nombre de clients aux demandes très exigeantes, une API régionale réduit la charge de connexion.
Pour une API régionale, le nom de domaine personnalisé que vous utilisez est spécifique à la région de déploiement de l’API. Si vous déployez une API régionale dans plusieurs régions, elle peut avoir le même nom de domaine personnalisé dans toutes les régions. Vous pouvez utiliser des domaines personnalisés avec Amazon Route 53 pour effectuer des tâches telles que le [routage basé sur la latence](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-latency). Pour de plus amples informations, veuillez consulter [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md) et [Configuration d’un nom de domaine personnalisé optimisé pour la périphérie dans API Gateway](how-to-edge-optimized-custom-domain-name.md).
Les points de terminaison d’API régionale transmettent tous les noms d’en-tête en l’état.
**Note**
Dans les cas où les clients d'API sont géographiquement dispersés, il peut toujours être judicieux d'utiliser un point de terminaison d'API régional, associé à votre propre CloudFront distribution Amazon, afin de garantir qu'API Gateway n'associe pas l'API à des distributions contrôlées par les services CloudFront . Pour plus d'informations sur ce cas d'utilisation, consultez [Comment configurer API Gateway avec ma propre CloudFront distribution ?](https://repost.aws/knowledge-center/api-gateway-cloudfront-distribution) .
## Point de terminaison d’API privée
Un *[point de terminaison d’API privée](api-gateway-basic-concept.md#apigateway-definition-private-api-endpoint)* est un point de terminaison d’API qui est uniquement accessible à partir de votre Amazon Virtual Private Cloud (VPC) à l’aide d’un point de terminaison d’un VPC d’interface, qui est une interface réseau de point de terminaison (ENI) créée dans votre VPC. Pour de plus amples informations, veuillez consulter [REST privé APIs dans API Gateway](apigateway-private-apis.md).
Les points de terminaison d’API privée transmettent tous les noms d’en-tête à travers en l’état.
# Modification d’un type de point de terminaison d’API publique ou privée dans API Gateway
La modification d’un type de point de terminaison d’API nécessite que vous mettiez à jour la configuration de l’API. Vous pouvez modifier un type d'API existant à l'aide de la console API Gateway AWS CLI, du ou d'un AWS SDK pour API Gateway. Le type de point de terminaison ne peut pas être modifié de nouveau tant que la modification en cours n’est pas terminée, mais votre API sera disponible.
Les modifications de types de points de terminaison suivantes sont prises en charge :
+ De « optimisés pour la périphérie » à « régionaux » ou « privés ».
+ De « régionaux » à « optimisés pour la périphérie » ou « privés ».
+ De « privés » à « régionaux »
Vous ne pouvez pas modifier une API privée en une API optimisée pour la périphérie.
Si vous modifiez une API publique « optimisée pour la périphérie » en API publique « régionale » et inversement, notez qu’une API optimisée pour la périphérie peut présenter des comportements différents de ceux d’une API régionale. Par exemple, une API optimisée pour la périphérie supprime l’en-tête `Content-MD5`. Toute valeur de MD5 hachage transmise au backend peut être exprimée dans un paramètre de chaîne de requête ou dans une propriété de corps. Toutefois, l’API régionale transmet cet en-tête, même si cela peut remplacer le nom de l’en-tête par un autre nom. Comprendre les différences vous aide à décider comment mettre à jour une API optimisée pour la périphérie en API régionale ou inversement.
**Topics**
+ [
## Utilisation de la console API Gateway pour modifier un type de point de terminaison d’API
](#migrate-api-using-console)
+ [
## Utilisez le AWS CLI pour modifier le type de point de terminaison d'une API
](#migrate-api-using-aws-cli)
## Utilisation de la console API Gateway pour modifier un type de point de terminaison d’API
Pour modifier le type de point de terminaison d’API de votre API, effectuez l’une des étapes suivantes :
**Pour convertir un point de terminaison public de « régional » ou « optimisé pour la périphérie » et vice-versa**
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 REST.
1. Choisissez **Paramètres de l’API**.
1. Dans la section **Détails de l’API**, choisissez **Modifier**.
1. Pour **Type de point de terminaison d’API**, sélectionnez **Optimisé pour la périphérie** ou **Régional**.
1. Sélectionnez **Enregistrer les modifications**.
1. Redéployez votre API afin que les modifications prennent effet.
**Pour convertir un point de terminaison privé en un point de terminaison régional**
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 REST.
1. Modifiez la politique de ressources de votre API afin de supprimer toute mention des points de terminaison VPC afin que les appels d'API provenant de l'extérieur VPCs ou de l'intérieur de votre VPC aboutissent.
1. Choisissez **Paramètres de l’API**.
1. Dans la section **Détails de l’API**, choisissez **Modifier**.
1. Pour **Type de point de terminaison d’API**, sélectionnez **Régional**.
1. Sélectionnez **Enregistrer les modifications**.
1. Supprimez la politique de ressources de votre API.
1. Redéployez votre API afin que les modifications prennent effet.
Comme vous migrez le type de point de terminaison de privé vers régional, API Gateway remplace le type d'adresse IP par. IPv4 Pour de plus amples informations, veuillez consulter [Types d’adresses IP pour les API REST dans API Gateway](api-gateway-ip-address-type.md).
**Pour convertir un point de terminaison régional en un point de terminaison privé**
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 REST.
1. Créez une politique de ressources qui accorde l’accès à votre VPC ou votre point de terminaison de VPC. Pour de plus amples informations, veuillez consulter [Étape 3 : configurer une politique de ressources pour une API privée](apigateway-private-api-create.md#apigateway-private-api-set-up-resource-policy).
1. Choisissez **Paramètres de l’API**.
1. Dans la section **Détails de l’API**, choisissez **Modifier**.
1. Pour **Type de point de terminaison d’API**, sélectionnez **Privé**.
1. (Facultatif) Pour le point de **terminaison VPC IDs**, sélectionnez le point de terminaison VPC IDs que vous souhaitez associer à votre API privée.
1. Sélectionnez **Enregistrer les modifications**.
1. Redéployez votre API afin que les modifications prennent effet.
Étant donné que vous migrez le type de point de terminaison d’une API régionale vers une API privée, API Gateway remplace le type d’adresse IP par Double pile. Pour de plus amples informations, veuillez consulter [Types d’adresses IP pour les API REST dans API Gateway](api-gateway-ip-address-type.md).
## Utilisez le AWS CLI pour modifier le type de point de terminaison d'une API
La [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)commande suivante met à jour une API optimisée pour les périphériques vers une API régionale :
```
aws apigateway update-rest-api \
--rest-api-id a1b2c3 \
--patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL
```
La réponse positive contient un code de statut `200 OK` et une charge utile similaire à ce qui suit :
```
{
"createdDate": "2017-10-16T04:09:31Z",
"description": "Your first API with Amazon API Gateway. This is a sample API that integrates via HTTP with our demo Pet Store endpoints",
"endpointConfiguration": {
"types": "REGIONAL"
},
"id": "a1b2c3",
"name": "PetStore imported as edge-optimized"
}
```
La [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)commande suivante met à jour une API régionale vers une API optimisée pour les périphériques :
```
aws apigateway update-rest-api \
--rest-api-id a1b2c3 \
--patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE
```
Comme il [put-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-rest-api.html)s'agit de mettre à jour les définitions d'API, il ne s'applique pas à la mise à jour d'un type de point de terminaison d'API.
# Politiques de sécurité pour REST APIs dans API Gateway
Une *politique de sécurité* est une combinaison prédéfinie d’une version minimale du protocole TLS et de suites de chiffrement offertes par API Gateway. Lorsque vos clients établissent une liaison TLS vers votre API ou nom de domaine personnalisé, la politique de sécurité applique la version TLS et la suite de chiffrement acceptées par API Gateway. Les politiques de sécurité protègent votre nom de domaine APIs et celui de vos noms de domaine personnalisés contre les problèmes de sécurité du réseau tels que la falsification et l'écoute entre un client et un serveur.
API Gateway prend en charge les politiques de sécurité existantes et les politiques de sécurité améliorées. `TLS_1_0`et `TLS_1_2` sont des politiques de sécurité héritées. Utilisez ces politiques de sécurité à des fins de rétrocompatibilité. Toute politique qui commence par `SecurityPolicy_` est une politique de sécurité renforcée. Utilisez-les pour les charges de travail régulées, la gouvernance avancée ou pour utiliser la cryptographie post-quantique. Lorsque vous utilisez une politique de sécurité améliorée, vous devez également définir le mode d’accès aux points de terminaison pour une meilleure gouvernance. Pour de plus amples informations, veuillez consulter [Mode d’accès au point de terminaison](#apigateway-security-policies-endpoint-access-mode).
## Comment API Gateway applique les politiques de sécurité
L'exemple suivant montre comment API Gateway applique les politiques de sécurité en utilisant la politique de `SecurityPolicy_TLS13_1_3_2025_09` sécurité comme exemple.
La politique `SecurityPolicy_TLS13_1_3_2025_09` de sécurité accepte le trafic TLS 1.3 et rejette le trafic TLS 1.2 et TLS 1.0. Pour le trafic TLS 1.3, la politique de sécurité accepte les suites de chiffrement suivantes :
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway n'accepte aucune autre suite de chiffrement. Par exemple, la politique de sécurité rejetterait tout trafic TLS 1.3 utilisant la suite de `AES128-SHA` chiffrement. Pour plus d'informations sur les versions TLS et les chiffrements pris en charge, consultez. [Politiques de sécurité prises en charge](apigateway-security-policies-list.md)
Pour contrôler le protocole TLS et les chiffrements utilisés par les clients pour accéder à votre API Gateway, vous pouvez utiliser les variables de `$context.cipherSuite` contexte `$context.tlsVersion` et dans vos journaux d'accès. Pour de plus amples informations, veuillez consulter [Surveillance des API REST dans API Gateway](rest-api-monitor.md).
## Mode d’accès au point de terminaison
Le mode d’accès au point de terminaison est un paramètre supplémentaire que vous devez spécifier pour toute API REST ou tout nom de domaine personnalisé utilisant une politique de sécurité améliorée commençant par `SecurityPolicy_`. Vous le faites lorsque vous créez votre ressource ou si vous modifiez la politique de sécurité d'une stratégie existante à une stratégie améliorée.
Lorsque le mode d'accès au point de terminaison est défini sur`STRICT`, toutes les demandes adressées à votre API REST ou à votre nom de domaine personnalisé doivent passer les vérifications suivantes :
+ La demande doit provenir du même type de point de terminaison API Gateway que votre ressource. Il peut s’agir d’un point de terminaison régional, d’un point de terminaison optimisé pour la périphérie ou d’un point de terminaison privé.
+ Si vous utilisez un point de terminaison régional ou privé, API Gateway utilise la correspondance d'hôtes SNI. Si vous utilisez un point de terminaison optimisé pour les périphériques, API Gateway est conforme à CloudFront la protection frontale du domaine. Pour plus d'informations, consultez la section [Frontage du domaine](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions).
Si l'une de ces conditions n'est pas remplie, API Gateway rejette la demande. Nous vous recommandons d'utiliser le mode d'accès aux `STRICT` terminaux lorsque cela est possible.
Pour migrer une API ou un nom de domaine existant afin d'utiliser le mode d'accès strict aux terminaux, mettez d'abord à jour votre politique de sécurité vers une politique de sécurité renforcée et conservez le mode d'accès aux terminaux défini sur`BASIC`. Après avoir validé votre trafic et vos journaux d'accès, définissez le mode d'accès au point de terminaison sur`STRICT`. Lorsque vous migrez le mode d'accès au point de terminaison de `STRICT` vers`BASIC`, votre point de terminaison sera indisponible pendant environ 15 minutes au fur et à mesure que les modifications se propagent.
Vous ne devez pas définir le mode d'accès au point de terminaison sur `STRICT` pour certaines architectures d'applications, mais plutôt sur`BASIC`. Le tableau suivant présente certaines architectures d'applications et une recommandation pour que votre API REST ou votre nom de domaine personnalisé puisse utiliser le mode d'accès aux `STRICT` terminaux.
| Architecture | Migration suggérée |
| --- | --- |
| Utilisation d'un point de terminaison VPC pour accéder à un nom de domaine public personnalisé. | Cette architecture utilise un trafic de type cross-endpoint. Nous vous recommandons de migrer vers[Noms de domaine personnalisés pour le privé APIs dans API Gateway](apigateway-private-custom-domains.md). |
| Utiliser n'importe quelle méthode pour appeler une API privée qui n'utilise pas de nom de domaine personnalisé ni de noms DNS privés. | Cette architecture crée une discordance entre l'en-tête de l'hôte et le SNI utilisé dans le handshake TLS et ne respecte pas les restrictions de fronting CloudFront du domaine. Nous vous recommandons de migrer votre VPC pour utiliser un DNS privé. |
| Utilisation du partitionnement de domaine pour distribuer du contenu sur plusieurs domaines ou sous-domaines. | Cette architecture crée une discordance entre l'en-tête de l'hôte et le SNI utilisé dans le handshake TLS et ne respecte pas les restrictions de fronting CloudFront du domaine. Nous vous recommandons d'utiliser cet anti-modèle `HTTP/2` et de migrer hors de celui-ci. |
Voici les points à prendre en compte lors de l'utilisation du mode d'accès aux terminaux :
+ Si le mode d'accès au point de terminaison d'une API ou d'un nom de domaine est défini comme `STRICT` tel, vous ne pouvez pas modifier le type de point de terminaison. Pour modifier le type de point de terminaison, changez d'abord le mode d'accès au point de terminaison sur`BASIC`.
+ Une fois que vous avez changé le mode d'accès aux terminaux de `BASIC` à`STRICT`, API Gateway met 15 minutes à appliquer le mode d'accès strict aux terminaux.
+ Lorsque vous modifiez une politique de sécurité d'une stratégie commençant `SecurityPolicy_` par une stratégie existante, vous devez annuler le mode d'accès au point de terminaison sur`""`.
## Considérations
Voici quelques considérations relatives aux politiques de sécurité pour REST APIs dans API Gateway :
+ Vous pouvez importer la politique de sécurité dans un fichier de définition OpenAPI. Pour de plus amples informations, veuillez consulter [x-amazon-apigateway-endpoint-mode d'accèsx-amazon-apigateway-security-politique](openapi-extensions-security-policy.md).
+ Votre API peut être mappée à un nom de domaine personnalisé avec une politique de sécurité différente de celle de votre API. Lorsque vous invoquez ce nom de domaine personnalisé, API Gateway utilise la politique de sécurité de l'API pour négocier le handshake TLS. 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.
+ Si vous modifiez votre politique de sécurité, la mise à jour prend environ 15 minutes. Vous pouvez surveiller l'état `apiStatus` de votre API. Au fur et à mesure que votre API sera mise à jour, elle l'`apiStatus`est `UPDATING` et lorsqu'elle sera terminée, elle le sera`AVAILABLE`. Lorsque le statut de votre API est `UPDATING` défini, vous pouvez toujours l'invoquer.
+ API Gateway prend en charge les politiques de sécurité pour tous APIs. Toutefois, vous ne pouvez choisir qu'une politique de sécurité pour REST APIs. API Gateway prend uniquement en charge la politique de `TLS_1_2` sécurité pour HTTP ou WebSocket APIs.
+ Vous ne pouvez pas mettre à jour la politique de sécurité d'une API de `TLS_1_0` à`TLS_1_2`.
+ Certaines politiques de sécurité prennent en charge les suites de chiffrement ECDSA et RSA. Si vous utilisez ce type de politique avec un nom de domaine personnalisé, les suites de chiffrement correspondent au type de clé de certificat fourni par le client, soit RSA, soit ECDSA. Si vous utilisez ce type de politique avec une API REST, les suites de chiffrement correspondent aux suites de chiffrement compatibles avec les types de certificats RSA.
# Politiques de sécurité prises en charge
Les tableaux suivants décrivent les [politiques de sécurité](apigateway-security-policies.md) qui peuvent être spécifiées pour chaque type de point de terminaison d'API REST et chaque type de nom de domaine personnalisé. Ces politiques vous permettent de contrôler les connexions entrantes. API Gateway ne prend en charge le protocole TLS 1.2 qu'en sortie. Vous pouvez mettre à jour la politique de sécurité de votre API ou de votre nom de domaine personnalisé à tout moment.
Les politiques énoncées `FIPS` dans le titre sont compatibles avec le Federal Information Processing Standard (FIPS), qui est une norme gouvernementale américaine et canadienne qui spécifie les exigences de sécurité pour les modules cryptographiques qui protègent les informations sensibles. Pour en savoir plus, consultez la [norme fédérale de traitement de l'information (FIPS) 140](https://aws.amazon.com/compliance/fips/) sur la page *Conformité à la sécurité du AWS cloud*.
Toutes les politiques FIPS s'appuient sur le module cryptographique AWS-LC validé FIPS. Pour en savoir plus, consultez la page du module [cryptographique AWS-LC sur le site du programme de validation du module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) *cryptographique du NIST*.
Les politiques énoncées `PQ` dans le titre utilisent la [cryptographie post-quantique (PQC)](https://aws.amazon.com/security/post-quantum-cryptography/) pour implémenter des algorithmes hybrides d'échange de clés pour le TLS afin de garantir la confidentialité du trafic contre les futures menaces informatiques quantiques.
Les politiques énoncées `PFS` dans le titre utilisent le [Perfect Forward Secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy) pour garantir que les clés de session ne sont pas compromises.
Les politiques qui contiennent les deux `FIPS` et qui figurent `PQ` dans leur titre prennent en charge ces deux fonctionnalités.
## Politiques de sécurité par défaut
Lorsque vous créez une nouvelle API REST ou un nouveau domaine personnalisé, une politique de sécurité par défaut est attribuée à la ressource. Le tableau suivant indique la politique de sécurité par défaut pour ces ressources.
| **Ressource** | **Nom de la politique de sécurité par défaut** |
| --- | --- |
| Régional APIs | TLS\$11\$10 |
| Optimisé pour les bords APIs | TLS\$11\$10 |
| Privé APIs | TLS\$11\$12 |
| Domaine régional | TLS\$11\$12 |
| Domaine optimisé pour les périphériques | TLS\$11\$12 |
| Domaine privé | TLS\$11\$12 |
## Politiques de sécurité prises en charge pour les noms de domaine régionaux, privés APIs et personnalisés
Le tableau suivant décrit les politiques de sécurité qui peuvent être spécifiées pour les noms de domaine régionaux, privés APIs et personnalisés :
| **Politique de sécurité** | **Versions TLS prises en charge** | **Chiffrements pris en charge** |
| --- | --- | --- |
| SecurityPolicy\$1 TLS13 \$11\$13\$12025\$109 | TLS13. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$13\$1FIPS\$12025\$109 | TLS13. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$1FIPS\$1PFS\$1PQ\$12025\$109 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$1PFS\$1PQ\$12025\$109 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$1PQ\$12025\$109 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$12021\$106 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$12 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS13. TLS12. TLS11. TLS10. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## Politiques de sécurité prises en charge pour les noms de domaine personnalisés APIs et optimisés pour les périphériques
Le tableau suivant décrit les politiques de sécurité qui peuvent être spécifiées pour les noms de domaine personnalisés optimisés pour APIs les périphériques et pour les périphériques :
| **Nom de la politique de sécurité** | **Versions TLS prises en charge** | **Chiffrements pris en charge** |
| --- | --- | --- |
| SecurityPolicy\$1 TLS13 \$12025\$1EDGE | TLS13. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS12 \$1PFS\$12025\$1EDGE | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS12 \$12018\$1EDGE | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS13. TLS12. TLS11. TLS10. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## Noms de chiffrement OpenSSL et RFC
OpenSSL et IETF RFC 5246 utilisent des noms différents pour les mêmes chiffrements. Le tableau suivant met en correspondance le nom OpenSSL et le nom RFC pour chaque chiffrement. Pour plus d’informations, consultez [ciphers](https://docs.openssl.org/1.1.1/man1/ciphers/) dans la documentation OpenSSL.
| **Nom de chiffrement OpenSSL** | **Nom de chiffrement RFC** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1 SHA256 | TLS\$1AES\$1128\$1GCM\$1 SHA256 |
| TLS\$1AES\$1256\$1GCM\$1 SHA384 | TLS\$1AES\$1256\$1GCM\$1 SHA384 |
| TLS\$1 \$1 \$1 CHACHA20 POLY1305 SHA256 | TLS\$1 \$1 \$1 CHACHA20 POLY1305 SHA256 |
| ECDHE-RSA- -GCM- AES128 SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1 SHA256 |
| ECDHE-RSA- - AES128 SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1 SHA256 |
| ECDHE-RSA- -SHA AES128 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| ECDHE-RSA- -GCM- AES256 SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1 SHA384 |
| ECDHE-RSA- - AES256 SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1 SHA384 |
| ECDHE-RSA- -SHA AES256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-GCM- SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1 SHA256 |
| AES256-GCM- SHA384 | TLS\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1 SHA384 |
| AES128-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1 SHA256 |
| AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| CBC3DES-SHA | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA |
# Comment modifier une politique de sécurité
Vous pouvez modifier la politique de sécurité de votre API. Si vous envoyez du trafic à votre adresse APIs via votre nom de domaine personnalisé, il n'est pas nécessaire que l'API et le nom de domaine personnalisé aient la même politique de sécurité. Lorsque vous invoquez ce nom de domaine personnalisé, API Gateway utilise la politique de sécurité de l'API pour négocier le handshake TLS. Toutefois, pour des raisons de cohérence, nous vous recommandons d'utiliser la même politique de sécurité pour votre nom de domaine et votre API personnalisés.
Si vous modifiez votre politique de sécurité, la mise à jour prend environ 15 minutes. Vous pouvez surveiller l'état `apiStatus` de votre API. Au fur et à mesure que votre API sera mise à jour, elle l'`apiStatus`est `UPDATING` et lorsqu'elle sera terminée, elle le sera`AVAILABLE`. Lorsque votre API est mise à jour, vous pouvez toujours l'invoquer.
------
#### [ AWS Management Console ]
**Pour modifier la politique de sécurité d'une API**
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 REST.
1. Choisissez **Paramètres de l’API**, puis **Modifier**.
1. Pour **la politique de sécurité**, sélectionnez une nouvelle stratégie commençant par`SecurityPolicy_`.
1. Pour le **mode d'accès au point de terminaison**, choisissez **Strict**.
1. Sélectionnez **Enregistrer les modifications**.
Redéployez l’API pour que les modifications prennent effet. Comme vous avez changé le mode d'accès aux terminaux en mode strict, il faudra environ 15 minutes pour que les modifications se propagent complètement.
------
#### [ AWS CLI ]
La [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)commande suivante met à jour une API afin d'utiliser la politique `SecurityPolicy_TLS13_1_3_2025_09` de sécurité :
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
Le résultat se présente comme suit :
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
"rootResourceId": "efg456"
}
```
La [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)commande suivante met à jour une API qui utilisait une politique de sécurité améliorée pour utiliser la politique `TLS_1_0` de sécurité.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "TLS_1_0"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": ""
}
]'
```
Le résultat se présente comme suit :
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "TLS_1_0",
"rootResourceId": "efg456"
}
```
------
# Types d’adresses IP pour les API REST 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). Nous vous recommandons de définir le type d’adresse IP sur Dualstack pour éviter l’épuisement de l’espace IP ou renforcer votre niveau de sécurité. Pour plus d’informations sur les avantages d’un type d’adresse IP à double pile, consultez [IPv6 sur AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
Pour limiter votre API au trafic IPv6 uniquement, vous pouvez créer une stratégie de ressources qui limite les adresses IP sources aux plages IPv6 uniquement. Vous pouvez modifier le type d’adresse IP en mettant à jour la configuration de l’API. Cette modification prend effet immédiatement. Vous n’avez pas besoin de redéployer votre API. Pour plus d’informations, consultez [Exemple : refuser le trafic API en fonction de l’adresse IP source ou de la plage](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example).
## Considérations relatives aux types d’adresses IP
Les considérations suivantes peuvent avoir une incidence sur votre utilisation des types d’adresses IP :
+ Le type d’adresse IP par défaut pour toutes les API régionales et optimisées pour la périphérie est IPv4.
+ Les API privées ne peuvent avoir qu’un type d’adresse IP à double pile.
+ 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.
+ Si vous migrez le type de point de terminaison d’une API régionale ou optimisée pour la périphérie vers une API privée, API Gateway remplace le type d’adresse IP par une adresse à double pile. Pour plus d’informations, consultez [Modification d’un type de point de terminaison d’API publique ou privée dans API Gateway](apigateway-api-migration.md).
+ Si vous migrez le type de point de terminaison d’une API privée vers une API régionale, vous devez définir le type d’adresse IP sur Dualstack. Une fois la migration du point de terminaison terminée, vous pouvez remplacer le type d’adresse IP par IPv4. Pour plus d’informations, consultez [Modification d’un type de point de terminaison d’API publique ou privée dans API Gateway](apigateway-api-migration.md).
+ 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.
+ Vous ne pouvez pas utiliser un fichier de définition externe pour configurer le type d’adresse IP de votre API.
# Modification du type d’adresse IP d’une API REST
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. Avant de modifier le type d’adresse IP, vérifiez que toutes les stratégies d’accès à vos API ont été mises à jour pour prendre en compte les appels IPv6.
------
#### [ AWS Management Console ]
**Pour modifier le type d’adresse IP d’une API REST**
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 REST.
1. Choisissez **Paramètres de l’API**, puis **Modifier**.
1. Pour Type d’adresse IP, choisissez **IPv4** ou **Dualstack**.
1. Sélectionnez **Enregistrer les modifications**.
La modification de la configuration de votre API prend effet immédiatement.
------
#### [ AWS CLI ]
La commande [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) suivante met à jour une API pour qu’elle possède le type d’adresse IP Dualstack :
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
Le résultat se présente comme suit :
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a dualstack IP address type",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"rootResourceId": "efg456"
}
```
------
# Méthodes pour REST APIs dans API Gateway
Dans API Gateway, une méthode d’API incarne une [demande de méthode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) et une [réponse de méthode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). La configuration d’une méthode d’API vous permet de définir les actions qu’un client doit ou devrait exécuter pour soumettre une demande d’accès au serveur principal et les réponses que le client reçoit en retour. Pour l’entrée, vous pouvez choisir les paramètres de demande de méthode (ou une charge utile applicable) pour que le client fournisse les données obligatoires ou facultatives au moment de l’exécution. Pour la sortie, vous déterminez le code de statut, les en-têtes et le corps applicable de la réponse de la méthode en tant que cibles auxquelles mapper les données de réponse du backend, avant qu’elles ne soient renvoyées au client. Pour aider le développeur client à comprendre les comportements et les formats d’entrée et de sortie de votre API, vous pouvez [documenter votre API](api-gateway-documenting-api.md) et [fournir des messages d’erreur appropriés](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) pour les [demandes non valides](api-gateway-method-request-validation.md).
Une demande de méthode d’API de demande HTTP. Pour configurer la demande de méthode, vous configurez une méthode HTTP (ou verbe), le chemin d’accès à une [ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) d’API, les en-têtes et les paramètres de chaîne de requête applicables. Vous configurez également une charge utile lorsque la méthode HTTP est `POST`, `PUT`ou `PATCH`. Par exemple, pour récupérer un animal de compagnie à l'aide de l'[PetStore exemple d'API](api-gateway-create-api-from-example.md), vous définissez la demande de méthode d'API`GET /pets/{petId}`, où `{petId}` est un paramètre de chemin pouvant prendre un nombre au moment de l'exécution.
```
GET /pets/1
Host: apigateway.us-east-1.amazonaws.com
...
```
Si le client spécifie un chemin d’accès incorrect, par exemple `/pet/1` ou `/pets/one` au lieu de `/pets/1`, une exception est renvoyée.
Une réponse de méthode d’API est une réponse HTTP avec un code de statut donné. Dans le cas d’une intégration autre que de proxy, vous devez configurer les réponses de méthode afin de spécifier les cibles obligatoires ou facultatives des mappages. Cela permet de transformer les en-têtes ou corps de la réponse d’intégration en en-têtes ou corps de la réponse de méthode associée. Le mappage peut être aussi simple qu’une [transformation d’identité](https://en.wikipedia.org/wiki/Identity_transform) qui transmet les en-têtes ou le corps via l’intégration en l’état. Par exemple, la réponse de méthode `200` suivante illustre un exemple de transfert d’une réponse d’intégration positive telle quelle.
```
200 OK
Content-Type: application/json
...
{
"id": "1",
"type": "dog",
"price": "$249.99"
}
```
En principe, vous pouvez définir une réponse de méthode correspondant à une réponse spécifique à partir du backend. En général, cela implique n’importe quelle réponse 2XX, 4XX et 5XX. Toutefois, il se peut que ce ne soit pas pratique, car souvent, vous ne connaissez pas forcément à l’avance toutes les réponses qu’un backend peut renvoyer. En pratique, vous pouvez désigner une réponse de méthode par défaut pour gérer l’inconnu ou des réponses non mappées depuis le backend. Il est recommandé de désigner la réponse 500 comme valeur par défaut. Dans tous les cas, vous devez configurer au moins une réponse de méthode pour les intégrations autres que de proxy. Sinon, API Gateway renvoie une réponse d’erreur 500 au client, même lorsque la demande aboutit au niveau du backend.
Pour prendre en charge un kit SDK fortement typé, tel qu’un kit SDK Java, pour votre API, vous devez définir le modèle de données de l’entrée de la demande de méthode, ainsi que le modèle de données de la sortie de la réponse de méthode.
## Conditions préalables
Avant de configurer une méthode d’API, vérifiez ce qui suit :
+ La méthode doit être disponible dans API Gateway. Suivez les instructions de la section [Didacticiel : création d’une API REST avec une intégration HTTP sans proxy](api-gateway-create-api-step-by-step.md).
+ Si vous souhaitez que la méthode communique avec une fonction Lambda, vous devez avoir déjà créé le rôle d’invocation Lambda et le rôle d’exécution Lambda dans IAM. Vous devez également avoir créé la fonction Lambda avec laquelle votre méthode pourra communiquer dans AWS Lambda. Pour créer les rôles et la fonction, suivez les instructions de [Création d’une fonction Lambda pour l’intégration Lambda autre que de proxy](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) dans [Choisissez un didacticiel AWS Lambda d'intégration](getting-started-with-lambda-integration.md).
+ Si vous souhaitez que la méthode communique avec HTTP ou une intégration de proxy HTTP, vous devez déjà avoir créé l’URL de point de terminaison HTTP avec lequel votre méthode va communiquer, et y avoir accès.
+ Vérifiez que vos certificats pour les points de terminaison HTTP et proxy HTTP sont pris en charge par API Gateway. Pour plus d’informations, consultez [Autorités de certification prises en charge par API Gateway pour les intégrations HTTP et les intégrations de proxy HTTP](api-gateway-supported-certificate-authorities-for-http-endpoints.md).
**Topics**
+ [
## Conditions préalables
](#method-setting-prerequisites)
+ [
# Configuration d’une demande de méthode dans API Gateway
](api-gateway-method-settings-method-request.md)
+ [
# Configuration d’une réponse de méthode dans API Gateway
](api-gateway-method-settings-method-response.md)
+ [
# Configuration d’une méthode à l’aide de la console API Gateway
](how-to-set-up-method-using-console.md)
# Configuration d’une demande de méthode dans API Gateway
La configuration d'une demande de méthode implique l'exécution des tâches suivantes, après avoir créé une [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource :
1. Création d’une API ou sélection d’une entité [Resource (Ressource)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) d’API existante.
1. Création d’une ressource [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) d’API consistant en un verbe HTTP spécifique sur la nouvelle API ou l’entité `Resource` d’API sélectionnée. Cette tâche peut être également décomposée en plusieurs tâches secondaires comme suit :
+ Ajout d’une méthode HTTP pour la demande de méthode
+ Configuration des paramètres de la demande
+ Définition d’un modèle pour le corps de la demande
+ Application d’un schéma d’autorisation
+ Activation de la validation de la demande
Vous pouvez effectuer ces tâches à l’aide des méthodes suivantes :
+ [Console API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)
+ AWS CLI [commandes ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) et put-method)](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)
+ AWS [Fonctions du SDK (par exemple, dans Node.js, [CreateResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) et PutMethod)](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property)
+ API REST API Gateway ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) et [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)).
**Topics**
+ [
## Configuration des ressources API
](#setup-method-resources)
+ [
## Configuration d’une méthode HTTP
](#setup-method-add-http-method)
+ [
## Configuration des paramètres de demande de méthode
](#setup-method-request-parameters)
+ [
## Configuration d’un modèle de demande de méthode
](#setup-method-request-model)
+ [
## Configuration de l’autorisation de demande de méthode
](#setup-method-request-authorization)
+ [
## Configuration de la validation de demande de méthode
](#setup-method-request-validation)
## Configuration des ressources API
Dans une API API Gateway, vous exposez les ressources adressables sous la forme d’une arborescence d’entités [Resources (Ressources)](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) de l’API, avec la ressource racine (`/`) au sommet de la hiérarchie. La ressource racine est relative à l’URL de base de l’API, qui se compose du point de terminaison de l’API et du nom de l’étape. Dans la console API Gateway, cette URI de base est appelée **Invoke URI (URI d’appel)** et s’affiche dans l’éditeur d’étape de l’API après le déploiement de l’API.
Le point de terminaison de l’API peut être un nom d’hôte par défaut ou un nom de domaine personnalisé. Le nom d’hôte par défaut a le format suivant :
```
{api-id}.execute-api.{region}.amazonaws.com
```
Dans ce format, le *\$1api-id\$1* représente l'identifiant d'API généré par API Gateway. La variable `{region}` représente la Région AWS (par exemple, `us-east-1`) que vous avez choisie lors de la création de l’API. Un nom de domaine personnalisé est un nom convivial sous un domaine Internet valide. Par exemple, si vous avez enregistré un domaine Internet du nom de `example.com`, n’importe quel `*.example.com` est un nom de domaine personnalisé valide. Pour plus d’informations, consultez [Création d’un nom de domaine valide](how-to-custom-domains.md).
Pour l'[PetStore exemple d'API](api-gateway-create-api-from-example.md), la ressource racine (`/`) expose l'animalerie. La ressource `/pets` désigne l’ensemble des animaux disponibles dans l’animalerie. `/pets/{petId}` expose un animal individuel d’un identifiant donné (`petId`). Le paramètre de chemin de `{petId}` est inclus dans les paramètres de la demande.
Pour configurer une ressource d’API, vous désignez une ressource existante comme son parent, puis vous créez la ressource enfant sous cette ressource parent. Vous commencez par la ressource racine en tant que parent, vous ajoutez une ressource à ce parent, vous ajoutez une autre ressource à cette ressource enfant en tant que nouveau parent, et ainsi de suite, jusqu’à son identificateur parent. Ensuite, vous ajoutez la ressource nommée au parent.
La commande [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) suivante récupère toutes les ressources d’une API :
```
aws apigateway get-resources --rest-api-id apiId
```
Pour l' PetStore exemple d'API, le résultat est le suivant :
```
{
"items": [
{
"path": "/pets",
"resourceMethods": {
"GET": {}
},
"id": "6sxz2j",
"pathPart": "pets",
"parentId": "svzr2028x8"
},
{
"path": "/pets/{petId}",
"resourceMethods": {
"GET": {}
},
"id": "rjkmth",
"pathPart": "{petId}",
"parentId": "6sxz2j"
},
{
"path": "/",
"id": "svzr2028x8"
}
]
}
```
Chaque élément répertorie les identificateurs de la ressource (`id`) et, à l’exception de la ressource racine, son parent immédiat (`parentId`), ainsi que le nom de la ressource (`pathPart`). La ressource racine est spéciale, car elle n’a pas de parent. Après avoir choisi une ressource comme parent, utilisez la commande suivante pour ajouter une ressource enfant :
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id parentId \
--path-part resourceName
```
Par exemple, pour ajouter de la nourriture pour animaux à vendre sur le PetStore site Web, utilisez la commande suivante :
```
aws apigateway create-resource --rest-api-id a1b2c3 \
--parent-id svzr2028x8 \
--path-part food
```
Le résultat se présente comme suit :
```
{
"path": "/food",
"pathPart": "food",
"id": "xdsvhp",
"parentId": "svzr2028x8"
}
```
### Utilisation d’une ressource proxy pour rationnaliser la configuration de l’API
Au fur et à mesure que l'entreprise se développe, le PetStore propriétaire peut décider d'ajouter de la nourriture, des jouets et d'autres articles liés aux animaux de compagnie à vendre. Pour que cela soit pris en charge, vous pouvez ajouter `/food`, `/toys` et d’autres ressources sous la ressource racine. Sous chaque catégorie de vente, vous pouvez également ajouter d’autres ressources, telles que `/food/{type}/{item}`, `/toys/{type}/{item}`, etc. Cela peut être fastidieux. Si vous décidez d’ajouter une couche intermédiaire `{subtype}` aux chemins d’accès de la ressource afin de modifier la hiérarchie de chemin d’accès en `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc., les modifications rendront la configuration de l’API existante inopérante. Pour éviter cela, vous pouvez utiliser une [ressource proxy](api-gateway-set-up-simple-proxy.md) API Gateway pour exposer un jeu de ressources d’API simultanément.
API Gateway définit une ressource proxy comme espace réservé afin qu’une ressource soit spécifiée lorsque la demande est envoyée. Une ressource proxy est exprimée par un paramètre de chemin spécial, `{proxy+}`, souvent désigné comme un paramètre de chemin gourmand. Le signe `+` indique quelles ressources enfants y sont ajoutées. L’espace réservé `/parent/{proxy+}` représente toute ressource correspondant au modèle de chemin `/parent/*`. Vous pouvez utiliser n’importe quelle chaîne pour le nom du paramètre Greedy Path.
La commande [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) suivante crée une ressource proxy sous la racine (`/{proxy+}`) :
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id rootResourceId \
--path-part {proxy+}
```
Le résultat se présente comme suit :
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "234jdr",
"parentId": "svzr2028x8"
}
```
Pour l’exemple d’API `PetStore`, vous pouvez utiliser `/{proxy+}` pour représenter `/pets` et `/pets/{petId}`. Cette ressource proxy peut également faire référence à toute autre ressource (existante ou to-be-added) `/food/{type}/{item}``/toys/{type}/{item}`, telle que, etc.`/food/{type}/{subtype}/{item}`, ou`/toys/{type}/{subtype}/{item}`, etc. Le développeur du backend détermine la hiérarchie de ressource et le développeur client est responsable de sa compréhension. API Gateway ne fait que transmettre ce que le client a envoyé au backend.
Une API peut disposer de plus d’une ressource proxy. Par exemple, les ressources proxy suivantes sont autorisées au sein d’une API, en supposant que `/parent/{proxy+}` n’est pas le même parent que `/parent/{child}/{proxy+}`.
```
/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}
```
Lorsqu’une ressource proxy dispose de sœurs autres que de proxy, les ressources sœurs sont exclues de la représentation de la ressource proxy. Pour les exemples précédents, `/{proxy+}` fait référence à toutes les ressources situées sous la ressource racine, sauf les ressources `/parent[/*]`. En d’autres termes, une méthode de demande sur une ressource spécifique prime sur une méthode de demande sur une ressource générique au même niveau que la hiérarchie de ressource.
Le tableau suivant montre comment API Gateway achemine les demandes vers les ressources suivantes pour l’étape `prod` d’une API.
```
ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog
```
| Demande | Route sélectionnée | Explication |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | La demande correspond entièrement à cette ressource. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | La variable greedy path `/pets/{proxy+}` intercepte cette demande. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | La variable greedy path `/{proxy+}` intercepte cette demande. |
Une ressource proxy ne peut pas disposer de ressource enfant. Toute ressource d’API située après `{proxy+}` est redondante et ambiguë. Les ressources proxy suivantes ne sont pas autorisées au sein d’une API.
```
/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}
```
## Configuration d’une méthode HTTP
Une demande de méthode d’API est encapsulée par la ressource [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) d’API Gateway. Pour configurer la demande de méthode, vous devez d’abord instancier la ressource `Method`, et définir au moins une méthode HTTP et un type d’autorisation sur la méthode.
Étroitement associé à la ressource proxy, API Gateway prend en charge une méthode HTTP `ANY`. Cette méthode `ANY` représente n’importe quelle méthode HTTP à fournir au moment de l’exécution. Cela vous permet d’utiliser une seule configuration de méthode d’API pour toutes les méthodes HTTP prises en charge, `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` et `PUT`.
Vous pouvez configurer la méthode `ANY` sur une ressource autre que de proxy également. L’association de la méthode `ANY` à une ressource proxy vous permet d’obtenir une seule configuration de méthode d’API pour toutes les méthodes HTTP prises en charge par rapport à toutes les ressources d’une API. De plus, le backend peut évoluer sans rendre la configuration d’API existante inopérante.
Avant de configurer une méthode d’API, prenez en compte qui peut appeler la méthode. Définissez le type d’autorisation en fonction de votre plan. Pour un accès ouvert, définissez-le sur `NONE`. Pour utiliser les autorisations IAM, définissez le type d’autorisation sur `AWS_IAM`. Pour utiliser une fonction du mécanisme d’autorisation Lambda, définissez cette propriété sur `CUSTOM`. Pour utiliser un groupe d’utilisateurs Amazon Cognito, définissez le type d’autorisation sur `COGNITO_USER_POOLS`.
La commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante crée une demande de méthode pour le verbe `ANY` en utilisant les autorisations IAM pour contrôler son accès.
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method ANY \
--authorization-type AWS_IAM
```
Pour créer une demande de méthode d’API avec un autre type d’autorisation, consultez [Configuration de l’autorisation de demande de méthode](#setup-method-request-authorization).
## Configuration des paramètres de demande de méthode
Les paramètres de demande de méthode permettent à un client de fournir des données d’entrée ou un contexte d’exécution nécessaires pour terminer la demande de méthode. Un paramètre de méthode peut être un paramètre de chemin, un en-tête ou un paramètre de chaîne de requête. Dans le cadre de la configuration de la demande de méthode, vous devez déclarer les paramètres de demande obligatoires pour les rendre disponibles pour le client. Pour l’intégration autre que de proxy, vous pouvez traduire ces paramètres de demande en un formulaire compatible avec les exigences du serveur principal.
Par exemple, pour la demande de méthode `GET /pets/{petId}`, la variable de chemin d’accès `{petId}` est un paramètre de demande obligatoire. Vous pouvez déclarer ce paramètre de chemin lors de l’appel de la commande `put-method` de l’ AWS CLI. La commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante crée une méthode avec un paramètre de chemin obligatoire :
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id rjkmth \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.path.petId=true
```
Si un paramètre n’est pas obligatoire, vous pouvez le définir sur `false` dans `request-parameters`. Par exemple, si la méthode `GET /pets` utilise un paramètre de chaîne de requête `type` facultatif et un paramètre d’en-tête `age` facultatif, vous pouvez les déclarer à l’aide de la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante :
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.type=false,method.request.header.age=false
```
À la place de cette forme abrégée, vous pouvez utiliser une chaîne JSON pour définir la valeur `request-parameters` :
```
'{"method.request.querystring.type":false,"method.request.header.age":false}'
```
Grâce à cette configuration, le client peut rechercher les animaux par type :
```
GET /pets?type=dog
```
De plus, le client peut rechercher les chiens qui sont des chiots comme suit :
```
GET /pets?type=dog
age:puppy
```
Pour plus d’informations sur le mappage des paramètres de demande de méthode aux paramètres de demande d’intégration, consultez [Intégrations pour REST APIs dans API Gateway](how-to-integration-settings.md).
## Configuration d’un modèle de demande de méthode
Pour obtenir une méthode API pouvant accepter des données d’entrée dans une charge utile, vous pouvez utiliser un modèle. Un modèle est exprimé dans un [schéma JSON version 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) et décrit la structure des données du corps de la demande. Avec un modèle, un client peut déterminer de quelle manière créer une charge utile de demande de méthode en tant qu’entrée. Qui plus est, API Gateway utilise le modèle pour [valider une demande](api-gateway-method-request-validation.md), [générer un kit SDK](how-to-generate-sdk.md) et initialiser un modèle de mappage pour configurer l’intégration dans la console API Gateway. Pour obtenir des informations sur la façon de créer un [modèle](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), consultez [Comprendre les modèles de données](models-mappings-models.md).
En fonction des différents types de contenu, une méthode de charge utile peut avoir différents formats. Un modèle est indexé en fonction du type de média de la charge utile appliquée. API Gateway utilise l’en-tête de `Content-Type` requête pour déterminer le type de contenu. Pour configurer des modèles de demande de méthode, ajoutez des paires clé-valeur du `"media-type":"model-name"` format à la `requestModels` carte lors de l'appel de la AWS CLI `put-method` commande.
Pour utiliser le même modèle quel que soit le type de contenu, spécifiez `$default` comme clé.
Par exemple, pour définir un modèle sur la charge utile JSON de la demande de `POST /pets` méthode de l'API d' PetStore exemple, vous pouvez utiliser la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante :
```
aws apigateway put-method \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method POST \
--authorization-type "NONE" \
--request-models '{"application/json":"petModel"}'
```
Dans cet exemple, `petModel` correspond à la valeur de la propriété `name` d’une ressource [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) décrivant un animal. La définition de schéma réelle est exprimée sous forme d’une valeur de chaîne JSON de la propriété [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) de la ressource `Model`.
Dans Java, ou dans d’autres kits SDK fortement typés, de l’API, les données d’entrée sont exprimées en tant que classe `petModel` dérivée de la définition du schéma. Avec le modèle de demande, les données d’entrée dans le kit SDK généré sont intégrées à la classe `Empty`, qui est dérivée du modèle `Empty` par défaut. Dans ce cas, le client ne peut pas instancier la classe de données correcte pour fournir l’entrée requise.
## Configuration de l’autorisation de demande de méthode
Pour contrôler qui peut appeler la méthode d’API, vous pouvez configurer le [type d’autorisation](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) sur la méthode. Vous pouvez utiliser ce type pour activer l’un des mécanismes d’autorisation pris en charge, notamment les rôles et politiques IAM (`AWS_IAM`), un groupe d’utilisateurs Amazon Cognito (`COGNITO_USER_POOLS`) ou un mécanisme d’autorisation Lambda (`CUSTOM`).
Pour utiliser les autorisations IAM afin d’autoriser l’accès à la méthode d’API, définissez la propriété d’entrée `authorization-type` sur **AWS\$1IAM**. Lorsque vous définissez cette option, API Gateway vérifie la signature de l’appelant dans la demande en fonction des informations d’identification de l’appelant. Si l’utilisateur vérifié est autorisé à appeler la méthode, la demande est acceptée. Sinon, la demande est rejetée et l’appelant reçoit une réponse d’erreur de non-autorisation. L’appel à la méthode n’aboutit pas, à moins que l’appelant soit autorisé à appeler la méthode d’API. La politique IAM suivante accorde à l’appelant l’autorisation d’appeler les méthodes d’API créées dans le même Compte AWS :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:*:*:*"
}
]
}
```
------
Pour de plus amples informations, veuillez consulter [Contrôle de l’accès à une API REST avec des autorisations IAM](permissions.md).
Pour l’heure, vous pouvez uniquement accorder cette politique aux utilisateurs, groupes et rôles relevant du Compte AWS du propriétaire de l’API. Les utilisateurs d'un autre Compte AWS pays ne peuvent appeler les méthodes de l'API que s'ils sont autorisés à assumer un rôle au sein du propriétaire de l'API Compte AWS avec les autorisations nécessaires pour lancer l'`execute-api:Invoke`action. Pour plus d’informations sur les autorisations entre comptes, consultez [Utilisation des rôles IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).
Vous pouvez utiliser AWS CLI un AWS SDK ou un client d'API REST, tel que [Postman](https://www.postman.com/), qui implémente la [signature Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html).
Pour utiliser un mécanisme d’autorisation Lambda permettant d’accéder à la méthode d’API, définissez la propriété d’entrée `authorization-type` sur `CUSTOM` et définissez la propriété d’entrée [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) sur la valeur de propriété [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) d’un mécanisme d’autorisation Lambda qui existe déjà. Le mécanisme d’autorisation Lambda référencé peut être de type `TOKEN` ou `REQUEST`. Pour plus d’informations sur la création d’un mécanisme d’autorisation Lambda, consultez [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md).
Pour utiliser un groupe d’utilisateurs Amazon Cognito permettant d’accéder à la méthode d’API, définissez la propriété d’entrée `authorization-type` sur `COGNITO_USER_POOLS` et définissez la propriété d’entrée [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) sur la valeur de propriété [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) du mécanisme d’autorisation `COGNITO_USER_POOLS` qui a déjà été créé. Pour plus d’informations sur la création d’un mécanisme d’autorisation de groupe d’utilisateurs Amazon Cognito, consultez [Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur](apigateway-integrate-with-cognito.md).
## Configuration de la validation de demande de méthode
Vous pouvez activer la validation de demande lors de la configuration d’une demande de méthode d’API. Pour cela, commencez par créer un [validateur de demande](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). La [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html)commande suivante crée un validateur de demande uniquement pour le corps.
```
aws apigateway create-request-validator \
--rest-api-id 7zw9uyk9kl \
--name bodyOnlyValidator \
--validate-request-body \
--no-validate-request-parameters
```
Le résultat se présente comme suit :
```
{
"validateRequestParameters": false,
"validateRequestBody": true,
"id": "jgpyy6",
"name": "bodyOnlyValidator"
}
```
Vous pouvez utiliser ce validateur de demande pour utiliser la validation de demande dans le cadre de la configuration de la demande de méthode. La commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante crée une demande de méthode qui exige que le corps de la demande entrante corresponde à `PetModel` et comprenne deux paramètres de demande facultatifs :
```
aws apigateway put-method \
--rest-api-id 7zw9uyk9kl \
--resource-id xdsvhp \
--http-method PUT \
--authorization-type "NONE" \
--request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \
--request-models '{"application/json":"petModel"}' \
--request-validator-id jgpyy6
```
Pour inclure un paramètre de demande dans la validation de la demande, vous devez définir `validateRequestParameters` sur `true` pour le validateur de demande, et le paramètre de demande spécifique sur `true` dans la commande `put-method`.
# Configuration d’une réponse de méthode dans API Gateway
Une réponse de méthode d’API encapsule la sortie d’une demande de méthode d’API que le client recevra. Les données de sortie incluent un code de statut HTTP, certains en-têtes et éventuellement un corps.
Avec les intégrations autres que de proxy, les paramètres et le corps de réponse spécifiés peuvent être mappés à partir des données de la réponse d’intégration associés ou se voir attribuer certaines valeurs statiques en fonction des mappages. Ces mappages sont spécifiés dans la réponse d’intégration. Le mappage peut être une transformation identique qui transfère la réponse d’intégration telle quelle.
Avec une intégration de proxy, API Gateway transfère automatiquement la réponse du backend par le biais de la réponse de méthode. Il n’est pas nécessaire de configurer la réponse de méthode d’API. Toutefois, avec l’intégration de proxy Lambda, la fonction Lambda doit renvoyer un résultat dans [ce format de sortie](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) pour qu’API Gateway puisse mapper avec succès la réponse d’intégration à une réponse de méthode.
[https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters)
Lors de la définition des codes de statut pour une méthode d’API, vous devez en choisir par défaut pour gérer une réponse d’intégration quelconque de code de statut inattendu. Il est possible de définir `500` comme valeur par défaut, car cela revient à lancer des réponses non mappées comme une erreur côté serveur. Pour des raisons pédagogiques, la console API Gateway définit la réponse `200` comme valeur par défaut. Mais vous pouvez réinitialiser cette valeur sur la réponse `500`.
Pour configurer une réponse de méthode, vous devez avoir créé la demande de méthode.
## Configuration du code de statut de réponse de méthode
Le code de statut d’une réponse de méthode définit un type de réponse. Par exemple, les réponses de 200, 400 et 500 indiquent des réponses positives, d’erreur côté client et d’erreur côté serveur, respectivement.
Pour configurer un code de statut de réponse de méthode, définissez la propriété [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) sur un code de statut HTTP. La [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)commande suivante crée une réponse de `200` méthode.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200
```
## Configuration des paramètres de réponse de méthode
Les paramètres de méthode de réponse définissent les en-têtes que le client reçoit en réponse à la demande de méthode associée. Les paramètres de réponse spécifient également une cible vers laquelle API Gateway mappe un paramètre de réponse d’intégration, en fonction des mappages prescrits dans la réponse d’intégration de la méthode d’API.
Pour configurer les paramètres de réponse de la méthode, ajoutez au mappage [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) des paires clé/valeur `MethodResponse` au format `"{parameter-name}":"{boolean}"`. La [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)commande suivante définit l'`my-header`en-tête.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false
```
## Configuration des modèles de réponse de méthode
Un modèle de réponse de méthode définit un format pour le corps de la réponse de méthode. La configuration d’un modèle de réponse de méthode est nécessaire lorsque vous générez un kit SDK fortement typé pour l’API. Cela garantit que la sortie est lancée dans une classe correspondante dans Java ou Objective-C. Dans d’autres cas, la configuration d’un modèle est facultative.
Avant de configurer le modèle de réponse, vous devez d’abord créer le modèle dans API Gateway. Pour cela, vous pouvez appeler la commande `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)`. La commande [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) suivante crée un modèle `PetStorePet` pour décrire le corps de la réponse à la demande de méthode `GET /pets/{petId}`.
```
aws apigateway create-model \
--rest-api-id vaz7da96z6 \
--content-type application/json \
--name PetStorePet \
--schema '{ \
"$schema": "http://json-schema.org/draft-04/schema#", \
"title": "PetStorePet", \
"type": "object", \
"properties": { \
"id": { "type": "number" }, \
"type": { "type": "string" }, \
"price": { "type": "number" } \
} \
}'
```
Le résultat est créé en tant que ressource API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html).
Pour configurer les modèles de réponse de méthode afin de définir le format de charge utile, ajoutez la paire clé-valeur « application/json » : » PetStorePet "à la [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels)carte des ressources. [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) La [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)commande suivante crée une méthode de réponse qui utilise un modèle de réponse pour définir le format de charge utile :
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false \
--response-models '{"application/json":"PetStorePet"}'
```
# Configuration d’une méthode à l’aide de la console API Gateway
Lorsque vous créez une méthode à l’aide de la console d’API REST, vous configurez à la fois la demande d’intégration et la demande de méthode. Par défaut, API Gateway crée la réponse de méthode `200` de votre méthode.
Les instructions suivantes expliquent comment modifier les paramètres de requête de méthode et comment créer des réponses de méthode supplémentaires pour votre méthode.
**Topics**
+ [
## Modification d’une demande de méthode API Gateway dans la console API Gateway
](#how-to-method-settings-callers-console)
+ [
## Configuration d’une réponse de méthode API Gateway à l’aide de la console API Gateway
](#how-to-method-response-settings-console)
## Modification d’une demande de méthode API Gateway dans la console API Gateway
Ces instructions supposent que vous avez déjà créé votre demande de méthode. Pour plus d’informations sur la création d’une méthode, consultez [Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway](how-to-method-settings-console.md).
1. Dans le volet **Ressources**, choisissez votre méthode, puis l’onglet **Demande de méthode**.
1. Dans la section **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Pour **Autorisation**, sélectionnez un mécanisme d’autorisation disponible.
1. Pour activer l’accès ouvert à la méthode pour n’importe quel utilisateur, choisissez **Aucun**. Cette étape peut être ignorée si le paramètre par défaut n’a pas été modifié.
1. Pour utiliser les autorisations IAM afin de contrôler l’accès client à la méthode, sélectionnez `AWS_IAM`. Avec ce choix, seuls les utilisateurs des rôles IAM avec la bonne politique IAM attachée sont autorisés à appeler cette méthode.
Pour créer le rôle IAM, spécifiez une stratégie d’accès dans un format similaire à ce qui suit :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/"
]
}
]
}
```
------
Dans cette stratégie d’accès, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` est l’ARN de votre méthode. Vous pouvez trouver l’ARN de votre méthode en sélectionnant la méthode sur la page **Ressources**. Pour en savoir plus sur la définition d’autorisations IAM, consultez [Contrôle de l’accès à une API REST avec des autorisations IAM](permissions.md).
Pour créer le rôle IAM, vous pouvez adapter les instructions du didacticiel [Création d’une fonction Lambda pour l’intégration Lambda autre que de proxy](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda).
1. Pour utiliser un mécanisme d’autorisation Lambda, sélectionnez un jeton ou un mécanisme d’autorisation de demande. Créez un mécanisme d’autorisation Lambda pour que ce choix s’affiche dans le menu déroulant. Pour plus d’informations sur la création d’un mécanisme d’autorisation Lambda, consultez [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md).
1. Pour utiliser un groupe d’utilisateurs Amazon Cognito, choisissez un groupe d’utilisateurs disponible sous **Cognito user pool authorizers (Mécanismes d’autorisation du groupe d’utilisateurs Cognito)**. Créez un groupe d’utilisateurs dans Amazon Cognito, ainsi qu’un mécanisme d’autorisation de groupe d’utilisateurs Amazon Cognito dans API Gateway pour que ce choix s’affiche dans le menu déroulant. Pour plus d’informations sur la manière de créer un mécanisme d’autorisation de groupe d’utilisateurs Amazon Cognito, consultez [Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur](apigateway-integrate-with-cognito.md).
1. Pour spécifier la validation des demandes, sélectionnez une valeur dans le menu déroulant **Validateur de demande**. Pour désactiver la validation des demandes, sélectionnez **Aucune**. Pour plus d’informations concernant chaque option, consultez [Demande de validation pour REST APIs dans API Gateway](api-gateway-method-request-validation.md).
1. Sélectionnez **Clé d’API obligatoire** pour exiger une clé d’API. Lorsque cette option est activée, les clés d’API sont utilisées dans les [plans d’utilisation](api-gateway-api-usage-plans.md) afin de limiter le trafic client.
1. (Facultatif) Pour attribuer un nom d’opération dans un kit SDK Java de cette API généré par API Gateway, entrez un nom pour **Nom de l’opération**. Par exemple, pour la demande de méthode `GET /pets/{petId}`, le nom d’opération du kit SDK Java est, par défaut, `GetPetsPetId`. Ce nom est créé à partir du verbe HTTP der la méthode (`GET`) et des noms de variables du chemin de la ressource (`Pets` et `PetId`). Si vous définissez le nom de l’opération en tant que `getPetById`, le nom d’opération du kit SDK devient `GetPetById`.
1. Pour ajouter un paramètre de chaîne de requête à la méthode, procédez comme suit :
1. Choisissez **Paramètres de chaîne de requête d’URL**, puis **Ajouter une chaîne de requête**.
1. Pour **Nom**, entrez le nom du paramètre de chaîne de requête.
1. Sélectionnez **Obligatoire** si le paramètre de chaîne de requête récemment créé doit être utilisé pour une validation de demande. Pour plus d'informations sur la validation de demande, consultez [Demande de validation pour REST APIs dans API Gateway](api-gateway-method-request-validation.md).
1. Sélectionnez **Mise en cache** si le paramètre de chaîne de requête récemment créé doit être utilisé dans le cadre d’une clé de mise en cache. Pour plus d'informations sur la mise en cache, consultez [Utilisation de paramètres de méthode ou d’intégration en tant que clés de cache pour indexer les réponses mises en cache](api-gateway-caching.md#enable-api-gateway-cache-keys).
Pour supprimer le paramètre de chaîne de requête, choisissez **Supprimer**.
1. Pour ajouter un paramètre d’en-tête à la méthode, procédez comme suit :
1. Choisissez **En-têtes de demande HTTP**, puis **Ajouter un en-tête**.
1. Pour **Nom**, entrez le nom de l’en-tête.
1. Sélectionnez **Obligatoire** si l’en-tête récemment créé doit être utilisé pour une validation de demande. Pour plus d'informations sur la validation de demande, consultez [Demande de validation pour REST APIs dans API Gateway](api-gateway-method-request-validation.md).
1. Sélectionnez **Mise en cache** si l’en-tête récemment créé doit être utilisé dans le cadre d’une clé de mise en cache. Pour plus d'informations sur la mise en cache, consultez [Utilisation de paramètres de méthode ou d’intégration en tant que clés de cache pour indexer les réponses mises en cache](api-gateway-caching.md#enable-api-gateway-cache-keys).
Pour supprimer l’en-tête, choisissez **Supprimer**.
1. Pour déclarer le format de charge utile d’une demande de méthode avec le verbe HTTP `POST`, `PUT` ou `PATCH`, choisissez **Corps de la demande** et procédez comme suit :
1. Choisissez **Add model**.
1. Pour **Content-Type**, entrez un type MIME (par exemple, `application/json`).
1. Pour **Modèle**, sélectionnez un modèle dans le menu déroulant. Les modèles disponibles actuellement pour l’API incluent les modèles `Empty` et `Error` par défaut, ainsi que tous les modèles que vous avez créés et ajoutés à la collection [Models](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) de l’API. Pour plus d’informations sur la création d’un modèle, consultez [Modèles de données pour REST APIs](models-mappings-models.md).
**Note**
Le modèle est utile pour informer le client du format de données prévu pour une charge utile. Il permet également de générer un modèle de mappage squelettique. Il est important de générer un kit SDK fortement typé de l’API dans des langages comme Java, C\$1, Objective-C et Swift. Ceci est nécessaire uniquement si la validation de demande est activée pour la charge utile.
1. Choisissez **Enregistrer**.
## Configuration d’une réponse de méthode API Gateway à l’aide de la console API Gateway
Une méthode d’API peut avoir un ou plusieurs réponses. Chaque réponse est indexée selon son code de statut HTTP. Par défaut, la console API Gateway ajoute la réponse `200` aux réponses de méthode. Vous pouvez modifier cela, par exemple pour que la méthode renvoie plutôt la réponse `201`. Vous pouvez ajouter d’autres réponses, par exemple, `409` en cas d’accès refusé et `500` si des variables d’étape non initialisées sont utilisées.
Pour utiliser la console API Gateway pour modifier, supprimer ou ajouter une réponse à une méthode d’API, suivez les instructions suivantes.
1. Dans le volet **Ressources**, choisissez votre méthode, puis l’onglet **Réponse de méthode**. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.
1. Dans la section **Paramètres de réponse de la méthode**, choisissez **Créer une réponse**.
1. Pour **Code de statut HTTP**, entrez un code de statut HTTP, tel que `200`, `400` ou `500`.
Lorsqu’une réponse renvoyée par le backend n’a pas de méthode de réponse correspondante définie, API Gateway échoue à renvoyer la réponse au client. Au lieu de cela, une réponse d’erreur `500 Internal server error` est renvoyée.
1. Sélectionnez **Add header**.
1. Pour **Nom de l’en-tête**, entrez un nom.
Pour renvoyer un en-tête du backend au client, ajoutez-le dans la réponse de la méthode.
1. Choisissez **Ajouter un modèle** pour définir un format pour le corps de la réponse de méthode.
Entrez le type de média de la charge utile de la réponse pour **Type de contenu** et choisissez un modèle dans le menu déroulant **Modèles**.
1. Choisissez **Enregistrer**.
Pour modifier une réponse existante, accédez à la réponse de votre méthode, puis choisissez **Modifier**. Pour modifier le **Code de statut HTTP**, choisissez **Supprimer** et créez une nouvelle méthode de réponse.
Pour chaque réponse renvoyée par le backend, vous devez disposer d’une réponse compatible configurée comme réponse de méthode. Toutefois, le modèle de charge utile et d’en-têtes de réponse de méthode de configuration sont facultatifs, sauf si vous mappez le résultat à partir du backend à la réponse de méthode avant de revenir au client. De plus, un modèle de charge utile de réponse de méthode est important si vous générez un kit SDK fortement typé pour votre API.
# Contrôler et gérer l'accès à REST APIs dans API Gateway
API Gateway prend en charge plusieurs mécanismes pour contrôler et gérer l’accès à votre API.
Les mécanismes suivants peuvent être utilisés pour l’authentification et l’autorisation :
+ **Les politiques de ressources** vous permettent de créer des politiques basées sur les ressources pour autoriser ou refuser l'accès à vos méthodes APIs et à partir d'adresses IP sources ou de points de terminaison VPC spécifiés. Pour de plus amples informations, veuillez consulter [Contrôle d’accès à une API REST avec des politiques de ressources API Gateway](apigateway-resource-policies.md).
+ **Les rôles et politiques AWS IAM standard** offrent des contrôles d'accès flexibles et robustes qui peuvent être appliqués à une API complète ou à des méthodes individuelles. Les rôles et politiques IAM peuvent être utilisés 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ôle de l’accès à une API REST avec des autorisations IAM](permissions.md).
+ Les **balises IAM** peuvent être utilisées avec des politiques IAM pour contrôler l’accès. Pour de plus amples informations, veuillez consulter [Utilisation de balises pour contrôler l’accès aux ressources API REST API Gateway](apigateway-tagging-iam-policy.md).
+ **Les politiques de point de terminaison pour les points de terminaison VPC d'interface** [vous permettent d'associer des politiques de ressources IAM aux points de terminaison VPC d'interface afin d'améliorer la sécurité de vos données privées. APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html) Pour de plus amples informations, veuillez consulter [Utiliser les politiques de point de terminaison VPC pour le mode privé APIs dans API Gateway](apigateway-vpc-endpoint-policies.md).
+ Les **mécanismes d’autorisation Lambda** sont des fonctions Lambda qui contrôlent l’accès à vos méthodes d’API REST à l’aide d’authentification par jeton de porteur, ainsi qu’aux informations figurant dans les paramètres de la requête tels que les en-têtes, chemins, chaînes de requête, variables d’étape ou variables de contexte. Les autorisateurs Lambda sont utilisés pour contrôler qui peut appeler les méthodes d’API REST. Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md).
+ Les **groupes d'utilisateurs Amazon Cognito** vous permettent de créer des solutions d'authentification et d'autorisation personnalisables pour votre REST. APIs Les groupes d’utilisateurs Amazon Cognito sont utilisés pour contrôler qui peut appeler les méthodes d’API REST. Pour de plus amples informations, veuillez consulter [Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur](apigateway-integrate-with-cognito.md).
Les mécanismes suivants peuvent être utilisés pour effectuer d’autres tâches liées au contrôle de l’accès :
+ Le **partage des ressources cross-origin (CORS)** vous permet de contrôler la façon dont votre API REST répond aux requêtes de ressources inter-domaines. Pour de plus amples informations, veuillez consulter [CORS pour REST APIs dans API Gateway](how-to-cors.md).
+ Les **certificats SSL côté client** peuvent être utilisés pour vérifier que les requêtes HTTP adressées à votre système backend proviennent d’API Gateway. Pour de plus amples informations, veuillez consulter [Génération et configuration d’un certificat SSL pour l’authentification backend dans API Gateway](getting-started-client-side-ssl-authentication.md).
+ **AWS WAF** peut être utilisé pour protéger votre API API Gateway contre les menaces web courantes. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md).
Les mécanismes suivants peuvent être utilisés pour suivre et limiter l’accès que vous avez accordé aux clients autorisés :
+ Les **plans d’utilisation** vous permettent de fournir des **clés d’API** à vos clients. Vous pouvez ensuite suivre et limiter l’utilisation de vos étapes et méthodes d’API pour chaque clé d’API. Pour de plus amples informations, veuillez consulter [Plans d'utilisation et clés d'API pour REST APIs dans API Gateway](api-gateway-api-usage-plans.md).
# Contrôle d’accès à une API REST avec des politiques de ressources API Gateway
Les *politiques de ressources* Amazon API Gateway sont des documents de politique JSON que vous attachez à une API pour contrôler si un principal spécifié (généralement un groupe ou un rôle IAM) peut appeler l’API. Vous pouvez utiliser des politiques de ressources API Gateway pour autoriser l’appel sécurisé de votre API par :
+ Utilisateurs d'un AWS compte spécifié.
+ les plages d’adresses IP ou les blocs d’adresse CIDR d’un source spécifiée ;
+ Clouds privés virtuels (VPCs) ou points de terminaison VPC spécifiés (quel que soit le compte).
Vous pouvez joindre une politique de ressources pour n'importe quel type de point de terminaison d'API dans API Gateway à l' AWS Management Console aide de la AWS CLI ou AWS SDKs. Pour le [mode privé APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html), vous pouvez utiliser des politiques de ressources ainsi que des politiques de point de terminaison VPC pour contrôler quels principaux ont accès à quelles ressources et actions. Pour de plus amples informations, veuillez consulter [Utiliser les politiques de point de terminaison VPC pour le mode privé APIs dans API Gateway](apigateway-vpc-endpoint-policies.md).
Les politiques de ressources API Gateway sont différentes des politiques basées sur l’identité IAM. Les politiques basées sur l’identité IAM sont attachées à des utilisateurs, groupes ou rôles IAM et définissent les actions que ces identités sont capables d’exécuter, ainsi que les ressources sur lesquelles peuvent porter ces actions. Les politiques de ressources API Gateway sont attachées à des ressources. Vous pouvez utiliser des politiques de ressources API Gateway avec les politiques IAM. Pour plus d’informations, consultez [Politiques basées sur l’identité et politiques basées sur une ressource](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html).
**Topics**
+ [
# Présentation du langage de la politique d’accès pour Amazon API Gateway
](apigateway-control-access-policy-language-overview.md)
+ [
# Comment les politiques de ressources API Gateway affectent le flux de travail d’autorisation
](apigateway-authorization-flow.md)
+ [
# Exemples de politiques de ressources API Gateway
](apigateway-resource-policies-examples.md)
+ [
# Création et attachement d’une politique de ressources API Gateway à une API
](apigateway-resource-policies-create-attach.md)
+ [
# AWS clés de condition pouvant être utilisées dans les politiques de ressources d'API Gateway
](apigateway-resource-policies-aws-condition-keys.md)
# Présentation du langage de la politique d’accès pour Amazon API Gateway
Cette page décrit les éléments de base utilisés dans les politiques de ressources Amazon API Gateway.
Les politiques de ressources sont spécifiées en utilisant la même syntaxe que dans les politiquess IAM. Pour obtenir des informations complètes sur le langage de politique d’accès, consultez [Présentation des politiques IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) et [Référence des politiques Gestion des identités et des accès AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) dans le *Guide de l’utilisateur IAM*.
Pour plus d'informations sur la manière dont un AWS service décide si une demande donnée doit être autorisée ou refusée, voir [Déterminer si une demande est autorisée ou refusée](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow).
## Éléments courants dans une stratégie d’accès
Une politique de ressources contient à la base les éléments suivants :
+ **Ressources** : APIs il s'agit des ressources Amazon API Gateway pour lesquelles vous pouvez autoriser ou refuser des autorisations. Dans une politique, vous pouvez utiliser l’Amazon Resource Name (ARN) pour identifier la ressource. Vous pouvez également utiliser une syntaxe abrégée, qui sera automatiquement développée par API Gateway en ARN complet lors de l’enregistrement d’une politique de ressources. Pour en savoir plus, veuillez consulter la section [Exemples de politiques de ressources API Gateway](apigateway-resource-policies-examples.md).
Pour connaître le format de l’élément `Resource` complet, consultez [Format de l’expression Resource des autorisations d’exécution d’API dans API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-resource-format-for-executing-api).
+ **Actions** – pour chaque ressource, Amazon API Gateway prend en charge un ensemble d’opérations. Vous identifiez les opérations de ressource que vous accordez (ou refusez) en utilisant des mots clés d’action.
Par exemple, l’autorisation `execute-api:Invoke` va permettre à l’utilisateur d’appeler une API sur demande d’un client.
Pour connaître le format de l’élément `Action`, consultez [Format de l’expression Action des autorisations d’exécution d’API dans API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-action-format-for-executing-api).
+ **Effet** – L’effet produit lorsque l’utilisateur demande une action spécifique. Il peut s’agir de `Allow` ou `Deny`. Vous pouvez aussi explicitement refuser l’accès à une ressource, ce que vous pouvez faire afin de vous assurer qu’un utilisateur n’y a pas accès, même si une politique différente octroie l’accès.
**Note**
« Refus implicite » est la même chose que « Refus par défaut ».
Un « refus implicite » est différent d’un « refus explicite ». Pour plus d’informations, consultez [Différence entre refus par défaut et refus explicite](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#AccessPolicyLanguage_Interplay).
+ **Principal** – Compte ou utilisateur autorisé à accéder aux actions ou ressources dans l’instruction. Dans une politique de ressources, le principal est l’utilisateur ou le compte qui reçoit cette autorisation.
L’exemple de politique de ressources suivant montre les éléments de politique courants précédemment évoqués. La politique accorde l'accès à l'API selon les termes spécifiés *account-id* *region* à tout utilisateur dont l'adresse IP source se trouve dans le bloc d'adresses*123.4.5.6/24*. La politique refuse tout accès à l’API si l’adresse IP source de l’utilisateur n’est pas comprise dans cette plage.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:*"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:*",
"Condition": {
"NotIpAddress": {
"aws:SourceIp": "123.4.5.6/24"
}
}
}
]
}
```
------
# Comment les politiques de ressources API Gateway affectent le flux de travail d’autorisation
Lorsqu’API Gateway évalue la politique de ressources attachée à votre API, le résultat est affecté par le type d’authentification que vous avez défini pour l’API, comme illustré dans les diagrammes présentés dans les sections suivantes.
**Topics**
+ [
## Politique de ressources API Gateway uniquement
](#apigateway-authorization-flow-resource-policy-only)
+ [
## Mécanisme d’autorisation Lambda et politique de ressources
](#apigateway-authorization-flow-lambda)
+ [
## Politique de ressources et authentification IAM
](#apigateway-authorization-flow-iam)
+ [
## Politique de ressources et d’authentification Amazon Cognito
](#apigateway-authorization-flow-cognito)
+ [
## Tableaux de résultat des évaluations de politiques
](#apigateway-resource-policies-iam-policies-interaction)
## Politique de ressources API Gateway uniquement
Dans ce flux de travail, une politique de ressources API Gateway est attachée à l’API, mais aucun type d’authentification n’est défini pour l’API. L’évaluation de la politique consiste à obtenir une autorisation explicite en fonction des critères entrants de l’appelant. Un refus implicite ou explicite entraîne le refus de l’appelant.
![\[Flux d’autorisation pour une politique de ressources uniquement.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-auth-resource-policy-only.png)
Voici un exemple de politique de ressources.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
## Mécanisme d’autorisation Lambda et politique de ressources
Dans ce flux de travail, un mécanisme d’autorisation Lambda est configuré pour l’API en plus d’une politique de ressources. La politique de ressources est évaluée en deux phases. Avant d’appeler le mécanisme d’autorisation Lambda, API Gateway évalue la politique et vérifie tout refus explicite. S’il en trouve, l’accès sera immédiatement refusé à l’utilisateur. Sinon, le mécanisme d’autorisation Lambda est appelé et renvoie un [document de politique](api-gateway-lambda-authorizer-output.md) évalué avec la politique de ressources. Si votre mécanisme d’autorisation utilise la mise en cache, API Gateway peut renvoyer le document de politique mis en cache. Le résultat est déterminé sur la base du [tableau A](#apigateway-resource-policies-iam-policies-interaction).
Dans l’exemple de politique de ressources suivant, les appels sont autorisés uniquement à partir du point de terminaison de VPC dont l’ID est `vpce-1a2b3c4d`. Pendant l’évaluation d’authentification préalable, seuls les appels provenant du point de terminaison de VPC indiqué dans l’exemple peuvent continuer et évaluer le mécanisme d’autorisation Lambda. Tous les appels restants sont bloqués. Ce flux de travail d’autorisation est le même si vous utilisez un nom de domaine personnalisé pour une API privée.
![\[Flux d’autorisation pour une politique de ressources et un mécanisme d’autorisation Lambda.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-auth-lambda-resource-policy.png)
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}
```
------
## Politique de ressources et authentification IAM
Dans ce flux de travail, vous configurez l’authentification IAM pour l’API en plus d’une politique de ressources. Une fois que vous avez authentifié l’utilisateur auprès du service IAM, l’API évalue à la fois les politiques attachées à l’utilisateur et la politique de ressources. Le résultat varie selon que l'appelant est le même que le propriétaire de Compte AWS l'API Compte AWS ou non.
Si l’appelant et le propriétaire de l’API relèvent de comptes distincts, les politiques IAM et la politique de ressources autorisent toutes deux explicitement l’appelant à continuer. Pour plus d’informations, consultez [Tableau B](#apigateway-resource-policies-iam-policies-interaction).
Cependant, si l’appelant et le propriétaire de l’API relèvent du même Compte AWS, les politiques utilisateur IAM ou la politique de ressources doivent explicitement autoriser l’appelant à continuer. Pour plus d’informations, consultez [Tableau A](#apigateway-resource-policies-iam-policies-interaction).
![\[Flux d’autorisation pour une politique de ressources et une authentification IAM.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-auth-iam-resource-policy.png)
Voici un exemple de politique de ressources entre comptes. À supposer que la politique IAM contient un effet Allow (Autoriser), cette politique de ressources autorise uniquement les appels du VPC dont l’ID est `vpc-2f09a348`. Pour plus d’informations, consultez [Tableau B](#apigateway-resource-policies-iam-policies-interaction).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/"
],
"Condition" : {
"StringEquals": {
"aws:SourceVpc": "vpc-2f09a348"
}
}
}
]
}
```
------
## Politique de ressources et d’authentification Amazon Cognito
Dans ce flux de travail, un [groupe d’utilisateurs Amazon Cognito](apigateway-integrate-with-cognito.md) est configuré pour l’API en plus d’une politique de ressources. API Gateway tente d’abord d’authentifier l’appelant via Amazon Cognito. Ceci est généralement effectué via un [jeton JWT](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) fourni par l’appelant. Si l’authentification est réussie, la politique de ressources est évaluée de façon indépendante, et une autorisation explicite est requise. Un refus ou « ni autoriser ni refuser » entraîne un refus. Voici un exemple de politique de ressources pouvant être utilisée avec des groupes d’utilisateurs Amazon Cognito.
![\[Flux d’autorisation pour une politique de ressources et un mécanisme d’autorisation Amazon Cognito.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-auth-cognito-resource-policy.png)
Voici un exemple de politique de ressources qui autorise les appels uniquement à partir d'une source spécifiée IPs, en supposant que le jeton d'authentification Amazon Cognito contienne une autorisation. Pour plus d’informations, consultez [Tableau B](#apigateway-resource-policies-iam-policies-interaction).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
## Tableaux de résultat des évaluations de politiques
Le tableau A répertorie le comportement obtenu lorsque l’accès à une API API Gateway est contrôlé par une politique IAM ou un mécanisme d’autorisation Lambda et une politique de ressources API Gateway, qui se trouvent toutes les deux dans le même Compte AWS.
| **Politique IAM (ou mécanisme d’autorisation Lambda)** | **Politique de ressources API Gateway** | **Comportement obtenu** |
| --- | --- | --- |
| Autorisation | Autorisation | Autorisation |
| Autorisation | Ni autorisation ni refus | Autorisation |
| Autorisation | Refuser | Refus explicite |
| Ni autorisation ni refus | Autorisation | Autorisation |
| Ni autorisation ni refus | Ni autorisation ni refus | Refus implicite |
| Ni autorisation ni refus | Refuser | Refus explicite |
| Refuser | Autorisation | Refus explicite |
| Refuser | Ni autorisation ni refus | Refus explicite |
| Refuser | Refuser | Refus explicite |
Le tableau B répertorie le comportement qui en résulte lorsque l'accès à une API API Gateway est contrôlé par une politique IAM ou un autorisateur de groupes d'utilisateurs Amazon Cognito et une politique de ressources API Gateway, qui sont différentes. Comptes AWS Si l’un des deux est silencieux (pas d’autorisation ni de refus), l’accès entre comptes est refusé. En effet, l’accès intercompte nécessite que la politique de ressources et la politique IAM ou le mécanisme d’autorisation des groupes d’utilisateurs Amazon Cognito accordent explicitement l’accès.
| **Politique IAM (ou mécanisme d’autorisation des groupes d’utilisateurs Amazon Cognito)** | **Politique de ressources API Gateway** | **Comportement obtenu** |
| --- | --- | --- |
| Autorisation | Autorisation | Autorisation |
| Autorisation | Ni autorisation ni refus | Refus implicite |
| Autorisation | Refuser | Refus explicite |
| Ni autorisation ni refus | Autorisation | Refus implicite |
| Ni autorisation ni refus | Ni autorisation ni refus | Refus implicite |
| Ni autorisation ni refus | Refuser | Refus explicite |
| Refuser | Autorisation | Refus explicite |
| Refuser | Ni autorisation ni refus | Refus explicite |
| Refuser | Refuser | Refus explicite |
# Exemples de politiques de ressources API Gateway
Cette page présente quelques exemples de cas d’utilisation standard des politiques de ressources API Gateway.
Les exemples de politique suivants utilisent une syntaxe simplifiée pour spécifier la ressource d’API. Cette syntaxe simplifiée est une façon abrégée qui vous permet de faire référence à une ressource d’API plutôt que de spécifier l’Amazon Resource Name (ARN) complet. API Gateway convertit la syntaxe abrégée en ARN complet lorsque vous enregistrez la politique. Par exemple, vous pouvez spécifier la ressource `execute-api:/stage-name/GET/pets` dans une politique de ressources. API Gateway convertit la ressource `arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets` lorsque vous enregistrez la politique de ressources. API Gateway crée l'ARN complet en utilisant la région actuelle, votre ID de AWS compte et l'ID de l'API REST à laquelle la politique de ressources est associée. Vous pouvez utiliser `execute-api:/*` pour représenter toutes les étapes, méthodes et chemins dans l’API actuelle. Pour en savoir plus sur le langage de la politique d’accès, consultez [Présentation du langage de la politique d’accès pour Amazon API Gateway](apigateway-control-access-policy-language-overview.md).
**Topics**
+ [
## Exemple : autoriser les rôles d'un autre AWS compte à utiliser une API
](#apigateway-resource-policies-cross-account-example)
+ [
## Exemple : refuser le trafic API en fonction de l’adresse IP source ou de la plage
](#apigateway-resource-policies-source-ip-address-example)
+ [
## Exemple : Refuser le trafic API en fonction de l’adresse IP source ou de la plage lors de l’utilisation d’une API privée
](#apigateway-resource-policies-source-ip-address-vpc-example)
+ [
## Exemple : autoriser le trafic de l’API privée en fonction du point de terminaison d’un VPC ou d’un VPC source
](#apigateway-resource-policies-source-vpc-example)
## Exemple : autoriser les rôles d'un autre AWS compte à utiliser une API
L'exemple de politique de ressources suivant accorde l'accès à l'API dans un AWS compte à deux rôles dans un AWS compte différent via les [protocoles Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) (SigV4) ou [Signature Version 4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works) (SigV4a). Plus précisément, le rôle de développeur et d'administrateur du AWS compte identifié par `account-id-2` est autorisé à exécuter l'`GET`action sur la `pets` ressource (API) de votre AWS compte. `execute-api:Invoke`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/developer",
"arn:aws:iam::111122223333:role/Admin"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}
```
------
## Exemple : refuser le trafic API en fonction de l’adresse IP source ou de la plage
L’exemple de politique de ressources suivant refuse (bloque) le trafic entrant vers une API à partir de deux blocs d’adresses IP source spécifiés.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
Si vous utilisez des politiques utilisateur IAM ou des politiques de ressources API Gateway pour contrôler l'accès à API Gateway ou à toute autre API Gateway APIs, vérifiez que vos politiques sont mises à jour pour inclure les plages d' IPv6 adresses. Les politiques qui ne sont pas mises à jour pour gérer IPv6 les adresses peuvent avoir un impact sur l'accès du client à API Gateway lorsqu'il commence à utiliser le point de terminaison dualstack. Pour de plus amples informations, veuillez consulter [Utilisation des IPv6 adresses dans les politiques IAM](api-ref.md#api-reference-service-endpoints-dualstack-iam).
## Exemple : Refuser le trafic API en fonction de l’adresse IP source ou de la plage lors de l’utilisation d’une API privée
L’exemple de politique de ressources suivant refuse (bloque) le trafic entrant vers une API privée à partir de deux blocs d’adresses IP source spécifiés. Lorsque vous utilisez le mode privé APIs, le point de terminaison VPC pour `execute-api` réécrit l'adresse IP source d'origine. La condition `aws:VpcSourceIp` filtre la demande par rapport à l’adresse IP du demandeur d’origine.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"]
}
}
}
]
}
```
------
## Exemple : autoriser le trafic de l’API privée en fonction du point de terminaison d’un VPC ou d’un VPC source
L’exemple de politiques de ressources suivant autorise le trafic entrant vers une API privée uniquement à partir d’un VPC (Virtual Private Cloud) spécifié ou d’un point de terminaison d’un VPC.
Cet exemple de politique de ressources spécifie un VPC source :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpc": "vpc-1a2b3c4d"
}
}
}
]
}
```
------
Cet exemple de politique de ressources spécifie un point de terminaison d’un VPC source :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}
```
------
# Création et attachement d’une politique de ressources API Gateway à une API
Pour permettre à un utilisateur d’accéder à votre API en appelant le service d’exécution des API, vous devez créer une politique de ressources API Gateway et l’attacher à l’API. Lorsque vous attachez une politique votre API, celle-ci applique les autorisations de la politique aux méthodes de l’API. En cas de mise à jour de la politique de ressources, vous devrez déployer l’API.
**Topics**
+ [
## Conditions préalables
](#apigateway-resource-policies-prerequisites)
+ [
## Attachement d’une politique de ressources à une API API Gateway
](#apigateway-resource-policies-create-attach-procedure)
+ [
## Résolution des problèmes liés à votre politique de ressources
](#apigateway-resource-policies-troubleshoot)
## Conditions préalables
Pour mettre à jour une politique de ressources API Gateway, vous devez disposer des autorisations `apigateway:UpdateRestApiPolicy` et `apigateway:PATCH`.
Pour une API optimisée pour la périphérie ou régionale, vous pouvez attacher votre politique de ressources à votre API lors de sa création ou après son déploiement. Pour une API privée, vous ne pouvez pas déployer votre API sans politique de ressources. Pour de plus amples informations, veuillez consulter [REST privé APIs dans API Gateway](apigateway-private-apis.md).
## Attachement d’une politique de ressources à une API API Gateway
La procédure suivante vous montre comment attacher une politique de ressources à une API API Gateway.
------
#### [ AWS Management Console ]
**Pour attacher une politique de ressources à une API 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 REST.
1. Dans le panneau de navigation principal, choisissez **Stratégie de ressources**.
1. Choisissez **Create Policy** (Créer une stratégie).
1. (Facultatif) Choisissez **Sélectionnez un modèle** pour générer un exemple de politique.
Dans les exemples de politiques, les espaces réservés sont délimitées par des doubles accolades (`"{{placeholder}}"`). Remplacez chacun des espaces réservés (y compris les accolades) par les informations nécessaires.
1. Si vous n’utilisez pas l’un des exemples de modèle, entrez votre politique de ressources.
1. Sélectionnez **Enregistrer les modifications**.
Si l’API a déjà été déployée dans la console API Gateway, vous devez la redéployer pour que la politique de ressources prenne effet.
------
#### [ AWS CLI ]
AWS CLI Pour créer une nouvelle API et y associer une politique de ressources, utilisez la [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante :
```
aws apigateway create-rest-api \
--name "api-name" \
--policy "{\"jsonEscapedPolicyDocument\"}"
```
AWS CLI Pour associer une politique de ressources à une API existante, utilisez la [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)commande suivante :
```
aws apigateway update-rest-api \
--rest-api-id api-id \
--patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"'
```
Vous pouvez également joindre votre politique de ressources dans un `policy.json` fichier distinct et l'inclure dans votre [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande. La [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante crée une nouvelle API avec une politique de ressources :
```
aws apigateway create-rest-api \
--name "api-name" \
--policy file://policy.json
```
`policy.json` est une politique de ressources API Gateway, comme [Exemple : refuser le trafic API en fonction de l’adresse IP source ou de la plage](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example).
------
#### [ AWS CloudFormation ]
Vous pouvez l'utiliser CloudFormation pour créer une API avec une politique de ressources. L’exemple suivant crée une API REST avec l’exemple de politique de ressources [Exemple : refuser le trafic API en fonction de l’adresse IP source ou de la plage](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example).
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: testapi
Policy:
Statement:
- Action: 'execute-api:Invoke'
Effect: Allow
Principal: '*'
Resource: 'execute-api:/*'
- Action: 'execute-api:Invoke'
Effect: Deny
Principal: '*'
Resource: 'execute-api:/*'
Condition:
IpAddress:
'aws:SourceIp': ["192.0.2.0/24", "198.51.100.0/24" ]
Version: 2012-10-17
Resource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'helloworld'
MethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref Resource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: MOCK
RequestTemplates:
application/json: '{"statusCode": 200}'
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: '{}'
MethodResponses:
- StatusCode: 200
ResponseModels:
application/json: 'Empty'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- MethodGet
Properties:
RestApiId: !Ref Api
StageName: test
```
------
## Résolution des problèmes liés à votre politique de ressources
Les conseils suivants peuvent vous aider à résoudre les problèmes liés à votre politique de ressources.
### Mon API renvoie \$1"Message":"L’utilisateur: anonyme n’est pas autorisé à exécuter : execute-api:Invoke sur la ressource : arn:aws:execute-api:us-east-1:\$1\$1\$1\$1\$1\$1\$1\$1/\$1\$1\$1\$1/\$1\$1\$1\$1/"\$1
Dans votre politique de ressources, si vous attribuez au principal un AWS principal, tel que ce qui suit :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111111111111:role/developer",
"arn:aws:iam::111111111111:role/Admin"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}
```
------
Vous devez utiliser l’autorisation `AWS_IAM` pour chaque méthode de votre API, sinon votre API renvoie le message d’erreur précédent. Pour plus d’instructions sur l’activation de l’autorisation `AWS_IAM` pour une méthode, consultez [Méthodes pour REST APIs dans API Gateway](how-to-method-settings.md).
### Ma politique de ressources n’est pas mise à jour
Si vous mettez à jour la politique de ressources une fois l’API créée, vous devez déployer l’API pour propager les changements une fois le rattachement de la politique mise à jour effectué. La simple mise à jour ou le simple enregistrement de la politique ne modifie pas le comportement d’exécution de l’API. Pour plus d’informations sur le déploiement de votre API, consultez [Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md).
### Ma politique de ressources renvoie l’erreur suivante : document de politique non valide. Vérifiez la syntaxe de la politique et assurez-vous que les principaux sont valides.
Pour corriger cette erreur, nous vous recommandons de vérifier d’abord la syntaxe de la politique. Pour de plus amples informations, veuillez consulter [Présentation du langage de la politique d’accès pour Amazon API Gateway](apigateway-control-access-policy-language-overview.md). Nous vous recommandons également de vérifier que tous les principaux spécifiés sont valides et n’ont pas été supprimés.
En outre, si votre API se trouve dans une [région d’acceptation](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#optinregion), vérifiez que la région est activée pour tous les comptes de la politique de ressources.
# AWS clés de condition pouvant être utilisées dans les politiques de ressources d'API Gateway
Le tableau suivant contient les clés de AWS condition qui peuvent être utilisées dans les politiques de ressources d'API Gateway pour chaque type d'autorisation. APIs
Pour plus d'informations sur les clés de AWS condition, consultez la section [Clés contextuelles de condition AWS globales](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html).
| **Clés de condition** | **Critères** | **Nécessite `AuthN` ?** | **Type d’autorisation** |
| --- | --- | --- | --- |
| aws:CurrentTime | Aucun | Non | Tous |
| aws:EpochTime | Aucun | Non | Tous |
| aws:TokenIssueTime | Cette clé est uniquement présente dans les demandes signées à l'aide d'informations d'identification de sécurité temporaires. | Oui | IAM |
| aws:MultiFactorAuthPresent | Cette clé est uniquement présente dans les demandes signées à l'aide d'informations d'identification de sécurité temporaires. | Oui | IAM |
| aws:MultiFactorAuthAge | La clé est présente uniquement si l’élément MFA est présent dans la demande. | Oui | IAM |
| aws:PrincipalAccount | Aucun | Oui | IAM |
| aws:PrincipalArn | Aucun | Oui | IAM |
| aws:PrincipalOrgID | Cette clé ne figure dans le contexte de la demande que si le mandataire est membre d'une organisation. | Oui | IAM |
| aws:PrincipalOrgPaths | Cette clé ne figure dans le contexte de la demande que si le mandataire est membre d'une organisation. | Oui | IAM |
| aws:PrincipalTag | Cette clé figure dans le contexte de la demande si le mandataire utilise un utilisateur IAM avec des balises attachées. Elle est incluse pour un mandataire utilisant un rôle IAM avec des balises attachées ou des balises de session. | Oui | IAM |
| aws:PrincipalType | Aucun | Oui | IAM |
| aws:Referer | La clé est présente uniquement si la valeur est fournie par le mandataire dans l'en-tête HTTP. | Non | Tous |
| aws:SecureTransport | Aucun | Non | Tous |
| aws:SourceArn | Aucun | Non | Tous |
| aws:SourceIp | Aucun | Non | Tous |
| aws:SourceVpc | Cette clé ne peut être utilisée qu'à des fins privées APIs. | Non | Tous |
| aws:SourceVpce | Cette clé ne peut être utilisée qu'à des fins privées APIs. | Non | Tous |
| aws:VpcSourceIp | Cette clé ne peut être utilisée qu'à des fins privées APIs. | Non | Tous |
| aws:UserAgent | La clé est présente uniquement si la valeur est fournie par le mandataire dans l'en-tête HTTP. | Non | Tous |
| aws:userid | Aucun | Oui | IAM |
| aws:username | Aucun | Oui | IAM |
# Contrôle de l’accès à une API REST avec des autorisations IAM
Vous contrôlez l’accès à votre API Amazon API Gateway avec les [autorisations IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) en contrôlant l’accès aux deux processus de composant API Gateway suivants :
+ Pour créer, déployer et gérer une API dans API Gateway, vous devez accorder les autorisations aux développeurs d’API pour qu’ils exécutent les actions requises prises en charge par le composant de gestion des API API Gateway.
+ Pour appeler une API déployée ou pour actualiser la mise en cache de l’API, vous devez accorder les autorisations de l’appelant d’API pour exécuter les actions IAM obligatoires prises en charge par le composant de l’exécution d’API API Gateway.
Le contrôle d’accès pour les deux processus implique différents modèles d’autorisation, expliqués plus bas.
## Modèle d’autorisation API Gateway pour créer et gérer une API
Pour permettre à un développeur d’API de créer et gérer une API dans API Gateway, vous devez [créer des politiques d’autorisation IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) qui permettent à un développeur d’API spécifié de créer, mettre à jour, déployer, afficher ou supprimer les [entités d’API](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) requises. Vous attachez la politique d’autorisations à un utilisateur, un rôle ou un groupe.
Pour activer l’accès, ajoutez des autorisations à vos utilisateurs, groupes ou rôles :
+ Utilisateurs et groupes dans AWS IAM Identity Center :
Créez un jeu d’autorisations. Suivez les instructions de la rubrique [Création d’un jeu d’autorisations](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) du *Guide de l’utilisateur AWS IAM Identity Center *.
+ Utilisateurs gérés dans IAM par un fournisseur d’identité :
Créez un rôle pour la fédération d’identité. Suivez les instructions de la rubrique [Création d’un rôle pour un fournisseur d’identité tiers (fédération)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) dans le *Guide de l’utilisateur IAM*.
+ Utilisateurs IAM :
+ Créez un rôle que votre utilisateur peut assumer. Suivez les instructions de la rubrique [Création d’un rôle pour un utilisateur IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) dans le *Guide de l’utilisateur IAM*.
+ (Non recommandé) Attachez une politique directement à un utilisateur ou ajoutez un utilisateur à un groupe d’utilisateurs. Suivez les instructions de la rubrique [Ajout d’autorisations à un utilisateur (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) du *Guide de l’utilisateur IAM*.
Pour plus d’informations sur l’utilisation de ce modèle d’autorisation, consultez [Stratégies basées sur l'identité d'API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
## Modèle d’autorisation API Gateway pour l’appel d’une API
Pour permettre à un appelant d’API d’appeler l’API ou d’actualiser sa mise en cache, vous devez créer des politiques IAM qui permettent à un appelant d’API spécifié d’appeler la méthode d’API pour laquelle l’authentification d’utilisateur est activée. Le développeur d’API définit la propriété `authorizationType` de la méthode sur `AWS_IAM` pour imposer à l’appelant de soumettre les informations d’identification de l’utilisateur à l’authentification. API Gateway prend en charge Signature Version 4a (SigV4a) et Signature Version 4 (SigV4) pour authentifier les informations d’identification de l’utilisateur. Pour plus d’informations, consultez [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Vous pouvez ensuite attacher la politique à un utilisateur, un groupe ou un rôle.
Dans cette déclaration de politique d’autorisation IAM, l’élément IAM `Resource` contient la liste des méthodes d’API déployées et identifiées par les verbes HTTP fournis et les [chemins d’accès des ressources](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API Gateway. L’élément IAM `Action` contient les actions d’exécution requises des API API Gateway. Ces actions incluent `execute-api:Invoke` ou `execute-api:InvalidateCache`, où `execute-api` désigne le composant d’exécution des API sous-jacent d’API Gateway.
Pour plus d’informations sur l’utilisation de ce modèle d’autorisation, consultez [Contrôler l’accès pour l’appel d’une API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
Lorsqu'une API est intégrée à un AWS service (par exemple, AWS Lambda) dans le back-end, API Gateway doit également être autorisée à accéder aux AWS ressources intégrées (par exemple, en invoquant une fonction Lambda) au nom de l'appelant de l'API. Pour accorder ces autorisations, créez un rôle IAM du type **service AWS pour API Gateway**. Lorsque vous créez ce rôle dans la console de gestion IAM, le rôle résultant contient la politique d’approbation IAM suivante qui déclare API Gateway en tant qu’entité de confiance autorisée à assumer le rôle :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Si vous créez le rôle IAM en appelant la commande [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) de la CLI ou une méthode de kit SDK correspondante, vous devez fournir la politique d’approbation ci-dessus en tant que paramètre d’entrée de `assume-role-policy-document`. N'essayez pas de créer une telle politique directement dans la console de gestion IAM ou d'appeler la commande AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) ou une méthode du SDK correspondante.
Pour qu'API Gateway puisse appeler le AWS service intégré, vous devez également associer à ce rôle des politiques d'autorisation IAM appropriées pour appeler les AWS services intégrés. Par exemple, pour appeler une fonction Lambda, vous devez inclure la politique d’autorisations IAM suivante dans le rôle IAM :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
------
Notez que Lambda prend en charge la stratégie d’accès basée sur les ressources, qui combine les stratégies d’approbation et d’autorisation. Lors de l’intégration d’une API à une fonction Lambda à l’aide de la console API Gateway, il ne vous est pas demandé de définir ce rôle IAM explicitement, car la console définit pour vous les autorisations basées sur les ressources sur la fonction Lambda, avec votre consentement.
**Note**
Pour mettre en place un contrôle d'accès à un AWS service, vous pouvez utiliser le modèle d'autorisation basé sur l'appelant, dans lequel une politique d'autorisation est directement attachée à l'utilisateur ou au groupe de l'appelant, ou le modèle d'autorisation basé sur les rôles, dans lequel une politique d'autorisation est attachée à un rôle IAM que API Gateway peut assumer. Les politiques d’autorisation peuvent varier dans les deux modèles. Par exemple, la politique basée sur l’appelant bloque l’accès tandis que la politique basée sur les rôles l’autorise. Vous pouvez en profiter pour demander à un utilisateur d'accéder à un AWS service uniquement via une API API Gateway.
# Contrôler l’accès pour l’appel d’une API
Dans cette section, vous allez découvrir le modèle d’autorisation permettant de contrôler l’accès à votre API avec des autorisations IAM. Lorsque l'autorisation IAM est activée, les clients doivent utiliser la version de signature 4a (SIGv4a) et la version de signature 4 (Sigv4) pour signer leurs demandes avec des informations d'identification. AWS Pour plus d’informations, consultez [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html).
Dans cette section, nous allons vous présenter un modèle de déclaration de politique IAM et la référence de cette déclaration. La référence de la déclaration de politique inclut les formats des champs `Action` et `Resource` liés au service d’exécution des API. Utilisez ces références pour créer votre déclaration de politique IAM. Lorsque vous créez votre déclaration de politique IAM, tenez compte de la façon dont les politiques de ressources API Gateway affectent le flux d’autorisation. Pour de plus amples informations, veuillez consulter [Comment les politiques de ressources API Gateway affectent le flux de travail d’autorisation](apigateway-authorization-flow.md).
Pour le mode privé APIs, vous devez utiliser une combinaison d'une politique de ressources API Gateway et d'une politique de point de terminaison VPC. Pour plus d’informations, consultez les rubriques suivantes :
+ [Contrôle d’accès à une API REST avec des politiques de ressources API Gateway](apigateway-resource-policies.md)
+ [Utiliser les politiques de point de terminaison VPC pour le mode privé APIs dans API Gateway](apigateway-vpc-endpoint-policies.md)
## Contrôle des personnes habilitées à appeler une méthode d’API API Gateway avec les politiques IAM
Pour contrôler qui peut ou non appeler une API déployée avec les autorisations IAM, créez un document de politique IAM avec les autorisations requises. Un modèle pour un tel document de politique est affiché comme suit.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Permission",
"Action": [
"execute-api:Execution-operation"
],
"Resource": [
"arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path"
]
}
]
}
```
------
Ici, `Permission` doit être remplacé par `Allow` ou `Deny`, selon que vous voulez accorder ou révoquer les autorisations incluses. `Execution-operation` doit être remplacé par les opérations prises en charge par le service d’exécution des API. `METHOD_HTTP_VERB` représente un verbe HTTP pris en charge par les ressources spécifiées. `Resource-path` est l’espace réservé du chemin d’URL d’une instance `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` d’API déployée prenant en charge ledit verbe `METHOD_HTTP_VERB`. Pour de plus amples informations, veuillez consulter [Référence de déclaration de politique IAM pour l’exécution des API dans API Gateway](#api-gateway-calling-api-permissions).
**Note**
Pour que les politiques IAM soient efficaces, vous devez avoir activé l’authentification IAM sur les méthodes de l’API en définissant `AWS_IAM` pour la propriété `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` de la méthode. Faute de quoi ces méthodes d’API seront accessibles au public.
Par exemple, pour accorder à un utilisateur l’autorisation d’afficher la liste des « pets » exposés par une API spécifiée, mais lui refuser l’autorisation d’ajouter un « pet » à la liste, vous pouvez inclure la déclaration suivante dans la politique IAM :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets"
]
}
]
}
```
------
Pour accorder à un utilisateur l’autorisation d’afficher un « pet » exposé spécifique par une API configurée en tant que `GET /pets/{petId}`, vous pouvez inclure la déclaration suivante dans la politique IAM :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2"
]
}
]
}
```
------
## Référence de déclaration de politique IAM pour l’exécution des API dans API Gateway
Les informations suivantes décrivent le format des expressions Action et Resource des déclarations de politique IAM d’autorisation d’accès pour l’exécution d’une API.
### Format de l’expression Action des autorisations d’exécution d’API dans API Gateway
L’expression `Action` des autorisations d’exécution d’API a le format général suivant :
```
execute-api:action
```
où se *action* trouve une action d'exécution d'API disponible :
+ **\$1**, qui représente l’ensemble des actions suivantes.
+ **Invoke**, utilisée pour appeler une API sur demande d’un client.
+ **InvalidateCache**, utilisée pour invalider le cache API sur demande d'un client.
### Format de l’expression Resource des autorisations d’exécution d’API dans API Gateway
L’expression `Resource` des autorisations d’exécution d’API a le format général suivant :
```
arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier
```
où :
+ *region*est la AWS région (telle que **us-east-1** ou **\$1** pour toutes les AWS régions) qui correspond à l'API déployée pour la méthode.
+ *account-id*est l'identifiant de AWS compte à 12 chiffres du propriétaire de l'API REST.
+ *api-id*est l'identifiant qu'API Gateway a attribué à l'API pour la méthode.
+ *stage-name*est le nom de l'étape associée à la méthode.
+ *HTTP-VERB*est le verbe HTTP de la méthode. Les valeurs possibles sont GET, POST, PUT, DELETE, PATCH.
+ *resource-path-specifier*est le chemin d'accès à la méthode souhaitée.
**Note**
Si vous spécifiez un caractère générique (`*`), l’expression `Resource` applique le caractère générique au reste de l’expression.
Voici quelques exemples d’expression Resource :
+ **arn:aws:execute-api:\$1:\$1:\$1**pour n'importe quel chemin de ressource à n'importe quelle étape, pour n'importe quelle API dans n'importe quelle AWS région.
+ **arn:aws:execute-api:us-east-1:\$1:\$1**pour tout chemin de ressource à n'importe quelle étape, pour toute API de la AWS région de`us-east-1`.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1**pour tout chemin de ressource à n'importe quelle étape, pour l'API dont l'identifiant est *api-id* dans la AWS région de us-east-1.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1**pour tout chemin de ressource au stade de`test`, pour l'API dont l'identifiant est situé *api-id* dans la AWS région us-east-1.
Pour en savoir plus, veuillez consulter la section [Référence Amazon Resource Name (ARN) API Gateway](arn-format-reference.md).
# Exemples de politiques IAM pour les autorisations d’exécution d’API
Pour en savoir plus sur les modèles d’autorisation et pour d’autres informations générales, consultez [Contrôler l’accès pour l’appel d’une API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
La déclaration de politique suivante donne à l’utilisateur l’autorisation d’appeler n’importe quelle méthode POST sur le chemin `mydemoresource`, à l’étape `test`, pour l’API avec l’identifiant `a123456789`, en supposant que l’API correspondante a été déployée dans la région AWS us-east-1 :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*"
]
}
]
}
```
------
L’exemple de déclaration de politique suivant accorde à l’utilisateur l’autorisation d’appeler n’importe quelle méthode sur le chemin de ressource `petstorewalkthrough/pets`, à n’importe quelle étape, pour l’API ayant l’identifiant `a123456789`, dans n’importe quelle région AWS où l’API correspondante a été déployée :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets"
]
}
]
}
```
------
# Utiliser les politiques de point de terminaison VPC pour le mode privé APIs dans API Gateway
Pour améliorer la sécurité de votre API privée, vous pouvez créer une politique de point de terminaison de VPC. La politique de point de terminaison de VPC est une politique de ressources IAM qui est jointe au point de terminaison d’un VPC. Pour plus d’informations, consultez [Contrôle de l'accès aux services avec des points de terminaison de VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html).
Vous pouvez créer une politique de point de terminaison de VPC pour exécuter les tâches suivantes.
+ Autoriser uniquement certaines organisations ou ressources à accéder à votre point de terminaison de VPC et à invoquer votre API.
+ Utiliser une seule politique et éviter les politiques basées sur les sessions ou les rôles pour contrôler le trafic à destination de votre API.
+ Resserrez le périmètre de sécurité de votre application lors de la migration d'une application sur site vers AWS.
## Considérations d’une politique de point de terminaison de VPC
Tenez compte des points suivants pour votre politique de point de terminaison de VPC :
+ L’identité de l’invocateur est évaluée en fonction de la valeur de l’en-tête `Authorization`. La politique du point de terminaison du VPC est d’abord évaluée, puis API Gateway évalue la demande en fonction du type d’autorisation configuré dans la demande de méthode. Le tableau suivant montre comment la politique de point de terminaison du VPC est évaluée en fonction du contenu de la valeur d’en-tête `Authorization`.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-vpc-endpoint-policies.html)
+ Si votre contrôle d’accès repose sur l’utilisation d’un jeton porteur, tel qu’un mécanisme d’autorisation Lambda ou Amazon Cognito, vous pouvez contrôler votre périmètre de sécurité à l’aide des [propriétés de la ressource](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties).
+ Si votre contrôle d’autorisation utilise l’autorisation IAM, vous pouvez contrôler votre périmètre de sécurité en utilisant les [propriétés de la ressource](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties) et les [propriétés du principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-principal).
+ Les politiques de point de terminaison de VPC peuvent être utilisées conjointement avec des politiques de ressources API Gateway. La politique de ressources API Gateway spécifie les principaux pouvant accéder à l’API. La politique de point de terminaison spécifie qui peut accéder au VPC et qui APIs peut être appelé depuis le point de terminaison du VPC. Votre API privée a besoin d’une politique de ressources, mais il n’est pas nécessaire de créer une politique de point de terminaison de VPC personnalisée.
## Exemples de politique de point de terminaison de VPC
Vous pouvez créer des politiques pour les points de terminaison Amazon Virtual Private Cloud pour Amazon API Gateway dans lesquelles vous pouvez spécifier :
+ Le principal qui peut exécuter des actions.
+ Les actions qui peuvent être effectuées.
+ Les ressources qui peuvent avoir des actions exécutées sur elles.
Cela dépend du contenu de votre en-tête d’autorisation. Pour de plus amples informations, veuillez consulter [Considérations d’une politique de point de terminaison de VPC](#apigateway-vpc-endpoint-policies-considerations). Pour d'autres exemples de politiques, consultez la section [Exemples de politiques de périmètre des données](https://github.com/aws-samples/data-perimeter-policy-examples) sur le GitHub site Web.
Pour attacher la politique au point de terminaison de VPC, vous devez utiliser la console VPC. Pour plus d’informations, consultez [Contrôle de l'accès aux services avec des points de terminaison de VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html).
## Exemple 1 : politique de point de terminaison VPC accordant l'accès à deux APIs
L'exemple de politique suivant n'accorde l'accès qu'à deux points spécifiques APIs via le point de terminaison VPC auquel la politique est attachée.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*",
"arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*"
]
}
]
}
```
------
## Exemple 2 : politique de point de terminaison de VPC accordant l’accès aux méthodes GET
L’exemple de politique suivant accorde aux utilisateurs l’accès aux méthodes `GET` pour une API spécifique via le point de terminaison de VPC auquel la politique est attachée.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*"
]
}
]
}
```
------
## Exemple 3 : politique de point de terminaison de VPC accordant à un utilisateur spécifique l’accès à une API spécifique
L’exemple de politique suivant accorde à un utilisateur spécifique l’accès à une API spécifique via le point de terminaison de VPC auquel la politique est attachée.
Dans ce cas, étant donné que la politique restreint l’accès à des principaux IAM spécifiques, vous devez définir `authorizationType` sur `AWS_IAM` ou `NONE`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": {
"AWS": [
"arn:aws:iam::123412341234:user/MyUser"
]
},
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*"
]
}
]
}
```
------
## Exemple 4 : politique de point de terminaison de VPC autorisant les utilisateurs à accéder à un nom de domaine personnalisé spécifique et à chaque API mappée à ce domaine
L'exemple de politique suivant accorde aux utilisateurs l'accès à un nom de domaine personnalisé spécifique pour le mode privé APIs via le point de terminaison VPC auquel la politique est attachée. Avec cette politique, tant qu'un utilisateur a créé une association d'accès au nom de domaine entre le point de terminaison VPC et le nom de domaine personnalisé et qu'il est autorisé à invoquer le nom de domaine personnalisé et toute API privée mappée au nom de domaine personnalisé, l'utilisateur peut invoquer n'importe quelle API APIs mappée à ce nom de domaine personnalisé. Pour de plus amples informations, veuillez consulter [Noms de domaine personnalisés pour le privé APIs dans API Gateway](apigateway-private-custom-domains.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"*"
],
"Condition": {
"ArnEquals": {
"execute-api:viaDomainArn": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6",
}
}
}
]
}
```
------
## Exemple 5 : politique de point de terminaison VPC accordant ou refusant l'accès à des ressources spécifiques APIs et à des ressources de domaine
L'exemple de politique suivant accorde aux utilisateurs l'accès à des ressources spécifiques APIs et à des domaines. Avec cette politique, tant qu'un utilisateur a créé une association d'accès au nom de domaine entre le point de terminaison VPC et le nom de domaine personnalisé et qu'il est autorisé à invoquer le nom de domaine personnalisé et toute API privée mappée au nom de domaine personnalisé, l'utilisateur peut invoquer les ressources privées APIs et de domaine autorisées. Pour de plus amples informations, veuillez consulter [Noms de domaine personnalisés pour le privé APIs dans API Gateway](apigateway-private-custom-domains.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6",
"arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/*"
]
},
{
"Effect": "Deny",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/admin/*",
"arn:aws:execute-api:us-west-2:111122223333:bcd123455/*"
]
}
]
}
```
------
## Exemple 6 : politique de point de terminaison de VPC accordant ou refusant l’accès aux principaux et aux ressources appartenant à une organisation
L’exemple de politique suivant autorise l’accès aux principaux et aux ressources appartenant à une organisation.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Condition": {
"StringEquals": {
"aws:ResourceOrgID": "o-abcd1234",
"aws:PrincipalOrgID": "o-abcd1234"
}
},
"Action": "*",
"Resource": "*",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources"
}
]
}
```
------
# Utiliser des balises pour contrôler l'accès à REST APIs dans API Gateway
L'autorisation d'accès à REST APIs peut être affinée à l'aide du contrôle d'accès basé sur les attributs dans les politiques IAM.
Pour de plus amples informations, veuillez consulter [Utilisation de balises pour contrôler l’accès aux ressources API REST API Gateway](apigateway-tagging-iam-policy.md).
# Utilisation des mécanismes d’autorisation Lambda API Gateway
Utilisez un *mécanisme d’autorisation Lambda* (anciennement appelé *mécanisme d’autorisation personnalisée*) pour contrôler l’accès à votre API. Lorsqu’un client soumet une méthode sur votre API, API Gateway appelle votre mécanisme d’autorisation Lambda. Ce dernier prend l’identité de l’appelant en entrée et renvoie une politique IAM en sortie.
Utilisez un mécanisme d’autorisation Lambda pour implémenter un schéma d’autorisation personnalisée. Votre schéma peut utiliser des paramètres de demande pour déterminer l'identité de l'appelant ou utiliser une stratégie d'authentification par jeton porteur telle que SAML OAuth . Créez un autorisateur Lambda dans la console API REST API Gateway, à l'aide du ou d'un AWS CLI SDK. AWS
## Flux d’autorisation du mécanisme d’autorisation Lambda
Le schéma suivant illustre le flux d’autorisation d’un mécanisme d’autorisation Lambda.
![\[Flux de travail d'autorisation Lambda API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/custom-auth-workflow.png)
**Flux de travail d'autorisation Lambda API Gateway**
1. Le client appelle une méthode sur une API API Gateway, en transmettant un jeton de porteur ou des paramètres de demande.
1. API Gateway vérifie si la demande de méthode est configurée avec un mécanisme d’autorisation Lambda. Si c’est le cas, API Gateway appelle la fonction Lambda.
1. La fonction Lambda authentifie l’appelant. La fonction peut procéder à l’authentification de différentes manières :
+ En appelant un OAuth fournisseur pour obtenir un jeton OAuth d'accès.
+ En appelant un fournisseur SAML pour obtenir une assertion SAML.
+ En générant une politique IAM basée sur les valeurs des paramètres de la demande.
+ En extrayant les informations d’identification d’une base de données.
1. La fonction Lambda renvoie une politique IAM et un identifiant principal. Si la fonction Lambda ne renvoie pas ces informations, l’appel échoue.
1. API Gateway évalue la politique IAM.
+ Si l’accès est refusé, API Gateway renvoie un code de statut HTTP approprié, par exemple `403 ACCESS_DENIED`.
+ Si l’accès est autorisé, API Gateway invoque la méthode.
Si vous activez la mise en cache des autorisations, API Gateway met en cache la politique afin que la fonction du mécanisme d’autorisation Lambda ne soit pas invoquée à nouveau. Assurez-vous que votre politique s’applique à toutes les ressources et méthodes de votre API.
Vous pouvez personnaliser la réponse de passerelle `403 ACCESS_DENIED` ou `401 UNAUTHORIZED`. Pour en savoir plus, veuillez consulter la section [Réponses de passerelle pour REST APIs dans API Gateway](api-gateway-gatewayResponse-definition.md).
## Choix d’un type de mécanisme d’autorisation Lambda
Il existe deux types de mécanismes d’autorisation Lambda :
**Mécanisme d’autorisation Lambda basé sur les paramètres de la demande (mécanisme d’autorisation `REQUEST`)**
Un mécanisme d’autorisation `REQUEST` reçoit l’identité de l’appelant dans une combinaison d’en-têtes, de paramètres de chaîne de requête, et de variables [`stageVariables`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) et [`$context`](api-gateway-mapping-template-reference.md#context-variable-reference). Vous pouvez utiliser un mécanisme d’autorisation `REQUEST` pour créer des politiques précises basées sur les informations de plusieurs sources d’identité, telles que les variables contextuelles `$context.path` et `$context.httpMethod`.
Si vous activez la mise en cache des autorisations pour un mécanisme d’autorisation `REQUEST`, API Gateway vérifie que toutes les sources d’identité spécifiées sont présentes dans la demande. Si une source d’identité spécifiée est absente, nulle ou vide, API Gateway renvoie une réponse HTTP `401 Unauthorized` sans appeler la fonction du mécanisme d’autorisation Lambda. Lorsque plusieurs sources d’identité sont définies, elles sont toutes utilisées pour obtenir la clé de cache du mécanisme d’autorisation, en respectant l’ordre établi. Vous pouvez définir une clé de cache précise en utilisant plusieurs sources d’identité.
Si vous modifiez une partie de la clé de cache et redéployez votre API, le mécanisme d’autorisation ignore le document de politique mis en cache et en génère un nouveau.
Si vous désactivez la mise en cache des autorisations pour un mécanisme d’autorisation `REQUEST`, API Gateway transmet directement la demande à la fonction Lambda.
**Mécanisme d’autorisation Lambda par jeton (mécanisme d’autorisation `TOKEN`)**
Un `TOKEN` autorisateur reçoit l'identité de l'appelant dans un jeton porteur, tel qu'un jeton Web JSON (JWT) ou un jeton. OAuth
Si vous activez la mise en cache des autorisations pour un mécanisme d’autorisation `TOKEN`, le nom de l’en-tête spécifié dans la source du jeton devient la clé de cache.
En outre, vous pouvez utiliser la validation par jeton pour saisir une RegEx déclaration. API Gateway effectue la validation initiale du jeton d’entrée en fonction de cette expression et invoque la fonction du mécanisme d’autorisation Lambda quand la validation aboutit. Cela contribue à réduire le nombre d'appels à votre API.
La propriété `IdentityValidationExpression` est prise en charge pour les mécanismes d’autorisation `TOKEN` uniquement. Pour de plus amples informations, veuillez consulter [x-amazon-apigateway-authorizer objet](api-gateway-swagger-extensions-authorizer.md).
**Note**
Nous vous recommandons d’utiliser un mécanisme d’autorisation `REQUEST` pour contrôler l’accès à votre API. Vous pouvez contrôler l’accès à votre API sur la base de plusieurs sources d’identité lorsque vous utilisez un mécanisme d’autorisation `REQUEST`, alors qu’une seule source d’identité suffit lorsque vous utilisez un mécanisme d’autorisation `TOKEN`. En outre, vous pouvez séparer les clés de cache en utilisant plusieurs sources d’identité pour un mécanisme d’autorisation `REQUEST`.
## Exemple de fonction de mécanisme d’autorisation Lambda `REQUEST`
L’exemple de code suivant crée une fonction de mécanisme d’autorisation Lambda qui autorise une demande si l’en-tête `HeaderAuth1` fourni par le client, le paramètre de requête `QueryString1` et la variable d’étape `StageVar1` correspondent aux valeurs `headerValue1`, `queryValue1` et `stageValue1` spécifiées, respectivement.
------
#### [ Node.js ]
```
// A simple request-based authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header, QueryString1
// query parameter, and stage variable of StageVar1 all match
// specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
// respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var pathParameters = event.pathParameters;
var stageVariables = event.stageVariables;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var restApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var method = apiGatewayArnTmp[2];
var resource = '/'; // root resource
if (apiGatewayArnTmp[3]) {
resource += apiGatewayArnTmp[3];
}
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1"
&& stageVariables.StageVar1 === "stageValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Help function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17'; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple request-based authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied headerauth1 header, QueryString1
# query parameter, and stage variable of StageVar1 all match
# specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
# respectively.
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
pathParameters = event['pathParameters']
stageVariables = event['stageVariables']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
restApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
method = apiGatewayArnTmp[2]
resource = '/'
if (apiGatewayArnTmp[3]):
resource += apiGatewayArnTmp[3]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return response
else:
print('unauthorized')
response = generateDeny('me', event['methodArn'])
return response
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17'
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
return authResponse
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
Dans cet exemple, la fonction du mécanisme d’autorisation Lambda vérifie les paramètres d’entrée et agit comme suit :
+ Si toutes les valeurs de paramètre obligatoires correspondent aux valeurs attendues, la fonction du mécanisme d’autorisation renvoie une réponse HTTP `200 OK` et une politique IAM qui ressemble à ce qui suit, et la demande de la méthode aboutit :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
+ Sinon, la fonction du mécanisme d’autorisation renvoie une réponse HTTP `401 Unauthorized` et la demande de méthode échoue.
En plus de renvoyer une stratégie IAM, la fonction du mécanisme d'autorisation Lambda doit également renvoyer l'identifiant principal de l'appelant. Elle peut éventuellement renvoyer un objet `context` qui inclut des informations supplémentaires transmissibles au backend d’intégration. Pour de plus amples informations, veuillez consulter [Sortie d’un mécanisme d’autorisation Lambda API Gateway](api-gateway-lambda-authorizer-output.md).
Dans le code de production, vous devrez peut-être authentifier l’utilisateur avant d’accorder l’autorisation. Vous pouvez ajouter une logique d’authentification dans la fonction Lambda en appelant un fournisseur d’authentification, comme indiqué dans la documentation de ce fournisseur.
## Exemple de fonction de mécanisme d’autorisation Lambda `TOKEN`
L’exemple de code suivant crée une fonction de mécanisme d’autorisation Lambda`TOKEN` qui permet à un appelant d’invoquer une méthode si la valeur du jeton fournie par le client est `allow`. L’appelant n’est pas autorisé à invoquer la demande si la valeur du jeton est `deny`. Si la valeur du jeton est `unauthorized` ou une chaîne vide, la fonction du mécanisme d’autorisation renvoie une réponse `401 UNAUTHORIZED`.
------
#### [ Node.js ]
```
// A simple token-based authorizer example to demonstrate how to use an authorization token
// to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
// a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
// the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty
// string, the authorizer function returns an HTTP 401 status code. For any other token value,
// the authorizer returns an HTTP 500 status code.
// Note that token values are case-sensitive.
export const handler = function(event, context, callback) {
var token = event.authorizationToken;
switch (token) {
case 'allow':
callback(null, generatePolicy('user', 'Allow', event.methodArn));
break;
case 'deny':
callback(null, generatePolicy('user', 'Deny', event.methodArn));
break;
case 'unauthorized':
callback("Unauthorized"); // Return a 401 Unauthorized response
break;
default:
callback("Error: Invalid token"); // Return a 500 Invalid token response
}
};
// Help function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17';
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke';
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
```
------
#### [ Python ]
```
# A simple token-based authorizer example to demonstrate how to use an authorization token
# to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
# a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
# the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty
# string, the authorizer function returns an HTTP 401 status code. For any other token value,
# the authorizer returns an HTTP 500 status code.
# Note that token values are case-sensitive.
import json
def lambda_handler(event, context):
token = event['authorizationToken']
if token == 'allow':
print('authorized')
response = generatePolicy('user', 'Allow', event['methodArn'])
elif token == 'deny':
print('unauthorized')
response = generatePolicy('user', 'Deny', event['methodArn'])
elif token == 'unauthorized':
print('unauthorized')
raise Exception('Unauthorized') # Return a 401 Unauthorized response
return 'unauthorized'
try:
return json.loads(response)
except BaseException:
print('unauthorized')
return 'unauthorized' # Return a 500 error
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17'
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
```
------
Dans cet exemple, lorsque l’API reçoit une demande de méthode, API Gateway transmet le jeton source à cette fonction du mécanisme d’autorisation Lambda dans l’attribut `event.authorizationToken`. La fonction du mécanisme d’autorisation Lambda lit le jeton et agit comme suit :
+ Si la valeur du jeton est `allow`, la fonction du mécanisme d’autorisation renvoie une réponse HTTP `200 OK` et une politique IAM qui ressemble à ce qui suit, et la demande de méthode aboutit :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
+ Si la valeur du jeton est `deny`, la fonction du mécanisme d’autorisation renvoie une réponse HTTP `200 OK` et une politique IAM `Deny` qui ressemble à ce qui suit, et la demande de méthode échoue :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
**Note**
En dehors de l’environnement de test, API Gateway renvoie une réponse HTTP `403 Forbidden` et la demande de méthode échoue.
+ Si la valeur du jeton est `unauthorized` ou une chaîne vide, la fonction du mécanisme d’autorisation renvoie une réponse HTTP `401 Unauthorized` et l’appel de la méthode échoue.
+ Si le jeton a n’importe quelle autre valeur, le client reçoit une réponse `500 Invalid token` et l’appel de la méthode échoue.
En plus de renvoyer une stratégie IAM, la fonction du mécanisme d'autorisation Lambda doit également renvoyer l'identifiant principal de l'appelant. Elle peut éventuellement renvoyer un objet `context` qui inclut des informations supplémentaires transmissibles au backend d’intégration. Pour de plus amples informations, veuillez consulter [Sortie d’un mécanisme d’autorisation Lambda API Gateway](api-gateway-lambda-authorizer-output.md).
Dans le code de production, vous devrez peut-être authentifier l’utilisateur avant d’accorder l’autorisation. Vous pouvez ajouter une logique d’authentification dans la fonction Lambda en appelant un fournisseur d’authentification, comme indiqué dans la documentation de ce fournisseur.
## Exemples supplémentaires de fonctions de mécanisme d’autorisation Lambda
La liste suivante présente d’autres exemples de fonctions de mécanisme d’autorisation Lambda. Vous pouvez créer une fonction Lambda dans le même compte, ou dans un autre compte, que celui dans lequel vous avez créé votre API.
Dans l'exemple précédent, vous pouvez utiliser les fonctions Lambda intégrées [AWSLambdaBasicExecutionRole](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html), car ces fonctions n'appellent aucun autre AWS service. Si votre fonction Lambda appelle d'autres AWS services, vous devez attribuer un rôle d'exécution IAM à la fonction Lambda. Pour créer le rôle, suivez les instructions dans [Rôle d’exécution AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html).
**Exemples supplémentaires de fonctions de mécanisme d’autorisation Lambda**
+ Pour un exemple d'application, voir [Open Banking Brésil - Exemples GitHub d'autorisation](https://github.com/aws-samples/openbanking-brazilian-auth-samples) sur.
+ Pour plus d'exemples de fonctions Lambda, voir [ aws-apigateway-lambda-authorizer-blueprints](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints) on. GitHub
+ Vous pouvez créer un mécanisme d’autorisation Lambda qui authentifie les utilisateurs à l’aide de groupes d’utilisateurs Amazon Cognito, et autorise les appelants sur la base d’un entrepôt de politiques à l’aide de Verified Permissions. Pour de plus amples informations, veuillez consulter [Contrôle de l’accès sur la base des attributs d’une identité avec Verified Permissions](apigateway-lambda-authorizer-verified-permissions.md).
+ La console Lambda fournit un plan Python, que vous pouvez utiliser en choisissant **Utiliser un plan puis en choisissant le plan**. **api-gateway-authorizer-python**
# Configuration d’un mécanisme d’autorisation Lambda API Gateway
Une fois votre fonction Lambda créée, vous allez la configurer en tant que mécanisme d’autorisation pour votre API. Vous allez ensuite configurer votre méthode pour invoquer votre mécanisme d’autorisation Lambda afin de déterminer si un appelant peut invoquer votre méthode. Vous pouvez créer une fonction Lambda dans le même compte, ou dans un autre compte, que celui dans lequel vous avez créé votre API.
Vous pouvez tester votre mécanisme d’autorisation Lambda à l’aide des outils intégrés de la console API Gateway ou de [Postman](https://www.postman.com/). Pour apprendre à utiliser Postman pour tester votre fonction de mécanisme d’autorisation Lambda, consultez [Appel d’une API avec un mécanisme d’autorisation Lambda API Gateway](call-api-with-api-gateway-lambda-authorization.md).
## Configuration d’un mécanisme d’autorisation Lambda (console)
La procédure suivante montre comment créer un mécanisme d’autorisation Lambda dans la console d’API REST API Gateway. Pour en savoir plus sur les différents types de mécanismes d’autorisation Lambda, consultez [Choix d’un type de mécanisme d’autorisation Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-choose).
------
#### [ REQUEST authorizer ]
**Pour configurer un mécanisme d’autorisation Lambda `REQUEST`**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez une API, puis choisissez **Mécanismes d’autorisation**.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Pour **Nom du mécanisme d’autorisation**, entrez un nom pour le mécanisme d’autorisation.
1. Pour **Type de mécanisme d'autorisation**, sélectionnez **Lambda**.
1. Pour la **fonction Lambda**, sélectionnez l' Région AWS endroit où vous avez créé votre fonction d'autorisation Lambda, puis entrez le nom de la fonction.
1. Laissez **Rôle d’appel Lambda** vide pour que la console d’API REST API Gateway définisse une politique basée sur les ressources. La politique autorise API Gateway à invoquer la fonction Lambda du mécanisme d’autorisation. Vous pouvez également choisir de saisir le nom d’un rôle IAM pour autoriser API Gateway à invoquer la fonction du mécanisme d’autorisation Lambda. Pour obtenir un exemple de rôle, consultez [Création d’un rôle IAM assumable](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies).
1. Pour **Charge utile d’événement Lambda**, sélectionnez **Effectuer une demande**.
1. Pour **Type de source d'identité**, sélectionnez un type de paramètre. Les types de paramètre pris en charge sont `Header`, `Query string`, `Stage variable` et `Context`. Pour ajouter des sources d'identité supplémentaires, choisissez **Ajouter un paramètre**.
1. Pour mettre en cache la politique d'autorisation générée par le mécanisme d'autorisation, maintenez active l'option **Mise en cache des autorisations**. Quand la mise en cache de la politique est activée, vous pouvez modifier la valeur **TTL**. Le fait de définir **TTL** sur zéro désactive la mise en cache de la politique.
Si vous activez la mise en cache, votre mécanisme d’autorisation doit renvoyer une politique applicable à toutes les méthodes d’une API. Pour appliquer une politique spécifique à une méthode, utilisez les variables contextuelles `$context.path` et `$context.httpMethod`.
1. Choisissez **Créer un mécanisme d’autorisation**.
------
#### [ TOKEN authorizer ]
**Pour configurer un mécanisme d’autorisation Lambda `TOKEN`**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez une API, puis choisissez **Mécanismes d’autorisation**.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Pour **Nom du mécanisme d’autorisation**, entrez un nom pour le mécanisme d’autorisation.
1. Pour **Type de mécanisme d'autorisation**, sélectionnez **Lambda**.
1. Pour la **fonction Lambda**, sélectionnez l' Région AWS endroit où vous avez créé votre fonction d'autorisation Lambda, puis entrez le nom de la fonction.
1. Laissez **Rôle d’appel Lambda** vide pour que la console d’API REST API Gateway définisse une politique basée sur les ressources. La politique autorise API Gateway à invoquer la fonction Lambda du mécanisme d’autorisation. Vous pouvez également choisir de saisir le nom d’un rôle IAM pour autoriser API Gateway à invoquer la fonction du mécanisme d’autorisation Lambda. Pour obtenir un exemple de rôle, consultez [Création d’un rôle IAM assumable](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies).
1. Pour **Charge utile d’événement Lambda**, sélectionnez **Jeton**.
1. Pour **Source de jeton**, entrez le nom de l'en-tête contenant le jeton d'autorisation. L’appelant doit inclure un en-tête portant ce nom pour envoyer le jeton d’autorisation au mécanisme d’autorisation Lambda.
1. (Facultatif) Pour la **validation du jeton**, entrez une RegEx déclaration. API Gateway effectue la validation initiale du jeton d'entrée en fonction de cette expression et appelle le mécanisme d'autorisation quand la validation aboutit.
1. Pour mettre en cache la politique d'autorisation générée par le mécanisme d'autorisation, maintenez active l'option **Mise en cache des autorisations**. Si la mise en cache de la politique est activée, le nom de l'en-tête spécifié dans **Source de jeton** devient la clé de cache. Quand la mise en cache de la politique est activée, vous pouvez modifier la valeur **TTL**. Le fait de définir **TTL** sur zéro désactive la mise en cache de la politique.
Si vous activez la mise en cache, votre mécanisme d’autorisation doit renvoyer une politique applicable à toutes les méthodes d’une API. Pour appliquer une politique spécifique à la méthode, vous pouvez désactiver **Mise en cache des autorisations**.
1. Choisissez **Créer un mécanisme d’autorisation**.
------
Une fois que vous avez créé votre mécanisme d’autorisation Lambda, vous pouvez le tester. La procédure suivante montre comment tester votre mécanisme d’autorisation Lambda.
------
#### [ REQUEST authorizer ]
**Pour tester un mécanisme d’autorisation Lambda `REQUEST`**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez le nom de votre mécanisme d’autorisation.
1. Sous **Tester le mécanisme d’autorisation**, saisissez une valeur pour votre source d’identité.
Si vous utilisez l’[Exemple de fonction de mécanisme d’autorisation Lambda `REQUEST`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-request-lambda-function-create), procédez comme suit :
1. Sélectionnez **En-tête** et entrez **headerValue1**, puis choisissez **Ajouter un paramètre**.
1. Sous **Type de source d’identité**, sélectionnez **Chaîne de requête** et entrez **queryValue1**, puis choisissez **Ajouter un paramètre**.
1. Sous **Type de source d’identité**, sélectionnez **Variable d’étape** et entrez **stageValue1**.
Vous ne pouvez pas modifier les variables contextuelles pour l’invocation de test, mais vous pouvez modifier le modèle d’événement de test **Mécanisme d’autorisation API Gateway** pour votre fonction Lambda. Vous pouvez ensuite tester la fonction de votre mécanisme d’autorisation Lambda avec des variables contextuelles modifiées. Pour plus d’informations, consultez [Testing Lambda functions in the console](https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html) dans le *Guide du développeur AWS Lambda *.
1. Choisissez **Tester le mécanisme d'autorisation**.
------
#### [ TOKEN authorizer ]
**Pour tester un mécanisme d’autorisation Lambda `TOKEN`**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez le nom de votre mécanisme d’autorisation.
1. Sous **Tester le mécanisme d’autorisation**, saisissez une valeur pour votre jeton.
Si vous utilisez l’[Exemple de fonction de mécanisme d’autorisation Lambda `TOKEN`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create), procédez comme suit :
1. Pour **authorizationToken**, saisissez **allow**.
1. Choisissez **Tester le mécanisme d'autorisation**.
Si votre mécanisme d’autorisation Lambda refuse avec succès une demande dans l’environnement de test, le test répond par une réponse HTTP `200 OK`. En revanche, en dehors de l’environnement de test, API Gateway renvoie une réponse HTTP `403 Forbidden` et la demande de méthode échoue.
------
## Configuration d’un mécanisme d’autorisation Lambda (AWS CLI)
La commande [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) suivante montre comment créer un mécanisme d’autorisation Lambda à l’aide de l’ AWS CLI.
------
#### [ REQUEST authorizer ]
La commande [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) suivante crée un mécanisme d’autorisation `REQUEST`, et utilise l’en-tête `Authorizer` et la variable de contexte `accountId` comme sources d’identité :
```
aws apigateway create-authorizer \
--rest-api-id 1234123412 \
--name 'First_Request_Custom_Authorizer' \
--type REQUEST \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \
--identity-source 'method.request.header.Authorization,context.accountId' \
--authorizer-result-ttl-in-seconds 300
```
------
#### [ TOKEN authorizer ]
La commande [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) suivante crée un mécanisme d’autorisation `TOKEN`, et utilise l’en-tête `Authorization` comme source d’identité :
```
aws apigateway create-authorizer \
--rest-api-id 1234123412 \
--name 'First_Token_Custom_Authorizer' \
--type TOKEN \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \
--identity-source 'method.request.header.Authorization' \
--authorizer-result-ttl-in-seconds 300
```
------
Une fois que vous avez créé votre mécanisme d’autorisation Lambda, vous pouvez le tester. La [test-invoke-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-authorizer.html)commande suivante teste un autorisateur Lambda :
```
aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \
--authorizer-id efg1234 \
--headers Authorization='Value'
```
## Configuration d’une méthode pour utiliser un mécanisme d’autorisation Lambda (console)
Après avoir configuré votre mécanisme d’autorisation Lambda, vous devez l’attacher à une méthode pour votre API. Si votre mécanisme d’autorisation utilise la mise en cache des autorisations, assurez-vous de mettre à jour la politique afin qu’elle contrôle l’accès à la nouvelle méthode.
**Pour configurer une méthode d’API pour utiliser un mécanisme d’autorisation Lambda**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez une API.
1. Choisissez **Ressources**, puis sélectionnez une nouvelle méthode ou une méthode existante.
1. Dans l’onglet **Demande de méthode**, sous **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Pour **Mécanisme d’autorisation**, dans le menu déroulant, sélectionnez le mécanisme d’autorisation Lambda que vous venez de créer.
1. (Facultatif) Si vous souhaitez transmettre le jeton d’autorisation au backend, choisissez **En-têtes de demande HTTP**. Choisissez **Ajouter un en-tête**, puis ajoutez le nom de l’en-tête d’autorisation. Pour **Nom**, saisissez le nom de l’en-tête qui correspond au nom **Source du jeton** que vous avez spécifié lorsque vous avez créé le mécanisme d’autorisation Lambda pour l’API. Cette étape ne s’applique pas aux mécanismes d’autorisation `REQUEST`.
1. Choisissez **Enregistrer**.
1. Sélectionnez **Deploy API** pour déployer l’API dans une étape. Pour un mécanisme d’autorisation `REQUEST` utilisant les variables d’étape, vous devez également définir les variables d’étape requises et spécifier leurs valeurs dans la page **Étapes**.
## Configuration d’une méthode pour utiliser un mécanisme d’autorisation Lambda (AWS CLI)
Après avoir configuré votre mécanisme d’autorisation Lambda, vous devez l’attacher à une méthode pour votre API. Vous pouvez créer une méthode ou utiliser une opération de correctif pour associer un mécanisme d’autorisation à une méthode existante. Si votre mécanisme d’autorisation utilise la mise en cache des autorisations, assurez-vous de mettre à jour la politique afin qu’elle contrôle l’accès à la nouvelle méthode.
La commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante crée une méthode utilisant un mécanisme d’autorisation Lambda :
```
aws apigateway put-method --rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type CUSTOM \
--authorizer-id efg1234
```
La commande [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) suivante met à jour une méthode existante afin qu’elle utilise un mécanisme d’autorisation Lambda :
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234"
```
# Données d’entrée d’un mécanisme d’autorisation Lambda API Gateway
La section suivante explique le format de l’entrée envoyée par API Gateway à un mécanisme d’autorisation Lambda.
## Format d'entrée `TOKEN`
Pour un mécanisme d’autorisation Lambda (anciennement appelé Custom Authorizer) de type `TOKEN`, vous devez spécifier un en-tête personnalisé comme **Token Source** (Source de jeton) lorsque vous configurez le mécanisme d’autorisation de votre API. Le client de l’API doit transmettre le jeton d’autorisation requis dans l’en-tête de la demande entrante. À réception de la demande de méthode entrante, API Gateway extrait le jeton à partir de l’en-tête personnalisé. Il transmet ensuite le jeton en tant que propriété `authorizationToken` de l’objet `event` de la fonction Lambda, en plus de l’ARN de méthode via la propriété `methodArn` :
```
{
"type":"TOKEN",
"authorizationToken":"{caller-supplied-token}",
"methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
```
Dans cet exemple, la propriété `type` spécifie le type de mécanisme d’autorisation, à savoir `TOKEN`. La valeur `{caller-supplied-token}` provient de l’en-tête d’autorisation d’une demande client et peut correspondre à n’importe quelle valeur de chaîne. La propriété `methodArn` est l’ARN de la demande de méthode entrante et elle est renseignée par API Gateway conformément à la configuration du mécanisme d’autorisation Lambda.
## Format d'entrée `REQUEST`
Pour un mécanisme d’autorisation Lambda de type `REQUEST`, API Gateway transmet les paramètres de demande à la fonction Lambda du mécanisme d’autorisation de l’objet `event`. Les paramètres de demande comprennent les en-têtes, les paramètres des chemins, les paramètres des chaînes d’interrogation, les variables d’étape et certaines variables de contexte de demande. L’appelant de l’API peut définir les paramètres des chemins, les en-têtes et les paramètres des chaînes d’interrogation. Le développeur de l’API doit définir les variables d’étape pendant le déploiement de l’API, et API Gateway fournit le contexte de la demande au moment de l’exécution.
**Note**
Les paramètres de chemin peuvent être transmis comme paramètres de la demande à la fonction du mécanisme d’autorisation Lambda, mais ils ne peuvent pas être utilisés comme sources d’identité.
L’exemple suivant montre les données d’entrée pour un mécanisme d’autorisation `REQUEST` et une méthode d’API (`GET /request`) avec une intégration proxy :
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"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"
}
}
```
Le contexte `requestContext` est un mappage de paires clé-valeur et correspond à la variable [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference). Son résultat est dépendant de l’API.
API Gateway peut ajouter de nouvelles clés au mappage. Pour plus d’informations sur l’entrée de la fonction Lambda dans l’intégration de proxy Lambda, consultez [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format).
# Sortie d’un mécanisme d’autorisation Lambda API Gateway
La sortie de la fonction du mécanisme d’autorisation Lambda est un objet de type dictionnaire, qui doit inclure l’identifiant principal (`principalId`) et un document de politique (`policyDocument`) contenant la liste des déclarations de politique. La sortie peut également inclure un mappage `context` contenant des paires clé-valeur. Si l’API applique un plan d’utilisation ([https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource) est défini sur `AUTHORIZER`), la fonction du mécanisme d’autorisation Lambda doit renvoyer l’une des clés d’API du plan d’utilisation comme valeur de la propriété `usageIdentifierKey`.
Voici un exemple de sortie de ce type.
------
#### [ JSON ]
****
```
{
"principalId": "yyyyyyyy",
"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": {
"stringKey": "value",
"numberKey": "1",
"booleanKey": "true"
},
"usageIdentifierKey": "{api-key}"
}
```
------
Dans cet exemple, une déclaration de politique indique s’il faut permettre ou interdire (`Effect`) au service d’exécution API Gateway d’appeler (`Action`) la méthode d’API spécifiée (`Resource`). Il se peut que vous deviez contrôler l’accès à plusieurs ressources en fonction de votre mécanisme d’autorisation. Vous pouvez utiliser un caractère générique (`*`) pour spécifier un type de ressource (méthode). Pour plus d’informations sur le paramétrage des politiques valides pour appeler une API, consultez [Référence de déclaration de politique IAM pour l’exécution des API dans API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-calling-api-permissions).
Pour un ARN de méthode activé par autorisation, par exemple `arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]`, la longueur maximale est de 1 600 octets. Les valeurs de paramètre de chemin, dont la taille est déterminée au moment de l’exécution, peuvent entraîner un dépassement de limite de la longueur de l’ARN. Dans ce cas, le client API reçoit une réponse `414 Request URI too long`.
De plus, l’ARN de ressources, comme indiqué dans la sortie de déclaration de politique par l’autorisateur, est actuellement limitée à 512 caractères. Pour cette raison, vous ne devez pas utiliser d’URI avec un jeton JWT d’une longueur significative dans une URI de demande. Vous pouvez plutôt transmettre le jeton JWT en toute sécurité dans un en-tête de demande.
Vous pouvez accéder à la valeur `principalId` d’un modèle de mappage à l’aide de la variable `$context.authorizer.principalId`. C’est utile si vous souhaitez transmettre la valeur au backend. Pour de plus amples informations, veuillez consulter [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference).
Vous pouvez accéder à la valeur `stringKey`, `numberKey` ou `booleanKey` (par exemple, `"value"`, `"1"` ou `"true"`) du mappage `context` d’un modèle de mappage en appelant `$context.authorizer.stringKey`, `$context.authorizer.numberKey` ou `$context.authorizer.booleanKey`, respectivement. Les valeurs renvoyées sont toutes obtenues à l’aide de stringify. Notez que vous ne pouvez pas définir un objet ou un tableau JSON comme valeur valide d’une clé dans le mappage `context`.
Vous pouvez utiliser le mappage `context` pour renvoyer les informations d’identification mises en cache depuis le mécanisme d’autorisation vers le backend, via un modèle de mappage de demande d’intégration. En exploitant les informations d’identification mises en cache, le backend offre une meilleure expérience utilisateur et évite ainsi d’accéder aux clés secrètes et d’ouvrir des jetons d’autorisation pour chaque demande.
Pour l’intégration du proxy Lambda, API Gateway transmet l’objet `context` depuis un mécanisme d’autorisation Lambda directement à la fonction Lambda du backend via l’entrée `event`. Vous pouvez récupérer les paires clé-valeur `context` de la fonction Lambda en appelant `$event.requestContext.authorizer.key`.
`{api-key}` représente une clé d’API dans le plan d’utilisation de l’étape d’API. Pour de plus amples informations, veuillez consulter [Plans d'utilisation et clés d'API pour REST APIs dans API Gateway](api-gateway-api-usage-plans.md).
L’exemple de mécanisme d’autorisation Lambda renvoie l’exemple de sortie suivant. L'exemple de sortie contient une déclaration de politique visant à bloquer (`Deny`) les appels à la `GET` méthode pour l'`dev`étape d'une API (`ymy8tbxw7b`) d'un AWS compte (`123456789012`).
------
#### [ JSON ]
****
```
{
"principalId": "user",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
}
]
}
}
```
------
# Appel d’une API avec un mécanisme d’autorisation Lambda API Gateway
Après avoir configuré le mécanisme d’autorisation Lambda (anciennement appelé Custom Authorizer) et déployé l’API, vous devez tester l’API avec le mécanisme d’autorisation Lambda activé. Pour cela, vous avez besoin d’un client REST, tel que cURL ou [Postman](https://www.postman.com/). Dans les exemples suivants, nous utilisons Postman.
**Note**
**Lors de l'appel d'une méthode activée par l'autorisateur, API Gateway n'enregistre pas l'appel CloudWatch si le jeton requis pour l'`TOKEN`autorisateur n'est pas défini, est nul ou est invalidé par l'expression de validation du jeton spécifiée.** De même, API Gateway n'enregistre pas l'appel CloudWatch si l'une des sources d'identité requises pour l'`REQUEST`autorisateur n'est pas définie, est nulle ou est vide.
Nous détaillons ci-après comment utiliser Postman pour appeler ou tester une API avec le mécanisme d’autorisation Lambda `TOKEN`. La méthode peut servir à appeler une API avec un mécanisme d’autorisation Lambda `REQUEST` si vous spécifiez le chemin, l’en-tête ou les paramètres des chaînes d’interrogation requis de façon explicite.
**Pour appeler une API avec le Custom `TOKEN` Authorizer**
1. Ouvrez **Postman**, sélectionnez la méthode **GET** et collez la valeur du champ **Invoke URL** de l’API dans le champ d’URL adjacent.
Ajoutez l’en-tête de jeton d’autorisation Lambda et définissez la valeur `allow`. Sélectionnez **Send (Envoyer)**.
![\[Appel d’une API à l’aide d’un jeton d’autorisation Lambda Allow\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/custom-auth-call-api-with-allow-token.png)
La réponse montre que le mécanisme d’autorisation Lambda API Gateway renvoie une réponse **200 OK** et autorise l’appel à accéder au point de terminaison HTTP (http://httpbin.org/get) intégré avec la méthode.
1. Toujours dans l’application Postman, remplacez la valeur de l’en-tête de jeton d’autorisation Lambda par `deny`. Sélectionnez **Send (Envoyer)**.
![\[Appel d’une API à l’aide d’un jeton d’autorisation Lambda Deny\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/custom-auth-call-api-with-deny-token.png)
La réponse montre que le mécanisme d’autorisation Lambda API Gateway renvoie une réponse **403 Forbidden (403 Interdit)** sans autoriser l’appel à accéder au point de terminaison HTTP.
1. Dans l’application Postman, remplacez la valeur de l’en-tête de jeton d’autorisation Lambda par `unauthorized`, puis sélectionnez **Send (Envoyer)**.
![\[Appel d’une API à l’aide d’un jeton d’autorisation Lambda Unauthorized\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/custom-auth-call-api-with-unauthorized-token.png)
La réponse montre qu’API Gateway renvoie une réponse **401 Unauthorized (401 Accès non autorisé)** sans autoriser l’appel à accéder au point de terminaison HTTP.
1. Maintenant, remplacez la valeur de l’en-tête de jeton d’autorisation Lambda par `fail`. Sélectionnez **Send (Envoyer)**.
![\[Appel d’une API à l’aide d’un jeton d’autorisation Lambda Fail\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/custom-auth-call-api-with-fail-token.png)
La réponse montre qu’API Gateway renvoie une réponse **500 Internal Server Error (500 Erreur interne du serveur)** sans autoriser l’appel à accéder au point de terminaison HTTP.
# Configuration d’un mécanisme d’autorisation Lambda API Gateway entre comptes
Vous pouvez désormais également utiliser une AWS Lambda fonction d'un autre AWS compte comme fonction d'autorisation d'API. Chaque compte peut se trouver dans n’importe quelle région où Amazon API Gateway est disponible. La fonction d'autorisation Lambda peut utiliser des stratégies d'authentification par jeton porteur, telles que SAML. OAuth Cela facilite la gestion et le partage centralisés d'une fonction d'autorisation Lambda centrale entre plusieurs API Gateway. APIs
Dans cette section, nous montrons comment configurer une fonction d’autorisation Lambda entre comptes à l’aide de la console Amazon API Gateway.
Ces instructions supposent que vous disposez déjà d'une API API Gateway dans un AWS compte et d'une fonction d'autorisation Lambda dans un autre compte.
## Configuration d’un mécanisme d’autorisation Lambda entre comptes à l’aide de la console API Gateway
Connectez-vous à la console Amazon API Gateway dans le compte qui contient votre API, puis procédez comme suit :
1. Choisissez votre API, puis dans le panneau de navigation principal, choisissez **Mécanismes d’autorisation**.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Pour **Nom du mécanisme d’autorisation**, entrez un nom pour le mécanisme d’autorisation.
1. Pour **Type de mécanisme d'autorisation**, sélectionnez **Lambda**.
1. Pour **Fonction Lambda**, entrez l’ARN complet de la fonction de mécanisme d’autorisation Lambda que vous avez dans votre deuxième compte.
**Note**
Dans la console Lambda, vous trouverez l’ARN de votre fonction dans le coin supérieur droit de la fenêtre de la console.
1. Un avertissement accompagné d’une chaîne de commande `aws lambda add-permission` s’affichera. Cette politique accorde à API Gateway l’autorisation d’invoquer la fonction Lambda de mécanisme d’autorisation. Copiez la commande et enregistrez-la pour plus tard. Vous exécuterez la commande après avoir créé le mécanisme d’autorisation.
1. Pour **Charge utile d’événement Lambda**, sélectionnez **Jeton** pour un mécanisme d’autorisation `TOKEN` ou **Effectuer une demande** pour un mécanisme d’autorisation `REQUEST`.
1. Selon le choix effectué à l’étape précédente, réalisez l’une des actions suivantes :
1. Pour l’option **Jeton**, procédez comme suit :
+ Pour **Source de jeton**, entrez le nom de l'en-tête contenant le jeton d'autorisation. Le client d’API doit inclure un en-tête portant ce nom pour envoyer le jeton d’autorisation au mécanisme d’autorisation Lambda.
+ Pour la **validation du jeton**, entrez éventuellement une RegEx instruction. API Gateway effectue la validation initiale du jeton d'entrée en fonction de cette expression et appelle le mécanisme d'autorisation quand la validation aboutit. Cela contribue à réduire le nombre d'appels à votre API.
+ Pour mettre en cache la politique d'autorisation générée par le mécanisme d'autorisation, maintenez active l'option **Mise en cache des autorisations**. Quand la mise en cache de la politique est activée, vous pouvez choisir de remplacer la valeur **TTL**. Le fait de définir **TTL** sur zéro désactive la mise en cache de la politique. Si la mise en cache de la politique est activée, le nom de l'en-tête spécifié dans **Source de jeton** devient la clé de cache. Si plusieurs valeurs sont transmises à cet en-tête dans la demande, toutes les valeurs deviennent la clé de cache, l’ordre étant préservé.
**Note**
La valeur **TTL** par défaut est de 300 secondes. Actuellement, sa valeur maximale est de 3 600 secondes ; elle ne peut pas être augmentée.
1. Pour l’option **Request**, effectuez les opérations suivantes :
+ Pour **Type de source d'identité**, sélectionnez un type de paramètre. Les types de paramètre pris en charge sont `Header`, `Query string`, `Stage variable` et `Context`. Pour ajouter des sources d'identité supplémentaires, choisissez **Ajouter un paramètre**.
+ Pour mettre en cache la politique d'autorisation générée par le mécanisme d'autorisation, maintenez active l'option **Mise en cache des autorisations**. Quand la mise en cache de la politique est activée, vous pouvez choisir de remplacer la valeur **TTL**. Le fait de définir **TTL** sur zéro désactive la mise en cache de la politique.
API Gateway utilise les sources d’identité spécifiées comme clé de mise en cache du mécanisme d’autorisation de la demande. Lorsque la mise en cache est activée, API Gateway appelle la fonction Lambda du mécanisme d’autorisation uniquement si toutes les sources d’identité spécifiées sont présentes lors de l’exécution. Si une source d’identité spécifiée est absente, nulle ou vide, API Gateway renvoie une réponse `401 Unauthorized` sans appeler la fonction Lambda du mécanisme d’autorisation.
Lorsque plusieurs sources d’identité sont définies, elles sont toutes utilisées pour obtenir la clé du cache du mécanisme d’autorisation. Si une partie de la clé du cache est modifiée, le mécanisme d’autorisation ignore le document de la politique mis en cache et en génère un nouveau. Si un en-tête à plusieurs valeurs est transmis dans la demande, toutes les valeurs font partie de la clé de cache, l’ordre étant préservé.
+ Lorsque la mise en cache est désactivée, il n’est pas nécessaire de spécifier une source d’identité.
**Note**
Pour activer la mise en cache, votre mécanisme d’autorisation doit renvoyer une politique applicable à toutes les méthodes d’une API. Pour appliquer une politique spécifique à la méthode, vous pouvez désactiver **Mise en cache des autorisations**.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Collez la chaîne de `aws lambda add-permission` commande que vous avez copiée à l'étape précédente dans une AWS CLI fenêtre configurée pour votre deuxième compte. Remplacez `AUTHORIZER_ID` par l’ID de votre mécanisme d’autorisation. Cela permet d’accorder à votre premier compte l’accès à la fonction de mécanisme d’autorisation Lambda de votre deuxième compte.
# Contrôle de l’accès sur la base des attributs d’une identité avec Verified Permissions
Utilisez Amazon Verified Permissions pour contrôler l’accès à votre API API Gateway. Lorsque vous utilisez API Gateway avec Verified Permissions, Verified Permissions crée un mécanisme d’autorisation Lambda qui utilise des décisions d’autorisation précises pour contrôler l’accès à votre API. Verified Permissions autorise les appelants sur la base d’un schéma d’entrepôt de politiques et de politiques utilisant le langage de politique Cedar pour définir des autorisations précises pour les utilisateurs de l’application. Pour plus d’informations, consultez [Create a policy store with a connected API and identity provider](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/getting-started-api-policy-store.html) dans le *Guide de l’utilisateur Amazon Verified Permissions*.
Verified Permissions prend en charge les groupes d’utilisateurs Amazon Cognito ou les fournisseurs d’identité OpenID Connect (OIDC) comme sources d’identité. Verified Permissions présume que le principal a déjà été identifié et authentifié. Les autorisations vérifiées ne sont prises en charge que pour le REST régional et optimisé pour les périphériques. APIs
## Création d’un mécanisme d’autorisation Lambda à l’aide de Verified Permissions
Verified Permissions crée un mécanisme d’autorisation Lambda pour déterminer si un principal est autorisé à effectuer une action sur votre API. Vous allez créer la politique Cedar que Verified Permissions utilisera pour effectuer ses tâches d’autorisation.
Voici un exemple de politique Cedar qui autorise l’invocation d’une API sur la base du groupe d’utilisateurs Amazon Cognito `us-east-1_ABC1234` pour le groupe `developer` sur la ressource `GET /users` d’une API. Verified Permissions détermine l’appartenance du groupe en recherchant l’identité de l’appelant dans le jeton de porteur.
```
permit(
principal in MyAPI::UserGroup::"us-east-1_ABC1234|developer",
action in [ MyAPI::Action::"get /users" ],
resource
);
```
Verified Permissions peut éventuellement attacher le mécanisme d’autorisation aux méthodes de votre API. Pour les étapes de production de votre API, nous vous recommandons de ne pas autoriser Verified Permissions à attacher le mécanisme d’autorisation à votre place.
La liste suivante indique comment configurer Verified Permissions pour qu’il attache ou non le mécanisme d’autorisation Lambda à la demande de méthode envoyée à votre API.
**Verified Permissions attache le mécanisme d’autorisation pour vous (AWS Management Console)**
Lorsque vous choisissez **Créer un entrepôt de politiques** dans la console Verified Permissions, sur la page **Déployer l’intégration d’application**, sélectionnez **Maintenant**.
**Verified Permissions n’attache pas le mécanisme d’autorisation pour vous (AWS Management Console)**
Lorsque vous choisissez **Créer un entrepôt de politiques** dans la console Verified Permissions, sur la page **Déployer l’intégration d’application**, sélectionnez **Plus tard**.
Verified Permissions crée tout de même un mécanisme d’autorisation Lambda pour vous. Le mécanisme d’autorisation Lambda commence par `AVPAuthorizerLambda-`. Pour apprendre à attacher votre mécanisme d’autorisation à une méthode, consultez [Configuration d’une méthode pour utiliser un mécanisme d’autorisation Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-console).
**Verified Permissions attache le mécanisme d’autorisation pour vous (CloudFormation)**
Dans le CloudFormation modèle généré par les autorisations vérifiées, dans la `Conditions` section, définissez sur. `"Ref": "shouldAttachAuthorizer"` `true`
**Verified Permissions n’attache pas le mécanisme d’autorisation pour vous (CloudFormation)**
Dans le CloudFormation modèle généré par les autorisations vérifiées, dans la `Conditions` section, définissez sur. `"Ref": "shouldAttachAuthorizer"` `false`
Verified Permissions crée tout de même un mécanisme d’autorisation Lambda pour vous. Le mécanisme d’autorisation Lambda commence par `AVPAuthorizerLambda-`. Pour apprendre à attacher votre mécanisme d’autorisation à une méthode, consultez [Configuration d’une méthode pour utiliser un mécanisme d’autorisation Lambda (AWS CLI)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-cli).
## Appel d’un mécanisme d’autorisation Lambda à l’aide de Verified Permissions
Vous pouvez appeler votre mécanisme d’autorisation Lambda en fournissant une identité ou un jeton d’accès dans l’en-tête `Authorization`. Pour de plus amples informations, veuillez consulter [Appel d’une API avec un mécanisme d’autorisation Lambda API Gateway](call-api-with-api-gateway-lambda-authorization.md).
API Gateway met en cache la politique renvoyée par votre mécanisme d’autorisation Lambda pendant 120 secondes. Vous pouvez modifier la TTL dans la console API Gateway ou à l’aide de l’ AWS CLI.
# Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur
Au lieu d’utiliser des [rôles et politiques IAM](permissions.md) ou des [mécanismes d’autorisation Lambda](apigateway-use-lambda-authorizer.md) (anciennement appelés mécanismes d’autorisation personnalisée), vous pouvez utiliser un [groupe d’utilisateurs Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) pour contrôler les personnes pouvant accéder à votre API dans Amazon API Gateway.
Pour utiliser un groupe d’utilisateurs Amazon Cognito avec votre API, vous devez d’abord créer un mécanisme d’autorisation de type `COGNITO_USER_POOLS`, puis configurer une méthode d’API permettant d’utiliser ce mécanisme d’autorisation. Une fois l’API déployée, le client doit d’abord connecter l’utilisateur au groupe d’utilisateurs, obtenir une [identité ou un jeton d’accès](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) pour l’utilisateur, puis appeler la méthode API avec l’un des jetons, qui sont généralement définis sur l’en-tête `Authorization` de la demande. L’appel d’API réussit uniquement si le jeton requis est fourni et qu’il est valide. Dans le cas contraire, le client n’est pas autorisé à effectuer l’appel, il ne dispose pas des informations d’identification qui peuvent être autorisées.
Le jeton d’identité est utilisé pour autoriser les appels d’API en fonction des requêtes d’identité de l’utilisateur connecté. Le jeton d’accès est utilisé pour autoriser les appels d’API en fonction des règles personnalisées des ressources protégées par un accès spécifié. Pour plus d’informations, consultez [Utilisation des jetons avec les groupes d’utilisateurs](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) et [Serveur de ressources et portées personnalisées](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html).
Pour créer et configurer un groupe d’utilisateurs Amazon Cognito pour votre API, exécutez les tâches suivantes :
+ Utilisez la console Amazon Cognito, le CLI/SDK ou l'API pour créer un groupe d'utilisateurs, ou utilisez-en un appartenant à un autre compte. AWS
+ Utilisez la console API Gateway, l’interface de ligne de commande/le kit SDK, ou encore l’API pour créer un mécanisme d’autorisation API Gateway avec le groupe d’utilisateurs choisi.
+ Utilisez la console API Gateway, l’interface de ligne de commande/le kit SDK, ou encore l’API pour activer le mécanisme d’autorisation sur les méthodes d’API sélectionnées.
Pour appeler des méthodes d’API avec un groupe d’utilisateurs activé, vos clients d’API effectuent les tâches suivantes :
+ Utilisez Amazon Cognito CLI/SDK ou l'API pour connecter un utilisateur au groupe d'utilisateurs choisi et obtenir un jeton d'identité ou un jeton d'accès. Pour en savoir plus sur l'utilisation du SDKs, consultez les [exemples de code pour Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). AWS SDKs
+ Utilisez un cadre spécifique au client pour appeler l’API API Gateway déployée et fournir le jeton approprié dans l’en-tête `Authorization`.
En tant que développeur d’API, vous devez fournir à vos développeurs clients l’ID du groupe d’utilisateurs, un ID client et éventuellement les secrets client associés, qui sont définis dans le cadre groupe d’utilisateurs.
**Note**
Pour permettre à un utilisateur de se connecter avec les informations d’identification Amazon Cognito et d’obtenir également des informations d’identification temporaires à utiliser avec les autorisations d’un rôle IAM, utilisez les [identités fédérées Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Pour chaque méthode HTTP du point de terminaison de ressources d’API, définissez le type d’autorisation, la catégorie `Method Execution`, sur `AWS_IAM`.
Dans cette section, nous allons expliquer comment créer un groupe d’utilisateurs, intégrer une API API Gateway avec le groupe d’utilisateurs et appeler une API intégrée au groupe d’utilisateurs.
**Topics**
+ [
# Création d’un groupe d’utilisateurs Amazon Cognito pour une API REST
](apigateway-create-cognito-user-pool.md)
+ [
# Intégration d’une API REST avec un groupe d’utilisateurs Amazon Cognito
](apigateway-enable-cognito-user-pool.md)
+ [
# Appel d’une API REST intégrée avec un groupe d’utilisateurs Amazon Cognito
](apigateway-invoke-api-integrated-with-cognito-user-pool.md)
+ [
# Configuration d’un mécanisme d’autorisation Amazon Cognito entre comptes pour une API REST à l’aide de la console API Gateway
](apigateway-cross-account-cognito-authorizer.md)
+ [
# Créez un autorisateur Amazon Cognito pour une API REST à l'aide de CloudFormation
](apigateway-cognito-authorizer-cfn.md)
# Création d’un groupe d’utilisateurs Amazon Cognito pour une API REST
Avant d’intégrer votre API avec un groupe d’utilisateurs, vous devez créer ce groupe d’utilisateurs dans Amazon Cognito. La configuration de votre groupe d’utilisateurs doit respecter tous les [quotas de ressources pour Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Toutes les variables Amazon Cognito définies par l’utilisateur, telles que les groupes, les utilisateurs et les rôles doivent utiliser uniquement des caractères alphanumériques. Pour obtenir des instructions afin de créer un groupe d’utilisateurs, consultez [Didacticiel : création d’un groupe d’utilisateurs](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) dans le *Guide du développeur Amazon Cognito*.
Notez l’ID du groupe d’utilisateurs, l’ID du client et les codes secrets du client. Le client doit fournir ces informations à Amazon Cognito pour permettre à l’utilisateur de s’inscrire dans le groupe d’utilisateurs, de se connecter au groupe d’utilisateurs et d’obtenir un jeton d’identité ou d’accès à inclure dans les demandes pour appeler les méthodes d’API configurées avec le groupe d’utilisateurs. Vous devez également spécifier le nom du groupe d’utilisateurs lorsque vous le configurez en tant que mécanisme d’autorisation dans API Gateway, comme décrit dans la section suivante.
Si vous utilisez des jetons d'accès pour autoriser des appels de méthode d'API, assurez-vous de configurer l'intégration de l'application avec le groupe d'utilisateurs pour configurer les règles personnalisées de votre choix sur un serveur de ressources donné. Pour plus d’informations sur l’utilisation de jetons avec des groupes d’utilisateurs Amazon Cognito, consultez [Utilisation des jetons avec les groupes d’utilisateurs](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Pour plus d’informations sur les serveurs de ressources, consultez [Définition des serveurs de ressources pour votre groupe d’utilisateurs](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html).
Notez les identificateurs du serveur de ressources configurés et les noms de règles personnalisées. Vous en avez besoin pour créer les noms complets des étendues d'accès pour **OAuth les étendues**, qui sont utilisés par l'`COGNITO_USER_POOLS`autorisateur.
![\[Serveurs de ressources et règles de groupes d’utilisateurs Amazon Cognito\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png)
# Intégration d’une API REST avec un groupe d’utilisateurs Amazon Cognito
Après avoir créé un groupe d’utilisateurs Amazon Cognito, dans API Gateway, vous devez ensuite créer un mécanisme d’autorisation `COGNITO_USER_POOLS` qui utilise le groupe d’utilisateurs. La procédure suivante montre comment procéder à l’aide de la console API Gateway.
**Note**
Vous pouvez utiliser l’action [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) pour créer un mécanisme d’autorisation `COGNITO_USER_POOLS` qui utilise plusieurs groupes d’utilisateurs. Vous pouvez utiliser jusqu’à 1 000 groupes d’utilisateurs pour un mécanisme d’autorisation `COGNITO_USER_POOLS`. Cette limite ne peut pas être augmentée.
**Important**
Après avoir effectué l’une des procédures ci-dessous, vous devez déployer ou redéployer votre API pour propager les modifications. Pour plus d’informations sur le déploiement de votre API, consultez [Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md).
**Pour créer un mécanisme d’autorisation `COGNITO_USER_POOLS` à l’aide de la console API Gateway**
1. Créez une API ou sélectionnez une API existante dans API Gateway.
1. Dans le panneau de navigation principal, choisissez **Mécanismes d'autorisation**.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Pour configurer le nouveau mécanisme d'autorisation afin d'utiliser un groupe d'utilisateurs, procédez comme suit :
1. Pour **Nom du mécanisme d’autorisation**, entrez un nom.
1. Pour **Type de mécanisme d'autorisation**, sélectionnez **Cognito**.
1. Pour le **groupe d'utilisateurs Cognito,** choisissez l' Région AWS endroit où vous avez créé votre Amazon Cognito et sélectionnez un groupe d'utilisateurs disponible.
Vous pouvez utiliser une variable d’étape pour définir votre groupe d’utilisateurs. Utilisez le format suivant pour votre groupe d’utilisateurs : `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`.
1. Pour **Source du jeton**, entrez **Authorization** comme nom d'en-tête pour transmettre le jeton d'identité ou le jeton d'accès renvoyé par Amazon Cognito lorsqu'un utilisateur se connecte avec succès.
1. (Facultatif) Entrez une expression régulière dans le champ **Validation du jeton** pour valider le champ `aud` (public) du jeton d’identité avant que la demande soit autorisée avec Amazon Cognito. Notez que lors de l'utilisation d'un jeton d'accès, cette validation rejette la demande en raison du jeton d'accès ne contenant pas le champ `aud`.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Après avoir créé le mécanisme d’autorisation `COGNITO_USER_POOLS`, vous pouvez essayer de l’invoquer en fournissant un jeton d’identité alloué à partir du groupe d’utilisateurs. Vous ne pouvez pas utiliser de jeton d’accès pour essayer d’invoquer votre mécanisme d’autorisation.
Vous pouvez obtenir ce jeton d’identité en appelant le [kit SDK d’identité Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) afin de connecter l’utilisateur. Vous pouvez également utiliser l’action [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). Si vous ne configurez pas de **Portées d’autorisation**, API Gateway traite le jeton fourni comme un jeton d’identité.
La procédure précédente crée un mécanisme d’autorisation `COGNITO_USER_POOLS` qui utilise le groupe d’utilisateurs Amazon Cognito que vous venez de créer. En fonction de la façon dont vous activez le mécanisme d’autorisation sur une méthode d’API, vous pouvez utiliser un jeton d’identité ou un jeton d’accès qui est alloué à partir du groupe d’utilisateurs intégré.
**Pour configurer un mécanisme d’autorisation `COGNITO_USER_POOLS` sur les méthodes**
1. Sélectionnez **Ressources**. Choisissez une nouvelle méthode ou choisissez une méthode existante. Si nécessaire, créez une ressource.
1. Dans l'onglet **Demande de méthode**, sous **Paramètres de demande de méthode**, choisissez **Modifier**.
1. Pour **Mécanisme d’autorisation**, dans le menu déroulant, sélectionnez les **mécanismes d’autorisation de groupe d’utilisateurs Amazon Cognito** que vous venez de créer.
1. Pour utiliser un jeton d’identité, procédez comme suit :
1. Laissez l’option **Portées d’autorisation** vide.
1. Si nécessaire, dans **Demande d’intégration**, ajoutez les expressions `$context.authorizer.claims['property-name']` ou `$context.authorizer.claims.property-name` dans un modèle de mappage de corps pour transmettre la propriété des champs standard d’identité spécifiée du groupe d’utilisateurs au backend. Pour les noms de propriété simples, tels que `sub` ou `custom-sub`, les deux notations sont identiques. Pour les noms de propriété complexes, tels que `custom:role`, vous ne pouvez pas utiliser la notation par points. Par exemple, les expressions de mappage suivantes transmettent les [champs standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `sub` et `email` de la requête au backend :
```
{
"context" : {
"sub" : "$context.authorizer.claims.sub",
"email" : "$context.authorizer.claims.email"
}
}
```
Si vous avez déclaré un champ de requête personnalisé lors de la configuration d’un groupe d’utilisateurs, vous pouvez respecter le même modèle pour accéder aux champs personnalisés. L’exemple suivant permet d’obtenir un champ `role` personnalisé d’une requête :
```
{
"context" : {
"role" : "$context.authorizer.claims.role"
}
}
```
Si le champ de requête personnalisé est déclaré en tant que `custom:role`, utilisez l’exemple suivant pour obtenir la propriété de la requête :
```
{
"context" : {
"role" : "$context.authorizer.claims['custom:role']"
}
}
```
1. Pour utiliser un jeton d’accès, procédez comme suit :
1. Pour **Portées d’autorisation**, entrez un ou plusieurs noms complets d’une portée qui a été configurée lorsque le groupe d’utilisateurs Amazon Cognito a été créé. Par exemple, en suivant l’exemple fourni dans [Création d’un groupe d’utilisateurs Amazon Cognito pour une API REST](apigateway-create-cognito-user-pool.md), l’une des portées est `https://my-petstore-api.example.com/cats.read`.
Lors de l’exécution, l’appel de méthode réussit si une portée indiquée sur la méthode de cette étape correspond à une portée demandée dans le jeton entrant. Dans le cas contraire, l’appel échoue en renvoyant une réponse `401 Unauthorized`.
1. Choisissez **Enregistrer**.
1. Répétez ces étapes pour les autres méthodes de votre choix.
Avec l'`COGNITO_USER_POOLS`autorisateur, si l'option **OAuthScopes** n'est pas spécifiée, API Gateway traite le jeton fourni comme un jeton d'identité et vérifie l'identité revendiquée par rapport à celle du groupe d'utilisateurs. Sinon, API Gateway traite le jeton fourni comme un jeton d’accès et vérifie les portées d’accès qui sont demandées dans le jeton par rapport aux portées d’autorisation déclarées sur la méthode.
Au lieu d’utiliser la console API Gateway, vous pouvez également activer un groupe d’utilisateurs Amazon Cognito sur une méthode en spécifiant un fichier de définition OpenAPI et en important la définition d’API dans API Gateway.
**Pour importer un mécanisme d’autorisation COGNITO\$1USER\$1POOLS avec un fichier de définition OpenAPI**
1. Créez (ou exportez) un fichier de définition OpenAPI pour votre API.
1. Spécifiez la définition JSON du mécanisme d’autorisation `COGNITO_USER_POOLS` (`MyUserPool`) dans la section `securitySchemes` dans OpenAPI 3.0 ou dans la section `securityDefinitions` dans OpenAPI 2.0 comme suit :
------
#### [ OpenAPI 3.0 ]
```
"securitySchemes": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}
```
------
#### [ OpenAPI 2.0 ]
```
"securityDefinitions": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}
```
------
1. Pour utiliser le jeton d’identité pour l’autorisation de méthode, ajoutez `{ "MyUserPool": [] }` à la définition `security` de la méthode, comme indiqué dans la méthode GET suivante sur la ressource racine.
```
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": []
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}
```
1. Pour utiliser le jeton d’accès pour l’autorisation de méthode, modifiez la définition de sécurité ci-dessus pour `{ "MyUserPool": [resource-server/scope, ...] }`:
```
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}
```
1. Si nécessaire, vous pouvez définir d’autres paramètres de configuration d’API à l’aide des définitions ou des extensions OpenAPI appropriées. Pour de plus amples informations, veuillez consulter [Extensions OpenAPI pour API Gateway](api-gateway-swagger-extensions.md).
# Appel d’une API REST intégrée avec un groupe d’utilisateurs Amazon Cognito
Pour appeler une méthode pour laquelle un mécanisme d’autorisation de groupe d’utilisateurs est configuré, le client doit effectuer les opérations suivantes :
+ Autoriser l’utilisateur à s’inscrire dans le groupe d’utilisateurs.
+ Autoriser l’utilisateur à se connecter au groupe d’utilisateurs.
+ Obtenez un [jeton d’identité ou d’accès](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) de l’utilisateur connecté à partir du groupe d’utilisateurs.
+ Inclure le jeton dans l’en-tête `Authorization` (ou tout autre en-tête vous avez spécifié lors de la création du mécanisme d’autorisation).
Vous pouvez utiliser [AWS Amplify]() pour effectuer ces tâches. Pour plus d’informations, consultez [Intégration d’Amazon Cognito avec des applications Web et mobiles](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html).
+ Pour Android, consultez [Mise en route avec Amplify pour Android](https://docs.amplify.aws/android/build-a-backend/auth/).
+ Pour utiliser iOS, consultez [Mise en route avec Amplify pour iOS](https://docs.amplify.aws/swift/build-a-backend/auth/).
+ Pour l'utiliser JavaScript, consultez [Getting Started with Amplify pour Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/).
# Configuration d’un mécanisme d’autorisation Amazon Cognito entre comptes pour une API REST à l’aide de la console API Gateway
Vous pouvez désormais également utiliser un groupe d'utilisateurs Amazon Cognito d'un autre AWS compte comme autorisateur d'API. Le groupe d'utilisateurs Amazon Cognito peut utiliser des stratégies d'authentification par jeton porteur, telles que OAuth le protocole SAML. Il est ainsi facile de gérer et de partager de manière centralisée un autorisateur de groupe d'utilisateurs Amazon Cognito central sur plusieurs API Gateway. APIs
Dans cette section, nous montrons comment configurer un groupe d’utilisateurs Amazon Cognito entre comptes à l’aide de la console Amazon API Gateway.
Ces instructions supposent que vous disposez déjà d'une API API Gateway sur un AWS compte et d'un groupe d'utilisateurs Amazon Cognito sur un autre compte.
## Création d’un mécanisme d’autorisation Amazon Cognito entre comptes pour une API REST
Connectez-vous à la console Amazon API Gateway dans le compte qui contient votre API, puis procédez comme suit :
1. Créez une API ou sélectionnez une API existante dans API Gateway.
1. Dans le panneau de navigation principal, choisissez **Mécanismes d'autorisation**.
1. Choisissez **Créer un mécanisme d'autorisation**.
1. Pour configurer le nouveau mécanisme d'autorisation afin d'utiliser un groupe d'utilisateurs, procédez comme suit :
1. Pour **Nom du mécanisme d’autorisation**, entrez un nom.
1. Pour **Type de mécanisme d'autorisation**, sélectionnez **Cognito**.
1. Pour **Groupe d’utilisateurs Cognito**, entrez l’ARN complet du groupe d’utilisateurs que vous avez dans votre deuxième compte.
**Note**
Dans la console Amazon Cognito, vous pouvez trouver l’ARN de votre groupe d’utilisateurs dans le champ **Pool ARN (ARN du groupe)** du volet **General Settings (Paramètres généraux)**.
1. Pour **Source du jeton**, entrez **Authorization** comme nom d'en-tête pour transmettre le jeton d'identité ou le jeton d'accès renvoyé par Amazon Cognito lorsqu'un utilisateur se connecte avec succès.
1. (Facultatif) Entrez une expression régulière dans le champ **Validation du jeton** pour valider le champ `aud` (public) du jeton d’identité avant que la demande soit autorisée avec Amazon Cognito. Notez que lors de l'utilisation d'un jeton d'accès, cette validation rejette la demande en raison du jeton d'accès ne contenant pas le champ `aud`.
1. Choisissez **Créer un mécanisme d'autorisation**.
# Créez un autorisateur Amazon Cognito pour une API REST à l'aide de CloudFormation
Vous pouvez l'utiliser CloudFormation pour créer un groupe d'utilisateurs Amazon Cognito et un autorisateur Amazon Cognito. L'exemple de CloudFormation modèle effectue les opérations suivantes :
+ Créez un groupe d’utilisateurs Amazon Cognito. Un client doit d’abord connecter l’utilisateur à un groupe d’utilisateurs et obtenir un [jeton d’identité ou d’accès](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Si vous utilisez des jetons d'accès pour autoriser des appels de méthode d'API, assurez-vous de configurer l'intégration de l'application avec le groupe d'utilisateurs pour configurer les règles personnalisées de votre choix sur un serveur de ressources donné.
+ Il crée une API API Gateway avec une méthode `GET`.
+ Crée un mécanisme d’autorisation Amazon Cognito qui utilise l’en-tête `Authorization` comme source du jeton.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
UserPool:
Type: AWS::Cognito::UserPool
Properties:
AccountRecoverySetting:
RecoveryMechanisms:
- Name: verified_phone_number
Priority: 1
- Name: verified_email
Priority: 2
AdminCreateUserConfig:
AllowAdminCreateUserOnly: true
EmailVerificationMessage: The verification code to your new account is {####}
EmailVerificationSubject: Verify your new account
SmsVerificationMessage: The verification code to your new account is {####}
VerificationMessageTemplate:
DefaultEmailOption: CONFIRM_WITH_CODE
EmailMessage: The verification code to your new account is {####}
EmailSubject: Verify your new account
SmsMessage: The verification code to your new account is {####}
UpdateReplacePolicy: Retain
DeletionPolicy: Retain
CogAuthorizer:
Type: AWS::ApiGateway::Authorizer
Properties:
Name: CognitoAuthorizer
RestApiId:
Ref: Api
Type: COGNITO_USER_POOLS
IdentitySource: method.request.header.Authorization
ProviderARNs:
- Fn::GetAtt:
- UserPool
- Arn
Api:
Type: AWS::ApiGateway::RestApi
Properties:
Name: MyCogAuthApi
ApiDeployment:
Type: AWS::ApiGateway::Deployment
Properties:
RestApiId:
Ref: Api
DependsOn:
- CogAuthorizer
- ApiGET
ApiDeploymentStageprod:
Type: AWS::ApiGateway::Stage
Properties:
RestApiId:
Ref: Api
DeploymentId:
Ref: ApiDeployment
StageName: prod
ApiGET:
Type: AWS::ApiGateway::Method
Properties:
HttpMethod: GET
ResourceId:
Fn::GetAtt:
- Api
- RootResourceId
RestApiId:
Ref: Api
AuthorizationType: COGNITO_USER_POOLS
AuthorizerId:
Ref: CogAuthorizer
Integration:
IntegrationHttpMethod: GET
Type: HTTP_PROXY
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Outputs:
ApiEndpoint:
Value:
Fn::Join:
- ""
- - https://
- Ref: Api
- .execute-api.
- Ref: AWS::Region
- "."
- Ref: AWS::URLSuffix
- /
- Ref: ApiDeploymentStageprod
- /
```
# Intégrations pour REST APIs dans API Gateway
Après avoir configuré une méthode d’API, vous devez l’intégrer avec un point de terminaison dans le serveur principal. Un point de terminaison principal est également appelé point de terminaison d'intégration et peut être une fonction Lambda, une page Web HTTP ou AWS une action de service.
Comme avec la méthode d’API, l’intégration de l’API possède une demande d’intégration et une réponse d’intégration. Une demande d’intégration encapsule une demande HTTP reçue par le backend. Elle peut ou non être différente de la demande de méthode soumise par le client. Une réponse d’intégration est une réponse HTTP encapsulant la sortie renvoyée par le backend.
La configuration d’une demande d’intégration comprend les opérations suivantes : la configuration de la transmission des demandes de méthode soumises par le client au backend ; la configuration de la transformation des données de la demande, le cas échéant, aux données de la demande d’intégration ; la définition de la fonction Lambda à appeler, la définition du serveur HTTP auquel envoyer la demande entrante, ou de l’action de service AWS à appeler.
La configuration d’une réponse d’intégration (applicable uniquement aux intégrations autres que de proxy) comprend les opérations suivantes : la configuration de la transmission des résultats renvoyés par le backend à une réponse de méthode d’un code de statut donné, la configuration de la transformation des paramètres de réponse d’intégration spécifiés aux paramètres de réponse de méthode préconfigurés, et la configuration du mappage du corps de la réponse d’intégration corps au corps de la réponse de la méthode en fonction des modèles de mappage de corps spécifiés.
Par programmation, une demande d’intégration est encapsulée par la ressource [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) et une réponse d’intégration par la ressource [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) d’API Gateway.
Pour configurer une demande d’intégration, vous créez une ressource [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) et vous l’utilisez pour configurer l’URL du point de terminaison de l’intégration. Vous définissez ensuite les autorisations IAM d’accès au backend, et vous spécifiez les mappages pour transformer les données des demandes entrantes avant de les transmettre au backend. Pour configurer une réponse d’intégration pour l’intégration autre que d’un proxy, vous créez une ressource [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) et vous l’utilisez pour définir sa réponse de méthode cible. Vous pouvez ensuite configurer le mappage de la sortie du backend à la réponse de la méthode.
**Topics**
+ [
# Configuration d’une demande d’intégration dans API Gateway
](api-gateway-integration-settings-integration-request.md)
+ [
# Configuration d’une réponse d’intégration dans API Gateway
](api-gateway-integration-settings-integration-response.md)
+ [
# Intégrations Lambda pour REST APIs dans API Gateway
](set-up-lambda-integrations.md)
+ [
# Intégrations HTTP pour REST APIs dans API Gateway
](setup-http-integrations.md)
+ [
# Diffusez la réponse d'intégration pour vos intégrations de proxy dans API Gateway
](response-transfer-mode.md)
+ [
# Intégrations privées pour REST APIs dans API Gateway
](private-integration.md)
+ [
# Intégrations fictives pour REST APIs dans API Gateway
](how-to-mock-integration.md)
# Configuration d’une demande d’intégration dans API Gateway
Pour configurer une demande d’intégration, vous effectuez les tâches facultatives et obligatoires suivantes :
1. Choisissez un type d’intégration qui détermine la façon dont la demande de méthode est transmise au backend.
1. Pour les intégrations non simulées, spécifiez une méthode HTTP et l’URI du point de terminaison de l’intégration ciblée, à l’exception de l’intégration `MOCK`.
1. Pour les intégrations avec les fonctions Lambda et les AWS autres actions de service, définissez un rôle IAM avec les autorisations requises pour qu'API Gateway appelle le backend en votre nom.
1. Pour les intégrations autres que de proxy, définissez les mappages de paramètres nécessaires pour mapper les paramètres de demande de méthode prédéfinis sur les paramètres de demande d’intégration correspondants.
1. Pour les intégrations autres que de proxy, définissez les mappages de corps nécessaires pour mapper le corps de la demande de méthode entrante d’un type de contenu donné en fonction du modèle de mappage spécifié.
1. Pour les intégrations autres que de proxy, spécifiez la condition selon laquelle les données de la demande de méthode entrante sont transmises au backend en l’état.
1. Vous pouvez également spécifier la manière de gérer la conversion de type pour une charge utile binaire.
1. Si vous le souhaitez, vous pouvez déclarer un nom d’espace de nom de cache et des paramètres clés de cache pour activer la mise en cache d’API.
Ces tâches impliquent la création d’une ressource d’[intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) d’API Gateway et la configuration des valeurs de propriétés correspondantes. Vous pouvez le faire à l'aide de la console API Gateway, de AWS CLI commandes, d'un AWS SDK ou de l'API REST API Gateway.
**Topics**
+ [
# Tâches de base d’une demande d’intégration d’API
](integration-request-basic-setup.md)
+ [
# Choix d’un type d’intégration d’API API Gateway
](api-gateway-api-integration-types.md)
+ [
# Configuration de l’intégration de proxy avec une ressource proxy
](api-gateway-set-up-simple-proxy.md)
+ [
# Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway
](how-to-method-settings-console.md)
# Tâches de base d’une demande d’intégration d’API
Une demande d’intégration est une demande HTTP qu’API Gateway soumet au backend en la transmettant avec les données de demande soumises par le client et en les transformant, le cas échéant. La méthode HTTP (ou verbe) et l’URI de la demande d’intégration sont dictées par le backend (à savoir, le point de terminaison d’intégration). Elles peuvent être identiques ou différentes de la méthode HTTP et de l’URI de la demande de méthode, respectivement.
Par exemple, lorsqu’une fonction Lambda renvoie un fichier récupéré dans Amazon S3, vous pouvez exposer cette opération intuitivement en tant que demande de méthode `GET` au client même si la demande d’intégration correspondante nécessite l’utilisation d’une demande `POST` pour appeler la fonction Lambda. Pour un point de terminaison HTTP, il est probable que la demande de méthode et la demande d’intégration correspondante utilisent toutes deux le même verbe HTTP. Toutefois, cela n’est pas obligatoire. Vous pouvez intégrer la demande de méthode suivante :
```
GET /{var}?query=value
Host: api.domain.net
```
Avec la demande d’intégration suivante :
```
POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...
{
path: "{var}'s value",
type: "value"
}
```
En tant que développeur d’API, vous pouvez utiliser n’importe quel verbe HTTP et URI pour qu’une demande de méthode corresponde à vos besoins. Cependant, vous devez suivre les conditions du point de terminaison de l’intégration. Lorsque les données de la demande de méthode sont différentes des données de la demande d’intégration, vous pouvez rapprocher la différence en fournissant des mappages à partir des données de demande de la méthode aux données de la demande d’intégration.
Dans les exemples précédents, le mappage traduit les valeurs de variable de chemin d’accès (`{var}`) et de paramètre de demande (`query`) de la demande de méthode `GET` aux valeurs des propriétés `path` et `type` de charge utile de la demande d’intégration. Les autres données de demandes mappables comprennent les en-têtes et le corps des demandes. Celles-ci sont décrites dans [Mappage des paramètres pour REST APIs dans API Gateway](rest-api-parameter-mapping.md).
Lors de la configuration de la demande d’intégration HTTP ou de proxy HTTP, vous attribuez l’URL du point de terminaison HTTP backend en tant que valeur d’URI de la demande d’intégration. Par exemple, dans l' PetStoreAPI, la demande de méthode pour obtenir une page de pets possède l'URI de demande d'intégration suivant :
```
http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
Lors de la configuration de l’intégration Lambda ou de proxy Lambda, vous attribuez l’Amazon Resource Name (ARN) pour appeler la fonction Lambda en tant que valeur d’URI de la demande d’intégration. Cet ARN présente le format suivant :
```
arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations
```
La partie après `arn:aws:apigateway:api-region:lambda:path/`, à savoir `/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`, est le chemin d’URI de l’API REST de l’action [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) Lambda. Si vous utilisez la console API Gateway pour configurer l’intégration Lambda, API Gateway crée l’ARN et l’attribue à l’URI d’intégration après vous avoir invité à choisir le `lambda-function-name` à partir d’une région.
Lorsque vous configurez la demande d'intégration avec une autre action de AWS service, l'URI de la demande d'intégration est également un ARN, similaire à l'intégration avec l'action Lambda`Invoke`. Par exemple, pour l'intégration avec l'[GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)action d'Amazon S3, l'URI de demande d'intégration est un ARN au format suivant :
```
arn:aws:apigateway:api-region:s3:path/{bucket}
```
L’URI de la demande d’intégration correspond à la convention de chemin pour spécifier l’action, où `{bucket}` est l’espace réservé d’un nom de compartiment. Une action de AWS service peut également être référencée par son nom. Grâce au nom de l’action, l’URI de demande d’intégration pour l’action `GetBucket` d’Amazon S3 devient la suivante :
```
arn:aws:apigateway:api-region:s3:action/GetBucket
```
Grâce à l’URI de la demande d’intégration basée sur l’action, le nom du compartiment (`{bucket}`) doit être spécifié dans le corps de la demande d’intégration (`{ Bucket: "{bucket}" }`), en respectant le format d’entrée de l’action `GetBucket`.
Pour les AWS intégrations, vous devez également configurer les [informations d'identification](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials) pour permettre à API Gateway d'appeler les actions intégrées. Vous pouvez créer un rôle IAM ou choisir un rôle IAM existant pour qu’API Gateway appelle l’action, puis spécifier le rôle à l’aide de son ARN. Voici un exemple de cet ARN :
```
arn:aws:iam::account-id:role/iam-role-name
```
Ce rôle IAM doit contenir une politique permettant l’exécution de l’action. Il doit également avoir déclaré API Gateway (dans la relation d’approbation du rôle) en tant qu’entité de confiance pour assumer le rôle. Ces autorisations peuvent être accordées sur l’action même. Ce sont les autorisations basées sur les ressources. Pour l’intégration Lambda, vous pouvez appeler l’action [addPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) de Lambda pour définir les autorisations basées sur les ressources, puis définissez `credentials` sur null dans la demande d’intégration API Gateway.
Nous avons vu la configuration de l’intégration de base. Les paramètres avancés comprennent les données de demande de méthode de mappage aux données de demande d’intégration. Pour de plus amples informations, veuillez consulter [Transformations de données pour REST APIs dans API Gateway](rest-api-data-transformations.md).
# Choix d’un type d’intégration d’API API Gateway
Vous choisissez un type d’intégration d’API en fonction des types de point de terminaison d’intégration que vous utilisez et de la façon dont vous souhaitez que vos données soient transmises de et vers le point de terminaison d’intégration. Pour une fonction Lambda, vous pouvez avoir l’intégration de proxy Lambda ou l’intégration personnalisée Lambda. Pour un point de terminaison HTTP, vous pouvez avoir l’intégration de proxy HTTP ou l’intégration personnalisée HTTP. Pour une action de AWS service, vous avez uniquement AWS intégré le type non proxy. API Gateway prend également en charge l’intégration simulée, où API Gateway sert de point de terminaison d’intégration pour répondre à une demande de méthode.
L'intégration personnalisée Lambda est un cas particulier d'intégration, où le point de terminaison AWS d'intégration correspond à l'[action d'appel de fonction du service Lambda](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html).
Par programmation, vous choisissez un type d’intégration en définissant la propriété [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type) de la ressource [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Pour l’intégration de proxy Lambda, la valeur est `AWS_PROXY`. Pour l’intégration personnalisée Lambda et toutes les autres intégrations AWS , c’est `AWS`. Pour l’intégration de proxy HTTP et l’intégration HTTP, la valeur est `HTTP_PROXY` et `HTTP`, respectivement. Pour l’intégration simulée, la valeur `type` est `MOCK`.
L’intégration de proxy Lambda prend en charge une configuration d’intégration simplifiée avec une seule fonction Lambda. Cette configuration est simple et peut évoluer avec le backend sans besoin de manipuler la configuration existante. Pour ces raisons, il est vivement recommandé d’effectuer l’intégration avec une fonction Lambda.
En revanche, l’intégration personnalisée Lambda permet de réutiliser les modèles de mappage configurés pour divers points de terminaison d’intégration qui ont des exigences similaires de formats de données d’entrée et de sortie. La configuration est plus complexe ; elle est recommandée pour des scénarios d’application plus avancés.
De même, l’intégration de proxy HTTP dispose d’une configuration d’intégration simplifiée et peut évoluer avec le backend sans besoin de manipuler la configuration existante. L’intégration personnalisée HTTP est plus complexe à configurer, mais elle permet de réutiliser les modèles de mappage configurés pour d’autres points de terminaison d’intégration.
La liste suivante récapitule les types d’intégration pris en charge :
+ `AWS` : ce type d’intégration permet à une API d’exposer les actions de service AWS . Dans l’intégration `AWS`, vous devez configurer à la fois la demande d’intégration et la réponse d’intégration et configurer les mappages de données nécessaires de la demande de méthode à la demande d’intégration et de la réponse d’intégration à la réponse de méthode.
+ `AWS_PROXY` : ce type d’intégration permet d’intégrer une méthode d’API avec l’action d’appel de fonction Lambda grâce à une configuration d’intégration simplifiée, souple et polyvalente. Cette intégration s’appuie sur les interactions directes entre le client et la fonction Lambda intégrée.
Avec ce type d’intégration, également appelée intégration de proxy Lambda, vous ne configurez pas la demande d’intégration ou la réponse d’intégration. API Gateway transmet la demande entrante du client comme entrée à la fonction Lambda de backend. La fonction Lambda intégrée prend l’[entrée de ce format](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) et analyse l’entrée de tous les sources disponibles, y compris les en-têtes de demande, les variables d’URL de chemin, les paramètres des chaînes de requête et le corps correspondants. La fonction renvoie le résultat respectant ce [format de sortie](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format).
Il s'agit du type d'intégration préféré pour appeler une fonction Lambda via API Gateway. Il ne s'applique à aucune autre action de AWS service, y compris aux actions Lambda autres que l'action d'appel de fonction.
+ `HTTP` : ce type d’intégration permet à une API d’exposer les points de terminaison HTTP du backend. Avec l’intégration `HTTP`, également appelée intégration personnalisée HTTP, vous devez configurez pas la demande d’intégration et la réponse d’intégration. Vous devez configurer les mappages de données nécessaires de la demande de méthode à la demande d’intégration et de la réponse d’intégration à la réponse de méthode.
+ `HTTP_PROXY`: L’intégration de proxy HTTP permet à un client d’accéder aux points de terminaison HTTP du backend avec une configuration d’intégration rationalisée sur une seule méthode d’API. Vous ne définissez pas la demande d’intégration ou la réponse d’intégration. API Gateway transmet la demande entrante du client vers le point de terminaison HTTP et transmet la réponse sortante du point de terminaison HTTP au client.
+ `MOCK` : ce type d’intégration permet à API Gateway de renvoyer une réponse sans envoyer la demande au backend. Cela est utile pour le test d’API, car le code peut être utilisé pour tester la configuration de l’intégration sans encourir des frais pour l’utilisation du backend et pour permettre le développement collaboratif d’une API.
Dans le cadre du développement collaboratif, une équipe peut isoler ses efforts de développement en configurant des simulations de composants d’API détenus par d’autres équipes en utilisant les intégrations `MOCK`. Cela permet également de renvoyer les en-têtes CORS et de s’assurer que la méthode d’API autorise l’accès CORS. De fait, la console API Gateway intègre la méthode `OPTIONS` pour prendre en charge CORS avec une intégration simulée. Les [réponses de passerelle](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) sont d’autres exemples d’intégrations simulées.
# Configuration de l’intégration de proxy avec une ressource proxy
Pour configurer une intégration de proxy dans une API API Gateway avec une [ressource proxy](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource), exécutez les tâches suivantes :
+ Créer une ressource proxy avec une variable de chemin gourmande `{proxy+}`.
+ Définir la méthode `ANY` sur la ressource proxy.
+ Intégrer la ressource et la méthode avec un backend à l’aide du type d’intégration HTTP ou Lambda.
**Note**
Les variables de chemin gourmandes en ressources, les méthodes `ANY` et les types d’intégration de proxy sont des fonctions indépendantes, même si elles sont couramment utilisées ensemble. Vous pouvez configurer une méthode spécifique HTTP sur une ressource gourmande ou appliquer des types d’intégration différente de proxy à une ressource proxy.
API Gateway adopte certaines restrictions et limitations lors de la gestion des méthodes avec une intégration de proxy Lambda ou une intégration de proxy HTTP. Pour en savoir plus, consultez [Remarques importantes concernant Amazon API Gateway](api-gateway-known-issues.md).
**Note**
Lorsque vous utilisez l’intégration de proxy avec un comportement relais, API Gateway renvoie l’en-tête `Content-Type:application/json` par défaut si le type de contenu d’une charge utile n’est pas spécifié.
Une ressource proxy est plus puissante lorsqu’elle est intégrée avec un backend à l’aide de l’intégration de proxy HTTP ou de l’[intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) de proxy Lambda.
## Intégration de proxy HTTP avec une ressource proxy
L’intégration de proxy HTTP, désignée par `HTTP_PROXY` dans l’API REST API Gateway, est utilisée pour l’intégration d’une demande de méthode avec un point de terminaison HTTP du backend. Avec ce type d’intégration, API Gateway passe simplement l’intégralité de la demande et de la réponse entre le frontend et le backend, avec certaines [restrictions et limitations](api-gateway-known-issues.md).
**Note**
L’intégration de proxy HTTP prend en charge les en-têtes à valeurs multiples et les chaînes de requête.
Lors de l’application de l’intégration de proxy HTTP à une ressource proxy, vous pouvez configurer votre API de façon à exposer tout ou partie de la hiérarchie des points de terminaison du backend HTTP avec une configuration d’intégration unique. Par exemple, supposons que le site Web de votre backend est organisé en plusieurs branches de nœuds d’arborescence éloignées du nœud racine (`/site`) comme : `/site/a0/a1/.../aN`, `/site/b0/b1/.../bM`, etc. Si vous intégrez la méthode `ANY` sur une ressource proxy `/api/{proxy+}` avec les points de terminaison du backend avec des chemins d’URL `/site/{proxy}`, une demande d’intégration unique peut prendre en charge n’importe quelle opération HTTP (GET, POST, etc.) sur `[a0, a1, ..., aN, b0, b1, ...bM, ...]`. Si vous appliquez une intégration de proxy à une méthode HTTP spécifique, par exemple, `GET`, à la place, la demande d’intégration qui en résulte fonctionne avec les opérations (par exemple, `GET`) spécifiées sur n’importe lequel de ces nœuds du backend.
## Intégration de proxy Lambda avec une ressource proxy
L’intégration de proxy Lambda, désignée par `AWS_PROXY` dans l’API REST API Gateway, est utilisée pour l’intégration d’une demande de méthode avec une fonction Lambda sur le backend. Avec ce type d’intégration, API Gateway applique un modèle de mappage par défaut pour envoyer l’ensemble de la demande à la fonction Lambda et transforme la sortie de la fonction Lambda en réponses HTTP.
De même, vous pouvez appliquer l’intégration de proxy Lambda à une ressource proxy `/api/{proxy+}` afin de configurer une intégration unique de façon pour qu’une fonction Lambda du backend réagisse individuellement aux modifications des ressources d’API sous `/api`.
# Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway
La configuration d’une méthode d’API définit la méthode et décrit ses comportements. Pour configurer une méthode, vous devez spécifier une ressource, y compris la racine (« / »), sur laquelle cette méthode est exposée, une méthode HTTP (`GET`, `POST`, etc.) et son mode d’intégration avec le backend ciblé. La demande et la réponse de méthode spécifient le contrat avec l’application appelante, en stipulant les paramètres que l’API peut recevoir et à quoi ressemble la réponse.
Les procédures suivantes décrivent comment utiliser la console API Gateway pour créer une demande d’intégration.
**Topics**
+ [
## Configuration d’une intégration Lambda
](#how-to-method-settings-console-lambda)
+ [
## Configuration d’une intégration HTTP
](#how-to-method-settings-console-http)
+ [
## Configuration d'une intégration AWS de services
](#how-to-method-settings-console-aws)
+ [
## Configuration d’une intégration simulée
](#how-to-method-settings-console-mock)
## Configuration d’une intégration Lambda
Utilisez une intégration de fonction Lambda pour intégrer votre API avec une fonction Lambda. Au niveau de l’API, il s’agit d’un type d’intégration `AWS` si vous créez une intégration autre que de proxy, ou d’un type d’intégration `AWS_PROXY` si vous créez une intégration proxy.
**Pour configurer une intégration Lambda**
1. Dans le volet **Ressources**, choisissez **Créer une méthode**.
1. Pour **Type de méthode**, sélectionnez une méthode HTTP.
1. Sous **Integration type (Type d’intégration)**, choisissez **Lambda function (Fonction Lambda)**.
1. Pour utiliser une intégration proxy Lambda, activez **Intégration proxy Lambda**. Pour en savoir plus sur les intégrations proxy Lambda, consultez [Présentation de l’intégration de proxy Lambda API Gateway](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy).
1. Pour **Fonction Lambda**, entrez le nom de la Fonction Lambda.
Si vous utilisez une Fonction Lambda dans une région différente de celle de votre API, sélectionnez la région dans le menu déroulant et entrez le nom de la Fonction Lambda. Si vous utilisez une Fonction Lambda entre comptes, entrez l’ARN de la fonction.
1. Pour utiliser la valeur de délai d’expiration par défaut de 29 secondes, gardez **Délai d’expiration** activé. Pour définir un délai d’expiration personnalisé, choisissez **Délai d’expiration** et entrez une valeur de délai d’expiration comprise entre `50` et `29000` millisecondes.
1. (Facultatif) Vous pouvez configurer les paramètres de requête de méthode à l’aide des menus déroulants suivants. Choisissez **Paramètres de requête de méthode** et configurez votre demande de méthode. Pour plus d’informations, consultez l’étape 3 de la page [Modification d’une demande de méthode API Gateway dans la console API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Vous pouvez également configurer les paramètres de votre demande de méthode après avoir créé votre méthode.
1. Choisissez **Créer une méthode**.
## Configuration d’une intégration HTTP
Utilisez une intégration HTTP pour intégrer votre API avec un point de terminaison HTTP. Au niveau API, il s'agit du type d'intégration `HTTP`.
**Pour configurer une intégration HTTP**
1. Dans le volet **Ressources**, choisissez **Créer une méthode**.
1. Pour **Type de méthode**, sélectionnez une méthode HTTP.
1. Pour **Type d’intégration**, choisissez **HTTP**.
1. Pour utiliser une intégration proxy HTTP, activez **Intégration proxy HTTP**. Pour en savoir plus sur les intégrations proxy HTTP, consultez [Configuration des intégrations de proxy HTTP dans API Gateway](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource).
1. Dans le champ **Méthode HTTP**, sélectionnez le type de méthode HTTP qui correspond le mieux au service backend HTTP.
1. Pour **URL de point de terminaison**, entrez l’URL du service backend HTTP que cette méthode doit utiliser.
1. Pour **Gestion du contenu**, sélectionnez un comportement de gestion du contenu.
1. Pour utiliser la valeur de délai d'expiration par défaut de 29 secondes, gardez **Délai d'expiration** activé. Pour définir un délai d’expiration personnalisé, choisissez **Délai d’expiration** et entrez une valeur de délai d’expiration comprise entre `50` et `29000` millisecondes.
1. (Facultatif) Vous pouvez configurer les paramètres de requête de méthode à l’aide des menus déroulants suivants. Choisissez **Paramètres de requête de méthode** et configurez votre demande de méthode. Pour plus d’informations, consultez l’étape 3 de la page [Modification d’une demande de méthode API Gateway dans la console API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Vous pouvez également configurer les paramètres de votre demande de méthode après avoir créé votre méthode.
1. Choisissez **Créer une méthode**.
## Configuration d'une intégration AWS de services
Utilisez une intégration AWS de service pour intégrer votre API directement à un AWS service. Au niveau API, il s'agit du type d'intégration `AWS`.
Pour configurer une API Gateway, effectuez l’une des opérations suivantes :
+ Créez une fonction Lambda.
+ Définissez une autorisation de ressource sur la Fonction Lambda.
+ Effectuez toute autre action de service Lambda.
Vous devez choisir **Service AWS **.
**Pour configurer une intégration AWS de services**
1. Dans le volet **Ressources**, choisissez **Créer une méthode**.
1. Pour **Type de méthode**, sélectionnez une méthode HTTP.
1. Pour **Type d’intégration**, choisissez **Service AWS **.
1. Pour **AWS Région**, choisissez la AWS région que vous souhaitez que cette méthode utilise pour appeler l'action.
1. Pour le **AWS service**, choisissez le AWS service que vous souhaitez appeler par cette méthode.
1. Pour **AWS sous-domaine**, entrez le sous-domaine utilisé par le AWS service. En règle générale, vous laisserez ce champ vide. Certains services AWS peuvent prendre en charge les sous-domaines comme partie des hôtes. Consultez la documentation du service pour savoir si cela possible et, le cas échéant, obtenir davantage d’informations.
1. Dans le champ **Méthode HTTP**, sélectionnez le type de méthode HTTP qui correspond à l’action. Pour le type de méthode HTTP, consultez la documentation de référence de l'API pour le AWS service que vous avez choisi pour le **AWS service**.
1. Pour **Type d’action**, sélectionnez **Utiliser un nom d’action** pour utiliser une action d’API ou **Utiliser un remplacement de chemin** pour utiliser un chemin de ressource personnalisé. Pour connaître les actions disponibles et les chemins de ressources personnalisés, consultez la documentation de référence de l'API pour le AWS service que vous avez choisi pour le **AWS service**.
1. Entrez un **Nom d’action** ou un **Remplacement de chemin**.
1. Pour **Rôle d’exécution**, entrez l’ARN du rôle IAM que la méthode va utiliser pour appeler l’action.
Pour créer un rôle IAM, vous pouvez adapter les instructions dans [Étape 1 : créer le rôle d'exécution du proxy de AWS service](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles). Spécifiez une stratégie d’accès avec le nombre souhaité de déclarations d’actions et de ressources. Pour de plus amples informations, veuillez consulter [Fonctionnement d'Amazon API Gateway avec IAM](security_iam_service-with-iam.md).
Pour connaître la syntaxe des instructions d'action et de ressource, consultez la documentation du AWS service que vous avez choisi pour le **AWS service**.
Pour la relation d’approbation du rôle IAM, spécifiez la déclaration suivante qui autorise API Gateway à effectuer des actions au nom de votre compte AWS :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Pour utiliser la valeur de délai d'expiration par défaut de 29 secondes, gardez **Délai d'expiration** activé. Pour définir un délai d’expiration personnalisé, choisissez **Délai d’expiration** et entrez une valeur de délai d’expiration comprise entre `50` et `29000` millisecondes.
1. (Facultatif) Vous pouvez configurer les paramètres de requête de méthode à l’aide des menus déroulants suivants. Choisissez **Paramètres de requête de méthode** et configurez votre demande de méthode. Pour plus d’informations, consultez l’étape 3 de la page [Modification d’une demande de méthode API Gateway dans la console API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Vous pouvez également configurer les paramètres de votre demande de méthode après avoir créé votre méthode.
1. Choisissez **Créer une méthode**.
## Configuration d’une intégration simulée
Utilisez une configuration simulée si vous souhaitez qu’API Gateway agisse en tant que backend pour renvoyer des réponses statiques. Au niveau API, il s'agit du type d'intégration `MOCK`. Généralement, vous pouvez utiliser l’intégration `MOCK` si votre API n’est pas encore finalisée, mais que vous devez générer des réponses d’API pour débloquer les équipes dépendantes et réaliser les tests. Pour la méthode `OPTION`, API Gateway définit l’intégration `MOCK` par défaut afin de renvoyer des en-têtes CORS pour la ressource d’API appliquée.
**Pour configurer une intégration simulée**
1. Dans le volet **Ressources**, choisissez **Créer une méthode**.
1. Pour **Type de méthode**, sélectionnez une méthode HTTP.
1. Pour **Type d’intégration**, sélectionnez **Mock**.
1. (Facultatif) Vous pouvez configurer les paramètres de requête de méthode à l’aide des menus déroulants suivants. Choisissez **Paramètres de requête de méthode** et configurez votre demande de méthode. Pour plus d’informations, consultez l’étape 3 de la page [Modification d’une demande de méthode API Gateway dans la console API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Vous pouvez également configurer les paramètres de votre demande de méthode après avoir créé votre méthode.
1. Choisissez **Créer une méthode**.
# Configuration d’une réponse d’intégration dans API Gateway
Dans le cas d’une intégration autre que de proxy, vous devez configurer au moins une réponse d’intégration, et en faire la réponse par défaut, pour transmettre le résultat renvoyé par le backend au client. Vous pouvez choisir de transmettre le résultat en l’état ou de transformer les données de réponse d’intégration aux données de réponse de la méthode si les deux ont des formats différents.
Dans le cas d’une intégration de proxy, API Gateway transmet automatiquement la sortie du backend au client sous la forme d’une réponse HTTP. Vous ne configurez pas soit une réponse d’intégration soit une réponse de méthode.
Pour configurer une réponse d’intégration, effectuez les tâches facultatives et obligatoires suivantes :
1. Spécifiez un code de statut HTTP d’une méthode de réponse à laquelle les données de réponse d’intégration sont mappées. C’est obligatoire.
1. Définissez une expression régulière pour sélectionner la sortie du serveur principal à représenter par cette réponse d’intégration. Si vous laissez ce champ vide, la réponse est la réponse par défaut utilisée pour recueillir les réponses qui n’ont pas encore été configurées.
1. Le cas échéant, déclarez des mappages composés de paires clé/valeur pour mapper des paramètres de réponse d’intégration spécifiés à des paramètres de réponse de méthode donnés.
1. Le cas échéant, ajoutez des modèles de mappage de corps pour transformer les charges utiles de réponse d’intégration données en charges utiles de réponse de méthode spécifiées.
1. Le cas échéant, spécifiez la manière de gérer la conversion de type pour une charge utile binaire.
Une réponse d’intégration est une réponse HTTP encapsulant la réponse du backend. Pour un point de terminaison HTTP, la réponse du backend est une réponse HTTP. Le code de statut de réponse d’intégration peut prendre le code de statut renvoyé par le backend, et le corps de réponse d’intégration est la charge utile renvoyée par le backend. Pour un point de terminaison Lambda, la réponse du backend est la sortie renvoyée par la fonction Lambda. Avec l’intégration Lambda, la sortie de fonction Lambda est renvoyée en tant que réponse `200 OK`. La charge utile peut contenir le résultat sous la forme de données JSON, y compris une chaîne JSON ou un objet JSON, ou un message d’erreur sous la forme d’un objet JSON. Vous pouvez attribuer une expression régulière à la propriété [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) pour mapper une réponse d’erreur à une réponse d’erreur HTTP appropriée. Pour plus d’informations sur la réponse d’erreur de la fonction Lambda, consultez [Gestion des erreurs Lambda dans API Gateway](handle-errors-in-lambda-integration.md). Avec l’intégration de proxy Lambda, la fonction Lambda doit renvoyer une sortie au format suivant :
```
{
statusCode: "...", // a valid HTTP status code
headers: {
custom-header: "..." // any API-specific custom header
},
body: "...", // a JSON string.
isBase64Encoded: true|false // for binary support
}
```
Il n’y a pas besoin de mapper la réponse de la fonction Lambda à la réponse HTTP adéquate.
Pour renvoyer le résultat au client, configurez la réponse d’intégration pour transmettre la réponse du point de terminaison en l’état à la réponse de méthode correspondante. Vous pouvez également mapper les données de réponse du point de terminaison aux données de réponse de la méthode. Les données de réponse qui peuvent être mappées comprennent le code de statut de réponse, les paramètres d’en-tête de réponse et le corps de réponse. Si aucune réponse de méthode n’est définie pour le code de statut renvoyé, API Gateway renvoie une erreur 500. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md).
# Intégrations Lambda pour REST APIs dans API Gateway
Vous pouvez intégrer une méthode API avec une fonction Lambda en utilisant l’intégration de proxy Lambda ou l’intégration autre que proxy (personnalisée) Lambda.
Avec l’intégration de proxy Lambda, la configuration requise est simple. Définissez la méthode HTTP de l’intégration sur POST, l’URI du point de terminaison de l’intégration sur l’ARN de l’action d’appel de la fonction Lambda d’une fonction Lambda spécifique, et autorisez API Gateway à appeler la fonction Lambda en votre nom.
Avec l’intégration autre que de proxy Lambda, outre la configuration de l’intégration de proxy, vous pouvez spécifier la façon dont les données des demandes entrantes sont mappées à la demande d’intégration et la façon dont les données de réponse d’intégration résultantes sont mappées à la réponse de méthode.
**Topics**
+ [
# Intégrations de proxy Lambda dans API Gateway
](set-up-lambda-proxy-integrations.md)
+ [
# Configuration d’intégrations personnalisées Lambda dans API Gateway
](set-up-lambda-custom-integrations.md)
+ [
# Configuration d’un appel asynchrone de la fonction Lambda du backend
](set-up-lambda-integration-async.md)
+ [
# Gestion des erreurs Lambda dans API Gateway
](handle-errors-in-lambda-integration.md)
# Intégrations de proxy Lambda dans API Gateway
La section suivante explique comment utiliser une intégration de proxy Lambda.
**Topics**
+ [
## Présentation de l’intégration de proxy Lambda API Gateway
](#api-gateway-create-api-as-simple-proxy)
+ [
## Prise en charge des en-têtes à valeurs multiples et des paramètres de chaîne de requête
](#apigateway-multivalue-headers-and-parameters)
+ [
## Format d’entrée d’une fonction Lambda pour l’intégration de proxy
](#api-gateway-simple-proxy-for-lambda-input-format)
+ [
## Format de sortie d’une fonction Lambda pour l’intégration de proxy
](#api-gateway-simple-proxy-for-lambda-output-format)
+ [
# Configurez l'intégration du proxy Lambda pour API Gateway à l'aide du AWS CLI
](set-up-lambda-proxy-integration-using-cli.md)
+ [
# Configuration d’une ressource proxy avec une intégration de proxy Lambda à l’aide d’une définition OpenAPI
](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## Présentation de l’intégration de proxy Lambda API Gateway
L’intégration de proxy Lambda Amazon API Gateway est un mécanisme simple, puissant et agile pour créer une API avec la configuration d’une seule méthode d’API. L’intégration de proxy Lambda permet au client d’appeler une seule fonction Lambda du backend. La fonction accède à de nombreuses ressources ou fonctionnalités d'autres AWS services, notamment en appelant d'autres fonctions Lambda.
Dans l’intégration de proxy Lambda, quand un client envoie une demande d’API, API Gateway transmet à la fonction Lambda intégrée un [objet d’événement](#api-gateway-simple-proxy-for-lambda-input-format), si ce n’est que l’ordre des paramètres de la demande n’est pas préservé. Les [données de la demande](#api-gateway-simple-proxy-for-lambda-input-format) incluent les en-têtes de demande, les paramètres de chaîne de requête, les variables du chemin de l’URL, la charge utile et les données de configuration de l’API. Les données de configuration peuvent inclure le nom de la phase de déploiement en cours, les variables de la phase, l’identité de l’utilisateur ou le contexte d’autorisation (le cas échéant). La fonction Lambda du backend analyse les données de la demande entrante pour déterminer la réponse qu’elle renvoie. Pour qu’API Gateway transmette la sortie Lambda comme réponse de l’API au client, la fonction Lambda doit renvoyer le résultat dans [ce format](#api-gateway-simple-proxy-for-lambda-output-format).
Dans la mesure où API Gateway n’intervient pas beaucoup entre le client et la fonction Lambda du backend pour l’intégration de proxy Lambda, le client et la fonction Lambda intégrée peuvent s’adapter aux modifications de l’autre sans interrompre la configuration de l’intégration existante de l’API. Pour ce faire, le client doit suivre les protocoles d’application édictés par la fonction Lambda du backend.
Vous pouvez configurer une intégration de proxy Lambda pour n’importe quelle méthode d’API. Mais une intégration de proxy Lambda est plus puissante quand elle est configurée pour une méthode d’API impliquant une ressource proxy générique. La ressource proxy générique peut être symbolisée par la variable spéciale de chemin modélisé `{proxy+}`, l’espace réservé de la méthode fourre-tout `ANY`, ou les deux. Le client peut transmettre les entrées de la fonction Lambda du backend dans la demande entrante comme paramètres de la demande ou comme charge utile applicable. Les paramètres de la demande comprennent les en-têtes, les variables du chemin de l’URL, les paramètres de la chaîne de requête et la charge utile applicable. La fonction Lambda intégrée vérifie l’ensemble des sources d’entrée avant de traiter la demande et de répondre au client avec des messages d’erreur significatifs si l’une des entrées requises est manquante.
Lors de l’appel d’une méthode d’API intégrée avec la méthode HTTP générique `ANY` et la ressource générique `{proxy+}`, le client soumet une demande avec une méthode HTTP particulière à la place de `ANY`. Le client spécifie également un chemin d’URL particulier au lieu de `{proxy+}` et inclut tous les en-têtes requis, les paramètres de chaîne de requête ou une charge utile applicable.
La liste suivante résume les comportements d’exécution de différentes méthodes d’API avec l’intégration de proxy Lambda :
+ `ANY /{proxy+}` : le client doit choisir une méthode HTTP particulière, doit définir une hiérarchie de chemins de ressources spécifiques et peut définir des en-têtes, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en tant qu’entrées de la fonction Lambda intégrée.
+ `ANY /res` : le client doit choisir une méthode HTTP particulière et peut définir des en-têtes, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en tant qu’entrées de la fonction Lambda intégrée.
+ `GET|POST|PUT|... /{proxy+}` : le client peut définir une hiérarchie de chemins de ressources spécifiques, des en-têtes, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en tant qu’entrées de la fonction Lambda intégrée.
+ `GET|POST|PUT|... /res/{path}/...` : le client doit choisir un segment de chemin particulier (pour la variable `{path}`) et peut définir des en-têtes de demande, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en entrée à la fonction Lambda intégrée.
+ `GET|POST|PUT|... /res` : le client peut choisir des en-têtes de demande, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en entrée à la fonction Lambda intégrée.
Dans les deux cas, la ressource proxy `{proxy+}` et la ressource personnalisée `{custom}` sont exprimées comme des variables de chemin modélisé. Cependant, `{proxy+}` peut faire référence à n’importe quelle ressource de la hiérarchie des chemins, tandis que `{custom}` ne fait référence qu’à un segment de chemin particulier. Par exemple, une épicerie peut organiser son stock de produits en ligne par noms de département, catégories de produit et types de produits. Le site web de l’épicerie peut alors représenter les produits disponibles par les variables de chemin modélisé suivantes des ressources personnalisées : `/{department}/{produce-category}/{product-type}`. Par exemple, les pommes sont représentées par `/produce/fruit/apple` et les carottes par `/produce/vegetables/carrot`. Le site peut également utiliser `/{proxy+}` pour représenter n’importe quel département, catégorie de produit ou type de produit qu’un client peut rechercher lors de ses achats dans la boutique en ligne. Par exemple, `/{proxy+}` peut faire référence à l’un des articles suivants :
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
Pour permettre aux clients de rechercher n’importe quel produit disponible, sa catégorie et le département du magasin associé, vous pouvez exposer une seule méthode `GET /{proxy+}` avec les autorisations en lecture seule. De même, pour permettre à un superviseur de mettre à jour l'inventaire du `produce` département, vous pouvez configurer une autre méthode unique `PUT /produce/{proxy+}` d' read/write autorisation. Pour permettre à un caissier de mettre à jour le total cumulé d'un légume, vous pouvez configurer une `POST /produce/vegetables/{proxy+}` méthode avec des read/write autorisations. Pour permettre à un responsable de boutique d'effectuer toute action possible sur n'importe quel produit disponible, le développeur de la boutique en ligne peut exposer la `ANY /{proxy+}` méthode avec read/write des autorisations. Dans tous les cas, au moment de l’exécution, le client ou l’employé doit sélectionner un produit spécifique d’un type donné dans un département choisi, une catégorie de produits spécifique d’un département donné ou un département spécifique.
Pour plus d’informations sur la configuration des intégrations de proxy API Gateway, consultez [Configuration de l’intégration de proxy avec une ressource proxy](api-gateway-set-up-simple-proxy.md).
L’intégration de proxy nécessite que le client ait une connaissance plus approfondie des exigences du backend. Par conséquent, pour garantir des performances d’application et une expérience de l’utilisateur optimales, le développeur du backend doit communiquer clairement au développeur du client les exigences du backend et fournir un mécanisme de retour d’erreur robuste lorsque les exigences ne sont pas satisfaites.
## Prise en charge des en-têtes à valeurs multiples et des paramètres de chaîne de requête
API Gateway prend désormais en charge les en-têtes multiples et les paramètres de chaîne de requête portant le même nom. Les en-têtes à valeurs multiples et les en-têtes et paramètres à valeur unique peuvent être combinés dans les mêmes demandes et réponses. Pour plus d’informations, consultez [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](#api-gateway-simple-proxy-for-lambda-input-format) et [Format de sortie d’une fonction Lambda pour l’intégration de proxy](#api-gateway-simple-proxy-for-lambda-output-format).
## Format d’entrée d’une fonction Lambda pour l’intégration de proxy
Avec l’intégration de proxy Lambda, API Gateway mappe l’intégralité de la demande du client avec le paramètre `event` en entrée de la fonction Lambda du backend. L’exemple suivant montre la structure d’un événement qu’API Gateway envoie à une intégration de proxy Lambda.
Dans cet exemple, nous supposons que l’invocation d’API Gateway était la suivante :
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
Le résultat se présente comme suit :
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"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": "IP",
"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
}
```
**Note**
Dans l’entrée :
La clé `headers` ne peut contenir que des en-têtes à valeur unique.
La clé `multiValueHeaders` peut contenir des en-têtes à valeurs multiples, ainsi que des en-têtes à valeur unique.
Si vous spécifiez des valeurs pour `headers` et `multiValueHeaders`, API Gateway les fusionne en une seule liste. Si la même paire clé-valeur est spécifiée dans les deux, seules les valeurs de `multiValueHeaders` s’afficheront dans la liste fusionnée.
Dans l’entrée de la fonction Lambda du backend, l’objet `requestContext` est une association de paires clé/valeur. Dans chaque paire, la clé est le nom d’une propriété de la variable [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) et la valeur est la valeur de cette propriété. API Gateway peut ajouter de nouvelles clés au mappage.
D’après les fonctions activées, le mappage `requestContext` peut varier d’une API à l’autre. Ainsi, dans l’exemple précédent, puisqu’aucun type d’autorisation n’est spécifié, il n’y a aucune propriété `$context.authorizer.*` ou `$context.identity.*` présente. Lorsqu’un type d’autorisation est spécifié, API Gateway transmet les informations sur l’utilisateur autorisé au point de terminaison d’intégration dans un objet `requestContext.identity`, comme suit :
+ Lorsque le type d’autorisation est `AWS_IAM`, les informations sur l’utilisateur autorisé comprennent des propriétés `$context.identity.*`.
+ Lorsque le type d’autorisation est `COGNITO_USER_POOLS` (mécanisme d’autorisation Amazon Cognito), les informations sur l’utilisateur autorisé comprennent les propriétés `$context.identity.cognito*` et `$context.authorizer.claims.*`.
+ Lorsque le type d’autorisation est `CUSTOM` (mécanisme d’autorisation Lambda), les informations sur l’utilisateur autorisé comprennent les propriétés `$context.authorizer.principalId`, ainsi que d’autres propriétés `$context.authorizer.*` applicables.
## Format de sortie d’une fonction Lambda pour l’intégration de proxy
Avec l’intégration de proxy Lambda, API Gateway demande à la fonction Lambda du backend de renvoyer la sortie selon le format JSON suivant :
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
```
Dans la sortie :
+ Les clés `headers` et`multiValueHeaders` peuvent être non précisées si aucun en-tête de réponse supplémentaire ne doit être renvoyé.
+ La clé `headers` ne peut contenir que des en-têtes à valeur unique.
+ La clé `multiValueHeaders` peut contenir des en-têtes à valeurs multiples, ainsi que des en-têtes à valeur unique. Vous pouvez utiliser la clé `multiValueHeaders` pour spécifier l’ensemble de vos en-têtes supplémentaires, y compris n’importe quel en-tête à valeur unique.
+ Si vous spécifiez des valeurs pour `headers` et `multiValueHeaders`, API Gateway les fusionne en une seule liste. Si la même paire clé-valeur est spécifiée dans les deux, seules les valeurs de `multiValueHeaders` s’afficheront dans la liste fusionnée.
Pour activer CORS pour l’intégration de proxy Lambda, vous devez ajouter `Access-Control-Allow-Origin:domain-name` à la sortie `headers`. `domain-name` peut être `*` pour n’importe quel nom de domaine. La sortie `body` est regroupée côté frontal en tant que charge utile de réponse de méthode. Si `body` est un blob binaire, vous pouvez l’encoder en tant que chaîne codée en Base64 en définissant `isBase64Encoded` sur `true` et en configurant `*/*` comme un **type de support binaire**. Sinon, vous pouvez le définir sur `false` ou le laisser non spécifié.
**Note**
Pour plus d’informations sur l’activation de la prise en charge des fichiers binaires, consultez [Activation de la prise en charge binaire à l’aide de la console API Gateway](api-gateway-payload-encodings-configure-with-console.md). Pour obtenir un exemple de fonction Lambda, consultez [Renvoi d’un support binaire d’une intégration de proxy Lambda dans API Gateway](lambda-proxy-binary-media.md).
Si le format de la sortie de la fonction est différent, API Gateway renvoie une réponse d’erreur `502 Bad Gateway`.
Pour renvoyer une réponse dans une fonction Lambda dans Node.js, vous pouvez utiliser des commandes telles que les suivantes :
+ Pour renvoyer un résultat positif, appelez `callback(null, {"statusCode": 200, "body": "results"})`.
+ Pour générer une exception, appelez `callback(new Error('internal server error'))`.
+ Pour une erreur côté client (par exemple, si un paramètre obligatoire est manquant), vous pouvez appeler `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` pour renvoyer l’erreur sans générer d’exception.
Dans une fonction `async` Lambda dans Node.js, la syntaxe équivalente serait la suivante :
+ Pour renvoyer un résultat positif, appelez `return {"statusCode": 200, "body": "results"}`.
+ Pour générer une exception, appelez `throw new Error("internal server error")`.
+ Pour une erreur côté client (par exemple, si un paramètre obligatoire est manquant), vous pouvez appeler `return {"statusCode": 400, "body": "Missing parameters of ..."}` pour renvoyer l’erreur sans générer d’exception.
# Configurez l'intégration du proxy Lambda pour API Gateway à l'aide du AWS CLI
Dans cette section, nous vous expliquons comment configurer une API avec l’intégration de proxy Lambda à l’aide de l’ AWS CLI. Pour obtenir des instructions détaillées sur l’utilisation de la console API Gateway afin de configurer une ressource proxy avec l’intégration de proxy Lambda, consultez [Didacticiel : création d’une API REST avec une intégration de proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md).
À titre d’exemple, nous utilisons l’exemple suivant de fonction Lambda comme backend de l’API :
```
export const handler = async(event, context) => {
console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}
res.body = "Hello, " + greeter + "!";
return res
};
```
Si l’on compare ce code à la configuration de l’intégration personnalisée Lambda dans [Configuration d’intégrations personnalisées Lambda dans API Gateway](set-up-lambda-custom-integrations.md), l’entrée de cette fonction Lambda peut être exprimée dans les paramètres et le corps de la demande. Vous avez plus de latitude pour permettre au client de transmettre les mêmes données d’entrée. Ici, le client peut transmettre le nom de l’hôte sous la forme d’une propriété de paramètre de chaîne de demande, d’en-tête ou de corps. La fonction peut également prendre en charge l’intégration personnalisée Lambda. La configuration de l’API est plus simple. Vous ne configurez pas du tout la réponse de la méthode ou la réponse de l’intégration.
**Pour configurer une intégration de proxy Lambda à l'aide du AWS CLI**
1. Utilisez la [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante pour créer une API :
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Le résultat se présente comme suit :
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
Vous allez utiliser l’API `id` (`te6si5ach7`) et `rootResourceId` (`krznpq9xpg`) tout au long de cet exemple.
1. Utilisez la commande [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) suivante pour créer une [ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API Gateway de `/greeting` :
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
Le résultat se présente comme suit :
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Vous allez utiliser la valeur `id` (`2jf6xt`) de la ressource `{proxy+}` pour créer une méthode sur la ressource `/{proxy+}` à l’étape suivante.
1. Utilisez la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante pour créer une demande de méthode `ANY` `ANY /{proxy+}` :
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
Le résultat se présente comme suit :
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
Cette méthode d’API permet au client de recevoir ou d’envoyer des salutations de la fonction Lambda au backend.
1. Utilisez la commande [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) suivante pour configurer l’intégration de la méthode `ANY /{proxy+}` avec une fonction Lambda nommée `HelloWorld`. Cette fonction répond à la demande par un message `"Hello, {name}!"` si le paramètre `greeter` est précisé, ou `"Hello, World!"` si le paramètre de chaîne de demande n’est pas défini.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
**Important**
Pour les intégrations Lambda, vous devez utiliser la méthode HTTP `POST` pour la demande d’intégration, conformément à la [spécification de l’action de service Lambda pour les appels de fonction](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Le rôle IAM `apigAwsProxyRole` doit avoir des politiques permettant au service `apigateway` d’appeler des fonctions Lambda. Pour plus d’informations sur les autorisations IAM, consultez [Modèle d’autorisation API Gateway pour l’appel d’une API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api).
Le résultat se présente comme suit :
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations",
"httpMethod": "POST",
"cacheNamespace": "vvom7n",
"credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole",
"type": "AWS_PROXY"
}
```
Plutôt que de fournir un rôle IAM pour `credentials`, vous pouvez utiliser la commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) pour ajouter des autorisations basées sur les ressources. C’est ce que fait la console API Gateway.
1. Utilisez la commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) suivante pour déployer l’API sur une étape `test` :
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testez l’API à l’aide des commandes cURL suivantes dans un terminal.
Appel de l’API avec le paramètre de chaîne de demande `?greeter=jane` :
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane'
```
Appel de l’API avec un paramètre d’en-tête `greeter:jane` :
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-H 'greeter: jane'
```
Appel de l’API avec un corps `{"greeter":"jane"}` :
```
curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
Dans tous les cas, la sortie est une réponse 200 avec le corps de réponse suivant :
```
Hello, jane!
```
# Configuration d’une ressource proxy avec une intégration de proxy Lambda à l’aide d’une définition OpenAPI
Pour configurer une ressource proxy avec le type d’intégration de proxy Lambda, créez une ressource d’API avec un paramètre de chemin gourmand (par exemple, `/parent/{proxy+}`) et intégrez cette ressource avec un backend de fonction Lambda (par exemple, `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`) sur la méthode `ANY`. Le paramètre de chemin gourmand doit se trouver à la fin du chemin de ressource d’API. Comme avec une ressource autre que de proxy, vous pouvez configurer la ressource proxy à l’aide de la console API Gateway, en important un fichier de définitions OpenAPI ou en appelant l’API REST API Gateway directement.
Le fichier de définitions d’API OpenAPI suivant présente un exemple d’API avec une ressource proxy intégrée à une fonction Lambda nommée `SimpleLambda4ProxyResource`.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/testStage"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"basePath": "/testStage",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
}
}
```
------
Avec l’intégration de proxy Lambda, au moment de l’exécution, API Gateway mappe une demande entrante dans le paramètre d’entrée `event` de la fonction Lambda. L’entrée inclut la méthode de demande, le chemin, les en-têtes, les paramètres de chaîne de demande, la charge utile, le contexte associé et les variables d’étape définies. Le format d’entrée est expliqué dans [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Pour qu’API Gateway mappe correctement la sortie Lambda aux réponses HTTP, la fonction Lambda doit sortir le résultat au format décrit dans [Format de sortie d’une fonction Lambda pour l’intégration de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format).
Avec l’intégration de proxy Lambda d’une ressource proxy via la méthode `ANY`, la fonction Lambda du backend unique sert de gestionnaire d’événements pour toutes les demandes via la ressource proxy. Par exemple, pour consigner les modèles de trafic, vous pouvez demander à un appareil mobile d’envoyer ses informations de localisation, notamment l’état, la ville, la rue et le bâtiment en soumettant une demande avec `/state/city/street/house` dans le chemin d’URL de la ressource proxy. La fonction Lambda du backend peut ensuite analyser le chemin d’URL et insérer les tuples d’emplacement dans une table DynamoDB.
# Configuration d’intégrations personnalisées Lambda dans API Gateway
Pour vous montrer comment configurer l’intégration personnalisée Lambda, ou intégration sans proxy, nous allons créer une API d’API Gateway pour exposer la méthode `GET /greeting?greeter={name}` afin d’invoquer une fonction Lambda. Utilisez l’un des exemples de fonctions Lambda suivants pour votre API.
Utilisez l’un des exemples de fonctions Lambda suivants :
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;
// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';
// Log the greeting to CloudWatch
console.log('Hello: ', greeting);
// Return a greeting to the caller
return greeting;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
}
if event['greeter'] == "":
res['body'] = "Hello, World"
elif (event['greeter']):
res['body'] = "Hello, " + event['greeter'] + "!"
else:
raise Exception('Missing the required greeter parameter.')
return res
```
------
La fonction répond avec un message `"Hello, {name}!"` si la valeur du paramètre `greeter` est une chaîne non vide. Elle renvoie un message `"Hello, World!"` si la valeur `greeter` est une chaîne vide. La fonction renvoie un message d’erreur `"Missing the required greeter parameter."` si le paramètre d’hôte n’est pas défini dans la demande entrante. Nous nommons la fonction `HelloWorld`.
Vous pouvez la créer dans la console Lambda ou à l’aide de la AWS CLI. Dans cette section, nous faisons référence à cette fonction avec l’ARN suivant :
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
Avec la fonction Lambda définie dans le backend, commencez à configurer l’API.
**Pour configurer l'intégration personnalisée Lambda à l'aide du AWS CLI**
1. Utilisez la [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante pour créer une API :
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Le résultat se présente comme suit :
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
Vous allez utiliser l’API `id` (`te6si5ach7`) et `rootResourceId` (`krznpq9xpg`) tout au long de cet exemple.
1. Utilisez la commande [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) suivante pour créer une [ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API Gateway de `/greeting` :
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
Le résultat se présente comme suit :
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Vous allez utiliser la valeur `id` (`2jf6xt`) de la ressource `greeting` pour créer une méthode sur la ressource `/greeting` à l’étape suivante.
1. Utilisez la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante pour créer une demande de méthode d’API `GET /greeting?greeter={name}` :
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false
```
Le résultat se présente comme suit :
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
Cette méthode d’API permet au client de recevoir des salutations de la fonction Lambda au backend. Le paramètre `greeter` est facultatif, car le backend doit gérer soit un appelant anonyme, soit un appelant auto-identifié.
1. Utilisez la [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)commande suivante pour configurer la `200 OK` réponse à la demande de méthode de `GET /greeting?greeter={name}` :
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. Utilisez la commande [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) suivante pour configurer l’intégration de la méthode `GET /greeting?greeter={name}` avec une fonction Lambda nommée `HelloWorld`. La fonction répond à la demande par un message `"Hello, {name}!"` si le paramètre `greeter` est précisé, ou `"Hello, World!"` si le paramètre de chaîne de demande n’est pas défini.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
Le modèle de mappage fourni ici convertit le paramètre de chaîne de demande `greeter` en propriété `greeter` de la charge utile JSON. Ceci est nécessaire parce que l’entrée d’une fonction Lambda doit être exprimée dans le corps.
**Important**
Pour les intégrations Lambda, vous devez utiliser la méthode HTTP `POST` pour la demande d’intégration, conformément à la [spécification de l’action de service Lambda pour les appels de fonction](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Le paramètre `uri` est l’ARN de l’action d’appel de fonction.
Le résultat se présente comme suit :
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"
},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}
```
Le rôle IAM `apigAwsProxyRole` doit avoir des politiques qui permettent au service `apigateway` d’appeler des fonctions Lambda. Plutôt que de préciser un rôle IAM pour `credentials`, vous pouvez appeler la commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) pour ajouter des autorisations basées sur les ressources. C’est ainsi que la console API Gateway ajoute ces autorisations.
1. Utilisez la [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)commande suivante pour configurer la réponse d'intégration afin de transmettre la sortie de la fonction Lambda au client en tant que réponse de `200 OK` méthode :
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
En définissant le modèle de sélection sur une chaîne vide, la réponse `200 OK` est la valeur par défaut.
Le résultat se présente comme suit :
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. Utilisez la commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) suivante pour déployer l’API sur une étape `test` :
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testez l’API à l’aide de la commande cURL suivante dans un terminal :
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'
```
# Configuration d’un appel asynchrone de la fonction Lambda du backend
Dans l’intégration autre que de proxy (personnalisée) Lambda, la fonction Lambda du backend est, par défaut, invoquée de façon synchrone. Il s’agit du comportement souhaité pour la plupart des opérations d’API REST. Dans certaines applications, toutefois, les appels doivent avoir lieu de façon asynchrone (sous la forme d’une opération par lots ou d’une opération à latence longue), généralement par un autre composant du backend. Dans ce cas, la fonction Lambda du backend est invoquée de façon asynchrone et la méthode d’API REST frontale ne renvoie aucun résultat.
Vous pouvez également configurer la fonction Lambda pour une intégration Lambda autre que de proxy de sorte qu’elle soit invoquée de façon asynchrone en spécifiant `'Event'` en tant que [type d’appel](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). La procédure à suivre est expliquée ci-après :
## Configuration de l’appel asynchrone Lambda dans la console API Gateway
Pour que tous les appels soient asynchrones :
+ Dans **Requête d’intégration**, ajoutez un en-tête `X-Amz-Invocation-Type` avec une valeur statique de `'Event'`.
Pour que les clients décident si les appels sont asynchrones ou synchrones :
1. Dans **Requête de méthode**, ajoutez un en-tête `InvocationType`.
1. Dans **Requête d’intégration**, ajoutez un en-tête `X-Amz-Invocation-Type` avec une expression de mappage de `method.request.header.InvocationType`.
1. Les clients peuvent inclure l’en-tête `InvocationType: Event` dans les requêtes API pour les appels asynchrones, ou `InvocationType: RequestResponse` pour les appels synchrones.
## Configuration de l’appel asynchrone de Lambda à l’aide d’OpenAPI
Pour que tous les appels soient asynchrones :
+ Ajoutez l'`X-Amz-Invocation-Type`en-tête à la **x-amazon-apigateway-integration**section.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "'Event'"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
Pour que les clients décident si les appels sont asynchrones ou synchrones :
1. Ajoutez l’en-tête suivant sur tout [objet d’élément de chemin OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. Ajoutez l'`X-Amz-Invocation-Type`en-tête à la **x-amazon-apigateway-integration**section.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
1. Les clients peuvent inclure l’en-tête `InvocationType: Event` dans les requêtes API pour les appels asynchrones, ou `InvocationType: RequestResponse` pour les appels synchrones.
## Configurer l'appel asynchrone Lambda à l'aide de CloudFormation
Les CloudFormation modèles suivants montrent comment configurer les `AWS::ApiGateway::Method` appels asynchrones.
Pour que tous les appels soient asynchrones :
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: "'Event'"
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Pour que les clients décident si les appels sont asynchrones ou synchrones :
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
RequestParameters:
method.request.header.InvocationType: false
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Les clients peuvent inclure l’en-tête `InvocationType: Event` dans les requêtes API pour les appels asynchrones, ou `InvocationType: RequestResponse` pour les appels synchrones.
# Gestion des erreurs Lambda dans API Gateway
Pour les intégrations personnalisées Lambda, vous devez mapper les erreurs renvoyées par Lambda dans la réponse d'intégration à des réponses d'erreurs HTTP standard pour vos clients. Sinon, les erreurs Lambda sont renvoyées en tant que réponses `200 OK` par défaut et le résultat n'est pas intuitif pour les utilisateurs de l'API.
Lambda peut renvoyer deux types d'erreurs : des erreurs standard et des erreurs personnalisées. Dans votre API, vous devez les gérer différemment.
Avec l'intégration de proxy Lambda, Lambda doit renvoyer une sortie au format suivant :
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
Dans cette sortie, `statusCode` est généralement `4XX` pour une erreur de client et `5XX` pour une erreur de serveur. API Gateway traite ces erreurs en mappant l'erreur Lambda à une réponse d'erreur HTTP, en fonction du code `statusCode` spécifié. Pour qu'API Gateway transmette le type d'erreur, (par exemple `InvalidParameterException`), dans le cadre de la réponse au client, la fonction Lambda doit inclure un en-tête (par exemple, `"X-Amzn-ErrorType":"InvalidParameterException"`) dans la propriété `headers`.
**Topics**
+ [
## Gestion des erreurs Lambda standard dans API Gateway
](#handle-standard-errors-in-lambda-integration)
+ [
## Gestion des erreurs Lambda personnalisées dans API Gateway
](#handle-custom-errors-in-lambda-integration)
## Gestion des erreurs Lambda standard dans API Gateway
Le format AWS Lambda d'une erreur standard est le suivant :
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
Ici, `errorMessage` est une expression de chaîne de l'erreur. `errorType` est un type d'erreur ou d'exception dépendant du langage. `stackTrace` est une liste d'expressions de chaîne montrant la trace de la pile conduisant à l'apparition de l'erreur.
Par exemple, considérez la fonction Lambda JavaScript (Node.js) suivante.
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
Cette fonction renvoie l'erreur Lambda standard suivante, contenant `Malformed input ...` comme message d'erreur :
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
De même, examinez la fonction Lambda Python suivante qui génère une `Exception` avec le même message d'erreur `Malformed input ...`.
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
Cette fonction renvoie l'erreur Lambda standard suivante :
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
Notez que les valeurs de propriété `errorType` et `stackTrace` sont dépendantes du langage. L'erreur standard s'applique également à n'importe quel objet d'erreur qui est une extension de l'objet `Error` ou une sous-classe de la classe `Exception`.
Pour mapper l'erreur Lambda standard à une réponse de méthode, vous devez d'abord décider d'un code de statut HTTP pour une erreur Lambda donnée. Vous définissez ensuite un modèle d'expression régulière sur la `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` propriété du code d'état HTTP [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)associé au code d'état HTTP donné. Dans la console API Gateway, ce `selectionPattern` est désigné comme **Expressions régulières de l’erreur Lambda** dans la section **Réponse d’intégration** sous chaque réponse d’intégration.
**Note**
API Gateway utilise des expressions régulières de type modèle Java pour le mappage de réponse. Pour plus d’informations, consultez la section [Modèles](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) dans la documentation Oracle.
Par exemple, utilisez ce qui suit [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)pour configurer une nouvelle `selectionPattern` expression :
```
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
```
Veillez également à configurer le code d'erreur correspondant (`400`) dans la [réponse de méthode](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Sinon, API Gateway renvoie une réponse d'erreur de configuration non valide lors de l'exécution.
**Note**
Lors de l'exécution, API Gateway met en correspondance le message `errorMessage` de l'erreur Lambda avec le modèle de l'expression régulière sur la propriété `selectionPattern`. S'il existe une correspondance, API Gateway renvoie l'erreur Lambda en tant que réponse HTTP du code de statut HTTP correspondant. S'il n'existe pas de correspondance, API Gateway renvoie l'erreur sous la forme d'une réponse par défaut ou émet une exception de configuration non valide si aucune réponse par défaut n'est configurée.
La définition de la valeur `selectionPattern` sur `.*` pour une réponse donnée revient à réinitialiser cette réponse comme la réponse par défaut. En effet, un tel modèle de sélection correspond à tous les messages d'erreur, y compris null, c'est-à-dire, tout message d'erreur non spécifié. Le mappage résultant remplace le mappage par défaut. Si vous utilisez `.+` comme modèle de sélection pour filtrer les réponses, il se peut qu’il ne corresponde pas à une réponse contenant un caractère de nouvelle ligne (`\n`).
Pour mettre à jour une `selectionPattern` valeur existante à l'aide de AWS CLI, appelez l'[update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)opération pour remplacer la valeur du `/selectionPattern` chemin par l'expression regex spécifiée du `Malformed*` modèle.
Pour définir l’expression `selectionPattern` à l’aide de la console API Gateway, saisissez l’expression dans la zone de texte **Expressions régulières de l’erreur Lambda** lors de la configuration ou de la mise à jour d’une réponse d’intégration d’un code de statut HTTP spécifié.
## Gestion des erreurs Lambda personnalisées dans API Gateway
Au lieu de l'erreur standard décrite dans la section précédente, vous AWS Lambda permet de renvoyer un objet d'erreur personnalisé sous forme de chaîne JSON. L'erreur peut être n'importe quel objet JSON valide. Par exemple, la fonction Lambda JavaScript (Node.js) suivante renvoie une erreur personnalisée :
```
export const handler = (event, context, callback) => {
...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};
```
Vous devez transformer l'objet `myErrorObj` en chaîne JSON avant d'appeler `callback` pour quitter la fonction. Sinon, `myErrorObj` est renvoyé sous la forme d'une chaîne `"[object Object]"`. Lorsqu'une méthode de votre API est intégrée à la fonction Lambda précédente, API Gateway reçoit une réponse d'intégration avec la charge utile suivante :
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
Comme avec toute réponse d'intégration, vous pouvez transmettre cette réponse d'erreur telle quelle à la réponse de méthode. Vous pouvez aussi avoir un modèle de mappage pour transformer la charge utile en un autre format. Prenons l'exemple du modèle de mappage de corps suivant pour une réponse de méthode d'un code du statut `500` :
```
{
errorMessage: $input.path('$.errorMessage');
}
```
Ce modèle convertit le corps de réponse d'intégration qui contient la chaîne JSON d'erreur personnalisée en le corps de réponse de méthode suivant. Ce corps de réponse de méthode contient l'objet JSON d'erreur personnalisée :
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
En fonction des exigences de votre API, il se peut que vous ayez besoin de transmettre tout ou partie des propriétés d'erreur personnalisée comme paramètres d'en-tête de réponse de méthode. Vous pouvez le faire en appliquant les mappages d'erreur personnalisée du corps de réponse d'intégration aux en-têtes de réponse de méthode.
Par exemple, l'extension OpenAPI suivante définit un mappage à partir des propriétés `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` et `errorMessage.trace` aux en-têtes `error_type`, `error_status`, `error_trace_function` et `error_trace`, respectivement.
```
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
"method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type": "integration.response.body.errorMessage.errorType",
"method.response.header.error_trace": "integration.response.body.errorMessage.trace"
},
...
}
}
}
```
Lors de l'exécution, API Gateway désérialise le paramètre `integration.response.body` lorsqu'il effectue les mappages d'en-tête. Toutefois, cette désérialisation s'applique uniquement aux body-to-header mappages pour les réponses d'erreur personnalisées Lambda et ne s'applique pas aux mappages utilisant. body-to-body `$input.body` Avec ces mappages custom-error-body-to -header, le client reçoit les en-têtes suivants dans le cadre de la réponse de méthode, à condition que les `error_type` en-têtes`error_status`, `error_trace``error_trace_function`, et soient déclarés dans la demande de méthode.
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
La propriété `errorMessage.trace` du corps de réponse d'intégration est une propriété complexe. Elle est mappée à l'en-tête `error_trace` sous la forme d'une chaîne JSON.
# Intégrations HTTP pour REST APIs dans API Gateway
Vous pouvez intégrer une méthode API avec un point de terminaison HTTP grâce à l’intégration de proxy HTTP ou à l’intégration personnalisée HTTP.
API Gateway prend en charge les ports de point de terminaison suivants : 80, 443 et 1024-65535.
Avec l’intégration de proxy, la configuration est simple. Il vous suffit de définir la méthode HTTP et l’URI du point de terminaison HTTP, en fonction des exigences du backend, si vous n’êtes pas concerné par le codage de contenu ou la mise en cache.
Avec l’intégration personnalisée, la configuration est plus complexe. Outre la configuration de l’intégration de proxy, vous devez spécifier la façon dont les données des demandes entrantes sont mappées à la demande d’intégration et la façon dont les données de réponse d’intégration résultantes sont mappées à la réponse de méthode.
**Topics**
+ [
## Configuration des intégrations de proxy HTTP dans API Gateway
](#api-gateway-set-up-http-proxy-integration-on-proxy-resource)
+ [
## Configuration des intégrations personnalisées HTTP dans API Gateway
](#set-up-http-custom-integrations)
## Configuration des intégrations de proxy HTTP dans API Gateway
Pour configurer une ressource proxy avec le type d’intégration de proxy HTTP, créez une ressource d’API avec un paramètre de chemin gourmand (par exemple, `/parent/{proxy+}`) et intégrez cette ressource avec un point de terminaison de backend HTTP (par exemple, `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) sur la méthode `ANY`. Le paramètre de chemin gourmand doit se trouver à la fin du chemin de ressource.
Comme avec une ressource autre que de proxy, vous pouvez configurer une ressource proxy avec l’intégration de proxy HTTP à l’aide de la console API Gateway, en important un fichier de définition OpenAPI ou en appelant directement l’API REST API Gateway. Pour obtenir des instructions détaillées sur l’utilisation de la console API Gateway afin de configurer une ressource proxy avec l’intégration HTTP, consultez [Didacticiel : création d’une API REST avec une intégration de proxy HTTP](api-gateway-create-api-as-simple-proxy-for-http.md).
Le fichier de définition OpenAPI suivant montre un exemple d'API avec une ressource proxy intégrée au [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)site Web.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
},
"servers": [
{
"url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
}
}
```
------
Dans cet exemple, une clé de cache est déclarée sur le paramètre de chemin `method.request.path.proxy` de la ressource proxy. Il s’agit du paramètre par défaut lorsque vous créez l’API à l’aide de la console API Gateway. Le chemin de base de l'API (`/test`correspondant à une étape) est mappé à la PetStore page du site Web (`/petstore`). La demande d'intégration unique reflète l'ensemble du PetStore site Web en utilisant la variable de chemin gourmand de l'API et la méthode `ANY` fourre-tout. Les exemples suivants illustrent cette mise en miroir.
+ **Définir `ANY` en tant que `GET` et `{proxy+}` en tant que `pets`**
Demande de méthode initiée depuis le serveur frontal :
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
Demande d’intégration envoyée au backend :
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
Les instances d’exécution de la méthode `ANY` et de la ressource proxy sont toutes les deux valides. L’appel renvoie une réponse `200 OK` avec la charge utile contenant le premier lot d’animaux domestiques, telle que retournée depuis le serveur principal.
+ **Définir `ANY` en tant que `GET` et `{proxy+}` en tant que `pets?type=dog`**
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
Demande d’intégration envoyée au backend :
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
Les instances d’exécution de la méthode `ANY` et de la ressource proxy sont toutes les deux valides. L’appel renvoie une réponse `200 OK` avec la charge utile contenant le premier lot de chiens spécifiés, telle que retournée depuis le serveur principal.
+ **Définir `ANY` en tant que `GET` et `{proxy+}` en tant que `pets/{petId}`**
Demande de méthode initiée depuis le serveur frontal :
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
Demande d’intégration envoyée au backend :
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
Les instances d’exécution de la méthode `ANY` et de la ressource proxy sont toutes les deux valides. L’appel renvoie une réponse `200 OK` avec la charge utile contenant l’animal spécifié, telle que retournée depuis le backend.
+ **Définir `ANY` en tant que `POST` et `{proxy+}` en tant que `pets`**
Demande de méthode initiée depuis le serveur frontal :
```
POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...
{
"type" : "dog",
"price" : 1001.00
}
```
Demande d’intégration envoyée au backend :
```
POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...
{
"type" : "dog",
"price" : 1001.00
}
```
Les instances d’exécution de la méthode `ANY` et de la ressource proxy sont toutes les deux valides. L’appel renvoie une réponse `200 OK` avec la charge utile contenant l’animal récemment créé, telle que retournée depuis le backend.
+ **Définir `ANY` en tant que `GET` et `{proxy+}` en tant que `pets/cat`**
Demande de méthode initiée depuis le serveur frontal :
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
Demande d’intégration envoyée au backend :
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
L’instance d’exécution du chemin de ressource proxy ne correspond pas au point de terminaison du backend et la demande qui en résulte n’est pas valide. Par conséquent, une réponse `400 Bad Request` est renvoyée avec le message d’erreur suivant.
```
{
"errors": [
{
"key": "Pet2.type",
"message": "Missing required field"
},
{
"key": "Pet2.price",
"message": "Missing required field"
}
]
}
```
+ **Définir `ANY` en tant que `GET` et `{proxy+}` en tant que `null`**
Demande de méthode initiée depuis le serveur frontal :
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
Demande d’intégration envoyée au backend :
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
La ressource ciblée est le parent de la ressource proxy, mais l’instance d’exécution de la méthode `ANY` n’est pas définie dans l’API sur cette ressource. Par conséquent, cette demande `GET` renvoie une réponse `403 Forbidden` avec le message d’erreur `Missing Authentication Token` comme celle renvoyée par API Gateway. Si l’API expose la méthode `ANY` ou `GET` sur la ressource parent (`/`), l’appel renvoie une réponse `404 Not Found` avec le message `Cannot GET /petstore` telle que retournée depuis le serveur principal.
Pour toute demande de client, si l’URL de point de terminaison ciblée n’est pas valide ou si le verbe HTTP est valide, mais non pris en charge, le backend renvoie une réponse `404 Not Found`. Pour une méthode HTTP non prise en charge, une réponse `403 Forbidden` est renvoyée.
## Configuration des intégrations personnalisées HTTP dans API Gateway
Avec l’intégration personnalisée HTTP, également connue sous le nom d’intégration sans proxy, vous contrôlez davantage les données à transmettre entre une méthode d’API et une intégration d’API, et leur mode de transmission. Pour ce faire, vous devez utiliser les mappages de données.
Dans le cadre de la configuration de la demande de méthode, vous définissez la propriété [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters) sur une ressource [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). Cette action permet de déclarer quels paramètres de la demande de méthode (qui sont mis en service à partir du client) doivent être mappés aux paramètres de demande d’intégration ou aux propriétés de corps applicables avant d’être envoyés vers le backend. Ensuite, dans le cadre de la configuration de la demande d'intégration, vous définissez la propriété [RequestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) sur la ressource d'intégration [correspondante pour spécifier](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) les mappages. parameter-to-parameter Vous définissez également la propriété [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestTemplates) afin de spécifier les modèles de mappage, un par type de contenu pris en charge. Les modèles de mappage mappent les paramètres de la demande de méthode, ou le corps, au corps de la demande d’intégration.
De même, dans le cadre de la configuration de la réponse de la méthode, vous définissez la propriété [ResponseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) sur la ressource. [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) Cette action permet de déclarer quels paramètres de la réponse de méthode (qui sont envoyés au client) doivent être mappés depuis les paramètres de réponse d’intégration ou certaines propriétés de corps applicables renvoyés par le backend. Vous allez ensuite configurer [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) pour choisir une réponse d’intégration en fonction de la réponse du backend. Pour une intégration HTTP sans proxy, il s’agit d’une expression régulière. Par exemple, pour mapper tous les codes d’état de réponse HTTP 2xx d’un point de terminaison HTTP à ce mappage de sortie, utilisez `2\d{2}`.
**Note**
API Gateway utilise des expressions régulières de type modèle Java pour le mappage de réponse. Pour plus d’informations, consultez la section [Modèles](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) dans la documentation Oracle.
Ensuite, dans le cadre de la configuration de la réponse d'intégration, vous définissez la propriété [ResponseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) sur la ressource [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)correspondante pour spécifier les mappages. parameter-to-parameter Vous définissez également le mappage [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseTemplates) afin de spécifier les modèles de mappage, un par type de contenu pris en charge. Les modèles de mappage mappent les paramètres de la réponse d’intégration, ou les propriétés du corps de la réponse d’intégration, au corps de la réponse de méthode.
Pour plus d’informations sur la configuration des modèles de mappage, consultez [Transformations de données pour REST APIs dans API Gateway](rest-api-data-transformations.md).
# Diffusez la réponse d'intégration pour vos intégrations de proxy dans API Gateway
Vous pouvez configurer l’intégration de votre proxy pour contrôler comment API Gateway renvoie votre réponse d’intégration. Par défaut, API Gateway attend de recevoir la réponse complète avant de commencer la transmission. Toutefois, si vous définissez le mode de transfert des réponses de votre intégration sur`STREAM`, API Gateway n'attend pas qu'une réponse soit complètement calculée avant de l'envoyer au client. Le streaming des réponses fonctionne pour tous les types de points de terminaison de l’API REST.
Utilisez le streaming de réponses dans les cas d'utilisation suivants :
+ Réduisez le time-to-first-byte (TTFB) pour les applications d'IA génératives telles que les chatbots.
+ Diffusez de gros fichiers d'image, de vidéo ou de musique sans utiliser d'URL pré-signée S3.
+ Réalisez des opérations de longue durée tout en signalant les progrès progressifs, tels que les événements envoyés par le serveur (SSE).
+ Dépassez la limite de charge utile de réponse de 10 Mo d'API Gateway.
+ Dépassez le délai d'expiration de 29 secondes d'API Gateway sans demander d'augmentation du délai d'intégration.
+ Recevez une charge utile binaire sans configurer les types de supports binaires.
## Considérations relatives au streaming de la charge utile de réponse
Les considérations suivantes peuvent avoir un impact sur votre utilisation du streaming de la charge utile de réponse :
+ Vous ne pouvez utiliser le streaming de charge utile de réponse que pour les types d'`AWS_PROXY`intégration `HTTP_PROXY` ou d'intégration. Cela inclut les intégrations de proxy Lambda et les intégrations privées qui utilisent des intégrations. `HTTP_PROXY`
+ Le paramètre du mode de transfert par défaut est`BUFFERED`. Pour utiliser le streaming de réponses, vous devez changer le mode de transfert de réponse sur`STREAM`.
+ Le streaming des réponses n'est pris en charge que pour REST APIs.
+ Les demandes de streaming ne sont pas prises en charge.
+ Vous pouvez diffuser votre réponse pendant 15 minutes maximum.
+ Vos streams sont sujets à des délais d'inactivité. Pour les points de terminaison régionaux ou privés, le délai d'expiration est de 5 minutes. Pour les points de terminaison optimisés pour les bords, le délai d'expiration est de 30 secondes.
+ Si vous utilisez le streaming de réponses pour une API REST régionale avec votre propre CloudFront distribution, vous pouvez atteindre un temps d'inactivité supérieur à 30 secondes en augmentant le délai de réponse de votre CloudFront distribution. Pour plus d'informations, consultez la section [Délai de réponse.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout)
+ Lorsque le mode de transfert des réponses est défini sur`STREAM`, API Gateway ne peut pas prendre en charge les fonctionnalités qui nécessitent de mettre en mémoire tampon l'intégralité de la réponse d'intégration. Pour cette raison, les fonctionnalités suivantes ne sont pas prises en charge par le streaming de réponses :
+ Mise en cache des terminaux
+ Codage du contenu. Si vous souhaitez compresser votre réponse d'intégration, faites-le dans votre intégration.
+ Transformation des réponses avec VTL
+ Dans chaque réponse de streaming, les 10 premiers Mo de charge utile de réponse ne sont soumis à aucune restriction de bande passante. Les données de charge utile de réponse supérieures à 10 Mo sont limitées à 2 Mo/s.
+ Lorsque la connexion entre le client et API Gateway ou entre API Gateway et Lambda est fermée en raison d'un délai d'attente, la fonction Lambda peut continuer à s'exécuter. Pour plus d'informations, voir [Configurer le délai d'expiration de la fonction Lambda.](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)
+ Le streaming des réponses entraîne un coût. Pour plus d’informations, consultez [API Gateway Pricing](https://aws.amazon.com/api-gateway/pricing/) (Tarification d’API Gateway).
# Configurer une intégration de proxy HTTP avec le streaming des réponses de charge utile dans API Gateway
Lorsque vous configurez le streaming de la charge utile des réponses, vous spécifiez le mode de transfert des réponses dans la demande d'intégration de votre méthode. Vous configurez ces paramètres dans la demande d'intégration pour contrôler le comportement d'API Gateway avant et pendant la réponse d'intégration. Lorsque vous utilisez le streaming de réponses, vous pouvez configurer le délai d'intégration jusqu'à 15 minutes.
Lorsque vous utilisez le streaming de réponse de charge utile avec une `HTTP_PROXY` intégration, API Gateway n'envoie le code d'état de la réponse HTTP ni aucun en-tête de réponse HTTP tant qu'il n'a pas reçu tous les en-têtes complets.
## Création d'une intégration de proxy HTTP avec le streaming de réponse à la charge utile
La procédure suivante explique comment importer une nouvelle API avec la valeur `responseTransferMode` définie sur`STREAM`. Si vous disposez d'une API d'intégration existante et que vous souhaitez la modifier`responseTransferMode`, consultez[Mettre à jour le mode de transfert des réponses pour une intégration de proxy HTTP](#response-streaming-http-update).
------
#### [ AWS Management Console ]
**Pour créer une intégration de proxy HTTP avec le streaming de réponses aux charges utiles**
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 REST.
1. Choisissez **Créer une ressource**.
1. Sous **Resource Name (Nom de la ressource)**, entrez **streaming**.
1. Choisissez **Créer une ressource**.
1. Lorsque la ressource **/streaming** est sélectionnée, choisissez **Create method**.
1. Pour **Type de méthode**, choisissez **ANY**.
1. Pour **Type d’intégration**, choisissez **HTTP**.
1. Choisissez l'**intégration du proxy HTTP**.
1. Pour le **mode de transfert Response**, choisissez **Stream**.
1. Pour la **méthode HTTP**, choisissez une méthode.
1. Pour l'**URL du point de terminaison**, entrez un point de terminaison d'intégration. Assurez-vous de choisir un point de terminaison qui produit une charge utile importante à renvoyer vers vous.
1. Choisissez **Créer une méthode**.
Après avoir créé votre méthode, déployez votre API.
**Pour déployer votre API**
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Pour **Étape**, sélectionnez **Nouvelle étape**.
1. Sous **Stage name (Nom de l’étape)**, entrez **prod**.
1. (Facultatif) Sous **Description**, entrez une description.
1. Choisissez **Déployer**.
------
#### [ AWS CLI ]
**Pour créer une nouvelle API avec diffusion en continu des réponses à la charge utile**
1. Copiez le fichier Open API suivant, puis enregistrez-le sous`ResponseStreamDemoSwagger.yaml`. Dans ce fichier, `responseTransferMode` est défini sur`STREAM`. Le point de terminaison d'intégration est défini sur`https://example.com`, mais nous vous recommandons de le modifier pour un point de terminaison qui produit une charge utile importante à vous renvoyer.
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/streaming:
get:
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "https://example.com"
type: "http_proxy"
timeoutInMillis: 900000
responseTransferMode: "STREAM"
```
1. Utilisez la `import-rest-api` commande suivante pour importer votre définition OpenAPI :
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. Utilisez la `create-deployment` commande suivante pour déployer votre nouvelle API sur une étape :
```
aws apigateway create-deployment \
--rest-api-id a1b2c3 \
--stage-name prod \
--region us-west-1
```
------
## Mettre à jour le mode de transfert des réponses pour une intégration de proxy HTTP
La procédure suivante montre comment mettre à jour le mode de transfert des réponses pour une intégration de proxy HTTP.
------
#### [ AWS Management Console ]
**Pour mettre à jour le mode de transfert des réponses pour une intégration de proxy 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 REST.
1. Choisissez une méthode.
1. Dans l’onglet **Requête d’intégration**, sous **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Pour le **mode de transfert Response**, choisissez **Stream**.
1. Choisissez **Enregistrer**.
Après avoir mis à jour votre méthode, déployez votre API.
**Pour déployer votre API**
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Pour **Étape**, sélectionnez **Nouvelle étape**.
1. Sous **Stage name (Nom de l’étape)**, entrez **prod**.
1. (Facultatif) Sous **Description**, entrez une description.
1. Choisissez **Déployer**.
------
#### [ AWS CLI ]
La `update-integration` commande suivante met à jour le mode de transfert d'une intégration de `BUFFERED` vers`STREAM`. Pour toutes les intégrations existantes APIs, le mode de transfert des réponses est défini sur. `BUFFERED`
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method GET \
--patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \
--region us-west-1
```
Vous devez redéployer votre API pour que les modifications prennent effet. Si vous avez personnalisé le délai d'intégration, cette valeur de délai est supprimée, car API Gateway diffuse votre réponse pendant 5 minutes maximum.
La `update-integration` commande suivante met à jour le mode de transfert d'une intégration de `STREAM` vers `BUFFERED` :
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method GET \
--patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \
--region us-west-1
```
Vous devez redéployer votre API pour que les modifications prennent effet.
------
# Configurer une intégration de proxy Lambda avec le streaming des réponses de charge utile dans API Gateway
Vous pouvez diffuser la réponse d'une fonction Lambda pour améliorer les performances du délai d'obtention du premier octet (TTFB) et renvoyer des réponses partielles au client dès qu'elles sont disponibles. API Gateway nécessite que vous utilisiez l'API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)Lambda pour appeler votre fonction Lambda. API Gateway transmet un objet d'événement à la fonction Lambda. La fonction Lambda du backend analyse les données de la demande entrante pour déterminer la réponse qu’elle renvoie. Pour qu'API Gateway diffuse la sortie Lambda, la fonction Lambda doit générer le [format](#response-transfer-mode-lambda-format) requis par API Gateway.
## Différences entre les intégrations de proxy Lambda entre le mode de transfert de réponse en flux et le mode de transfert de réponse en mémoire tampon
La liste suivante décrit les différences entre une intégration de proxy Lambda et une intégration de proxy Lambda pour le streaming de réponses :
+ API Gateway utilise l'[InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)API pour appeler l'intégration du proxy Lambda pour le streaming des réponses. Il en résulte un URI différent, qui est le suivant :
```
arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations
```
Cet ARN utilise une date différente pour la version de l'API et une action de service différente par rapport à l'intégration du proxy Lambda.
Si vous utilisez la console API Gateway pour le streaming des réponses, la console utilise l'URI qui vous convient.
+ Dans le cadre d'une intégration de proxy Lambda, API Gateway envoie la réponse au client uniquement après avoir reçu la réponse complète de Lambda. Dans le cadre d'une intégration de proxy Lambda pour le streaming des réponses, API Gateway lance le flux de charge utile après avoir reçu les métadonnées et le délimiteur valides de Lambda.
+ L'intégration du proxy Lambda pour le streaming des réponses utilise le même format d'entrée que l'intégration du proxy, mais elle nécessite un format de sortie différent.
## Format d'intégration du proxy Lambda pour le streaming des réponses
Lorsqu'API Gateway invoque une fonction Lambda avec flux de réponse, le format d'entrée est le même que celui d'une fonction Lambda pour l'intégration de proxy. Pour de plus amples informations, veuillez consulter [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format).
Lorsque Lambda diffuse une réponse à API Gateway, la réponse doit respecter le format suivant. Ce format utilise un délimiteur pour séparer les métadonnées JSON de la charge utile brute. Dans ce cas, les données de charge utile sont diffusées telles qu'elles sont transmises par votre fonction Lambda de streaming :
```
{
"headers": {"headerName": "headerValue", ...},
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"cookies" : ["cookie1", "cookie2"],
"statusCode": httpStatusCode
}PAYLOAD1 | PAYLOAD2 | PAYLOAD3
```
Dans la sortie :
+ Les `statusCode` touches `headers``multiValueHeaders`,`cookies`, et peuvent ne pas être spécifiées si aucun en-tête de réponse supplémentaire ne doit être renvoyé.
+ La clé `headers` ne peut contenir que des en-têtes à valeur unique.
+ La sortie s'attend à ce que les en-têtes contiennent l'un `Transfer-Encoding: chunked` ou `Content-length: number` l'autre. Si votre fonction ne renvoie aucun de ces en-têtes, API Gateway les ajoute `Transfer-Encoding: chunked` à l'en-tête de réponse.
+ La clé `multiValueHeaders` peut contenir des en-têtes à valeurs multiples, ainsi que des en-têtes à valeur unique. Vous pouvez utiliser la clé `multiValueHeaders` pour spécifier l’ensemble de vos en-têtes supplémentaires, y compris n’importe quel en-tête à valeur unique.
+ Si vous spécifiez des valeurs pour `headers` et `multiValueHeaders`, API Gateway les fusionne en une seule liste. Si la même paire clé-valeur est spécifiée dans les deux, seules les valeurs de `multiValueHeaders` s’afficheront dans la liste fusionnée.
+ Les métadonnées doivent être au format JSON valide. Seulement `headers``multiValueHeaders`, `cookies` et les `statusCode` touches sont prises en charge.
+ Vous devez fournir un délimiteur après le JSON des métadonnées. Le délimiteur doit être de 8 octets nuls et doit apparaître dans les 16 premiers Ko de données de flux.
+ API Gateway ne nécessite pas de format spécifique pour la charge utile de réponse de la méthode.
Si vous utilisez une URL de fonction pour diffuser votre fonction Lambda, vous devez modifier l'entrée et la sortie de votre fonction Lambda pour répondre à ces exigences.
Si la sortie de votre fonction Lambda ne répond pas aux exigences de ce format, API Gateway peut toujours appeler votre fonction Lambda. Le tableau suivant présente les combinaisons de paramètres de demande d'intégration d'API et de code de fonction Lambda pris en charge par API Gateway. Cela inclut les combinaisons prises en charge pour le mode de transfert des réponses en mode tampon.
| Mode de transfert de réponse | Le code de fonction est conforme au format requis | API d'appel Lambda | Pris en charge par API Gateway |
| --- | --- | --- | --- |
| Flux | Oui | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Oui. API Gateway diffuse votre réponse. |
| Flux | Non | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Non API Gateway appelle votre fonction Lambda et renvoie une réponse d'erreur de 500. |
| Flux | Oui | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Non API Gateway ne prend pas en charge cette configuration d'intégration. |
| Flux | Non | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Non API Gateway ne prend pas en charge cette configuration d'intégration. |
| Mis en mémoire tampon | Oui | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Non API Gateway ne prend pas en charge cette configuration d'intégration. |
| Mis en mémoire tampon | Non | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Non API Gateway ne prend pas en charge cette configuration d'intégration. |
| Mis en mémoire tampon | Oui | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway renvoie les en-têtes HTTP et le code d'état, mais pas le corps de la réponse. |
| Mis en mémoire tampon | Non | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Oui. Il s'agit d'une intégration de proxy Lambda. Pour plus d'informations, consultez la section Intégration du [proxy Lambda](set-up-lambda-proxy-integrations.md). |
# Configuration d'une intégration de proxy Lambda avec le streaming des réponses de charge utile dans API Gateway
Lorsque vous configurez le streaming de la charge utile de réponse, vous spécifiez le mode de transfert dans la demande d'intégration de votre ressource. Vous configurez ces paramètres dans la demande d'intégration pour contrôler le comportement d'API Gateway avant et pendant la réponse d'intégration.
## Exemples de fonctions Lambda pour le streaming des réponses
Votre fonction Lambda doit respecter le. [Format d'intégration du proxy Lambda pour le streaming des réponses](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format) Nous vous recommandons d'utiliser l'un des trois exemples de fonctions Lambda pour tester le streaming des réponses. Lorsque vous créez votre fonction Lambda, veillez à effectuer les opérations suivantes :
+ Prévoyez un délai d'attente suffisant pour votre fonction. Nous vous recommandons de configurer un délai d'au moins 1 minute pour en savoir plus sur le streaming des réponses. Lorsque vous créez vos ressources de production, assurez-vous que le délai d'expiration de votre fonction Lambda couvre l'ensemble du cycle de demande. Pour plus d'informations, voir [Configurer le délai d'expiration de la fonction Lambda.](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)
+ Utilisez le dernier moteur d'exécution de Node.js.
+ Utilisez une région dans laquelle le streaming des réponses Lambda est disponible.
------
#### [ Using HttpResponseStream.from ]
L'exemple de code suivant renvoie les objets de métadonnées JSON et les charges utiles au client à l'aide de la `awslambda.HttpResponseStream()` méthode sans utiliser la méthode du pipeline. Il n'est pas nécessaire de créer le délimiteur. Pour plus d'informations, consultez la section [Écrire des fonctions Lambda compatibles avec le streaming des réponses](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html).
```
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
"statusCode": 200,
"headers": {
"x-foo": "bar"
},
"multiValueHeaders": {
"x-mv1": ["hello", "world"],
"Set-Cookie": ["c1=blue", "c2=red"]
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("First payload ");
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("Final payload");
responseStream.end();
});
```
------
#### [ Using the pipeline method ]
Lambda recommande que lorsque vous écrivez des fonctions activées pour le streaming de réponses, vous utilisiez le `awslambda.streamifyResponse()` décorateur fourni par les environnements d'exécution natifs de Node.js, ainsi que la méthode. `pipeline()` Lorsque vous utilisez la méthode du pipeline, vous n'avez pas besoin de créer le délimiteur, Lambda le fait pour vous. Pour plus d'informations, consultez la section [Écrire des fonctions Lambda compatibles avec le streaming des réponses](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html).
L'exemple de code suivant renvoie les objets de métadonnées JSON et trois charges utiles au client.
```
import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
statusCode: 200,
headers: {
"Content-Type": "text/plain",
"X-Custom-Header": "Example-Custom-Header"
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
const dataStream = Readable.from(async function* () {
yield "FIRST payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "SECOND payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "THIRD payload\n";
await new Promise(r => setTimeout(r, 1000));
}());
await pipeline(dataStream, responseStream);
}
);
```
------
#### [ Without using the pipeline method ]
L'exemple de code suivant renvoie les objets de métadonnées JSON et trois charges utiles au client sans utiliser la `awslambda.HttpResponseStream()` méthode. Sans `awslambda.HttpResponseStream()` cette méthode, vous devez inclure un délimiteur de 8 octets nuls entre les métadonnées et la charge utile.
```
export const handler = awslambda.streamifyResponse(async (event, response, ctx) => {
response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}');
response.write("\x00".repeat(8)); // DELIMITER
await new Promise(r => setTimeout(r, 1000));
response.write("FIRST payload");
await new Promise(r => setTimeout(r, 1000));
response.write("SECOND payload");
await new Promise(r => setTimeout(r, 1000));
response.write("FINAL payload");
response.end();
});
```
------
## Création d'une intégration de proxy Lambda avec diffusion en continu de la réponse à la charge utile
La procédure suivante montre comment créer une intégration de proxy Lambda avec le streaming de réponse de charge utile. Utilisez l'exemple de fonction Lambda ou créez la vôtre.
------
#### [ AWS Management Console ]
**Pour créer une intégration de proxy Lambda avec le streaming de réponse à la charge utile**
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 REST.
1. Choisissez **Créer une ressource**.
1. Sous **Resource Name (Nom de la ressource)**, entrez **streaming**.
1. Choisissez **Créer une ressource**.
1. Lorsque la ressource **/streaming** est sélectionnée, choisissez **Create method**.
1. Pour **Type de méthode**, choisissez **ANY**.
1. Pour **Type d’intégration**, choisissez **Lambda**.
1. Choisissez l'intégration du **proxy Lambda**.
1. Pour le **mode de transfert Response**, choisissez **Stream**.
1. Pour la **fonction Lambda**, choisissez le nom de votre fonction Lambda.
La console API Gateway utilise automatiquement [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)l'API pour appeler la fonction Lambda. Vous êtes responsable de l'écriture d'une fonction Lambda compatible avec le streaming des réponses. Pour obtenir un exemple, consultez [Exemples de fonctions Lambda pour le streaming des réponses](#response-streaming-lambda-example).
1. Choisissez **Créer une méthode**.
Après avoir créé votre méthode, déployez votre API.
**Pour déployer votre API**
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Pour **Étape**, sélectionnez **Nouvelle étape**.
1. Sous **Stage name (Nom de l’étape)**, entrez **prod**.
1. (Facultatif) Sous **Description**, entrez une description.
1. Choisissez **Déployer**.
------
#### [ AWS CLI ]
La procédure suivante explique comment importer une nouvelle API avec la valeur `responseTransferMode` définie sur`STREAM`. Si vous disposez d'une API d'intégration existante et que vous souhaitez la modifier`responseTransferMode`, consultez[Mettre à jour le mode de transfert des réponses pour une intégration de proxy Lambda](#response-streaming-lambda-update).
**Pour créer une nouvelle API avec diffusion en continu de la réponse à la charge utile**
1. Copiez le fichier Open API suivant, puis enregistrez-le sous`ResponseStreamDemoSwagger.yaml`. Dans ce fichier, `responseTransferMode` est défini sur`STREAM`, et l'URI d'intégration est défini sur`arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`.
Remplacez le nom de la fonction par une fonction compatible `my-function` avec le streaming et remplacez les informations d'identification par un rôle IAM doté de politiques permettant au `apigateway` service d'invoquer des fonctions Lambda.
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/lambda:
get:
x-amazon-apigateway-integration:
httpMethod: "POST"
uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations"
type: "aws_proxy"
timeoutInMillis: 90000
responseTransferMode: "STREAM"
credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role"
```
Au lieu de fournir un rôle IAM pour les informations d'identification, vous pouvez utiliser la `add-permission` commande Lambda pour ajouter des autorisations basées sur les ressources.
1. Utilisez la `import-rest-api` commande suivante pour importer votre définition OpenAPI :
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. Utilisez la `create-deployment` commande suivante pour déployer votre nouvelle API sur une étape :
```
aws apigateway create-deployment \
--rest-api-id a1b2c2 \
--stage-name prod \
--region us-west-1
```
------
### Mettre à jour le mode de transfert des réponses pour une intégration de proxy Lambda
La procédure suivante montre comment mettre à jour le mode de transfert des réponses pour une intégration de proxy Lambda. Lorsque vous passez du mode de transfert des réponses au streaming, mettez à jour votre fonction Lambda afin qu'elle soit conforme aux exigences du streaming des réponses. Utilisez l'exemple de fonction Lambda ou créez la vôtre.
------
#### [ AWS Management Console ]
**Pour mettre à jour le mode de transfert des réponses pour une intégration de proxy Lambda**
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 REST.
1. Choisissez une méthode.
1. Dans l’onglet **Requête d’intégration**, sous **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Pour le **mode de transfert Response**, choisissez **Stream**.
1. Pour la **fonction Lambda**, choisissez le nom de votre fonction Lambda.
1. Choisissez **Enregistrer**.
Après avoir mis à jour votre méthode, déployez votre API.
**Pour déployer votre API**
1. Sélectionnez **Deploy API (Déployer une API)**.
1. Pour **Étape**, sélectionnez **Nouvelle étape**.
1. Sous **Stage name (Nom de l’étape)**, entrez **prod**.
1. (Facultatif) Sous **Description**, entrez une description.
1. Choisissez **Déployer**.
------
#### [ AWS CLI ]
1. Mettez à jour votre fonction Lambda pour qu'elle soit compatible avec le streaming.
1. Utilisez la AWS CLI commande suivante pour mettre à jour l'URI d'intégration et le mode de transfert des réponses de votre intégration :
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method ANY \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \
--region us-west-1
```
1. Redéployez l’API pour que les modifications prennent effet.
------
# Résoudre les problèmes liés au streaming des réponses dans API Gateway
Les conseils de dépannage suivants peuvent vous aider à résoudre les problèmes liés à APIs l'utilisation du streaming de réponses.
## Résolution de problème généraux
Vous pouvez utiliser l'onglet de test [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html)ou l'onglet de test de la console pour tester la réponse de votre stream. Les considérations suivantes peuvent avoir un impact sur votre utilisation de test invoke pour le streaming des réponses :
+ Lorsque vous testez votre méthode, API Gateway met en mémoire tampon votre charge utile de réponse diffusée en continu. Une fois que l'une des conditions suivantes est remplie, API Gateway renvoie une réponse unique contenant la charge utile mise en mémoire tampon :
+ La demande est complète
+ 35 secondes se sont écoulées
+ Plus de 1 Mo de charge utile de réponse ont été mis en mémoire tampon
+ Si plus de 35 secondes s'écoulent avant que votre méthode ne renvoie un statut de réponse HTTP et tous les en-têtes, le statut de réponse renvoyé est 0. TestInvokeMethod
+ API Gateway ne produit aucun journal d'exécution.
Après avoir déployé votre API, vous pouvez tester la réponse de votre flux à l'aide d'une commande curl. Nous vous recommandons d'utiliser l'`-i`option permettant d'inclure les en-têtes de réponse du protocole dans la sortie. Pour voir les données de réponse telles qu'elles arrivent, utilisez l'option curl `--no-buffer`
## Résoudre les erreurs cURL
Si vous testez une intégration et que vous recevez le message d'erreur`curl: (18) transfer closed with outstanding read data remaining`, assurez-vous que le délai d'expiration de votre intégration est suffisamment long. Si vous utilisez une fonction Lambda, vous devez mettre à jour le délai de réponse de la fonction Lambda. Pour plus d'informations, voir [Configurer le délai d'expiration de la fonction Lambda.](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)
## Résoudre les problèmes liés à la journalisation des accès
Vous pouvez utiliser les journaux d'accès pour votre stage d'API REST afin de consigner et de dépanner votre flux de réponses. Outre les variables existantes, vous pouvez utiliser les variables du journal d'accès suivantes :
`$context.integration.responseTransferMode`
Le mode de transfert des réponses de votre intégration. Il peut correspondre à `BUFFERED` ou `STREAMED`.
`$context.integration.timeToAllHeaders`
Le délai entre le moment où API Gateway établit la connexion d'intégration et le moment où il reçoit tous les en-têtes de réponse d'intégration du client.
`$context.integration.timeToFirstContent`
Le délai entre le moment où API Gateway établit la connexion d'intégration et le moment où il reçoit les premiers octets de contenu.
`$context.integration.latency` ou `$context.integrationLatency`
L'heure à laquelle API Gateway établit la connexion d'intégration jusqu'à ce que le flux de réponse d'intégration soit terminé.
La figure suivante montre comment ces variables du journal d'accès représentent les différents composants d'un flux de réponses.
![\[Variables du journal d'accès pour le streaming des réponses dans API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/response-streaming-figure.png)
Pour plus d’informations sur les journaux d’accès, consultez [Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway](set-up-logging.md). Vous pouvez également utiliser X-Ray pour surveiller votre flux de réponses. Pour de plus amples informations, veuillez consulter [Suivi des demandes des utilisateurs adressées aux API REST à l’aide de X-Ray dans API Gateway](apigateway-xray.md).
# Intégrations privées pour REST APIs dans API Gateway
Utilisez une intégration privée pour exposer vos HTTP/HTTPS ressources au sein d'un Amazon VPC afin que des clients extérieurs au VPC puissent y accéder. Cela étend l'accès à vos ressources VPC privées au-delà des limites du VPC. Vous pouvez contrôler l’accès à votre API à l’aide de n’importe quelle [méthode d’autorisation](apigateway-control-access-to-api.md) prise en charge par API Gateway.
Pour créer une intégration privée, vous devez d’abord créer un lien VPC. API Gateway prend en charge les liens VPC V2 pour REST. APIs Les liens VPC V2 vous permettent de créer des intégrations privées qui connectent votre API REST aux équilibreurs de charge d'application sans utiliser de Network Load Balancer. L'utilisation d'un Application Load Balancer vous permet de vous connecter à des applications ECSs basées sur des conteneurs Amazon et à de nombreux autres backends. Les liens VPC V1 sont considérés comme un type d'intégration traditionnel. Bien qu'ils soient pris en charge par API Gateway, nous vous recommandons de ne pas créer de nouveaux liens VPC V1.
## 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, le lien VPC et l'API REST.
+ Par défaut, le trafic d’intégration privée utilise le protocole HTTP. Pour utiliser le protocole HTTPS, [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)spécifiez un nom de serveur sécurisé, tel que`https://example.com:443/test`.
+ Dans le cas d'une intégration privée, API Gateway inclut la partie [étape](set-up-stages.md) du point de terminaison de l'API dans la demande adressée à vos ressources principales. Par exemple, si vous demandez l'`test`étape d'une API, API Gateway inclut `test/path` dans la demande votre intégration privée. Pour supprimer le nom de l'étape de la demande adressée à vos ressources principales, utilisez le [mappage des paramètres](rest-api-parameter-mapping.md) pour créer une substitution pour la `$context.requestOverride.path` variable.
+ Les intégrations privées avec AWS Cloud Map ne sont pas prises en charge.
**Topics**
+ [
## Considérations
](#private-integrations-considerations)
+ [
# Configuration des liens VPC V2 dans API Gateway
](apigateway-vpc-links-v2.md)
+ [
# Configurez une intégration privée
](set-up-private-integration.md)
+ [
# Intégration privée à l'aide de liaisons VPC V1 (ancienne version)
](vpc-links-v1.md)
# Configuration des liens VPC V2 dans API Gateway
Les liens VPC vous permettent de créer des intégrations privées qui connectent vos routes d'API aux ressources privées d'un VPC, telles que les équilibreurs de charge d'application ou les applications basées sur des conteneurs Amazon ECS. Une intégration privée utilise un lien VPC V2 pour encapsuler les connexions entre API Gateway et les ressources VPC ciblées. Vous pouvez réutiliser les liens VPC entre différentes ressources et. APIs
Lorsque vous créez un lien VPC, API Gateway crée et gère des [interfaces réseau élastiques](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) pour le lien VPC V2 de votre compte. Ce processus peut prendre quelques minutes. Lorsqu'une liaison VPC V2 est prête à être utilisée, son état passe de `PENDING` à. `AVAILABLE`
**Note**
Si aucun trafic n’est envoyé sur le lien VPC pendant 60 jours, il devient `INACTIVE`. Lorsqu’un lien VPC atteint l’état `INACTIVE`, API Gateway supprime toutes les interfaces réseau du lien VPC. Cela provoque l’échec des demandes d’API qui dépendent du lien VPC. Si les demandes d’API reprennent, API Gateway provisionne à nouveau les interfaces réseau. La création des interfaces réseau et la réactivation du lien VPC peut prendre quelques minutes. Vous pouvez utiliser l’état du lien VPC pour surveiller l’état de votre lien VPC.
## Créez un lien VPC V2 à l'aide du AWS CLI
Pour créer un lien VPC V2, toutes les ressources impliquées doivent appartenir au même AWS compte. La [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html)commande suivante crée un lien VPC :
```
aws apigatewayv2 create-vpc-link --name MyVpcLink \
--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678
```
**Note**
Les liens VPC V2 sont immuables. Après avoir créé un lien VPC V2, vous ne pouvez pas modifier ses sous-réseaux ou ses groupes de sécurité.
## Supprimez un lien VPC V2 à l'aide du AWS CLI
La [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html)commande suivante supprime un lien VPC.
```
aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123
```
## Disponibilité par région
Les liaisons VPC V2 sont prises en charge dans les régions et zones de disponibilité suivantes :
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/apigateway-vpc-links-v2.html)
# Configurez une intégration privée
Pour créer une intégration privée avec un Application Load Balancer ou un Network Load Balancer, vous devez créer une intégration de proxy HTTP, spécifier le [lien VPC V2](apigateway-vpc-links-v2.md) à utiliser et fournir l'ARN d'un Network Load Balancer ou d'un Application Load Balancer. Par défaut, le trafic d’intégration privée utilise le protocole HTTP. Pour utiliser le protocole HTTPS, [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)spécifiez un nom de serveur sécurisé, tel que`https://example.com:443/test`. Pour un didacticiel complet sur la création d'une API REST avec une intégration privée, consultez[Didacticiel : création d’une API REST avec une intégration privée](getting-started-with-private-integration.md).
## Création d’une intégration privée
La procédure suivante montre comment créer une intégration privée qui se connecte à un équilibreur de charge à l'aide d'un lien VPC V2.
------
#### [ AWS Management Console ]
Pour un didacticiel sur la création d'une intégration privée, voir,[Didacticiel : création d’une API REST avec une intégration privée](getting-started-with-private-integration.md).
------
#### [ AWS CLI ]
La commande [put-integration suivante crée une intégration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) privée qui se connecte à un équilibreur de charge à l'aide d'un lien VPC V2 :
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id bbb111
```
Au lieu de fournir directement l'ID de connexion, vous pouvez utiliser une variable d'étape à la place. Lorsque vous déployez votre API sur une étape, vous définissez l'ID VPC link V2. La commande [put-integration suivante crée une intégration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) privée à l'aide d'une variable d'étape pour l'ID VPC link V2 :
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkV2Id}"
```
Assurez-vous de mettre entre guillemets l'expression de la variable d'étape (\$1 \$1StageVariables.VPClinkV2ID\$1) et d'éviter le caractère \$1.
------
#### [ OpenAPI ]
Vous pouvez configurer une API avec l’intégration privée via l’importation de fichier d’API OpenAPI. Les paramètres sont similaires aux définitions OpenAPI d’une API avec des intégrations HTTP, à l’exception des points suivants :
+ Vous devez explicitement définir `connectionType` sur `VPC_LINK`.
+ Vous devez définir explicitement `connectionId` sur l’ID d’un `VpcLinkV2` ou d’une variable d’étape renvoyant à l’ID d’un `VpcLinkV2`.
+ Le `uri` paramètre de l'intégration privée pointe vers un HTTP/HTTPS point de terminaison dans le VPC, mais il est utilisé à la place pour configurer l'en-tête de la demande d'`Host`intégration.
+ Le paramètre `uri` de l’intégration privée avec un point de terminaison HTTPS dans le VPC est utilisé pour vérifier le nom de domaine par rapport à celui indiqué dans le certificat installé sur le point de terminaison du VPC.
Vous pouvez utiliser une variable d’étape pour référencer l’ID du `VpcLinkV2`. Vous pouvez également attribuer la valeur d’ID directement à `connectionId`.
Le fichier d’API OpenAPI au format JSON suivant montre un exemple de fichier de lien VPC référencé par une variable d’étape (`${stageVariables.vpcLinkIdV2}`) :
```
{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLinkV2"
},
"host": "abcdef123.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "https://example.com:443/path",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkV2Id}",
"integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Mettre à jour une intégration privée
L'exemple suivant met à jour le lien VPC V2 pour une intégration privée.
------
#### [ AWS Management Console ]
**Pour mettre à jour une intégration privée**
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 REST avec une intégration privée.
1. Choisissez la ressource et la méthode qui utilisent une intégration privée.
1. Dans l’onglet **Requête d’intégration**, sous **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Vous pouvez modifier les paramètres de votre intégration privée. Si vous utilisez actuellement un lien VPC V1, vous pouvez remplacer votre lien VPC par un lien VPC V2.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ AWS CLI ]
La commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) suivante met à jour une intégration privée pour utiliser un lien VPC V2 :
```
aws apigateway update-integration \
--rest-api-id a1b2c3d4e5 \
--resource-id a1b2c3 \
--http-method GET \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]"
```
------
# Intégration privée à l'aide de liaisons VPC V1 (ancienne version)
**Note**
L'implémentation suivante des intégrations privées utilise les liaisons VPC V1. Les liens VPC V1 sont des ressources héritées. Nous vous recommandons d'utiliser les [liens VPC V2 pour REST](apigateway-vpc-links-v2.md). APIs
Pour créer une intégration privée, vous devez d’abord créer un Network Load Balancer. Votre Network Load Balancer doit disposer d’un [écouteur](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) qui achemine les demandes vers les ressources de votre VPC. Afin d’améliorer la disponibilité de votre API, assurez-vous que votre Network Load Balancer achemine le trafic vers des ressources dans plusieurs zones de disponibilité dans le Région AWS. Ensuite, vous créez un lien VPC que vous utilisez pour connecter votre API et votre Network Load Balancer. Après avoir créé une liaison VPC, vous créez des intégrations privées pour acheminer le trafic de votre API vers les ressources de votre VPC via votre liaison VPC et votre Network Load Balancer. Le Network Load Balancer et l'API doivent appartenir à la même entité. Compte AWS
**Topics**
+ [
# Configuration d'un Network Load Balancer pour les intégrations privées d'API Gateway (ancienne version)
](set-up-nlb-for-vpclink-using-console.md)
+ [
# Accorder des autorisations à API Gateway pour créer un lien VPC (ancien)
](grant-permissions-to-create-vpclink.md)
+ [
# Configurez une API API Gateway avec des intégrations privées à l'aide de l' AWS CLI (ancienne)
](set-up-api-with-vpclink-cli.md)
+ [
# Comptes API Gateway utilisés pour les intégrations privées (anciens)
](set-up-api-with-vpclink-accounts.md)
# Configuration d'un Network Load Balancer pour les intégrations privées d'API Gateway (ancienne version)
**Note**
L'implémentation suivante des intégrations privées utilise les liaisons VPC V1. Les liens VPC V1 sont des ressources héritées. Nous vous recommandons d'utiliser les [liens VPC V2 pour REST](apigateway-vpc-links-v2.md). APIs
La procédure suivante décrit les étapes de configuration d’un équilibreur Network Load Balancer (NLB) pour les intégrations privées API Gateway à l’aide de la console Amazon EC2, et fournit des références renvoyant à des instructions détaillées pour chaque étape.
Pour chaque VPC dans lequel vous avez des ressources, il vous suffit de configurer un NLB et un autre. VPCLink L’équilibreur NLB prend en charge plusieurs [écouteurs](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) et [groupes cibles](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html) par équilibreur NLB. Vous pouvez configurer chaque service en tant qu'écouteur spécifique sur le NLB et utiliser un seul VPCLink pour vous connecter au NLB. Lors de la création de l’intégration privée dans API Gateway, vous définissez chaque service à l’aide du port spécifique qui a été attribué à chaque service. Pour de plus amples informations, veuillez consulter [Didacticiel : création d’une API REST avec une intégration privée](getting-started-with-private-integration.md). Le Network Load Balancer et l'API doivent appartenir à la même entité. Compte AWS
**Pour créer un Network Load Balancer pour une intégration privée à l’aide de la console API Gateway**
1. Connectez-vous à la console Amazon EC2 AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)
1. Configurez un serveur web sur une instance Amazon EC2. Pour voir un exemple de configuration, consultez [Installing a LAMP Web Server on Amazon Linux 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html) (Installation d’un serveur web LAMP sur Amazon Linux 2).
1. Créez un équilibreur Network Load Balancer, enregistrez l’instance EC2 auprès d’un groupe cible et ajoutez le groupe cible à un écouteur de l’équilibreur Network Load Balancer. Pour plus d’informations, suivez les instructions fournies dans la section [Premiers pas avec les équilibreurs Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html).
1. Une fois que l’équilibreur Network Load Balancer est créé, procédez de la façon suivante :
1. Notez l’ARN de l’équilibreur Network Load Balancer. Vous en aurez besoin pour créer un lien VPC dans API Gateway pour intégrer l’API aux ressources VPC derrière l’équilibreur Network Load Balancer.
1. Désactiver l'évaluation des groupes de sécurité pour PrivateLink.
+ Pour désactiver l'évaluation des groupes de sécurité pour le PrivateLink trafic à l'aide de la console, vous pouvez choisir l'onglet **Sécurité**, puis **Modifier**. Dans les **paramètres de sécurité**, décochez **Appliquer les règles de trafic entrant au PrivateLink trafic**.
+ Utilisez la [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html)commande suivante pour désactiver l'évaluation des groupes de sécurité pour PrivateLink le trafic :
```
aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \
--security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off
```
**Note**
N'ajoutez aucune dépendance à API Gateway CIDRs car elles sont susceptibles de changer sans préavis.
# Accorder des autorisations à API Gateway pour créer un lien VPC (ancien)
**Note**
L'implémentation suivante des intégrations privées utilise les liaisons VPC V1. Les liens VPC V1 sont des ressources héritées. Nous vous recommandons d'utiliser les [liens VPC V2 pour REST](apigateway-vpc-links-v2.md). APIs
Pour que vous ou un utilisateur de votre compte puissiez créer et gérer un lien VPC, vous devez disposer des autorisations requises pour créer, supprimer et afficher les configurations de service du point de terminaison du VPC, modifier ses autorisations de service et examiner les équilibreurs de charge. Pour accorder ces autorisations, suivez la procédure ci-dessous.
**Pour accorder des autorisations afin de créer, mettre à jour et supprimer un lien VPC**
1. Créez une politique IAM semblable à celle-ci :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:GET",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/vpclinks",
"arn:aws:apigateway:us-east-1::/vpclinks/*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource": "*"
}
]
}
```
------
Si vous souhaitez activer le balisage pour votre lien VPC, veillez à autoriser les opérations de balisage. Pour de plus amples informations, veuillez consulter [Autoriser les opérations de balisage](apigateway-tagging-iam-policy.md#allow-tagging).
1. Créez ou choisissez un rôle IAM et attachez-y la politique précédente.
1. Attribuez le rôle IAM à vous-même ou à un utilisateur de votre compte qui crée des liens VPC.
# Configurez une API API Gateway avec des intégrations privées à l'aide de l' AWS CLI (ancienne)
**Note**
L'implémentation suivante des intégrations privées utilise les liaisons VPC V1. Les liens VPC V1 sont des ressources héritées. Nous vous recommandons d'utiliser les [liens VPC V2 pour REST](apigateway-vpc-links-v2.md). APIs
Le didacticiel suivant montre comment utiliser le AWS CLI pour créer un lien VPC et une intégration privée. Les conditions préalables suivantes sont requises :
+ Vous avez besoin d’un équilibreur Network Load Balancer créé et configuré avec votre VPC source comme cible. Pour de plus amples informations, veuillez consulter [Configuration d'un Network Load Balancer pour les intégrations privées d'API Gateway (ancienne version)](set-up-nlb-for-vpclink-using-console.md). Il doit se trouver dans le même Compte AWS emplacement que votre API. Vous avez besoin de l’ARN de votre équilibreur Network Load Balancer pour créer votre lien VPC.
+ Pour créer et gérer un `VpcLink`, vous devez disposer des autorisations pour créer un `VpcLink` dans votre API. Vous n’avez pas besoin d’autorisations pour utiliser le `VpcLink`. Pour de plus amples informations, veuillez consulter [Accorder des autorisations à API Gateway pour créer un lien VPC (ancien)](grant-permissions-to-create-vpclink.md).
**Pour configurer une API avec l'intégration privée à l'aide de AWS CLI**
1. Utilisez la [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html)commande suivante pour créer un `VpcLink` ciblage du Network Load Balancer spécifié :
```
aws apigateway create-vpc-link \
--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef
```
La sortie de cette commande accuse réception de la requête et indique l’état `PENDING` de la création de `VpcLink`.
```
{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}
```
La création du `VpcLink` par API Gateway prend entre 2 et 4 minutes. Lorsque l’opération se termine correctement, l’attribut `status` indique `AVAILABLE`. Vous pouvez le vérifier à l'aide de la [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html)commande suivante :
```
aws apigateway get-vpc-link --vpc-link-id gim7c3
```
Si l’opération échoue, vous obtenez le statut `FAILED` et un message d’erreur sous `statusMessage`. Par exemple, si vous tentez de créer un `VpcLink` avec un équilibreur Network Load Balancer qui est déjà associé au point de terminaison du VPC, vous obtenez le message suivant au niveau de la propriété `statusMessage` :
```
"NLB is already associated with another VPC Endpoint Service"
```
Une fois la création du `VpcLink` réussie, vous pouvez créer une API et l’intégrer avec la ressource VPC par le biais du `VpcLink`.
Notez la valeur `id` du `VpcLink` que vous venez de créer. Dans cet exemple de sortie, il s’agit de `gim7c3`. Vous en aurez besoin pour configurer l’intégration privée.
1. Utilisez la [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante pour créer une [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource API Gateway :
```
aws apigateway create-rest-api --name 'My VPC Link Test'
```
Notez la valeur `id` de `RestApi` et la valeur `rootResourceId` de `RestApi` dans le résultat renvoyé. Vous avez besoin de cette valeur pour effectuer d’autres opérations sur l’API.
Ensuite, vous allez créer une API avec seulement une méthode `GET` sur la ressource racine (`/`) et intégrer la méthode avec le `VpcLink`.
1. Utilisez la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante pour créer la méthode `GET /` :
```
aws apigateway put-method \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"
```
Si vous n’utilisez pas l’intégration proxy avec le `VpcLink`, vous devez également configurer au moins une réponse de méthode avec le code de statut `200`. Vous allez utiliser l’intégration proxy ici.
1. Après avoir créé la méthode `GET /`, vous devez configurer l’intégration. Pour une intégration privée, vous devez utiliser le paramètre `connection-id` pour fournir l’ID `VpcLink`. Vous pouvez utiliser une variable d’étape ou saisir directement l’ID du `VpcLink`. Le paramètre `uri` n’est pas utilisé pour l’acheminement des demandes au point de terminaison, mais pour définir l’en-tête `Host` et pour la validation de certificat.
------
#### [ Use the VPC link ID ]
Utilisez la commande [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) suivante pour utiliser l’ID `VpcLink` directement dans l’intégration :
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3
```
------
#### [ Use a stage variable ]
Utilisez la commande [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) suivante afin d’utiliser une variable d’étape pour référencer l’ID du lien VPC. Lorsque vous déployez votre API dans une étape, vous devez définir l’ID du lien VPC.
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"
```
Assurez-vous de délimiter l’expression de la variable d’étape avec des guillemets droits (`${stageVariables.vpcLinkId}`) et d’y ajouter le caractère d’échappement `$`.
------
À tout moment, vous pouvez également mettre à jour l’intégration pour modifier `connection-id`. Utilisez la commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) suivante pour mettre à jour votre intégration :
```
aws apigateway update-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'
```
Assurez-vous d’utiliser une liste JSON obtenue à l’aide de stringify comme valeur du paramètre `patch-operations`.
Comme vous avez utilisé l’intégration proxy privée, votre API peut maintenant être déployée et testée.
1. Si vous avez utilisé la variable d’étape pour définir `connection-id`, vous devez déployer votre API pour la tester. Utilisez la commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) suivante pour déployer votre API avec une variable d’étape :
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name test \
--variables vpcLinkId=gim7c3
```
Pour mettre à jour la variable d’étape avec un autre ID `VpcLink` (par exemple, `asf9d7`), utilisez la commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) suivante :
```
aws apigateway update-stage \
--rest-api-id abcdef123 \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'
```
Lorsque vous codez en dur la propriété `connection-id` avec l’ID littéral `VpcLink`, vous n’avez pas besoin de déployer votre API pour la tester. Utilisez la [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html)commande pour tester votre API avant son déploiement.
1. Utilisez la commande suivante pour appeler votre API :
```
curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test
```
Vous pouvez également saisir l’URL d’invocation de votre API dans un navigateur web pour afficher le résultat.
# Comptes API Gateway utilisés pour les intégrations privées (anciens)
Les comptes API Gateway spécifiques à la région suivants IDs sont automatiquement ajoutés à votre service de point de terminaison VPC `AllowedPrincipals` lorsque vous créez un. `VpcLink`
| **Région** | **ID de compte** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap us-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
# Intégrations fictives pour REST APIs dans API Gateway
Amazon API Gateway prend en charge les intégrations simulées pour les méthodes API. Cette fonction permet aux développeurs d’API de générer des réponses d’API directement à partir d’API Gateway, sans nécessiter de backend d’intégration. En tant que développeur d’API, vous pouvez utiliser cette fonction pour débloquer les équipes dépendantes qui doivent utiliser une API avant la fin du développement du projet. Vous pouvez également utiliser cette fonction pour mettre en service une page de destination pour votre API, qui peut fournir une présentation de votre API et un accès à cette dernière. Pour obtenir un exemple de page de destination de ce type, consultez la demande et la réponse d’intégration de la méthode GET sur la ressource racine de l’exemple d’API présentées dans [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
En tant que développeur d’API, vous décidez de la façon dont API Gateway répond à une demande d’intégration simulée. Pour cela, vous configurez la demande d’intégration et la réponse d’intégration de la méthode pour associer une réponse à un code de statut donné. Pour une méthode avec l’intégration simulée permettant de renvoyer une réponse `200`, configurez le modèle de mappage du corps de la demande d’intégration pour qu’il renvoie ce qui suit.
```
{"statusCode": 200}
```
Configurer une réponse d’intégration `200` pour que le modèle de mappage de corps suivant, par exemple :
```
{
"statusCode": 200,
"message": "Go ahead without me."
}
```
De même, pour que la méthode renvoie, par exemple, une réponse d’erreur `500`, configurez le modèle de mappage du corps de la demande d’intégration pour qu’il renvoie ce qui suit.
```
{"statusCode": 500}
```
Configurer une réponse d’intégration `500` avec, par exemple, le modèle de mappage de corps suivant :
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
Sinon, vous pouvez obtenir qu’une méthode d’intégration simulée renvoie la réponse d’intégration par défaut sans définir le modèle de mappage de demande d’intégration. La réponse d’intégration par défaut correspond à celle ayant un statut de **HTTP status regex** non défini. Assurez-vous que les comportements de transfert appropriés sont définis.
**Note**
les intégrations simulées ne sont pas destinés à prendre en charge des modèles de réponse de grande taille. Si vous en avez besoin pour votre cas d’utilisation, vous devriez plutôt envisager d’utiliser une intégration Lambda.
À l’aide d’un modèle de mappage de demande d’intégration, vous pouvez injecter une logique d’application permettant de choisir la réponse d’intégration simulée à renvoyer selon certaines conditions. Par exemple, vous pouvez utiliser un paramètre de requête `scope` sur les demandes entrantes pour déterminer s’il faut renvoyer une réponse positive ou une réponse d’erreur :
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
Ainsi, la méthode de l’intégration simulée laisse passer les appels internes tout en rejetant d’autres types d’appels en renvoyant une réponse d’erreur.
Dans cette section, nous décrivons comment utiliser la console API Gateway pour activer l’intégration simulée d’une méthode d’API.
**Topics**
+ [
# Activation de l’intégration simulée à l’aide de la console API Gateway
](how-to-mock-integration-console.md)
# Activation de l’intégration simulée à l’aide de la console API Gateway
La méthode doit être disponible dans API Gateway. Suivez les instructions de la section [Didacticiel : création d’une API REST avec une intégration HTTP sans proxy](api-gateway-create-api-step-by-step.md).
1. Choisissez une ressource d’API et choisissez **Créer une méthode**.
Pour créer la méthode, procédez comme suit :
1. Pour **Type de méthode**, sélectionnez une méthode.
1. Pour **Type d’intégration**, sélectionnez **HTTP**.
1. Choisissez **Créer une méthode**.
1. Dans l’onglet **Requête de méthode**, pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **Paramètres de chaîne de requête d’URL**. Choisissez **Ajouter une chaîne de requête** et pour **Nom**, saisissez**scope**. Ce paramètre de requête permet de déterminer si l’appelant est interne ou autre.
1. Choisissez **Enregistrer**.
1. Dans l’onglet **Méthode de réponse**, choisissez **Créer une réponse**, puis procédez comme suit :
1. Pour **Statut HTTP**, saisissez **500**.
1. Choisissez **Enregistrer**.
1. Dans l’onglet **Demande d’intégration**, pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
1. Choisissez **Enregistrer**.
1. Dans l’onglet **Réponse d’intégration**, pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
{
"statusCode": 200,
"message": "Go ahead without me"
}
```
1. Choisissez **Enregistrer**.
1. Choisissez **Créer une réponse**.
Pour créer une réponse 500, procédez comme suit :
1. Pour **HTTP status regex (Regex statut HTTP)**, saisissez **5\$1d\$12\$1**.
1. Pour **Statut de la réponse de méthode**, sélectionnez **500**.
1. Choisissez **Enregistrer**.
1. Pour **5\$1d\$12\$1 - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis choisissez **Ajouter un modèle de mappage**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet. Pour tester votre intégration simulée, procédez comme suit :
1. Saisissez `scope=internal` sous **Chaînes de requête**. Sélectionnez **Test**. Le résultat de test indique :
```
Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body
{
"statusCode": 200,
"message": "Go ahead without me"
}
Response Headers
{"Content-Type":"application/json"}
```
1. Saisissez `scope=public` sous `Query strings` ou laissez le champ vide. Sélectionnez **Test**. Le résultat de test indique :
```
Request: /
Status: 500
Latency: 16 ms
Response Body
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
Response Headers
{"Content-Type":"application/json"}
```
Vous pouvez également renvoyer des en-têtes dans une réponse d’intégration simulée en ajoutant d’abord un en-tête à la réponse de méthode, puis en configurant un mappage d’en-tête d’intégration dans la réponse d’intégration. En fait, c’est ainsi que la console API Gateway permet à la prise en charge de CORS en renvoyant les en-têtes CORS requis.
# Demande de validation pour REST APIs dans API Gateway
Vous pouvez configurer API Gateway afin d’exécuter la validation de base d’une demande d’API avant de procéder à la demande d’intégration. Lorsque la validation échoue, API Gateway échoue immédiatement à la demande, renvoie une réponse d'erreur 400 à l'appelant et publie les résultats de la validation dans CloudWatch Logs. Cela permet de réduire les appels non nécessaires au backend. Qui plus est, il vous permet de vous concentrer sur les efforts de validation spécifiques à votre application. Vous pouvez valider un corps de demande en vérifiant que les paramètres de demande obligatoires sont valides et autres que null ou en indiquant un schéma de modèle pour la validation de données plus compliquées.
**Topics**
+ [
## Présentation de la validation de demande de base dans API Gateway
](#api-gateway-request-validation-basic-definitions)
+ [
# Modèles de données pour REST APIs
](models-mappings-models.md)
+ [
# Configuration de la validation de demande de base dans API Gateway
](api-gateway-request-validation-set-up.md)
+ [
# AWS CloudFormation modèle d'un exemple d'API avec validation de demande de base
](api-gateway-request-validation-sample-cloudformation.md)
## Présentation de la validation de demande de base dans API Gateway
API Gateway peut effectuer la validation de base des demandes, afin que vous puissiez vous concentrer sur la validation spécifique à l’application dans le backend. Pour la validation, API Gateway vérifie l’une ou l’ensemble des conditions suivantes :
+ Les paramètres de demande obligatoires dans l’URI, la chaîne de requête et les en-têtes d’une demande entrante sont inclus et non vides. API Gateway vérifie uniquement si un paramètre existe. Il ne vérifie ni son type ni son format.
+ Les données utiles de la demande adhère à la demande de [schéma JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) configurée de la méthode pour un type de contenu donné. Si aucun type de contenu correspondant n’est trouvé, la validation de demande n’est pas effectuée. Pour utiliser le même modèle quel que soit le type de contenu, définissez le type de contenu de votre modèle de données sur `$default`.
Pour activer la validation, vous indiquez des règles de validation dans un [validateur de demande](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html), vous ajoutez le validateur au [mappage des validateurs de demande](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) de l’API, puis vous affectez le validateur à des méthodes d’API individuelles.
**Note**
La validation du corps de la demande et les [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md) sont deux sujets distincts. Quand la charge utile d’une demande n’a pas de schéma de modèle correspondant, vous pouvez choisir de transmettre ou de bloquer la charge utile d’origine. Pour de plus amples informations, veuillez consulter [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
# Modèles de données pour REST APIs
Dans API Gateway, un modèle définit la structure de données d’une charge utile. Dans API Gateway, les modèles sont définis à l’aide du [schéma JSON version 4](https://tools.ietf.org/html/draft-zyp-json-schema-04). L’objet JSON suivant est un exemple de données figurant dans l’exemple d’animalerie.
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
Les données contiennent les éléments `id`, `type` et `price` de l’animal de compagnie. Un modèle de ces données vous permet de :
+ Utiliser la validation de base des demandes.
+ Créer des modèles de mappage pour la transformation des données.
+ Créer un type de données défini par l’utilisateur (UDT) lorsque vous générez un kit SDK.
![\[Exemple de modèle de données JSON pour PetStore l'API.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/how-to-validate-requests.png)
Dans ce modèle :
1. L’objet `$schema` représente un identifiant de version de schéma JSON valide. Ce schéma est le brouillon de schéma JSON version 4.
1. L’objet `title` est un identifiant du modèle lisible à l’œil. Ce titre est `PetStoreModel`.
1. Le mot clé de validation `required` requiert `type` et `price` pour la validation de base des demandes.
1. Les propriétés (`properties`) du modèle sont `id`, `type` et `price`. Chaque objet possède des propriétés qui sont décrites dans le modèle.
1. L’objet `type` ne peut avoir que les valeurs `dog`, `cat` ou `fish`.
1. L’objet `price` est un nombre limité entre un `minimum` de 25 et un `maximum` de 500.
## PetStore modèle
```
1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3 "title": "PetStoreModel",
4 "type" : "object",
5 "required" : [ "price", "type" ],
6 "properties" : {
7 "id" : {
8 "type" : "integer"
9 },
10 "type" : {
11 "type" : "string",
12 "enum" : [ "dog", "cat", "fish" ]
13 },
14 "price" : {
15 "type" : "number",
16 "minimum" : 25.0,
17 "maximum" : 500.0
18 }
19 }
20 }
```
Dans ce modèle :
1. Ligne 2, l’objet `$schema` représente un identifiant de version de schéma JSON valide. Ce schéma est le brouillon de schéma JSON version 4.
1. Ligne 3, l’objet `title` est un identifiant lisible du modèle. Ce titre est `PetStoreModel`.
1. Ligne 5, le mot clé de validation `required` requiert `type` et `price` pour la validation de base des demandes.
1. Lignes 6 à 17, les propriétés (`properties`) du modèle sont `id`, `type` et `price`. Chaque objet possède des propriétés qui sont décrites dans le modèle.
1. Ligne 12, l’objet `type` ne peut avoir que les valeurs `dog`, `cat` ou `fish`.
1. Lignes 14 à 17, l’objet `price` est un nombre limité entre un `minimum` de 25 et un `maximum` de 500.
## Création de modèles plus complexes
Vous pouvez utiliser la primitive `$ref` pour créer des définitions réutilisables pour des modèles plus longs. Par exemple, vous pouvez créer une définition appelée `Price` dans la section `definitions` décrivant l’objet `price`. La valeur de `$ref` est la définition `Price`.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReUsableRef",
"required" : ["price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "#/definitions/Price"
}
},
"definitions" : {
"Price": {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
Vous pouvez également référencer un autre schéma de modèle défini dans un fichier de modèle externe. Définissez la valeur de la propriété `$ref` en fonction de l’emplacement du modèle. Dans l’exemple suivant, le modèle `Price` est défini dans le modèle `PetStorePrice` dans l’API `a1234`.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStorePrice",
"type": "number",
"minimum": 25,
"maximum": 500
}
```
Le modèle le plus long peut référencer le modèle `PetStorePrice`.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReusableRefAPI",
"required" : [ "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
}
}
}
```
## Utilisation de modèles de données de sortie
Si vous transformez vos données, vous pouvez définir un modèle de charge utile dans la réponse d’intégration. Un modèle de charge utile peut être utilisé lorsque vous générez un kit SDK. Pour les langages fortement typés, comme Java, Objective-C ou Swift, l’objet correspond à un type de données défini par l’utilisateur (UDT). API Gateway crée un type UDT si vous lui fournissez un modèle de données lorsque vous générez un kit SDK. Pour plus d’informations sur les transformations de données, consultez [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
L’exemple suivant présente les données de sortie d’une réponse d’intégration.
```
{
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
}
```
L’exemple suivant est un modèle de données utiles qui décrit les données de sortie.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetStoreOutputModel",
"type" : "object",
"required" : [ "description", "askingPrice" ],
"properties" : {
"description" : {
"type" : "string"
},
"askingPrice" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
Avec ce modèle, vous pouvez appeler un kit SDK pour récupérer les valeurs des propriétés `description` et `askingPrice` en lisant les propriétés `PetStoreOutputModel[i].description` et `PetStoreOutputModel[i].askingPrice`. Si aucun modèle n’est fourni, API Gateway utilise le modèle vide pour créer un type UDT par défaut.
## Étapes suivantes
+ Cette section fournit des ressources que vous pouvez utiliser pour en apprendre davantage sur les concepts présentés dans cette rubrique.
Vous pouvez suivre les didacticiels de validation des demandes :
+ [Configuration la validation des demandes à l’aide de la console API Gateway](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
+ [Configurez la validation de base des demandes à l'aide du AWS CLI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
+ [Configuration de la validation de base des demandes à l’aide d’une définition OpenAPI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+ Pour plus d’informations sur la transformation des données et les modèles de mappage, consultez [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
# Configuration de la validation de demande de base dans API Gateway
Cette section explique comment configurer la validation des demandes pour API Gateway à l'aide de la console et d'une définition OpenAPI. AWS CLI
**Topics**
+ [
## Configuration la validation des demandes à l’aide de la console API Gateway
](#api-gateway-request-validation-setup-in-console)
+ [
## Configurez la validation de base des demandes à l'aide du AWS CLI
](#api-gateway-request-validation-setup-cli)
+ [
## Configuration de la validation de base des demandes à l’aide d’une définition OpenAPI
](#api-gateway-request-validation-setup-importing-swagger)
## Configuration la validation des demandes à l’aide de la console API Gateway
Vous pouvez utiliser la console API Gateway pour valider une demande en sélectionnant l’un des trois validateurs suivants pour une demande d’API :
+ **Valider le corps**.
+ **Valider les paramètres de chaîne de requête et les en-têtes**.
+ **Valider le corps et les paramètres et en-têtes des chaînes de requête**.
Lorsque vous appliquez l'un des validateurs à une méthode d'API, la console API Gateway ajoute le validateur à la carte de [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)l'API.
Pour suivre ce didacticiel, vous allez utiliser un CloudFormation modèle pour créer une API API Gateway incomplète. Cette API possède une ressource `/validator` avec les méthodes `GET` et `POST`. Ces deux méthodes sont intégrées avec le point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Vous allez configurer deux types de validation des demandes :
+ Dans la méthode `GET`, vous allez configurer la validation des demandes pour les paramètres de chaîne de requête d’URL.
+ Dans la méthode `POST`, vous allez configurer la validation des demandes pour le corps de la demande.
Cela permettra uniquement à certains appels d'API d'être transmis à l'API.
Téléchargez et décompressez [le modèle de création d'application pour CloudFormation](samples/request-validation-tutorial-console.zip). Vous allez utiliser ce modèle pour créer une API incomplète. Vous terminerez les étapes restantes dans la console API Gateway.
**Pour créer une CloudFormation pile**
1. Ouvrez la CloudFormation console à l'adresse [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Choisissez **Créer une pile**, puis choisissez **Avec de nouvelles ressources (standard).**
1. Dans **Spécifier le modèle**, choisissez **Charger un modèle de fichier**.
1. Sélectionnez le modèle que vous avez téléchargé.
1. Choisissez **Suivant**.
1. Pour **Nom de la pile**, saisissez **request-validation-tutorial-console**, puis choisissez **Suivant**.
1. Pour **Configurer les options de pile**, choisissez **Suivant**.
1. Pour les **fonctionnalités**, reconnaissez que CloudFormation vous pouvez créer des ressources IAM dans votre compte.
1. Choisissez **Suivant**, puis **Soumettre**.
CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Lorsque le statut de votre CloudFormation pile est **CREATE\$1COMPLETE**, vous êtes prêt à passer à l'étape suivante.
**Pour sélectionner l’API que vous venez de créer**
1. Sélectionnez la pile **request-validation-tutorial-console** nouvellement créée.
1. Sélectionnez **Ressources**.
1. Sous **ID physique**, choisissez votre API. Ce lien vous dirigera vers la console API Gateway.
Avant de modifier les méthodes `GET` et `POST`, vous devez créer un modèle.
**Pour créer un modèle**
1. Un modèle est requis pour utiliser la validation des demandes sur le corps d'une demande entrante. Pour créer un modèle, dans le volet de navigation principal, choisissez **Modèles**.
1. Sélectionnez **Créer un modèle**.
1. Pour **Nom**, saisissez **PetStoreModel**.
1. Pour **Type de contenu**, entrez **application/json**. Si aucun type de contenu correspondant n’est trouvé, la validation de demande n’est pas effectuée. Pour utiliser le même modèle quel que soit le type de contenu, saisissez **\$1default**.
1. Pour **Description**, saisissez **My PetStore Model** comme description du modèle.
1. Pour **Schéma du modèle**, collez le modèle suivant dans l’éditeur de code, puis choisissez **Créer**.
```
{
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
Pour plus d’informations sur le modèle, consultez [Modèles de données pour REST APIs](models-mappings-models.md).
**Pour configurer la validation de requête pour une méthode `GET`**
1. Dans le volet de navigation principal, choisissez **Ressources**, puis sélectionnez la méthode **GET**.
1. Dans l’onglet **Demande de méthode**, sous **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Pour **Validateur de requête**, sélectionnez **Valider les paramètres de chaîne de requête et les en-têtes**.
1. Sous **Paramètres de chaîne de requête d’URL**, procédez comme suit :
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **petType**.
1. Activez **Obligatoire**.
1. Maintenez **Mise en cache** désactivée.
1. Choisissez **Enregistrer**.
1. Dans l’onglet **Requête d’intégration**, sous **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Sous **Paramètres de chaîne de requête d’URL**, procédez comme suit :
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **petType**.
1. Pour **Mappage à partir de**, entrez **method.request.querystring.petType**. Cela mappe **petType** au type d’animal de compagnie.
Pour plus d’informations sur le mappage des données, consultez [le didacticiel sur le mappage des données](set-up-data-transformations-in-api-gateway.md#mapping-example-console).
1. Maintenez **Mise en cache** désactivée.
1. Choisissez **Enregistrer**.
**Pour tester la validation des requêtes pour la méthode `GET`**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour **Chaînes de requête**, saisissez **petType=dog**, puis choisissez **Tester**.
1. Le test de méthode renverra `200 OK` et une liste de chiens.
Pour obtenir des informations sur la façon de transformer ces données de sortie, consultez le [didacticiel sur le mappage des données](set-up-data-transformations-in-api-gateway.md#mapping-example-console).
1. Supprimez **petType=dog** et choisissez **Tester**.
1. Le test de méthode renverra une erreur `400` avec le message d’erreur suivant :
```
{
"message": "Missing required request parameters: [petType]"
}
```
**Pour configurer la validation de requête pour la méthode `POST`**
1. Dans le volet de navigation principal, sélectionnez **Ressources**, puis sélectionnez la méthode **POST**.
1. Dans l’onglet **Demande de méthode**, sous **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Pour **Validateur de requête**, sélectionnez **Valider le corps**.
1. Sous **Corps de la requête**, choisissez **Ajouter un modèle**.
1. Pour **Type de contenu**, entrez **application/json**. Si aucun type de contenu correspondant n’est trouvé, la validation de demande n’est pas effectuée. Pour utiliser le même modèle quel que soit le type de contenu, saisissez `$default`.
Pour **Modèle**, sélectionnez **PetStoreModel**.
1. Choisissez **Enregistrer**.
**Pour tester la validation de requête pour une méthode `POST`**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Sous **Corps de la requête**, collez ce qui suit dans l’éditeur de code :
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 400
}
```
Sélectionnez **Tester)**.
1. Le test de méthode renverra `200 OK` et un message de réussite.
1. Sous **Corps de la requête**, collez ce qui suit dans l’éditeur de code :
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 4000
}
```
Sélectionnez **Tester)**.
1. Le test de méthode renverra une erreur `400` avec le message d’erreur suivant :
```
{
"message": "Invalid request body"
}
```
Au bas des journaux de test, la raison pour laquelle le corps de la requête est non valide est renvoyée. Dans ce cas, le prix de l’animal de compagnie était supérieur au maximum spécifié dans le modèle.
**Pour supprimer une CloudFormation pile**
1. Ouvrez la CloudFormation console à l'adresse [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Sélectionnez votre CloudFormation pile.
1. Choisissez **Supprimer**, puis confirmez votre choix.
### Étapes suivantes
+ Pour obtenir des informations sur la façon de transformer les données de sortie et d’effectuer plus de mappage des données, consultez le [didacticiel sur le mappage des données](set-up-data-transformations-in-api-gateway.md#mapping-example-console).
+ Suivez le didacticiel [Configuration d’une validation de base des demandes à l’aide de l’interface AWS CLI](#api-gateway-request-validation-setup-cli), pour effectuer des étapes similaires à l’aide de l’interface AWS CLI.
## Configurez la validation de base des demandes à l'aide du AWS CLI
Vous pouvez créer un validateur pour configurer la validation des demandes à l’aide de l’interface AWS CLI. Pour suivre ce didacticiel, vous allez utiliser un CloudFormation modèle pour créer une API API Gateway incomplète.
**Note**
Il ne s'agit pas du même CloudFormation modèle que le didacticiel de la console.
À l’aide d’une ressource `/validator` pré-exposée, vous allez créer les méthodes `GET` et `POST`. Ces deux méthodes seront intégrées avec le point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Vous allez configurer les deux validations de demandes suivantes :
+ Sur la méthode `GET`, vous allez créer un validateur `params-only` pour valider les paramètres de chaîne de requête d’URL.
+ Sur la méthode `POST`, vous allez créer un validateur `body-only` pour valider le corps de la demande.
Cela permettra uniquement à certains appels d'API d'être transmis à l'API.
**Pour créer une CloudFormation pile**
Téléchargez et décompressez [le modèle de création d'application pour CloudFormation](samples/request-validation-tutorial-cli.zip).
Pour effectuer le didacticiel suivant, vous avez besoin de l’[AWS Command Line Interface (AWS CLI) version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Pour les commandes longues, un caractère d’échappement (`\`) est utilisé pour les fractionner en plusieurs lignes.
**Note**
Dans Windows, certaines commandes CLI Bash que vous utilisez couramment (par exemple `zip`) ne sont pas prises en charge par les terminaux intégrés du système d’exploitation. [Installez le sous-système Windows pour Linux](https://learn.microsoft.com/en-us/windows/wsl/install) afin d’obtenir une version intégrée avec Windows d’Ubuntu et Bash. Les exemples de commandes CLI de ce guide utilisent le formatage Linux. Les commandes qui incluent des documents JSON en ligne doivent être reformatées si vous utilisez la CLI Windows.
1. Utilisez la commande suivante pour créer la CloudFormation pile.
```
aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Utilisez la commande suivante pour voir l'état de votre CloudFormation pile.
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
```
1. Lorsque le statut de votre CloudFormation pile est défini`StackStatus: "CREATE_COMPLETE"`, utilisez la commande suivante pour récupérer les valeurs de sortie pertinentes pour les étapes futures.
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Les valeurs de sortie sont les suivantes :
+ ApiId, qui est l'ID de l'API. Pour ce didacticiel, l’ID d’API est `abc123`.
+ ResourceId, qui est l'ID de la ressource de validation dans laquelle les `POST` méthodes `GET` et sont exposées. Pour ce didacticiel, l’ID de ressource est `efg456`.
**Pour créer les validateurs de demandes et importer un modèle**
1. Un validateur est requis pour utiliser la validation des demandes avec l’interface AWS CLI. Utilisez la commande suivante pour créer un validateur qui valide uniquement les paramètres de demande.
```
aws apigateway create-request-validator --rest-api-id abc123 \
--no-validate-request-body \
--validate-request-parameters \
--name params-only
```
Notez l'ID du validateur `params-only`.
1. Utilisez la commande suivante pour créer un validateur qui valide uniquement le corps de la demande.
```
aws apigateway create-request-validator --rest-api-id abc123 \
--validate-request-body \
--no-validate-request-parameters \
--name body-only
```
Notez l'ID du validateur `body-only`.
1. Un modèle est requis pour utiliser la validation des demandes sur le corps d'une demande entrante. Utilisez la commande suivante pour importer un modèle.
```
aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'
```
Si aucun type de contenu correspondant n'est trouvé, la validation de demande n'est pas effectuée. Pour utiliser le même modèle quel que soit le type de contenu, spécifiez `$default` comme clé.
**Pour créer les méthodes `GET` et `POST`**
1. Utilisez la commande suivante pour ajouter la méthode HTTP `GET` sur la ressource `/validate`. Cette commande crée la méthode `GET`, ajoute le validateur `params-only` et définit la chaîne de requête `petType` selon les besoins.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--authorization-type "NONE" \
--request-validator-id aaa111 \
--request-parameters "method.request.querystring.petType=true"
```
Utilisez la commande suivante pour ajouter la méthode HTTP `POST` sur la ressource `/validate`. Cette commande crée la méthode `POST`, ajoute le validateur `body-only` et attache le modèle au validateur de corps uniquement.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
--request-validator-id bbb222 \
--request-models 'application/json'=PetStoreModel
```
1. Utilisez la commande suivante pour configurer la réponse `200 OK` de la méthode `GET /validate`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200
```
Utilisez la commande suivante pour configurer la réponse `200 OK` de la méthode `POST /validate`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Utilisez la commande suivante pour configurer une `Integration` avec un point de terminaison HTTP spécifié pour la méthode `GET /validation`.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
Utilisez la commande suivante pour configurer une `Integration` avec un point de terminaison HTTP spécifié pour la méthode `POST /validation`.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
1. Utilisez la commande suivante pour configurer une réponse d'intégration pour la méthode `GET /validation`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456\
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
Utilisez la commande suivante pour configurer une réponse d'intégration pour la méthode `POST /validation`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern ""
```
**Pour tester l’API**
1. Pour tester la méthode `GET` qui effectuera la validation des demandes pour les chaînes de requête, utilisez la commande suivante :
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--path-with-query-string '/validate?petType=dog'
```
Le résultat sera `200 OK` et une liste de chiens.
1. Utilisez la commande suivante pour tester sans inclure la chaîne de requête `petType`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
Le résultat sera une erreur `400`.
1. Pour tester la méthode `POST` qui effectuera la validation des demandes pour le corps de la demande, utilisez la commande suivante :
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'
```
Le résultat sera `200 OK` et un message de réussite.
1. Utilisez la commande suivante pour tester en utilisant un corps non valide.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'
```
Le résultat sera une erreur `400`, car le prix du chien est supérieur au prix maximum défini par le modèle.
**Pour supprimer une CloudFormation pile**
+ Utilisez la commande suivante pour supprimer vos CloudFormation ressources.
```
aws cloudformation delete-stack --stack-name request-validation-tutorial-cli
```
## Configuration de la validation de base des demandes à l’aide d’une définition OpenAPI
Vous pouvez déclarer un validateur de demande au niveau de l’API en spécifiant un ensemble d’objets [x-amazon-apigateway-request-Validators.RequestValidator objet](api-gateway-swagger-extensions-request-validators.requestValidator.md) dans le mappage d’[x-amazon-apigateway-requestobjet -validators](api-gateway-swagger-extensions-request-validators.md) afin de sélectionner la partie de la demande qui sera validée. Dans l’exemple de définition OpenAPI, il existe deux validateurs :
+ Le validateur `all` qui valide à la fois le corps, à l’aide du modèle de données `RequestBodyModel`, et les paramètres.
Le modèle de données `RequestBodyModel` exige que l’objet JSON en entrée contienne les propriétés `name`, `type` et `price`. La propriété `name` peut être une chaîne, `type` doit être l’un de champs d’énumération spécifiés (`["dog", "cat", "fish"]`) et `price` doit être compris entre 25 et 500. Le paramètre `id` n’est pas obligatoire.
+ Le validateur `param-only` qui valide uniquement les paramètres.
Pour activer un validateur de demande sur toutes les méthodes d’une API, spécifiez une propriété [x-amazon-apigateway-requestpropriété -validator](api-gateway-swagger-extensions-request-validator.md) au niveau de l’API de la définition OpenAPI. Dans l’exemple de définition OpenAPI, le validateur `all` est utilisé sur toutes les méthodes d’API, sauf s’il est remplacé. Lorsque vous utilisez un modèle pour valider le corps et qu’aucun type de contenu correspondant n’est trouvé, la validation de demande n’est pas effectuée. Pour utiliser le même modèle quel que soit le type de contenu, spécifiez `$default` comme clé.
Pour activer un validateur de demande sur une méthode individuelle, spécifiez la propriété `x-amazon-apigateway-request-validator` au niveau de la méthode. Dans cet exemple de définition OpenAPI, le validateur `param-only` remplace le validateur `all` sur la méthode `GET`.
Pour importer l’exemple OpenAPI dans API Gateway, consultez les instructions suivantes pour réaliser l’[Importation d’une API régionale dans API Gateway](import-export-api-endpoints.md) ou l’[Importation d’une API optimisée pour la périphérie dans API Gateway](import-edge-optimized-api.md).
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ReqValidators Sample",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "/v1"
}
}
} ],
"paths" : {
"/validation" : {
"get" : {
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RequestBodyModel"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"RequestBodyModel" : {
"required" : [ "name", "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"maximum" : 500.0,
"minimum" : 25.0,
"type" : "number"
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Error"
}
},
"Error" : {
"type" : "object"
}
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "1.0.0",
"title" : "ReqValidators Sample"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/validation" : {
"get" : {
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"consumes" : [ "application/json" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "RequestBodyModel",
"required" : true,
"schema" : {
"$ref" : "#/definitions/RequestBodyModel"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"definitions" : {
"RequestBodyModel" : {
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Error"
}
},
"Error" : {
"type" : "object"
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
# AWS CloudFormation modèle d'un exemple d'API avec validation de demande de base
L' CloudFormation exemple de définition de modèle suivant définit un exemple d'API avec la validation des demandes activée. L'API [PetStore est un sous-ensemble de l'API ](http://petstore-demo-endpoint.execute-api.com/petstore/pets). Elle expose une méthode `POST` pour l’ajout d’un animal de compagnie à la collection `pets` et d’une méthode `GET` pour interroger les animaux de compagnie par un type spécifié.
Deux valideurs de demandes sont déclarés :
**`GETValidator`**
Ce valideur est activé sur la méthode `GET`. Il autorise API Gateway à vérifier que le paramètre de requête obligatoire (`q1`) est inclus et non vide dans la demande entrante.
**`POSTValidator`**
Ce valideur est activé sur la méthode `POST`. Il autorise API Gateway à vérifier que le format de demande de charge utile est conforme au `RequestBodyModel` spécifié quand le type de contenu est `application/json`. Si aucun type de contenu correspondant n’est trouvé, la validation de demande n’est pas effectuée. Pour utiliser le même modèle quel que soit le type de contenu, spécifiez `$default`. `RequestBodyModel` contient un modèle supplémentaire, `RequestBodyModelId`, permettant de définir l’identifiant d’animal de compagnie.
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: ReqValidatorsSample
RequestBodyModelId:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModelId
properties:
id:
type: integer
RequestBodyModel:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet type, name, price, and ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModel
required:
- price
- name
- type
type: object
properties:
id:
"$ref": !Sub
- 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}'
- Api: !Ref Api
RequestBodyModelId: !Ref RequestBodyModelId
price:
type: number
minimum: 25
maximum: 500
name:
type: string
type:
type: string
enum:
- "dog"
- "cat"
- "fish"
GETValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: params-only
RestApiId: !Ref Api
ValidateRequestBody: False
ValidateRequestParameters: True
POSTValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: body-only
RestApiId: !Ref Api
ValidateRequestBody: True
ValidateRequestParameters: False
ValidationResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'validation'
ValidationMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: GET
AuthorizationType: NONE
RequestValidatorId: !Ref GETValidator
RequestParameters:
method.request.querystring.q1: true
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ValidationMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: POST
AuthorizationType: NONE
RequestValidatorId: !Ref POSTValidator
RequestModels:
application/json : !Ref RequestBodyModel
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: POST
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- ValidationMethodGet
- RequestBodyModel
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# Transformations de données pour REST APIs dans API Gateway
**Note**
Cette section explique les fonctionnalités que vous allez utiliser avec une intégration sans proxy. Toutefois, nous vous recommandons, dans la mesure du possible, d’utiliser une intégration proxy pour votre API REST. Une intégration proxy dispose d’une configuration d’intégration simplifiée et peut évoluer avec le backend sans qu’il soit nécessaire de modifier la configuration existante. Pour de plus amples informations, veuillez consulter [Choix d’un type d’intégration d’API API Gateway](api-gateway-api-integration-types.md).
Si vous utilisez une intégration sans proxy, vous pouvez utiliser deux fonctionnalités d’API Gateway pour transformer votre demande de méthode et votre réponse d’intégration. Vous pouvez transformer votre demande de méthode si elle utilise un format de données utiles différent de celui de la demande d’intégration. Vous pouvez transformer votre réponse d’intégration si elle renvoie un format de données utiles différent de celui que vous devez renvoyer dans la réponse de méthode. Pour plus d’informations sur le cycle de vie des demandes, consultez [Exemple de ressource pour une API REST](rest-api-develop.md#rest-api-develop-example).
L’exemple suivant montre une transformation de données dans laquelle, pour l’en-tête `"x-version:beta"`, le paramètre d’en-tête `x-version` est transformé en paramètre d’en-tête `app-version`. Les données passent de `x-version` à `app-version` dans la demande d’intégration. Ainsi, le point de terminaison d’intégration reçoit la valeur du paramètre d’en-tête transformé. Lorsque le point de terminaison d’intégration renvoie un code d’état, celui-ci passe de `200` à `204` avant la réponse de méthode.
![\[Schéma de transformation de données d’API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/develop-non-proxy.png)
Pour transformer des données, vous pouvez utiliser les fonctionnalités suivantes :
**Mappage de paramètres**
Dans un mappage des paramètres, vous pouvez modifier les paramètres du chemin d’URL de la demande d’intégration, les paramètres de la chaîne de requête d’URL ou les valeurs d’en-tête HTTP, mais vous ne pouvez pas modifier les données utiles de la demande d’intégration. Vous pouvez également modifier les valeurs de l’en-tête de réponse HTTP. Utilisez le mappage de paramètres pour créer des valeurs d’en-tête statiques pour le partage des ressources entre origines multiples (CORS).
Vous pouvez utiliser le mappage de paramètres dans votre demande d’intégration pour les intégrations proxy et sans proxy. En revanche, pour utiliser le mappage de paramètres dans une réponse d’intégration, vous avez besoin d’une intégration sans proxy. Le mappage de paramètres ne nécessite aucun script en [langage VTL (Velocity Template Language](https://velocity.apache.org/engine/devel/vtl-reference.html)). Pour de plus amples informations, veuillez consulter [Mappage des paramètres pour REST APIs dans API Gateway](rest-api-parameter-mapping.md).
**Transformations de modèles de mappage**
Pour transformer un modèle de mappage, vous allez utiliser un modèle de mappage pour mapper les paramètres de chemin d’URL, les paramètres de chaîne de requête d’URL, les en-têtes HTTP, ainsi que le corps de la demande d’intégration ou de la réponse d’intégration. Un *modèle de mappage* est un script exprimé dans le [langage VTL (Velocity Template Language) à](https://velocity.apache.org/engine/devel/vtl-reference.html) l'aide d'[JSONPath expressions](https://goessner.net/articles/JsonPath/) et appliqué à la charge utile en fonction de l'`Content-type`en-tête.
Un modèle de mappage vous permet d’effectuer les opérations suivantes :
+ Sélectionnez les données à envoyer à l'aide de l'intégration Services AWS, telles que les fonctions Amazon DynamoDB ou Lambda, ou les points de terminaison HTTP. Pour de plus amples informations, veuillez consulter [Tutoriel : Modifier la demande et la réponse d'intégration pour les intégrations aux services AWS](set-up-data-transformations-in-api-gateway.md).
+ Remplacer de manière conditionnelle les paramètres de demande d’intégration et de réponse d’intégration d’une API, créer des valeurs d’en-tête et remplacer des codes d’état. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md).
Vous pouvez également spécifier le comportement de votre API lorsqu’un corps de demande d’intégration comporte un en-tête `Content-type` sans modèles de mappage correspondants. C’est ce qu’on appelle le comportement de transmission d’intégration. Pour de plus amples informations, veuillez consulter [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
## Choisissez entre le mappage de paramètres et la transformation du modèle de mappage
Nous vous recommandons d’utiliser le mappage de paramètres pour transformer vos données lorsque cela est possible. Si votre API vous oblige à modifier le corps ou à effectuer des remplacements et modifications conditionnelles en fonction de la demande d’intégration entrante ou de la réponse d’intégration, et que vous ne pouvez pas utiliser d’intégration proxy, optez pour la transformation du modèle de mappage.
# Mappage des paramètres pour REST APIs dans API Gateway
**Note**
Si vous utilisez une API HTTP, consultez [Transformation des demandes et des réponses d’API HTTP dans API Gateway](http-api-parameter-mapping.md).
Dans le mappage de paramètres, vous mappez les paramètres de la demande ou de la réponse. Vous pouvez mapper des paramètres à l’aide d’expressions de mappage de paramètres ou de valeurs statiques. Pour obtenir la liste des expressions de mappage, consultez [Référence de source de mappage de paramètres pour REST APIs dans API Gateway](rest-api-parameter-mapping-sources.md). Vous pouvez utiliser le mappage de paramètres dans votre demande d’intégration pour les intégrations proxy et sans proxy. En revanche, pour utiliser le mappage de paramètres dans une réponse d’intégration, vous avez besoin d’une intégration sans proxy.
Par exemple, vous pouvez mapper le paramètre d’en-tête `puppies` de la demande de méthode au paramètre d’en-tête `DogsAge0` de la demande d’intégration. Si un client envoie l’en-tête `puppies:true` à votre API, la demande d’intégration envoie alors l’en-tête de demande `DogsAge0:true` au point de terminaison d’intégration. Le schéma suivant illustre le cycle de vie de la demande de cet exemple.
![\[Schéma d’un exemple de mappage des paramètres d’API Gateway pour une demande\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Pour créer cet exemple à l’aide d’API Gateway, consultez [Exemple 1 : association d’un paramètre de demande de méthode à un paramètre de demande d’intégration](request-response-data-mappings.md#request-response-data-mappings-example-1).
Autre exemple, vous pouvez également mapper le paramètre d’en-tête de réponse d’intégration `kittens` au paramètre d’en-tête de réponse de méthode`CatsAge0`. Ensuite, si le point de terminaison d’intégration renvoie `kittens:false`, le client reçoit l’en-tête `CatsAge0:false`. Le schéma suivant illustre le cycle de vie de la demande de cet exemple.
![\[Schéma d’un exemple de mappage de paramètres API Gateway pour une réponse\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [
# Exemples de mappage de paramètres pour REST APIs dans API Gateway
](request-response-data-mappings.md)
+ [
# Référence de source de mappage de paramètres pour REST APIs dans API Gateway
](rest-api-parameter-mapping-sources.md)
# Exemples de mappage de paramètres pour REST APIs dans API Gateway
Les exemples suivants montrent comment créer des expressions de mappage de paramètres à l’aide de la console API Gateway, d’OpenAPI et de modèles CloudFormation . Pour voir un exemple d’utilisation du mappage de paramètres dans le but de créer les en-têtes CORS requis, consultez [CORS pour REST APIs dans API Gateway](how-to-cors.md).
## Exemple 1 : association d’un paramètre de demande de méthode à un paramètre de demande d’intégration
L’exemple suivant mappe le paramètre d’en-tête `puppies` de la demande de méthode au paramètre d’en-tête `DogsAge0` de la demande d’intégration.
------
#### [ AWS Management Console ]
**Pour mapper le paramètre de la demande de méthode**
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 REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Développez **En-têtes de demande HTTP**.
1. Sélectionnez **Add header**.
1. Pour **Nom**, saisissez **puppies**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
Ajoute AWS Management Console automatiquement un mappage de paramètres de `method.request.header.puppies ` à `puppies` pour vous, mais vous devez modifier le **nom** pour qu'il corresponde au paramètre d'en-tête de demande attendu par votre point de terminaison d'intégration.
1. Pour **Nom**, saisissez **DogsAge0**.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
Les étapes suivantes montrent comment vérifier que votre mappage de paramètres a été effectué avec succès.
**(Facultatif) Testez votre mappage de paramètres.**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour les en-têtes, saisissez **puppies:true**.
1. Sélectionnez **Tester)**.
1. Dans **Journaux**, le résultat doit se présenter comme suit :
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
Le paramètre d’en-tête de la demande est passé de `puppies` à `DogsAge0`.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Exemple 2 : association de plusieurs paramètres de requête de méthode à différents paramètres de demande d’intégration
L’exemple suivant mappe le paramètre `methodRequestQueryParam` de la chaîne de requête de méthode à valeurs multiples au paramètre `integrationQueryParam` de la chaîne de requête de demande d’intégration, et mappe le paramètre d’en-tête `methodRequestHeaderParam` de la demande de méthode au paramètre de chemin `integrationPathParam` de la demande d’intégration.
------
#### [ AWS Management Console ]
**Pour mapper les paramètres de requête de méthode**
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 REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **Paramètres de chaîne de requête d’URL**.
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **methodRequestQueryParam**.
1. Développez **En-têtes de demande HTTP**.
1. Sélectionnez **Add header**.
1. Pour **Nom**, saisissez **methodRequestHeaderParam**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Choisissez **paramètres de chemin d’URL**.
1. Choisissez **Ajouter un paramètre de chemin**.
1. Pour **Nom**, saisissez **integrationPathParam**.
1. Pour **Mappage à partir de**, entrez **method.request.header.methodRequestHeaderParam**.
Cette opération mappe l’en-tête de demande de méthode que vous avez spécifié dans la demande de méthode à un nouveau paramètre de chemin de la demande d’intégration.
1. Choisissez **Paramètres de chaîne de requête d’URL**.
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **integrationQueryParam**.
1. Pour **Mappage à partir de**, entrez **method.request.multivaluequerystring.methodRequestQueryParam**.
Cette opération mappe le paramètre de chaîne de requête à valeurs multiples à un nouveau paramètre de chaîne de requête de demande d’intégration à valeur unique.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
La définition OpenAPI suivante crée les mappages de paramètres suivants pour une intégration HTTP :
+ l’en-tête de la demande de méthode, nommé `methodRequestHeaderParam`, avec le paramètre de chemin de la demande d’intégration, nommé `integrationPathParam` ;
+ la chaîne de requête de la demande de méthode à valeurs multiples, nommée `methodRequestQueryParam`, avec la chaîne de requête de la demande d’intégration, nommée `integrationQueryParam`.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée les mappages de paramètres suivants pour une intégration HTTP :
+ l’en-tête de la demande de méthode, nommé `methodRequestHeaderParam`, avec le paramètre de chemin de la demande d’intégration, nommé `integrationPathParam` ;
+ la chaîne de requête de la demande de méthode à valeurs multiples, nommée `methodRequestQueryParam`, avec la chaîne de requête de la demande d’intégration, nommée `integrationQueryParam`.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemple 3 : mappage de champs du corps de la demande JSON aux paramètres de la demande d’intégration
Vous pouvez également mapper les paramètres de demande d'intégration à partir des champs du corps de la demande JSON à l'aide d'une [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). L’exemple suivant mappe le corps de la demande de méthode à un en-tête de la demande d’intégration nommé `body-header`, et mappe une partie du corps de la demande, tel qu’il est exprimé par une expression JSON, à un en-tête de la demande d’intégration nommé `pet-price`.
Pour tester cet exemple, fournissez une entrée contenant une catégorie de prix, par exemple :
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS Management Console ]
**Pour mapper les paramètres de requête de méthode**
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 REST.
1. Choisissez la méthode `POST`, `PUT`, `PATCH` ou `ANY`.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Sélectionnez **Paramètres des en-têtes de requête d’URL**.
1. Sélectionnez **Ajouter un paramètre d’en-tête de requête**.
1. Pour **Nom**, saisissez **body-header**.
1. Pour **Mappage à partir de**, entrez **method.request.body**.
Cette opération mappe le corps de la demande de méthode à un nouveau paramètre d’en-tête de la demande d’intégration.
1. Sélectionnez **Ajouter un paramètre d’en-tête de requête**.
1. Pour **Nom**, saisissez **pet-price**.
1. Pour **Mappage à partir de**, entrez ** method.request.body[0].price**.
Cette opération mappe une partie du corps de la demande de méthode à un nouveau paramètre d’en-tête de la demande d’intégration.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante mappe les paramètres de la demande d’intégration à partir des champs du corps de la demande JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemple 4 : mappage de la réponse d’intégration à la réponse de méthode
Vous pouvez également mapper la réponse d’intégration à la réponse de méthode. L’exemple suivant mappe le corps de la réponse d’intégration à un en-tête de la réponse de méthode nommé `location`, mappe l’en-tête `x-app-id` de la réponse d’intégration à l’en-tête `id` de la réponse de méthode, et mappe l’en-tête à valeurs multiples `item` de la réponse d’intégration à l’en-tête `items` de la réponse de méthode.
------
#### [ AWS Management Console ]
**Pour mapper la réponse d’intégration**
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 REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Choisissez l’onglet **Méthode de réponse**, puis pour **Réponse 200**, sélectionnez **Modifier**.
1. Sous **Nom de l’en-tête**, choisissez **Ajouter un en-tête**.
1. Créez trois en-têtes nommés **id**, **item** et **location**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Réponse d’intégration**, puis pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Sous **Mappages d’en-tête**, saisissez ce qui suit.
1. Sous **ID**, saisissez **integration.response.header.x-app-id**.
1. Sous **Élément**, saisissez **integration.response.multivalueheader.item**.
1. Sous **Emplacement**, saisissez **integration.response.body.redirect.url**.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition d’OpenAPI suivante mappe la réponse d’intégration à la réponse de méthode.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# Référence de source de mappage de paramètres pour REST APIs dans API Gateway
Lorsque vous créez un mappage de paramètres, vous spécifiez les paramètres de demande de méthode ou de réponse d’intégration à modifier, et indiquez comment modifier ces paramètres.
Le tableau suivant indique les paramètres de requête de méthode que vous pouvez mapper, ainsi que l’expression permettant ce mappage. Dans ces expressions, *name* est le nom d'un paramètre de demande de méthode. Par exemple, pour mapper le paramètre d’en-tête de demande `puppies`, utilisez l’expression `method.request.header.puppies`. Votre expression doit respecter le modèle d’expression régulière `'^[a-zA-Z0-9._$-]+$]'`. Vous pouvez utiliser le mappage de paramètres dans votre demande d’intégration pour des intégrations avec ou sans proxy.
| **Source de données mappée** | **Expression de mappage** |
| --- | --- |
| Chemin de la demande de méthode | method.request.path.name |
| Chaîne de requête de la demande de méthode | method.request.querystring.name |
| Chaîne de requête de la demande de méthode à valeurs multiples | method.request.multivaluequerystring.name |
| En-tête de la demande de méthode | method.request.header.name |
| En-tête de demande de méthode à valeurs multiples | method.request.multivalueheader.name |
| Corps de la demande de méthode | method.request.body |
| corps de la demande de méthode (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*est une JSONPath expression pour un champ JSON du corps d'une demande. Pour plus d'informations, voir [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variables d’étape | stageVariables.name |
| Variables de contexte | `context.name` Le nom doit être l’une des [variables de contexte prises en charge](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valeur statique | `'static_value'`. *static\$1value*Il s'agit d'une chaîne littérale qui doit être placée entre guillemets simples. Par exemple, `'https://www.example.com'`. |
Le tableau suivant indique les paramètres de réponse d’intégration que vous pouvez mapper, ainsi que l’expression permettant ce mappage. Dans ces expressions, *name* est le nom d'un paramètre de réponse d'intégration. Vous pouvez mapper les paramètres d’en-tête d’une réponse de méthode à partir de n’importe quel en-tête ou corps de réponse d’intégration, de variables \$1context ou de valeurs statiques. Pour utiliser le mappage de paramètres pour une réponse d’intégration, il vous faut une intégration sans proxy.
| Source de données mappée | Expression de mappage |
| --- | --- |
| En-tête de réponse d’intégration | integration.response.header.name |
| En-tête de réponse d’intégration | integration.response.multivalueheader.name |
| Corps de réponse intégration | integration.response.body |
| Organisme de réponse à l'intégration (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*est une JSONPath expression pour un champ JSON du corps d'une réponse. Pour plus d'informations, voir [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variable d’étape | stageVariables.name |
| Variable de contexte | `context.name` Le nom doit être l’une des [variables de contexte prises en charge](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valeur statique | ` 'static_value'` *static\$1value*Il s'agit d'une chaîne littérale qui doit être placée entre guillemets simples. Par exemple, `'https://www.example.com'`. |
# Transformations de modèles de mappage pour REST APIs dans API Gateway
Une transformation de modèle de mappage utilise un modèle de mappage pour modifier votre demande d’intégration ou votre réponse d’intégration. Un *modèle de mappage* est un script exprimé dans le [langage VTL (Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html) et appliqué à une charge utile en [JSONPath ](https://goessner.net/articles/JsonPath/)fonction de l'`Content-type`en-tête. Vous utilisez des modèles de mappage lorsque vous transformez des modèles de mappage. Cette section décrit les informations conceptuelles relatives aux modèles de mappage.
Le schéma suivant montre le cycle de vie des demandes pour une `POST /pets` ressource intégrée à un point de terminaison PetStore d'intégration. Dans cette API, un utilisateur envoie des données sur un animal de compagnie, et le point de terminaison d’intégration renvoie les frais d’adoption relatifs à cet animal. Dans le cycle de vie de cette demande, les transformations du modèle de mappage filtrent le corps de la demande vers le point de terminaison d’intégration, et filtrent le corps de réponse provenant du point de terminaison d’intégration.
![\[Exemple de cycle de la demande\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/mapping-template-transforms.png)
Les sections suivantes expliquent le cycle de vie des demandes et réponses.
## Demande de méthode et demande d’intégration
Voici le corps de la demande envoyé à la demande de méthode dans l’exemple précédent :
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Le corps de cette demande n’est pas au format approprié pour être utilisé par le point de terminaison d’intégration. API Gateway transforme donc le modèle de mappage. API Gateway transforme le modèle de mappage uniquement parce qu’un modèle de mappage est défini pour le Content-Type `application/json`. Si vous ne définissez pas de modèle de mappage pour Content-Type, API Gateway transmet par défaut le corps au point de terminaison d’intégration par le biais de la demande d’intégration. Pour modifier ce comportement, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
Le modèle de mappage suivant transforme les données de la demande de méthode dans la demande d’intégration avant qu’elles ne soient envoyées au point de terminaison d’intégration :
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. La variable `$inputRoot` représente l’objet racine dans les données JSON d’origine de la section précédente. Les directives commencent par le symbole `#`.
1. `dog` est une concaténation de la valeur de l’utilisateur `id` et d’une valeur de chaîne.
1. `Age` provient du corps de la demande de méthode.
La sortie suivante est ensuite transmise au point de terminaison d’intégration :
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Réponse d’intégration et réponse de méthode
Une fois la demande envoyée avec succès au point de terminaison d’intégration, celui-ci envoie une réponse à la réponse d’intégration d’API Gateway. Voici un exemple de données de sortie provenant du point de terminaison d’intégration :
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
La réponse de méthode attend des données utiles différentes de celles renvoyées par la réponse d’intégration. API Gateway transforme le modèle de mappage. API Gateway transforme le modèle de mappage uniquement parce qu’un modèle de mappage est défini pour le Content-Type `application/json`. Si vous ne définissez pas de modèle de mappage pour Content-Type, API Gateway transmet par défaut le corps à la réponse de méthode par le biais de la réponse d’intégration. Pour modifier ce comportement, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
La sortie suivante est envoyée à la réponse de méthode :
```
{"adoptionFee": 19.95}
```
Ceci conclut l’exemple de transformation de modèle de mappage. Nous vous recommandons, dans la mesure du possible, d’utiliser une intégration de proxy pour transformer vos données au lieu de transformer le modèle de mappage. Pour de plus amples informations, veuillez consulter [Choix d’un type d’intégration d’API API Gateway](api-gateway-api-integration-types.md).
# Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway
Si votre demande de méthode comporte des données utiles et qu’aucun modèle de mappage n’est défini pour l’en-tête `Content-Type`, vous pouvez choisir de transmettre les données utiles de la demande fournie par le client au backend par l’intermédiaire de la demande d’intégration, sans recourir à une transformation. Ce processus est appelé transfert direct d’intégration.
Le comportement de transmission d’une demande entrante est déterminé par ce paramètre. Trois options sont disponibles :
**Quand aucun modèle ne correspond à l’en-tête Content-Type de la demande**
Sélectionnez cette option si vous voulez que le corps de la demande de méthode soit transmis au backend via la demande d’intégration sans transformation lorsque le type de contenu de la demande de méthode ne correspond à aucun type de contenu associé aux modèles de mappage.
Lorsque vous appelez l’API API Gateway, vous choisissez cette option en définissant `WHEN_NO_MATCH` en tant que valeur de la propriété `passthroughBehavior` sur [Intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Quand aucun modèle n’est défini (recommandé)**
Choisissez cette option si vous voulez que le corps de la demande de méthode soit transmis au backend via la demande d’intégration sans transformation lorsqu’aucun modèle de mappage n’est défini dans la demande d’intégration. Si un modèle est défini lorsque cette option est sélectionnée, la demande de méthode comprenant des données utiles et un type de contenu qui ne correspond pas au modèle de mappage défini sera rejetée avec une réponse HTTP 415 Unsupported Media Type.
Lorsque vous appelez l’API API Gateway, vous choisissez cette option en définissant `WHEN_NO_TEMPLATES` en tant que valeur de la propriété `passthroughBehavior` sur [Intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Jamais**
Choisissez cette option si vous ne voulez pas que le corps de la demande de méthode soit transmis au backend via la demande d’intégration sans transformation lorsqu’aucun modèle de mappage n’est défini dans la demande d’intégration. Si un modèle est défini lorsque cette option est sélectionnée, la demande de méthode d’un type de contenu non mappé est rejetée en renvoyant une réponse HTTP 415 Type de support non pris en charge.
Lorsque vous appelez l’API API Gateway, vous choisissez cette option en définissant `NEVER` en tant que valeur de la propriété `passthroughBehavior` sur [Intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Les exemples suivants illustrent les comportements de transmission possibles.
Exemple 1 : un modèle de mappage est défini dans la demande d’intégration pour le type de contenu `application/json`.
| Content-Type | Option de transmission | Comportement |
| --- | --- | --- |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1MATCH | La charge utile de la demande est transformée à l’aide du modèle. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande est transformée à l’aide du modèle. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | NEVER | La charge utile de la demande est transformée à l’aide du modèle. |
| application/json | WHEN\$1NO\$1MATCH | La charge utile de la demande est transformée à l’aide du modèle. |
| application/json | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande est transformée à l’aide du modèle. |
| application/json | NEVER | La charge utile de la demande est transformée à l’aide du modèle. |
| application/xml | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/xml | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
Exemple 2 : un modèle de mappage est défini dans la demande d’intégration pour le type de contenu `application/xml`.
| Content-Type | Option de transmission | Comportement |
| --- | --- | --- |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1TEMPLATES | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/json | WHEN\$1NO\$1TEMPLATES | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/json | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | La charge utile de la demande est transformée à l’aide du modèle. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande est transformée à l’aide du modèle. |
| application/xml | NEVER | La charge utile de la demande est transformée à l’aide du modèle. |
Exemple 3 : aucun modèle de mappage n’est défini dans la demande d’intégration.
| Content-Type | Option de transmission | Comportement |
| --- | --- | --- |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/json | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/json | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/xml | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
# Exemple de modèle de mappage supplémentaire pour REST APIs dans API Gateway
L’exemple suivant montre une API d’album photo API Gateway qui utilise des modèles de mappage pour transformer les données de la demande d’intégration et de la réponse d’intégration. Elle utilise également des modèles de données pour définir les données utiles de la demande de méthode et de la réponse d’intégration. Pour plus d’informations sur les modèles de données, consultez [Modèles de données pour REST APIs](models-mappings-models.md).
## Demande de méthode et demande d’intégration
Voici un modèle qui définit le corps de la demande de méthode. Ce modèle d’entrée exige le chargement d’une page de photos et un minimum de 10 photos pour chaque page. Vous pouvez utiliser ce modèle d’entrée pour générer un kit SDK ou utiliser le validateur de demande pour votre API. Dans ce dernier cas, si le corps de la demande de méthode ne respecte pas la structure de données du modèle, API Gateway fait échouer la demande.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
Voici un exemple de corps de demande de méthode qui respecte la structure de données du modèle de données précédent.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
Dans cet exemple, si le précédent corps de la demande de méthode a été soumis par le client, ce modèle de mappage transforme les données utiles pour qu’elles correspondent au format requis par le point de terminaison d’intégration.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
L’exemple suivant montre les données de sortie de la transformation :
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Ces données sont envoyées à la demande d’intégration, puis au point de terminaison d’intégration.
## Réponse d’intégration et réponse de méthode
Voici un exemple de modèle de sortie pour les données photo du point de terminaison d’intégration. Vous pouvez utiliser ce modèle comme modèle de réponse de méthode, ce qui s’avère nécessaire quand vous générez un kit SDK fortement typé pour l’API. Cela entraîne la conversion (cast) de la sortie en une classe appropriée en Java ou Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
Le point de terminaison d’intégration peut ne pas répondre par une réponse conforme à la structure de données de ce modèle. Par exemple, la réponse d’intégration peut ressembler à ce qui suit :
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
L’exemple de modèle de mappage suivant transforme les données de la réponse d’intégration dans le format attendu par la réponse de méthode :
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
L’exemple suivant montre les données de sortie de la transformation :
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Ces données sont envoyées à la réponse de méthode, puis renvoyées au client.
# Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway
Vous pouvez recourir à la transformation de modèle de mappage pour remplacer n’importe quel type de paramètre de demande, d’en-tête de réponse ou de code d’état de réponse. Vous allez utiliser un modèle de mappage pour :
+ Effectuer des mappages de many-to-one paramètres
+ Remplacer les paramètres une fois que les mappages API Gateway standard ont été appliqués
+ Mapper les paramètres de façon conditionnelle, en fonction du contenu du corps ou d’autres valeurs de paramètres
+ Créer des paramètres par programmation
+ Remplacer les codes de statut renvoyés par votre point de terminaison d’intégration
Les remplacements sont définitifs. Un remplacement ne peut être appliqué qu’une seule fois à chaque paramètre. Si vous tentez de remplacer le même paramètre à plusieurs reprises, API Gateway renvoie une réponse `5XX`. Si vous devez remplacer le même paramètre plusieurs fois tout au long du modèle, nous vous recommandons de créer une variable et d’appliquer le remplacement à la fin du modèle. Le modèle n’est appliqué qu’après l’analyse de l’ensemble du modèle.
## Exemple 1 : remplacement du code d’état en fonction du corps de la réponse d’intégration
L’exemple suivant utilise l’[exemple d’API](api-gateway-create-api-from-example.md) pour remplacer le code d’état en fonction du corps de la réponse d’intégration.
------
#### [ AWS Management Console ]
**Pour remplacer un code d’état en fonction du corps de la réponse d’intégration**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Create API** (Créer une API).
1. Sous **API REST**, choisissez **Création**.
1. Sous **Détails sur l’API**, choisissez **Exemple d’API**.
1. Sélectionnez **Create API** (Créer une API).
API Gateway crée un exemple d’API PetStore. Pour récupérer des informations sur un animal de compagnie, vous allez utiliser la demande de méthode d’API `GET /pets/{petId}`, où `{petId}` est un paramètre de chemin correspondant au numéro d’identification de l’animal.
Dans cet exemple, vous allez remplacer le code de réponse de la méthode `GET` par `400` lorsqu’une condition d’erreur est identifiée.
1. Dans l’arborescence **Ressources**, sous `GET`, choisissez la méthode sous `/{petId}`.
1. Tout d’abord, vous allez tester l’implémentation actuelle de l’API.
Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour **petId**, saisissez **-1**, puis choisissez **Tester**.
Le **corps de la réponse** indique une out-of-range erreur :
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
De plus, la dernière ligne sous **Journaux** se termine par : `Method completed with status: 200`.
L’intégration a été réalisée avec succès, mais une erreur s’est produite. Vous allez maintenant remplacer le code d’état en fonction de la réponse d’intégration.
1. Dans l’onglet **Réponse d’intégration**, pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**.
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Ce modèle de mappage utilise la variable `$context.responseOverride.status` pour remplacer le code d’état par `400` si la réponse d’intégration contient la chaîne `error`.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**.
1. Pour **petId**, saisissez **-1**.
1. Dans les résultats, le **corps de réponse** indique une out-of-range erreur :
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Cependant, la dernière ligne sous **Journaux** se termine maintenant par : `Method completed with status: 400`.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée la ressource `GET pets/{petId}` et remplace le code d’état en fonction du corps de la réponse d’intégration.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Exemple 2 : remplacement de l’en-tête de la demande et création de nouveaux en-têtes
L’exemple suivant utilise l’[exemple d’API](api-gateway-create-api-from-example.md) pour remplacer l’en-tête de la demande et créer de nouveaux en-têtes.
------
#### [ AWS Management Console ]
**Pour remplacer l’en-tête de demande d’une méthode en créant un nouvel en-tête**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez l’exemple d’API que vous avez créé dans le tutoriel précédent. Le nom de l'API doit être **PetStore**.
1. Dans l’arborescence **Ressources**, sous `GET`, choisissez la méthode sous `/pet`.
1. Dans l’onglet **Requête de méthode**, pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **En-têtes de demande HTTP**, puis **Ajouter un en-tête**.
1. Pour **Nom**, saisissez **header1**.
1. Choisissez **Ajouter un en-tête**, puis créez un second en-tête appelé **header2**.
1. Choisissez **Enregistrer**.
Vous pouvez maintenant combiner ces en-têtes en une seule valeur d’en-tête à l’aide d’un modèle de mappage.
1. Dans l’onglet **Demande d’intégration**, pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Pour **Transmission du corps de requête**, sélectionnez **Lorsqu’aucun modèle n’est défini (recommandé)**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Ce modèle de mappage remplace `header1` par la chaîne `pets`, et crée un en-tête à valeurs multiples appelé `$header3Value`, qui combine `header1` et `header2`.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**.
1. Sous **En-têtes**, copiez le code suivant :
```
header1:header1Val
header2:header2Val
```
1. Sélectionnez **Test**.
Dans **Journaux**, vous devriez voir une entrée incluant ce texte :
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée la ressource `GET pets`, remplace l’en-tête de la demande et crée de nouveaux en-têtes.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Pour remplacer un modèle de mappage, ajoutez une ou plusieurs des variables `$context` suivantes. Pour obtenir la liste des variables `$context`, consultez [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference).
# Tutoriel : Modifier la demande et la réponse d'intégration pour les intégrations aux services AWS
Le didacticiel suivant explique comment utiliser les transformations de modèles de mappage pour configurer des modèles de mappage afin de transformer les demandes et réponses d'intégration à l'aide de la console et de la AWS CLI.
**Topics**
+ [
## Configuration d’une transformation de données à l’aide de la console API Gateway
](#mapping-example-console)
+ [
## Configuration de la transformation des données à l'aide de la AWS CLI
](#mapping-example-cli)
+ [
## CloudFormation Modèle de transformation de données terminé
](#api-gateway-data-transformations-full-cfn-stack)
## Configuration d’une transformation de données à l’aide de la console API Gateway
[Dans ce didacticiel, vous allez créer une API et une table DynamoDB incomplètes à l'aide du fichier .zip .zip suivant. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) Cette API incomplète possède une ressource `/pets` avec les méthodes `GET` et `POST`.
+ La méthode `GET` obtiendra des données à partir du point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Les données de sortie seront transformées conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
+ La méthode `POST` permettra à l’utilisateur de publier (`POST`) les informations sur les animaux dans une table Amazon DynamoDB à l’aide d’un modèle de mappage.
Téléchargez et décompressez [le modèle de création d'application pour CloudFormation](samples/data-transformation-tutorial-console.zip). Vous allez utiliser ce modèle pour créer une table DynamoDB afin de publier les informations sur les animaux et une API incomplète. Vous terminerez les étapes restantes dans la console API Gateway.
**Pour créer une CloudFormation pile**
1. Ouvrez la CloudFormation console à l'adresse [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Choisissez **Créer une pile**, puis choisissez **Avec de nouvelles ressources (standard).**
1. Dans **Spécifier le modèle**, choisissez **Charger un modèle de fichier**.
1. Sélectionnez le modèle que vous avez téléchargé.
1. Choisissez **Suivant**.
1. Pour **Nom de la pile**, saisissez **data-transformation-tutorial-console**, puis choisissez **Suivant**.
1. Pour **Configurer les options de pile**, choisissez **Suivant**.
1. Pour les **fonctionnalités**, reconnaissez que CloudFormation vous pouvez créer des ressources IAM dans votre compte.
1. Choisissez **Suivant**, puis **Soumettre**.
CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Lorsque le statut de votre CloudFormation pile est **CREATE\$1COMPLETE**, vous êtes prêt à passer à l'étape suivante.
**Pour tester la réponse d’intégration `GET`**
1. Dans l'onglet **Ressources** de la CloudFormation pile pour**data-transformation-tutorial-console**, sélectionnez l'ID physique de votre API.
1. Dans le volet de navigation principal, choisissez **Ressources**, puis sélectionnez la méthode **GET**.
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
La sortie du test affichera les informations suivantes :
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Vous allez transformer cette sortie conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
**Pour transformer la réponse d’intégration `GET`**
1. Choisissez l’onglet **Réponse d’intégration**.
Aucun modèle de mappage n’est actuellement défini, de sorte que la réponse d’intégration ne sera pas transformée.
1. Pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Choisissez **Enregistrer**.
**Pour tester la réponse d’intégration `GET`**
+ Choisissez l’onglet **Tester**, puis choisissez **Tester**.
La sortie du test affichera la réponse transformée.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Pour transformer les données d’entrée issues de la méthode `POST`**
1. Choisissez la méthode **POST**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
Le CloudFormation modèle a rempli certains champs de demande d'intégration.
+ Le type d'intégration est Service AWS.
+ Service AWS Il s'agit de DynamoDB.
+ La méthode HTTP est `POST`.
+ L’action est `PutItem`.
+ Le rôle d'exécution permettant à API Gateway de placer un élément dans la table DynamoDB est. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation a créé ce rôle pour permettre à API Gateway de disposer des autorisations minimales nécessaires pour interagir avec DynamoDB.
Le nom de la table DynamoDB n’a pas été spécifié. Vous allez spécifier ce nom dans les étapes suivantes.
1. Pour **Transmission du corps de requête**, sélectionnez **Jamais**.
Cela signifie que l’API rejettera les données avec des types de contenu qui ne disposent pas d’un modèle de mappage.
1. Choisissez **Modèles de mappage**.
1. **Type de contenu** est défini sur `application/json`. Cela signifie que les types de contenu qui ne le sont pas application/json seront rejetés par l'API. Pour plus d’informations sur les comportements de transmission d’intégration, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
1. Saisissez le code suivant dans l’éditeur de texte.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Ce modèle spécifie la table en tant que `data-transformation-tutorial-console-ddb` et définit les éléments en tant que `id`, `type` et `price`. Ces éléments proviennent du corps de la méthode `POST`. Vous pouvez également utiliser un modèle de données pour favoriser la création d’un modèle de mappage. Pour de plus amples informations, veuillez consulter [Demande de validation pour REST APIs dans API Gateway](api-gateway-method-request-validation.md).
1. Choisissez **Enregistrer** pour enregistrer votre modèle de mappage.
**Pour ajouter une réponse de méthode et d’intégration à partir de la méthode `POST`**
Ils CloudFormation ont créé une méthode vide et une réponse d'intégration. Vous allez modifier cette réponse pour fournir plus d’informations. Pour plus d’informations sur la façon de modifier des réponses, consultez [Exemples de mappage de paramètres pour REST APIs dans API Gateway](request-response-data-mappings.md).
1. Dans l’onglet **Réponse d’intégration**, pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis choisissez **Ajouter un modèle de mappage**.
1. Pour **Type de contenu**, saisissez **application/json**.
1. Dans l’éditeur de code, entrez le modèle de mappage de sortie suivant pour envoyer un message de sortie :
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Pour plus d’informations sur les variables de contexte, consultez [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Choisissez **Enregistrer** pour enregistrer votre modèle de mappage.
**Test de la méthode `POST`**
Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Dans le corps de la demande, entrez l’exemple suivant.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Sélectionnez **Tester)**.
La sortie doit afficher votre message de réussite.
Vous pouvez ouvrir la console DynamoDB [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)à l'adresse pour vérifier que l'exemple d'élément figure dans votre tableau.
**Pour supprimer une CloudFormation pile**
1. Ouvrez la CloudFormation console à l'adresse [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Sélectionnez votre CloudFormation pile.
1. Choisissez **Supprimer**, puis confirmez votre choix.
## Configuration de la transformation des données à l'aide de la AWS CLI
[Dans ce didacticiel, vous allez créer une API et une table DynamoDB incomplètes à l'aide du fichier .zip .zip suivant. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) Cette API incomplète possède une ressource `/pets` avec une méthode `GET` intégrée au point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Vous allez créer une méthode `POST` pour vous connecter à une table DynamoDB et utiliser des modèles de mappage pour entrer des données dans une table DynamoDB.
+ Vous allez transformer les données de sortie conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
+ Vous allez créer une méthode `POST` pour permettre à l’utilisateur de publier (`POST`) les informations sur les animaux dans une table Amazon DynamoDB à l’aide d’un modèle de mappage.
**Pour créer une CloudFormation pile**
Téléchargez et décompressez [le modèle de création d'application pour CloudFormation](samples/data-transformation-tutorial-cli.zip).
Pour effectuer le didacticiel suivant, vous avez besoin de l’[AWS Command Line Interface (AWS CLI) version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Pour les commandes longues, un caractère d’échappement (`\`) est utilisé pour les fractionner en plusieurs lignes.
**Note**
Dans Windows, certaines commandes CLI Bash que vous utilisez couramment (par exemple `zip`) ne sont pas prises en charge par les terminaux intégrés du système d’exploitation. [Installez le sous-système Windows pour Linux](https://learn.microsoft.com/en-us/windows/wsl/install) afin d’obtenir une version intégrée avec Windows d’Ubuntu et Bash. Les exemples de commandes CLI de ce guide utilisent le formatage Linux. Les commandes qui incluent des documents JSON en ligne doivent être reformatées si vous utilisez la CLI Windows.
1. Utilisez la commande suivante pour créer la CloudFormation pile.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Utilisez la commande suivante pour voir l'état de votre CloudFormation pile.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Lorsque le statut de votre CloudFormation pile est défini`StackStatus: "CREATE_COMPLETE"`, utilisez la commande suivante pour récupérer les valeurs de sortie pertinentes pour les étapes futures.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Les valeurs de sortie sont les suivantes :
+ ApiRole, qui est le nom du rôle qui permet à API Gateway de placer des éléments dans la table DynamoDB. Pour ce didacticiel, le nom du rôle est `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableNom, qui est le nom de la table DynamoDB. Pour ce didacticiel, le nom de la table est `data-transformation-tutorial-cli-ddb`.
+ ResourceId, qui est l'identifiant de la ressource pour animaux de compagnie dans laquelle les `POST` méthodes `GET` et sont exposées. Pour ce didacticiel, l’ID de ressource est `efg456`.
+ ApiId, qui est l'ID de l'API. Pour ce didacticiel, l’ID d’API est `abc123`.
**Pour tester la méthode `GET` avant la transformation des données**
+ Utilisez la commande suivante pour tester la méthode `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
La sortie du test affichera les informations suivantes.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Vous allez transformer cette sortie conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
**Pour transformer la réponse d’intégration `GET`**
+ Utilisez la commande suivante pour mettre à jour la réponse d’intégration de la méthode `GET`. Remplacez le *rest-api-id* et *resource-id* par vos valeurs.
Utilisez la commande suivante pour créer la réponse d’intégration.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Pour tester la méthode `GET`**
+ Utilisez la commande suivante pour tester la méthode `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
La sortie du test affichera la réponse transformée.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Pour créer une méthode `POST`**
1. Utilisez la commande suivante pour créer une nouvelle méthode sur la ressource `/pets`.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Cette méthode vous permettra d'envoyer des informations relatives aux animaux de compagnie à la table DynamoDB que vous avez créée dans la pile. CloudFormation
1. Utilisez la commande suivante pour créer une Service AWS intégration sur la `POST` méthode.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Utilisez la commande suivante pour créer une réponse de méthode pour un appel réussi de la méthode `POST`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Utilisez la commande suivante pour créer une réponse d’intégration pour l’appel réussi de la méthode `POST`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Pour tester la méthode `POST`**
+ Utilisez la commande suivante pour tester la méthode `POST`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
La sortie affichera le message de réussite.
**Pour supprimer une CloudFormation pile**
+ Utilisez la commande suivante pour supprimer vos CloudFormation ressources.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## CloudFormation Modèle de transformation de données terminé
L'exemple suivant est un CloudFormation modèle complet, qui crée une API et une table DynamoDB avec `/pets` une ressource `GET` avec des méthodes et. `POST`
+ La méthode `GET` obtiendra des données à partir du point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Les données de sortie seront transformées conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
+ La méthode `POST` permettra à l’utilisateur de publier (`POST`) les informations sur les animaux de compagnie dans une table DynamoDB à l’aide d’un modèle de mappage.
### Exemple de CloudFormation modèle
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Exemples d’utilisation de variables pour transformer des modèles de mappage pour API Gateway
Les exemples suivants montrent comment utiliser les variables `$context`, `input` et `util` dans des modèles de mappage. Vous pouvez utiliser une intégration simulée ou une intégration Lambda sans proxy qui renvoie l’événement d’entrée dans API Gateway. Pour obtenir la liste de toutes les variables prises en charge pour les transformations de données, consultez [Variables pour les transformations de données pour API Gateway](api-gateway-mapping-template-reference.md).
## Exemple 1 : transmission de plusieurs variables `$context` au point de terminaison d’intégration
L’exemple suivant illustre un modèle de mappage qui mappe les variables `$context` entrantes aux variables de backend avec des noms légèrement différents dans une charge utile de la demande d’intégration :
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
L’une des variables est une clé d’API. Dans cet exemple, on suppose que la méthode exige une clé d’API.
## Exemple 2 : transmission de tous les paramètres de la demande au point de terminaison d’intégration via des données utiles JSON
L’exemple suivant transmet tous les paramètres de la demande, y compris les paramètres `path`, `querystring` et `header`, au point de terminaison d’intégration via des données utiles JSON :
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
Si une demande possède les paramètres d’entrée suivants :
+ Paramètre de chemin nommé `myparam`
+ Paramètres des chaînes de demande `querystring1=value1,value2`
+ En-têtes `"header1" : "value1"`.
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Exemple 3 : transmission d’une sous-section d’une demande de méthode au point de terminaison d’intégration
L’exemple suivant utilise le paramètre d’entrée `name` pour récupérer uniquement le paramètre `name`, et le paramètre d’entrée `input.json('$')` pour récupérer l’intégralité du corps de la demande de méthode :
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
Pour une demande qui inclut les paramètres de chaîne de demande `name=Bella&type=dog` et le corps suivant :
```
{
"Price" : "249.99",
"Age": "6"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
Ce modèle de mappage supprime le paramètre de chaîne de requête `type=dog`.
Si l'entrée JSON contient des caractères non échappés qui ne peuvent pas être analysés JavaScript, API Gateway peut renvoyer une réponse 400. Appliquez `$util.escapeJavaScript($input.json('$'))` pour que les données d’entrée JSON puissent être analysées correctement.
L’exemple précédent avec application de `$util.escapeJavaScript($input.json('$'))` est le suivant :
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
Dans ce cas, le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## Exemple 4 : Utiliser une JSONPath expression pour transmettre une sous-section d'une demande de méthode au point de terminaison d'intégration
L'exemple suivant utilise les JSONPath expressions pour récupérer uniquement le paramètre d'entrée `name` et le contenu `Age` du corps de la demande :
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
Pour une demande qui inclut les paramètres de chaîne de demande `name=Bella&type=dog` et le corps suivant :
```
{
"Price" : "249.99",
"Age": "6"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body" : "6"
}
```
Ce modèle de mappage supprime le paramètre de chaîne de requête `type=dog` et le champ `Price` du corps.
Si la charge utile d'une demande de méthode contient des caractères non échappés qui ne peuvent pas être analysés, API JavaScript Gateway peut renvoyer une réponse. `400` Appliquez `$util.escapeJavaScript()` pour que les données d’entrée JSON puissent être analysées correctement.
L’exemple précédent avec application de `$util.escapeJavaScript($input.json('$.Age'))` est le suivant :
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
Dans ce cas, le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## Exemple 5 : Utiliser une JSONPath expression pour transmettre des informations relatives à une demande de méthode au point de terminaison d'intégration
L’exemple suivant utilise `$input.params()`, `$input.path()` et `$input.json()` pour envoyer des informations sur une demande de méthode au point de terminaison d’intégration. Ce modèle de mappage utilise la méthode `size()` pour fournir le nombre d’éléments dans une liste.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
Pour une demande qui inclut le paramètre de chemin `123` et le corps suivant :
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
Si la charge utile d'une demande de méthode contient des caractères non échappés qui ne peuvent pas être analysés, API JavaScript Gateway peut renvoyer une réponse. `400` Appliquez `$util.escapeJavaScript()` pour que les données d’entrée JSON puissent être analysées correctement.
L’exemple précédent avec application de `$util.escapeJavaScript($input.json('$.things'))` est le suivant :
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# Variables pour les transformations de données pour API Gateway
Lorsque vous créez un mappage de paramètres, vous pouvez utiliser les variables context comme source de données. Lorsque vous transformez un modèle de mappage, vous pouvez utiliser les variables context, input et util dans les scripts que vous écrivez en [langage VTL (Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html). Pour des exemples de modèles de mappage qui utilisent ces variables de référence, consultez [Exemples d’utilisation de variables pour transformer des modèles de mappage pour API Gateway](api-gateway-mapping-variable-examples.md).
Pour obtenir la liste des variables de référence pour la journalisation des accès, consultez [Variables pour la journalisation des accès pour API Gateway](api-gateway-variables-for-access-logging.md).
## Variables context pour les transformations de données
Vous pouvez utiliser les variables `$context` suivantes (sensibles à la casse) pour les transformations de données.
| Paramètre | Description |
| --- | --- |
| \$1context.accountId | ID de AWS compte du propriétaire de l'API. |
| \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. |
| \$1context.authorizer.claims.property | Propriété des requêtes renvoyées depuis le groupe d’utilisateurs Amazon Cognito une fois que l’appelant de la méthode a été authentifié avec succès. Pour de plus amples informations, veuillez consulter [Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur](apigateway-integrate-with-cognito.md). L’appel de `$context.authorizer.claims` renvoie la valeur null. |
| \$1context.authorizer.principalId | Identifiant utilisateur principal associé au jeton envoyé par le client et retourné par un mécanisme d’autorisation Lambda API Gateway (anciennement appelé Custom Authorizer). Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | Valeur obtenue à l’aide de stringify de la paire clé-valeur spécifiée du mappage `context` renvoyé par une fonction du mécanisme d’autorisation Lambda API Gateway. Par exemple, si le mécanisme d’autorisation retourne le mappage `context` suivant :
l’appel de `$context.authorizer.key` renvoie la chaîne `"value"`, l’appel de `$context.authorizer.numKey` renvoie la chaîne `"1"` et l’appel de `$context.authorizer.boolKey` renvoie la chaîne `"true"`. En effet*property*, le seul caractère spécial pris en charge est le trait de soulignement`(_)`. Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | ID de demande du AWS point de terminaison. |
| \$1context.deploymentId | ID de déploiement de l’API. |
| \$1context.domainName | Nom de domaine complet utilisé pour invoquer l’API. Il doit être identique à l’en-tête `Host` entrant. |
| \$1context.domainPrefix | Première étiquette de `$context.domainName`. |
| \$1context.error.message | Chaîne contenant un message d’erreur API Gateway. Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans la journalisation des accès. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | La valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". |
| \$1context.error.responseType | Un [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans la journalisation des accès. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Chaîne contenant un message d’erreur de validation détaillé. |
| \$1context.extendedRequestId | L’ID généré et attribué par API Gateway à la demande d’API. L’ID de requête étendu contient des informations utiles pour le débogage et le dépannage. |
| \$1context.httpMethod | Méthode HTTP utilisée. Les valeurs valides sont les suivantes : `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` et `PUT`. |
| \$1context.identity.accountId | L'ID de AWS compte associé à la demande. |
| \$1context.identity.apiKey | Pour les méthodes d’API qui nécessitent une clé d’API, cette variable est la clé d’API associée à la demande de méthode. Pour les méthodes qui ne nécessitent aucune clé d’API, cette variable est null. Pour de plus amples informations, veuillez consulter [Plans d'utilisation et clés d'API pour REST APIs dans API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | ID de la clé d’API associé à une demande d’API qui nécessite une clé d’API. |
| \$1context.identity.caller | Identifiant principal de l’appelant qui a signé la demande. Pris en charge pour les ressources qui utilisent l’autorisation IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Liste séparée par des virgules de tous les fournisseurs d’authentification Amazon Cognito utilisés par l’appelant à l’origine de la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Par exemple, pour une identité provenant d’un groupe d’utilisateurs Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Pour plus d’informations sur les fournisseurs d’authentification Amazon Cognito disponibles, consultez [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) dans le *Guide du développeur Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Type d’authentification Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Les valeurs possibles incluent `authenticated` pour les identités authentifiées et `unauthenticated` pour les identités non authentifiées. |
| \$1context.identity.cognitoIdentityId | ID d’identité Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID de groupe d’identités Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID d’organisation AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | Adresse IP source de la connexion TCP immédiate envoyant la demande au point de terminaison API Gateway. |
| \$1context.identity.clientCert.clientCertPem | Certificat client codé PEM présenté par le client lors de l’authentification TLS mutuelle. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.subjectDN | Nom distinctif de l’objet du certificat présenté par un client. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.issuerDN | Nom distinctif de l’émetteur du certificat présenté par un client. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.serialNumber | Numéro de série du certificat. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.validity.notBefore | Date avant laquelle le certificat n’est pas valide. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.validity.notAfter | Date après laquelle le certificat n’est pas valide. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.vpcId | ID du VPC qui fait la demande au point de terminaison API Gateway. |
| \$1context.identity.vpceId | ID du point de terminaison de VPC qui envoie la demande au point de terminaison API Gateway. Présent uniquement lorsque vous disposez d’une API privée. |
| \$1context.identity.user | Identifiant principal de l’utilisateur qui sera autorisé à accéder aux ressources. Pris en charge pour les ressources qui utilisent l’autorisation IAM. |
| \$1context.identity.userAgent | En-tête [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) de l’appelant d’API. |
| \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. Pour de plus amples informations, veuillez consulter [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Renvoie `true` si la demande a été dirigée vers le canary et `false` si la demande n’a pas été dirigée vers le canary. Présent uniquement lorsqu’un canary a été activé. |
| \$1context.path | Chemin d’accès de la demande. Par exemple, pour une URL de demande autre que de proxy de https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, la valeur \$1context.path est /\$1stage\$1/root/child. |
| \$1context.protocol | Protocole de demande, par exemple, HTTP/1.1. API Gateway APIs peut accepter les requêtes HTTP/2, mais API Gateway envoie des demandes aux intégrations de backend à l'aide du protocole HTTP/1.1. Par conséquent, le protocole de requête est enregistré comme HTTP/1.1 même si un client envoie une requête qui utilise HTTP/2. |
| \$1context.requestId | Un ID pour la demande. Les clients peuvent remplacer cet ID de demande. Utiliser `$context.extendedRequestId` pour un ID de demande unique généré par API Gateway. |
| \$1context.requestOverride.header.header\$1name | Remplacement de l’en-tête de la requête. Si ce paramètre est défini, il contient les en-têtes à utiliser à la place des **HTTP Headers (En-têtes HTTP)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Remplacement du chemin de la requête. Si ce paramètre est défini, il contient le chemin de requête à utiliser à la place des **URL Path Parameters (Paramètres de chemin d’URL)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Remplacement de la chaîne d’interrogation de la requête. Si ce paramètre est défini, il contient les chaînes d’interrogation de la requête à utiliser à la place des **URL Query String Parameters (Paramètres de chaîne de requête d’URL)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | Remplacement de l’en-tête de la réponse. Si ce paramètre est défini, il contient l’en-tête qui est renvoyé à la place du Response header (En-tête de réponse) qui est défini comme le Default mapping (Mappage par défaut) dans le volet Integration Response (Réponse d’intégration). Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Remplacement du code de statut de la réponse. Si ce paramètre est défini, il contient le code du statut qui est renvoyé à la place du Method response status (Statut de la réponse de méthode) qui est défini comme le Default mapping (Mappage par défaut) dans le volet Integration Response (Réponse d’intégration). Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Durée des demandes au format [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Heure de la demande au format [Epoch](https://en.wikipedia.org/wiki/Unix_time), en millisecondes. |
| \$1context.resourceId | Identifiant attribué par API Gateway à votre ressource. |
| \$1context.resourcePath | Chemin de votre ressource. Par exemple, pour l’URI de demande autre que de proxy de `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, la valeur `$context.resourcePath` est `/root/child`. Pour de plus amples informations, veuillez consulter [Didacticiel : création d’une API REST avec une intégration HTTP sans proxy](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | Étape de déploiement de la demande d’API (par exemple, `Beta` ou `Prod`). |
| \$1context.wafResponseCode | Réponse reçue de [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` ou `WAF_BLOCK`. N’est pas défini si l’étape n’est pas associée à une liste ACL web. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | ARN complet de la liste ACL web utilisée pour déterminer s’il convient d’autoriser ou de bloquer la demande. N’est pas défini si l’étape n’est pas associée à une liste ACL web. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md). |
## Variables d’entrée
Vous pouvez utiliser les variables `$input` suivantes (sensibles à la casse) pour faire référence aux données utiles et aux paramètres de la demande de méthode. Les fonctions suivantes sont disponibles :
| Variable et fonction | Description |
| --- | --- |
| \$1input.body | Renvoie la charge utile de la demande brute sous forme de chaîne. Vous pouvez utiliser `$input.body` pour conserver des nombres à virgule flottante entiers, tels que `10.00`. |
| \$1input.json(x) | Cette fonction évalue une JSONPath expression et renvoie les résultats sous forme de chaîne JSON. Par exemple, `$input.json('$.pets')` renvoie une chaîne JSON représentant la structure `pets`. Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath). |
| \$1input.params() | Renvoie une carte de tous les paramètres de demande. Nous vous recommandons d’utiliser `$util.escapeJavaScript` pour désinfecter le résultat afin d’éviter une attaque potentielle par injection. Pour un contrôle total de la désinfection des requêtes, utilisez une intégration proxy sans modèle et gérez la désinfection des requêtes dans votre intégration. |
| \$1input.params(x) | Renvoie la valeur d’un paramètre de demande de méthode à partir du chemin, de la chaîne de requête ou d’une valeur d’en-tête (dans cet ordre) avec une chaîne de nom de paramètre `x`. Nous vous recommandons d’utiliser `$util.escapeJavaScript` pour désinfecter le paramètre afin d’éviter une attaque potentielle par injection. Pour un contrôle total de la désinfection des paramètres, utilisez une intégration proxy sans modèle et gérez la désinfection des requêtes dans votre intégration. |
| \$1input.path(x) | Prend une chaîne JSONPath d'expression (`x`) et renvoie une représentation du résultat sous forme d'objet JSON. Cela vous permet d’accéder aux éléments de la charge utile et de les manipuler en mode natif en [langage VTL (Apache Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html). Par exemple, si l’expression `$input.path('$.pets')` renvoie un objet comme suit :
`$input.path('$.pets').size()` renvoie `"3"`. Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath). |
## Variables d’étape
Vous pouvez utiliser les variables d'étape suivantes comme espaces réservés pour ARNs et URLs dans les intégrations de méthodes. Pour de plus amples informations, veuillez consulter [Utilisation de variables d’étape pour une API REST dans API Gateway](stage-variables.md).
| Syntaxe | Description |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'] ou \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*représente le nom d'une variable d'étape. |
## Variables util
Vous pouvez utiliser les variables util `$util` suivantes (sensibles à la casse) pour les modèles de mappage. Sauf indication contraire, le jeu de caractères par défaut est UTF-8.
| Fonction | Description |
| --- | --- |
| \$1util.escapeJavaScript() | Échape les caractères d'une chaîne en utilisant des règles de JavaScript chaîne. Cette fonction convertit tout guillemet simple (`'`) en guillemet d’échappement (`\'`). Cependant, les guillemets simples d’échappement ne sont pas valides en JSON. Par conséquent, lorsque la sortie de cette fonction est utilisée dans une propriété JSON, vous devez reconvertir les guillemets simples d’échappement (`\'`) en guillemets simples (`'`), comme illustré dans l’exemple suivant :
|
| \$1util.parseJson() | Prend la chaîne JSON (obtenue à l’aide de stringify) et renvoie une représentation objet du résultat. Vous pouvez utiliser le résultat de cette fonction pour accéder aux éléments de la charge utile et les manipuler en mode natif en langage VTL (Apache Velocity Template Language). Par exemple, si vous avez la charge utile suivante :
|
| \$1util.urlEncode() | Convertit une chaîne au format « application/ x-www-form-urlencoded ». |
| \$1util.urlDecode() | Décode une chaîne « application/ x-www-form-urlencoded ». |
| \$1util.base64Encode() | Encode les données dans une chaîne encodée en base64. |
| \$1util.base64Decode() | Décode les données d’une chaîne encodée en base64. |
# Réponses de passerelle pour REST APIs dans API Gateway
Une réponse de passerelle est identifiée par un type de réponse défini par API Gateway. La réponse se compose d’un code d’état HTTP, d’un ensemble d’en-têtes supplémentaires qui sont spécifiés par des mappages de paramètres et de données utiles qui sont générées par un modèle de mappage non [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html).
Dans l'API REST API Gateway, une réponse de passerelle est représentée par le [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Dans OpenAPI, une `GatewayResponse` instance est décrite par l'extension [x-amazon-apigateway-gateway-Respones.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md).
Pour activer une réponse de passerelle, vous configurez une réponse de passerelle pour un [type de réponse pris en charge](supported-gateway-response-types.md) au niveau de l’API. Chaque fois qu’API Gateway renvoie une réponse de ce type, les mappages d’en-tête et les modèles de mappage de charge utile définis dans la réponse de passerelle sont appliqués pour renvoyer les résultats mappés à l’appelant de l’API.
Dans la section suivante, nous allons voir comment configurer des réponses de passerelle à l’aide de la console API Gateway et de l’API REST API Gateway.
## Configuration de réponses de passerelle pour personnaliser des réponses d’erreur
Si API Gateway ne parvient pas à traiter une demande entrante, le service renvoie au client une réponse d’erreur sans transmettre la demande au backend d’intégration. Par défaut, la réponse d’erreur contient un court message d’erreur descriptif. Par exemple, si vous tentez d’appeler une opération sur une ressource d’API non définie, vous recevez une réponse d’erreur avec le message `{ "message": "Missing Authentication Token" }`. Si vous n’êtes pas encore familiarisé avec API Gateway, il peut être difficile de comprendre ce qui s’est réellement passé.
Pour certaines des réponses d’erreur, API Gateway autorise les développeurs d’API à effectuer une personnalisation pour renvoyer les réponses dans des formats différents. Pour l’exemple `Missing Authentication Token`, vous pouvez ajouter un conseil à la charge utile de réponse d’origine avec les causes possibles, comme dans cet exemple : `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`.
Lorsque votre API assure la médiation entre un échange externe et le AWS Cloud, vous utilisez des modèles de mappage VTL pour les demandes d'intégration ou les réponses d'intégration afin de mapper la charge utile d'un format à un autre. Toutefois, les modèles de mappage VTL fonctionnent uniquement pour les demandes valides avec des réponses positives.
Pour les demandes non valides, API Gateway contourne complètement l’intégration et renvoie une réponse d’erreur. Vous devez utiliser la personnalisation pour rendre les réponses d’erreur dans un format conforme pour l’échange. Ici, la personnalisation est rendue dans un modèle de mappage non-VTL prenant en charge uniquement les substitutions de variables simples.
Pour désigner de manière générale les réponses d’erreur générées par API Gateway à des réponses générées par API Gateway, nous les appelons *réponses de passerelle*. Cela permet de distinguer les réponses générées par API Gateway des réponses d’intégration. Un modèle de mappage de réponse de passerelle peut accéder à des valeurs de variable `$context` et des valeurs de propriété `$stageVariables`, ainsi qu’à des paramètres de demande de méthode, sous la forme `method.request.param-position.param-name`.
Pour plus d’informations sur les variables `$context`, consultez [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference). Pour plus d’informations sur `$stageVariables`, consultez [Variables d’étape](api-gateway-mapping-template-reference.md#stagevariables-template-reference). Pour plus d’informations sur les paramètres de demande de méthode, reportez-vous à la section [Variables d’entrée](api-gateway-mapping-template-reference.md#input-variable-reference).
**Topics**
+ [
## Configuration de réponses de passerelle pour personnaliser des réponses d’erreur
](#customize-gateway-responses)
+ [
# Configurer une réponse de passerelle pour une API REST à l’aide de la console API Gateway
](set-up-gateway-response-using-the-console.md)
+ [
# Configuration d’une réponse de passerelle à l’aide de l’API REST API Gateway
](set-up-gateway-response-using-the-api.md)
+ [
# Configuration d’une personnalisation de réponse de passerelle dans OpenAPI
](set-up-gateway-responses-in-swagger.md)
+ [
# Types de réponse de passerelle pour API Gateway
](supported-gateway-response-types.md)
# Configurer une réponse de passerelle pour une API REST à l’aide de la console API Gateway
L’exemple suivant montre comment configurer une réponse de passerelle pour une API REST à l’aide de la console API Gateway.
**Pour personnaliser une réponse de passerelle à 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 REST.
1. Dans le panneau de navigation principal, choisissez **Réponses de la passerelle**.
1. Choisissez un type de réponse, puis choisissez **Modifier**. Dans cette procédure, nous allons utiliser **Jeton d’authentification manquant** comme exemple.
1. Vous pouvez modifier le **Code de statut** généré par API Gateway pour renvoyer un autre code de statut qui répond aux exigences de votre API. Dans cet exemple, la personnalisation modifie le code de statut de la valeur par défaut (`403`) à `404`, car ce message d’erreur est émis lorsqu’un client appelle une ressource non prise en charge ou non valide qui peut être considérée comme non trouvée.
1. Pour renvoyer des en-têtes personnalisés, choisissez **Ajouter un en-tête de réponse** sous **En-têtes de réponse**. À titre d’illustration, nous allons ajouter les en-têtes personnalisés suivants :
```
Access-Control-Allow-Origin:'a.b.c'
x-request-id:method.request.header.x-amzn-RequestId
x-request-path:method.request.path.petId
x-request-query:method.request.querystring.q
```
Dans les mappages d’en-tête précédents, un nom de domaine statique (`'a.b.c'`) est mappé à l’en-tête `Allow-Control-Allow-Origin` pour autoriser l’accès CORS à l’API, l’en-tête de demande d’entrée de `x-amzn-RequestId` est mappé à `request-id` dans la réponse, la variable de chemin `petId` de la demande entrante est mappée à l’en-tête `request-path` dans la réponse et le paramètre de requête `q` de la demande d’origine est mappé à l’en-tête `request-query` de la réponse.
1. Sous **Modèles de réponse**, conservez `application/json` pour le **Type de contenu** et saisissez le modèle de mappage de corps suivant dans l’éditeur **Modèle de mappage de corps** :
```
{
"message":"$context.error.messageString",
"type": "$context.error.responseType",
"statusCode": "'404'",
"stage": "$context.stage",
"resourcePath": "$context.resourcePath",
"stageVariables.a": "$stageVariables.a"
}
```
Cet exemple montre comment mapper les propriétés `$context` et `$stageVariables` aux propriétés du corps de demande de passerelle.
1. Sélectionnez **Enregistrer les modifications**.
1. Déployez l’API dans une étape nouvelle ou existante.
Testez la réponse de votre passerelle en appelant la commande CURL suivante, en supposant que l’URL d’invocation de la méthode d’API correspondante est `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}` :
```
curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1
```
Comme le paramètre de chaîne de requête supplémentaire `q=1` n’est pas compatible avec l’API, une erreur est renvoyée par la réponse de passerelle spécifiée. Vous devriez obtenir une réponse de passerelle semblable à ce qui suit :
```
> GET /custErr/pets/5?q=1 HTTP/1.1
Host: o81lxisefl.execute-api.us-east-1.amazonaws.com
User-Agent: curl/7.51.0
Accept: */*
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 334
Connection: keep-alive
Date: Tue, 02 May 2017 03:15:47 GMT
x-amzn-RequestId: 123344566
Access-Control-Allow-Origin: a.b.c
x-amzn-ErrorType: MissingAuthenticationTokenException
header-1: static
x-request-query: 1
x-request-path: 5
X-Cache: Error from cloudfront
Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA==
{
"message":"Missing Authentication Token",
"type": MISSING_AUTHENTICATION_TOKEN,
"statusCode": '404',
"stage": custErr,
"resourcePath": /pets/{petId},
"stageVariables.a": a
}
```
L’exemple précédent suppose que le serveur principal d’API est [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets) et que l’API a une variable d’étape `a` définie.
# Configuration d’une réponse de passerelle à l’aide de l’API REST API Gateway
Avant de personnaliser une réponse de passerelle à l’aide de l’API REST API Gateway, vous devez avoir déjà créé une API et obtenu son identifiant. Pour extraire l’identifiant de l’API, vous pouvez suivre la relation de lien [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) et examiner le résultat.
**Pour personnaliser une réponse de passerelle à l’aide de l’API REST API Gateway**
1. Pour remplacer une [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)instance entière, appelez l'action [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html). Spécifiez la valeur souhaitée pour [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) dans le paramètre de chemin d’URL et indiquez dans la charge utile de la requête les mappages [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) et [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates).
1. Pour mettre à jour une partie d’une instance `GatewayResponse`, appelez l’action [GatewayResponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html). Spécifiez une valeur `responseType` souhaitée dans le paramètre de chemin d’URL et indiquez dans la charge utile de la requête les propriétés `GatewayResponse` individuelles que vous souhaitez, par exemple, le mappage `responseParameters` ou `responseTemplates`.
# Configuration d’une personnalisation de réponse de passerelle dans OpenAPI
Vous pouvez utiliser l’extension `x-amazon-apigateway-gateway-responses` au niveau racine de l’API pour personnaliser des réponses de passerelle dans OpenAPI. La définition OpenAPI suivante montre un exemple de personnalisation [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)du type. `MISSING_AUTHENTICATION_TOKEN`
```
"x-amazon-apigateway-gateway-responses": {
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.x-request-path": "method.input.params.petId",
"gatewayresponse.header.x-request-query": "method.input.params.q",
"gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'",
"gatewayresponse.header.x-request-header": "method.input.params.Accept"
},
"responseTemplates": {
"application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}"
}
}
```
Dans cet exemple, la personnalisation remplace la valeur par défaut du code du statut (`403`) par `404`. La personnalisation ajoute également à la réponse de passerelle quatre paramètres d’en-tête et un modèle de mappage de corps pour le type de média `application/json`.
# Types de réponse de passerelle pour API Gateway
API Gateway expose les réponses de passerelle suivantes pour personnalisation par les développeurs d’API.
| Type de réponse de passerelle | Code de statut par défaut | Description |
| --- | --- | --- |
| ACCESS\$1DENIED | 403 | Réponse de passerelle pour un échec d’autorisation, par exemple, lorsque l’accès est refusé par un mécanisme d’autorisation personnalisée ou Amazon Cognito. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| API\$1CONFIGURATION\$1ERROR | 500 | Réponse de passerelle pour une configuration d’API non valide, y compris une adresse de point de terminaison non valide soumise, l’échec du décodage base64 sur des données binaires lorsque la prise en charge binaire est activée, ou un mappage de réponse d’intégration qui ne peut correspondre à aucun modèle alors qu’aucun modèle par défaut n’est configuré. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_5XX`. |
| AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | Réponse de passerelle pour un échec de connexion à un mécanisme d’autorisation personnalisée ou Amazon Cognito. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_5XX`. |
| AUTHORIZER\$1FAILURE | 500 | Réponse de passerelle quand un mécanisme d’autorisation personnalisée ou Amazon Cognito n’a pas pu authentifier l’appelant. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_5XX`. |
| BAD\$1REQUEST\$1PARAMETERS | 400 | Réponse de passerelle quand le paramètre de demande ne peut pas être validé selon un valideur de demande activé. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| BAD\$1REQUEST\$1BODY | 400 | Réponse de passerelle quand le corps de demande ne peut pas être validé selon un valideur de demande activé. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| DEFAULT\$14XX | Null | Réponse de passerelle par défaut pour un type de réponse non spécifié avec le code de statut `4XX`. La modification du code de statut de cette réponse de passerelle de rechange modifie les codes de statut de toutes les autres réponses `4XX` sur une nouvelle valeur. La réinitialisation de ce code de statut à null rétablit les valeurs d’origine des codes de statut de toutes les autres réponses `4XX`. [AWS WAF les réponses personnalisées](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) ont priorité sur les réponses de passerelle personnalisées. |
| DEFAULT\$15XX | Null | Réponse de passerelle par défaut pour un type de réponse non spécifié avec un code de statut `5XX`. La modification du code de statut de cette réponse de passerelle de rechange modifie les codes de statut de toutes les autres réponses `5XX` sur une nouvelle valeur. La réinitialisation de ce code de statut à null rétablit les valeurs d’origine des codes de statut de toutes les autres réponses `5XX`. |
| EXPIRED\$1TOKEN | 403 | La réponse de la passerelle à une erreur d'expiration du jeton d' AWS authentification. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| INTEGRATION\$1FAILURE | 504 | Réponse de passerelle pour une erreur d’échec d’intégration. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_5XX`. |
| INTEGRATION\$1TIMEOUT | 504 | Réponse de passerelle pour une erreur d’intégration expirée. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_5XX`. |
| INVALID\$1API\$1KEY | 403 | Réponse de passerelle pour une clé d’API non valide soumise pour une méthode nécessitant une clé d’API. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| INVALID\$1SIGNATURE | 403 | Réponse de la passerelle à une erreur de AWS signature non valide. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| MISSING\$1AUTHENTICATION\$1TOKEN | 403 | Réponse de passerelle pour une erreur de jeton d’authentification manquant, y compris les cas où le client tente d’appeler une méthode ou une ressource d’API non prise en charge. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| QUOTA\$1EXCEEDED | 429 | Réponse de passerelle pour une erreur de dépassement de quota de plan d’utilisation. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| REQUEST\$1TOO\$1LARGE | 413 | Réponse de passerelle pour une erreur de demande trop volumineuse. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur `HTTP content length exceeded 10485760 bytes`. |
| RESOURCE\$1NOT\$1FOUND | 404 | Réponse de passerelle quand API Gateway ne peut pas trouver la ressource spécifiée après qu’une demande d’API a transmis une authentification et une autorisation, sauf pour une authentification et une autorisation de clé d’API. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| THROTTLED | 429 | Réponse de passerelle quand des limitations d’un plan d’utilisation sont dépassées au niveau de la méthode, de l’étape ou du compte. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| UNAUTHORIZED | 401 | Réponse de passerelle quand le mécanisme d’autorisation personnalisée ou Amazon Cognito n’a pas pu authentifier l’appelant. |
| UNSUPPORTED\$1MEDIA\$1TYPE | 415 | Réponse de passerelle quand une charge utile est d’un type de média non pris en charge, si le comportement de transmission strict est activé. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. |
| WAF\$1FILTERED | 403 | La réponse de passerelle quand une demande est bloquée par AWS WAF. Si le type de réponse n’est pas spécifié, cette réponse est définie par défaut sur le type `DEFAULT_4XX`. [AWS WAF les réponses personnalisées](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) ont priorité sur les réponses de passerelle personnalisées. |
# CORS pour REST 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 cross-origin lancées à partir de scripts s’exécutant dans le navigateur. Pour plus d’informations, consultez [What is CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)
## Activation ou non de la prise en charge de CORS
Une demande HTTP *cross-origin* est une demande effectuée pour :
+ Un autre *domaine* (par exemple, de `example.com` à `amazondomains.com`)
+ Un autre *sous-domaine* (par exemple, de `example.com` à `petstore.example.com`)
+ Un autre *port* (par exemple, de `example.com` à `example.com:10777`)
+ Un autre *protocole* (par exemple, de `https://example.com` à `http://example.com`)
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.
Les demandes HTTP cross-origin peuvent être réparties en deux types : les demandes *simples* et les demandes *non simples*.
## Activation de CORS pour une demande simple
Une demande HTTP est *simple* si toutes les conditions suivantes sont réunies :
+ Elle est émise par rapport à une ressource d’API qui autorise uniquement les demandes `GET`, `HEAD` et `POST`.
+ S’il s’agit d’une demande de la méthode `POST`, elle doit inclure un en-tête `Origin`.
+ Le type de contenu de la charge utile de la demande est `text/plain`, `multipart/form-data` ou `application/x-www-form-urlencoded`.
+ La demande ne contient pas d’en-têtes personnalisés.
+ Les exigences supplémentaires répertoriées dans la [documentation CORS Mozilla pour les demandes simples](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests).
Pour les demandes de méthode `POST` cross-origin simples, la réponse de votre ressource doit inclure l’en-tête `Access-Control-Allow-Origin: '*'` ou `Access-Control-Allow-Origin:'origin'`.
Toutes les autres demandes HTTP cross-origin sont des demandes *non simples*.
## Activation de CORS pour une demande non simple
Si les ressources de votre API reçoivent des demandes non simples, vous devez activer une prise en charge de CORS supplémentaire en fonction de votre type d’intégration.
### Activation de CORS pour les intégrations autres que de proxy
Pour de telles intégrations, le [protocole CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) exige du navigateur qu’il envoie une demande en amont au serveur et attende l’approbation (ou une demande d’informations d’identification) du serveur avant d’envoyer la demande réelle. Vous devez configurer votre API pour envoyer une réponse appropriée à la demande en amont.
Pour créer une réponse en amont :
1. Créez une méthode `OPTIONS` avec une intégration simulée.
1. Ajoutez les en-têtes de réponse suivants à la réponse de la méthode 200 :
+ `Access-Control-Allow-Headers`
+ `Access-Control-Allow-Methods`
+ `Access-Control-Allow-Origin`
1. Définissez le comportement de transfert direct sur `NEVER`. Dans ce cas, la demande de méthode d’un type de contenu non mappé sera rejetée en renvoyant une réponse HTTP 415 Type de support non pris en charge. Pour de plus amples informations, veuillez consulter [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
1. Entrez des valeurs pour les en-têtes de réponse. Pour autoriser toutes les origines, toutes les méthodes et les en-têtes communs, utilisez les valeurs d’en-tête suivantes :
+ `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`
+ `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'`
+ `Access-Control-Allow-Origin: '*'`
Après avoir créé la demande en amont, vous devez renvoyer l’en-tête `Access-Control-Allow-Origin: '*'` ou `Access-Control-Allow-Origin:'origin'` pour toutes les méthodes compatibles CORS pour toutes les 200 réponses, au moins.
### Activation de CORS pour les intégrations sans proxy à l'aide du AWS Management Console
Vous pouvez utiliser le AWS Management Console pour activer CORS. API Gateway crée une méthode `OPTIONS` et ajoute l’en-tête `Access-Control-Allow-Origin` à vos réponses d’intégration de méthode existantes. Cela ne fonctionne pas toujours et vous devez parfois modifier manuellement la réponse d’intégration pour renvoyer l’en-tête `Access-Control-Allow-Origin` pour toutes les méthodes compatibles CORS pour toutes 200 réponses, au moins.
Si les types de médias binaires sont définis sur `*/*` pour votre API, lorsqu’API Gateway crée une méthode `OPTIONS`, remplacez `contentHandling` par `CONVERT_TO_TEXT`.
La commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) suivante modifie le paramètre `contentHandling` en `CONVERT_TO_TEXT` pour une demande d’intégration :
```
aws apigateway update-integration \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
La [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)commande suivante change la valeur `contentHandling` en `CONVERT_TO_TEXT` pour une réponse d'intégration :
```
aws apigateway update-integration-response \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--status-code 200 \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
## Activation de la prise en charge de CORS pour les intégrations de proxy
Pour une intégration de proxy Lambda ou de proxy HTTP, votre backend est chargé de renvoyer les en-têtes `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods` et `Access-Control-Allow-Headers`, car une intégration de proxy ne renvoie pas de réponse d’intégration.
Les exemples de fonctions Lambda suivants renvoient les en-têtes CORS requis :
------
#### [ Node.js ]
```
export const handler = async (event) => {
const response = {
statusCode: 200,
headers: {
"Access-Control-Allow-Headers" : "Content-Type",
"Access-Control-Allow-Origin": "https://www.example.com",
"Access-Control-Allow-Methods": "OPTIONS,POST,GET"
},
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};
```
------
#### [ Python 3 ]
```
import json
def lambda_handler(event, context):
return {
'statusCode': 200,
'headers': {
'Access-Control-Allow-Headers': 'Content-Type',
'Access-Control-Allow-Origin': 'https://www.example.com',
'Access-Control-Allow-Methods': 'OPTIONS,POST,GET'
},
'body': json.dumps('Hello from Lambda!')
}
```
------
**Topics**
+ [
## Activation ou non de la prise en charge de CORS
](#apigateway-cors-request-types)
+ [
## Activation de CORS pour une demande simple
](#apigateway-cors-simple-request)
+ [
## Activation de CORS pour une demande non simple
](#apigateway-enable-cors-non-simple)
+ [
## Activation de la prise en charge de CORS pour les intégrations de proxy
](#apigateway-enable-cors-proxy)
+ [
# Activation de CORS sur une ressource à l’aide de la console API Gateway
](how-to-cors-console.md)
+ [
# Activation de CORS sur une ressource à l’aide de l’API d’importation API Gateway
](enable-cors-for-resource-using-swagger-importer-tool.md)
+ [
# Test de CORS pour une API API Gateway
](apigateway-test-cors.md)
# Activation de CORS sur une ressource à l’aide de la console API Gateway
Vous pouvez utiliser la console API Gateway afin d’activer la prise en charge de CORS pour une ou toutes les méthodes sur une ressource d’API REST que vous avez créée. Après avoir activé la prise en charge de CORS, définissez le comportement de transfert direct sur `NEVER`. Dans ce cas, la demande de méthode d’un type de contenu non mappé sera rejetée en renvoyant une réponse HTTP 415 Type de support non pris en charge. Pour de plus amples informations, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
**Important**
Les ressources peuvent contenir des ressources enfants. L’activation de la prise en charge de CORS pour une ressource et ses méthodes ne permet pas de l’activer de façon récursive pour les ressources enfants et leurs méthodes.
**Pour activer la prise en charge de CORS sur une ressource d’API REST**
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.
1. Sélectionnez une ressource sous **Resources**.
1. Dans la section **Détails de la ressource**, choisissez **Activer CORS**.
![\[Dans le volet Ressources, sélectionnez Activer CORS.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png)
1. Dans la zone **Activer CORS**, procédez comme suit :
1. (Facultatif) Si vous avez créé une réponse de passerelle personnalisée et que vous souhaitez activer la prise en charge de CORS pour une réponse, sélectionnez une réponse de passerelle.
1. Sélectionnez chaque méthode pour activer la prise en charge de CORS. CORS doit être activé sur la méthode `OPTION`.
Si vous activez la prise en charge de CORS pour une méthode `ANY`, CORS est activé pour toutes les méthodes.
1. Dans le champ de saisie **Access-Control-Allow-Headers**, entrez la chaîne statique d’une liste d’en-têtes séparés par des virgules que le client doit envoyer dans la demande réelle de la ressource. Utilisez la liste d’en-têtes `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` fournie par la console ou spécifiez vos propres en-têtes.
1. Utilisez la valeur `'*'` fournie par la console comme valeur d’en-tête **Access-Control-Allow-Origin** afin d’autoriser les demandes d’accès de toutes les origines, ou spécifiez une origine autorisée à accéder à la ressource.
1. Choisissez **Enregistrer**.
![\[Choix des en-têtes autorisés\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png)
**Important**
Lors de l’application des instructions ci-dessus à la méthode `ANY` dans une intégration de proxy, aucun en-tête CORS applicable n’est défini. Au lieu de cela, votre backend doit renvoyer les en-têtes CORS applicables, tels que `Access-Control-Allow-Origin`.
Une fois que CORS est activé sur la méthode `GET`, une méthode `OPTIONS` est ajoutée à la ressource, si elle n’existe pas déjà. La réponse `200` de la méthode `OPTIONS` est automatiquement configurée pour renvoyer les trois en-têtes `Access-Control-Allow-*` afin d’effectuer l’établissement de liaison en amont. En outre, la méthode réelle (`GET`) est également configurée par défaut pour renvoyer l’en-tête `Access-Control-Allow-Origin` dans sa réponse 200. En ce qui concerne les autres types de réponses, vous devrez les configurer manuellement pour renvoyer l’en-tête `Access-Control-Allow-Origin'` avec la valeur ’\$1’ ou les origines spécifiques, si vous ne souhaitez pas renvoyer l’erreur `Cross-origin access`.
Une fois la prise en charge de CORS activée sur votre ressource, vous devez déployer ou redéployer l’API pour que les nouveaux paramètres prennent effet. Pour de plus amples informations, veuillez consulter [Création d’un déploiement](set-up-deployments.md#create-deployment).
**Note**
Si vous ne parvenez pas à activer la prise en charge de CORS sur votre ressource après avoir suivi la procédure, nous vous recommandons de comparer votre configuration CORS à l’exemple de ressource d’API `/pets`. Pour apprendre à créer l’exemple d’API, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
# Activation de CORS sur une ressource à l’aide de l’API d’importation API Gateway
Si vous utilisez la fonction [API Gateway Import API (API d’importation API Gateway)](api-gateway-import-api.md), vous pouvez configurer la prise en charge de CORS à l’aide d’un fichier OpenAPI. Vous devez d’abord définir une méthode `OPTIONS` dans votre ressource, qui renvoie les en-têtes requis.
**Note**
Les navigateurs Web s'attendent Access-Control-Allow-Headers à ce que Access-Control-Allow-Origin des en-têtes soient configurés dans chaque méthode d'API qui accepte les requêtes CORS. En outre, certains navigateurs effectuent d’abord une demande HTTP auprès d’une méthode `OPTIONS` dans la même ressource, puis s’attendent à recevoir les mêmes en-têtes.
## Exemple de méthode `Options`
L’exemple suivant crée une méthode `OPTIONS` pour une intégration simulée.
------
#### [ OpenAPI 3.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
tags:
- CORS
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
type: mock
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
```
------
#### [ OpenAPI 2.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
consumes:
- "application/json"
produces:
- "application/json"
tags:
- CORS
x-amazon-apigateway-integration:
type: mock
requestTemplates: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
Une fois que vous avez configuré la méthode `OPTIONS` pour votre ressource, vous pouvez ajouter les en-têtes requis aux autres méthodes de la même ressource qui doivent accepter des demandes CORS.
1. Déclarez les en-têtes **Access-Control-Allow-Origin** et **Access-Control-Allow-Headers** pour les types de réponse.
------
#### [ OpenAPI 3.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
1. Dans la balise `x-amazon-apigateway-integration`, configurez le mappage de ces en-têtes à vos valeurs statiques :
------
#### [ OpenAPI 3.0 ]
```
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
responseTemplates:
application/json: |
{}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
```
------
## Exemple d’API
L’exemple suivant crée une API complète avec une méthode `OPTIONS` et une méthode `GET` avec une intégration `HTTP`.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "cors-api"
description: "cors-api"
version: "2024-01-16T18:36:01Z"
servers:
- url: "/{basePath}"
variables:
basePath:
default: "/test"
paths:
/:
get:
operationId: "GetPet"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
components:
schemas:
Empty:
type: "object"
```
------
#### [ OpenAPI 2.0 ]
```
swagger: "2.0"
info:
description: "cors-api"
version: "2024-01-16T18:36:01Z"
title: "cors-api"
basePath: "/test"
schemes:
- "https"
paths:
/:
get:
operationId: "GetPet"
produces:
- "application/json"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
definitions:
Empty:
type: "object"
```
------
# Test de CORS pour une API API Gateway
Vous pouvez tester la configuration CORS de votre API en appelant votre API et en vérifiant les en-têtes CORS dans la réponse. La commande `curl` suivante envoie une demande OPTIONS à une API déployée.
```
curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}
```
```
< HTTP/1.1 200 OK
< Date: Tue, 19 May 2020 00:55:22 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token
< x-amz-apigw-id: Abcd=
< Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT
```
Les en-têtes `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers` et `Access-Control-Allow-Methods` dans la réponse montrent que l’API prend en charge CORS. Pour de plus amples informations, veuillez consulter [CORS pour REST APIs dans API Gateway](how-to-cors.md).
# Types de médias binaires pour REST APIs dans API Gateway
Dans API Gateway, la demande et la réponse d’API peuvent avoir une charge utile textuelle ou binaire. Une charge utile de texte est une chaîne JSON codée en `UTF-8`. Une charge utile binaire est tout élément autre qu’une charge utile textuelle. La charge utile binaire peut être, par exemple, un fichier JPEG, un GZip fichier ou un fichier XML. La configuration d’API requise pour prendre en charge les supports binaires varie selon que votre API utilise des intégrations de proxy ou autre que de proxy.
Si vous utilisez une intégration proxy avec le streaming de réponse à la charge utile, vous n'avez pas besoin de configurer vos types de médias binaires. Pour de plus amples informations, veuillez consulter [Diffusez la réponse d'intégration pour vos intégrations de proxy dans API Gateway](response-transfer-mode.md).
## AWS Lambda intégrations de proxy
Pour gérer les charges utiles binaires pour les intégrations de AWS Lambda proxy, vous devez encoder la réponse de votre fonction en base64. Vous devez également configurer le [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)pour votre API. La configuration `binaryMediaTypes` de votre API est une liste de types de contenu que votre API traite comme des données binaires. Par exemple, les types de supports binaires incluent `image/png` ou `application/octet-stream`. Vous pouvez utiliser le caractère générique (`*`) pour couvrir plusieurs types de supports.
API Gateway utilise le premier en-tête `Accept` des clients pour déterminer si une réponse doit renvoyer un support binaire. Pour renvoyer un support binaire lorsque vous ne pouvez pas contrôler l’ordre des valeurs d’en-tête `Accept`, telles que les demandes d’un navigateur, définissez les types de supports binaires de votre API sur `*/*`.
Pour obtenir un exemple de code, consultez [Renvoi d’un support binaire d’une intégration de proxy Lambda dans API Gateway](lambda-proxy-binary-media.md).
Si vous utilisez une intégration de proxy Lambda avec le streaming de réponse à la charge utile, vous n'avez pas besoin de configurer vos types de supports binaires. Pour de plus amples informations, veuillez consulter [Configurer une intégration de proxy Lambda avec le streaming des réponses de charge utile dans API Gateway](response-transfer-mode-lambda.md).
## Intégrations autres que de proxy
Pour gérer les charges utiles binaires pour les intégrations sans proxy, vous devez ajouter les types de média à la [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)liste de la ressource. `RestApi` La configuration `binaryMediaTypes` de votre API est une liste de types de contenu que votre API traite comme des données binaires. [Vous pouvez également définir les propriétés [ContentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) sur l'intégration et les ressources. [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) La valeur `contentHandling` peut être `CONVERT_TO_BINARY`, `CONVERT_TO_TEXT` ou indéfinie.
**Note**
Pour les intégrations `MOCK` ou privées, la définition des propriétés `contentHandling` n’est pas prise en charge dans la AWS Management Console. Vous devez utiliser le AWS CLI CloudFormation, ou un SDK pour définir les `contentHandling` propriétés.
Selon la valeur de `contentHandling` et si l’en-tête `Content-Type` de la réponse ou l’en-tête `Accept` de la demande entrante correspond à une entrée de la liste `binaryMediaTypes`, API Gateway peut encoder les octets binaires bruts sous forme de chaîne codée en base64, décoder une chaîne codée en base64 pour obtenir les octets bruts ou passer le corps sans modification.
Vous devez configurer l’API comme suit pour prendre en charge les charges utiles binaires de votre API API Gateway :
+ Ajoutez les types de supports binaires souhaités à la `binaryMediaTypes` liste de la [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource. Si cette propriété et la propriété `contentHandling` ne sont pas définies, les charges utiles sont traitées en tant que chaînes JSON codées UTF-8.
+ Adressez la propriété `contentHandling` de la ressource [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
+ Pour que la charge utile de la demande soit convertie d’une chaîne codée en Base64 en son blob binaire, définissez la propriété sur `CONVERT_TO_BINARY`.
+ Pour que la charge utile de la demande soit convertie d’un blob binaire en une chaîne codée en Base64, définissez la propriété sur `CONVERT_TO_TEXT`.
+ Pour transmettre la charge utile sans modification, laissez la propriété indéfinie. Pour transmettre une charge utile binaire sans modification, vous devez également vous assurer que `Content-Type` correspond à l’une des entrées `binaryMediaTypes` et que les [comportements de transmission](integration-passthrough-behaviors.md) sont activés pour l’API.
+ Définissez la `contentHandling` propriété de la [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)ressource. La propriété `contentHandling`, l’en-tête `Accept` dans les demandes client et les `binaryMediaTypes` de vos API déterminent la façon dont API Gateway gère les conversions de type de contenu. Pour en savoir plus, consultez [Conversions du type de contenu dans API Gateway](api-gateway-payload-encodings-workflow.md).
**Important**
Lorsqu'une demande contient plusieurs types de support dans son en-tête `Accept`, API Gateway respecte uniquement le premier type de support `Accept`. Si vous ne pouvez pas contrôler l'ordre des types de support `Accept` et si le type de support de votre contenu binaire n'est pas le premier de la liste, ajoutez le premier type de support `Accept` dans la liste `binaryMediaTypes` de votre API. API Gateway gère tous les types de contenu de cette liste sous forme binaire.
Par exemple, pour envoyer un fichier JPEG en utilisant un élément `` dans un navigateur, ce dernier peut envoyer `Accept:image/webp,image/*,*/*;q=0.8` dans une demande. Si vous ajoutez `image/webp` à la liste `binaryMediaTypes`, le point de terminaison reçoit le fichier JPEG sous forme binaire.
Pour plus d’informations sur la façon dont API Gateway gère les charges utiles textuelles et binaires, consultez [Conversions du type de contenu dans API Gateway](api-gateway-payload-encodings-workflow.md).
# Conversions du type de contenu dans API Gateway
La combinaison des `binaryMediaTypes` de vos API, les en-têtes dans les demandes client et la propriété `contentHandling` d’intégration déterminent la manière dont API Gateway encode les charges utiles.
Le tableau suivant montre comment API Gateway convertit la charge utile de la demande pour des configurations spécifiques de l'`Content-Type`en-tête d'une demande, de la `binaryMediaTypes` liste d'une [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource et de la valeur de `contentHandling` propriété de la ressource d'[intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
| Charge utile de la demande de méthode | En-tête `Content-Type` de la demande | `binaryMediaTypes` | `contentHandling` | Charge utile de la demande d’intégration |
| --- | --- | --- | --- | --- |
| Données de texte | Tout type de données | Non défini | Non défini | UTF8-chaîne codée |
| Données de texte | Tout type de données | Non défini | CONVERT\$1TO\$1BINARY | Blob binaire décodé en Base64 |
| Données de texte | Tout type de données | Non défini | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée |
| Données de texte | Un type de données texte | Défini avec les types de supports correspondants | Non défini | Données de texte |
| Données de texte | Un type de données texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Blob binaire décodé en Base64 |
| Données de texte | Un type de données texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Données de texte |
| Données binaires | Un type de données binaires | Défini avec les types de supports correspondants | Non défini | Données binaires |
| Données binaires | Un type de données binaires | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Données binaires |
| Données binaires | Un type de données binaires | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Chaîne d'encodage en Base64 |
Le tableau suivant montre comment API Gateway convertit la charge utile de réponse pour des configurations spécifiques de l'`Accept`en-tête d'une demande, de la `binaryMediaTypes` liste d'une [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource et de la valeur de `contentHandling` propriété de la [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)ressource.
**Important**
Lorsqu'une demande contient plusieurs types de support dans son en-tête `Accept`, API Gateway respecte uniquement le premier type de support `Accept`. Si vous ne pouvez pas contrôler l'ordre des types de support `Accept` et si le type de support de votre contenu binaire n'est pas le premier de la liste, ajoutez le premier type de support `Accept` dans la liste `binaryMediaTypes` de votre API. API Gateway gère tous les types de contenu de cette liste sous forme binaire.
Par exemple, pour envoyer un fichier JPEG en utilisant un élément `` dans un navigateur, ce dernier peut envoyer `Accept:image/webp,image/*,*/*;q=0.8` dans une demande. Si vous ajoutez `image/webp` à la liste `binaryMediaTypes`, le point de terminaison reçoit le fichier JPEG sous forme binaire.
| Charge utile de la réponse d’intégration | En-tête `Accept` de la demande | `binaryMediaTypes` | `contentHandling` | Charge utile de la réponse de méthode |
| --- | --- | --- | --- | --- |
| Données texte ou binaires | Un type de texte | Non défini | Non défini | UTF8-chaîne codée |
| Données texte ou binaires | Un type de texte | Non défini | CONVERT\$1TO\$1BINARY | Blob décodé en Base64 |
| Données texte ou binaires | Un type de texte | Non défini | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée |
| Données de texte | Un type de texte | Défini avec les types de supports correspondants | Non défini | Données de texte |
| Données de texte | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Blob décodé en Base64 |
| Données de texte | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée |
| Données de texte | Un type binaire | Défini avec les types de supports correspondants | Non défini | Blob décodé en Base64 |
| Données de texte | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Blob décodé en Base64 |
| Données de texte | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | UTF8-chaîne codée |
| Données binaires | Un type de texte | Défini avec les types de supports correspondants | Non défini | Chaîne d'encodage en Base64 |
| Données binaires | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Données binaires |
| Données binaires | Un type de texte | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Chaîne d'encodage en Base64 |
| Données binaires | Un type binaire | Défini avec les types de supports correspondants | Non défini | Données binaires |
| Données binaires | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1BINARY | Données binaires |
| Données binaires | Un type binaire | Défini avec les types de supports correspondants | CONVERT\$1TO\$1TEXT | Chaîne d'encodage en Base64 |
Lors de la conversion d’une charge utile de texte en blob binaire, API Gateway suppose que les données de texte sont une chaîne encodée en base64 et génère les données binaires comme blob décodé en base64. Si la conversion échoue, elle retourne une réponse `500` indiquant une erreur de configuration de l’API. Vous ne fournissez pas de modèle de mappage pour ce type de conversion, même si vous devez activer les [comportements relais](integration-passthrough-behaviors.md) sur l’API.
Lors de la conversion d’une charge utile binaire en une chaîne de texte, API Gateway applique toujours un encodage en base64 sur les données binaires. Vous pouvez définir un modèle de mappage pour une charge utile de ce type, mais vous pouvez uniquement accéder à la chaîne d’encodage base64 dans le modèle de mappage via `$input.body`, comme illustré dans l’extrait d’un exemple de modèle de mappage.
```
{
"data": "$input.body"
}
```
Pour que la charge utile binaire soit passée sans modification, vous devez activer les [comportements relais](integration-passthrough-behaviors.md) sur l’API.
# Activation de la prise en charge binaire à l’aide de la console API Gateway
Cette section explique comment activer la prise en charge binaire à l’aide de la console API Gateway. À titre d’exemple, nous utilisons une API intégrée avec Amazon S3. Nous nous concentrons sur les tâches visant à définir les types de supports pris en charge afin de spécifier la façon dont la charge utile doit être gérée. Pour obtenir des informations détaillées sur la création d’une API intégrée avec Amazon S3, consultez [Didacticiel : création d’une API REST en tant que proxy Amazon S3](integrating-api-with-aws-services-s3.md).
**Pour activer la prise en charge binaire à l’aide de la console API Gateway**
1. Définissez les types de supports binaires pour l’API :
1. Créez une API ou choisissez une API existante. Pour cet exemple, nous appelons l’API `FileMan`.
1. Sous l’API sélectionnée dans le panneau de navigation principal, choisissez **Paramètres de l’API**.
1. Dans le volet **Paramètres de l’API**, choisissez **Gérer les types de supports** dans la section **Types de supports binaires**.
1. Choisissez **Ajouter un type de support binaire**.
1. Saisissez un type de support requis, par exemple **image/png**, dans le champ de texte d’entrée. Si nécessaire, répétez cette étape pour ajouter d’autres types de supports. Pour prendre en charge tous les types de supports binaires, spécifiez `*/*`.
1. Sélectionnez **Enregistrer les modifications**.
1. Définissez la façon dont les charges utiles du message sont traitées pour la méthode de l’API :
1. Créez une nouvelle ressource ou choisissez-en une existante dans l’API. Dans le cadre de cet exemple, nous utilisons la ressource `/{folder}/{item}`.
1. Créez une méthode ou choisissez-en une existante sur la ressource. À titre d’exemple, nous utilisons la méthode `GET /{folder}/{item}` intégrée avec l’action `Object GET` dans Amazon S3.
1. Dans **Gestion de contenu**, choisissez une option.
![\[Configuration de la méthode dans la console API Gateway.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png)
Choisissez **Passthrough** si vous ne souhaitez pas convertir le corps lorsque le client et le backend acceptent le même format binaire. Choisissez **Convertir en texte** pour convertir le corps binaire en chaîne encodée en base64 lorsque, par exemple, le backend a besoin qu’une charge utile de requête binaire soit passée en tant que propriété JSON. Choisissez **Convertir en binaire** lorsque le client envoie une chaîne encodée en base64 et si le backend nécessite le format binaire d’origine, ou lorsque le point de terminaison retourne une chaîne encodée en base64 et si le client accepte uniquement la sortie binaire.
1. Pour **Transmission du corps de requête**, choisissez **Lorsqu’aucun modèle n’est défini (recommandé)** pour activer le comportement de transmission pour le corps de la requête.
Vous pouvez également choisir **Jamais**. Cela signifie que l’API rejettera les données avec des types de contenus qui ne disposent pas d’un modèle de mappage.
1. Conservez l’en-tête `Accept` de la demande entrante dans la demande d’intégration. Procédez ainsi si vous avez défini `contentHandling` sur `passthrough` et que vous souhaitez remplacer ce paramètre au moment de l’exécution.
![\[Conservez l’en-tête Accept dans la demande d’intégration.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png)
1. Pour la conversion en texte, définissez un modèle de mappage afin de convertir les données binaires encodées en base64 au format requis.
Voici un exemple de modèle de mappage à convertir en texte :
```
{
"operation": "thumbnail",
"base64Image": "$input.body"
}
```
Le format de ce modèle de mappage s’appuie sur les exigences de point de terminaison de l’entrée.
1. Choisissez **Enregistrer**.
# Activation de la prise en charge binaire à l’aide de l’API REST API Gateway
Les tâches suivantes montrent comment activer la prise en charge binaire à l’aide des appels de l’API REST API Gateway.
**Topics**
+ [
## Ajout et mise à jour des types de supports binaires d’une API
](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [
## Configuration des conversions de charge utile de la demande
](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [
## Configuration des conversions de charge utile pour la réponse
](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [
## Conversion des données binaires en données de texte
](#api-gateway-payload-encodings-convert-binary-to-string)
+ [
## Conversion des données de texte en charge utile binaire
](#api-gateway-payload-encodings-convert-string-to-binary)
+ [
## Passage via une charge utile binaire
](#api-gateway-payload-encodings-pass-binary-as-is)
## Ajout et mise à jour des types de supports binaires d’une API
Pour permettre à API Gateway de prendre en charge un nouveau type de support binaire, vous devez ajouter le type de support binaire à la liste `binaryMediaTypes` de la ressource `RestApi`. Par exemple, pour qu’API Gateway gère les images JPEG, envoyez une demande `PATCH` à la ressource `RestApi` :
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/image~1jpeg"
}
]
}
```
La spécification de type MIME de `image/jpeg` qui fait partie de la valeur de propriété `path` est échappée comme `image~1jpeg`.
Pour mettre à jour les types de supports binaires pris en charge, remplacez ou supprimez le type de support de la liste `binaryMediaTypes` de la ressource `RestApi`. Par exemple, pour remplacer la prise en charge binaire des fichiers JPEG par celle des octets bruts, soumettez une demande `PATCH` à la ressource `RestApi`, comme suit :
```
PATCH /restapis/
{
"patchOperations" : [{
"op" : "replace",
"path" : "/binaryMediaTypes/image~1jpeg",
"value" : "application/octet-stream"
},
{
"op" : "remove",
"path" : "/binaryMediaTypes/image~1jpeg"
}]
}
```
## Configuration des conversions de charge utile de la demande
Si le point de terminaison nécessite une entrée binaire, définissez la propriété `contentHandling` de la ressource `Integration` sur `CONVERT_TO_BINARY`. Pour ce faire, présentez une `PATCH` demande, comme suit :
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## Configuration des conversions de charge utile pour la réponse
Si le client accepte le résultat comme blob binaire au lieu de la charge utile encodée en base64 renvoyée par le point de terminaison, définissez la propriété `contentHandling` de la ressource `IntegrationResponse` sur `CONVERT_TO_BINARY`. Pour ce faire, soumettez une demande `PATCH`, comme suit :
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## Conversion des données binaires en données de texte
Pour envoyer des données binaires sous forme de propriété JSON de l'entrée à AWS Lambda ou à Kinesis via API Gateway, procédez comme suit :
1. Activez la prise en charge de la charge utile binaire de l’API en ajoutant le nouveau type de support binaire de `application/octet-stream` à la liste de l’API `binaryMediaTypes`.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. Définissez `CONVERT_TO_TEXT` sur la propriété `contentHandling` de la ressource `Integration` et fournissez fournir un modèle de mappage pour attribuer la chaîne encodée en base64 des données binaires à une propriété JSON. Dans l’exemple suivant, la propriété JSON est `body` et `$input.body` contient la chaîne encodée en base64.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_TEXT"
},
{
"op" : "add",
"path" : "/requestTemplates/application~1octet-stream",
"value" : "{\"body\": \"$input.body\"}"
}
]
}
```
## Conversion des données de texte en charge utile binaire
Supposons qu’une fonction Lambda renvoie un fichier d’image sous forme de chaîne encodée en base64. Pour transmettre cette sortie binaire au client via API Gateway, procédez comme suit :
1. Mettez à jour la liste `binaryMediaTypes` de l’API en ajoutant le type de support binaire de `application/octet-stream`, s’il n’est pas déjà dans la liste.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream",
}]
}
```
1. Définissez la propriété `contentHandling` de la ressource `Integration` sur `CONVERT_TO_BINARY`. Ne définissez pas de modèle de mappage. Si vous ne définissez pas de modèle de mappage, API Gateway appelle le modèle de relais pour renvoyer le blob binaire encodé en base64 sous forme de fichier image au client.
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}
]
}
```
## Passage via une charge utile binaire
Pour stocker une image dans un compartiment Amazon S3 à l’aide d’API Gateway, procédez comme suit :
1. Mettez à jour la liste `binaryMediaTypes` de l’API en ajoutant le type de support binaire de `application/octet-stream`, s’il n’est pas déjà dans la liste.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. Sur la propriété `contentHandling` de la ressource `Integration`, définissez `CONVERT_TO_BINARY`. Définissez `WHEN_NO_MATCH` comme valeur de propriété `passthroughBehavior` sans définir de modèle de mappage. Cela permet à API Gateway d’appeler le modèle de relais.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
},
{
"op" : "replace",
"path" : "/passthroughBehaviors",
"value" : "WHEN_NO_MATCH"
}
]
}
```
# Importation et exportation d’encodages de contenu pour API Gateway
Pour importer la `binaryMediaTypes` liste sur un [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), utilisez l'extension API Gateway suivante dans le fichier de définition OpenAPI de l'API. L’extension est également utilisée pour exporter les paramètres de l’API.
+ [x-amazon-apigateway-binarypropriété -media-types](api-gateway-swagger-extensions-binary-media-types.md)
Pour importer et exporter la valeur de propriété `contentHandling` sur une ressource `Integration` ou `IntegrationResponse`, utilisez les extensions API Gateway suivantes pour les définitions OpenAPI :
+ [x-amazon-apigateway-integration objet](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integrationobjet .response](api-gateway-swagger-extensions-integration-response.md)
# Renvoi d’un support binaire d’une intégration de proxy Lambda dans API Gateway
Pour renvoyer un support binaire à partir d’une [intégration de proxy AWS Lambda](set-up-lambda-proxy-integrations.md), encodez en base64 la réponse de votre fonction Lambda. Vous devez également [configurer les types de supports binaires de votre API](api-gateway-payload-encodings-configure-with-console.md). Lorsque vous configurez les types de médias binaires de votre API, celle-ci traite ce type de contenu comme des données binaires. La taille de la charge utile ne doit pas dépasser 10 Mo.
**Note**
Pour utiliser un navigateur web pour appeler une API avec cet exemple d’intégration, définissez les types de supports binaires de votre API sur `*/*`. API Gateway utilise le premier en-tête `Accept` des clients pour déterminer si une réponse doit renvoyer un support binaire. Pour renvoyer un support binaire lorsque vous ne pouvez pas contrôler l’ordre des valeurs d’en-tête `Accept`, telles que les demandes d’un navigateur, définissez les types de supports binaires de votre API sur `*/*` (pour tous les types de contenu).
L’exemple de fonction Lambda suivant peut renvoyer aux clients une image binaire à partir d’Amazon S3 ou du texte. La réponse de la fonction inclut un en-tête `Content-Type` pour indiquer au client le type de données qu’elle renvoie. La fonction définit de manière conditionnelle la propriété `isBase64Encoded` dans sa réponse, en fonction du type de données qu’elle renvoie.
------
#### [ Node.js ]
```
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
const client = new S3Client({region: 'us-east-2'});
export const handler = async (event) => {
var randomint = function(max) {
return Math.floor(Math.random() * max);
}
var number = randomint(2);
if (number == 1){
const input = {
"Bucket" : "bucket-name",
"Key" : "image.png"
}
try {
const command = new GetObjectCommand(input)
const response = await client.send(command);
var str = await response.Body.transformToByteArray();
} catch (err) {
console.error(err);
}
const base64body = Buffer.from(str).toString('base64');
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64body,
'isBase64Encoded': true
}
} else {
return {
'headers': { "Content-Type": "text/html" },
'statusCode': 200,
'body': "
",
}
```
------
Pour plus d’informations sur les types de supports binaires, consultez [Types de médias binaires pour REST APIs dans API Gateway](api-gateway-payload-encodings.md).
# Accès aux fichiers binaires dans Amazon S3 via une API API Gateway
Les exemples suivants illustrent le fichier OpenAPI utilisé pour accéder aux images dans Amazon S3, le téléchargement d’une image depuis Amazon S3 et le chargement d’une image vers Amazon S3.
**Topics**
+ [
## Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Amazon S3
](#api-gateway-content-encodings-example-image-s3-swagger-file)
+ [
## Téléchargement d’une image depuis Amazon S3
](#api-gateway-content-encodings-example-download-image-from-s3)
+ [
## Chargement d’une image sur Amazon S3
](#api-gateway-content-encodings-example-upload-image-to-s3)
## Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Amazon S3
Le fichier OpenAPI suivant présent un exemple d’API qui illustre le téléchargement d’un fichier image depuis Amazon S3 et le chargement d’un fichier image vers Amazon S3. Cette API expose les méthodes `GET /s3?key={file-name}` et `PUT /s3?key={file-name}` de téléchargement et de chargement d’un fichier image spécifié. La méthode `GET` renvoie le fichier image sous la forme d'une chaîne encodée en base64 dans le cadre d'une sortie JSON, selon le modèle de mappage fourni, dans une réponse 200 OK. La méthode `PUT` prend un blob binaire brut comme entrée et renvoie une réponse 200 OK avec une charge utile vide.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/s3": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling": "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/s3": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200" }
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling" : "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Téléchargement d’une image depuis Amazon S3
Pour télécharger un fichier image (`image.jpg`) comme blob binaire depuis Amazon S3 :
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
La réponse de réussite ressemble à ceci :
```
200 OK HTTP/1.1
[raw bytes]
```
Les octets bruts sont renvoyés car l’en-tête `Accept` est défini sur un type de support binaire de `application/octet-stream` et la prise en charge binaire est activée pour l’API.
Vous pouvez également télécharger un fichier image (`image.jpg`) en tant que chaîne encodée en base64, au format d’une propriété JSON, à partir d’Amazon S3, ajouter un modèle de réponse à la réponse d’intégration 200, comme illustré dans le bloc de définition OpenAPI en caractères gras suivant :
```
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
},
```
La demande pour télécharger le fichier image ressemble à ce qui suit :
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
La réponse de réussite ressemble à ce qui suit :
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Chargement d’une image sur Amazon S3
Pour charger un fichier image (`image.jpg`) comme blob binaire vers Amazon S3 :
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
La réponse de réussite ressemble à ce qui suit :
```
200 OK HTTP/1.1
```
Pour charger un fichier image (`image.jpg`) sous la forme d’une chaîne encodée en base64 vers Amazon S3 :
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
La charge utile d’entrée doit être une chaîne encodée en base64 car la valeur de l’en-tête `Content-Type` est définie sur `application/json`. La réponse de réussite ressemble à ce qui suit :
```
200 OK HTTP/1.1
```
# Accès aux fichiers binaires dans Lambda à l’aide d’une API API Gateway
L'exemple OpenAPI suivant montre comment accéder à un fichier binaire AWS Lambda via une API API Gateway. Cette API expose les méthodes `GET /lambda?key={file-name}` et `PUT /lambda?key={file-name}` de téléchargement et de chargement d’un fichier image spécifié. La méthode `GET` renvoie le fichier image sous la forme d'une chaîne encodée en base64 dans le cadre d'une sortie JSON, selon le modèle de mappage fourni, dans une réponse 200 OK. La méthode `PUT` prend un blob binaire brut comme entrée et renvoie une réponse 200 OK avec une charge utile vide.
Vous créez la fonction Lambda que votre API appelle, et elle doit renvoyer une chaîne codée en base64 avec l’en-tête `Content-Type` `application/json`.
**Topics**
+ [
## Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Lambda
](#api-gateway-content-encodings-example-image-lambda-swagger-file)
+ [
## Téléchargement d’une image depuis Lambda
](#api-gateway-content-encodings-example-download-image-from-lambda)
+ [
## Chargement d’une image vers Lambda
](#api-gateway-content-encodings-example-upload-image-to-lambda)
## Fichier OpenAPI d’un exemple d’API pour accéder aux images dans Lambda
Le fichier OpenAPI suivant présente un exemple d’API qui illustre le téléchargement d’un fichier image depuis Lambda et le chargement d’un fichier image vers Lambda.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/lambda": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/lambda": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling" : "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Téléchargement d’une image depuis Lambda
Pour télécharger un fichier image (`image.jpg`) comme blob binaire depuis Lambda :
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
La réponse de réussite ressemble à ce qui suit :
```
200 OK HTTP/1.1
[raw bytes]
```
Pour télécharger un fichier image (`image.jpg`) sous la forme d’une chaîne encodée en base64, au format d’une propriété JSON, depuis Lambda :
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
La réponse de réussite ressemble à ce qui suit :
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Chargement d’une image vers Lambda
Pour charger un fichier image (`image.jpg`) comme blob binaire vers Lambda :
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
La réponse de réussite ressemble à ce qui suit :
```
200 OK
```
Pour charger un fichier image (`image.jpg`) sous la forme d’une chaîne encodée en base64 vers Lambda :
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
La réponse de réussite ressemble à ce qui suit :
```
200 OK
```
# Invocation d’une API REST dans API Gateway
Pour appeler une API déployée, les clients soumettent des demandes à l’URL du service des composants API Gateway pour l’exécution de l’API, connu sous le nom de `execute-api`.
L’URL de base pour les API REST se présente au format suivant :
```
https://api-id.execute-api.region.amazonaws.com/stage/
```
où *api-id* est l’ID de l’API, *region* la région AWS et *stage* le nom de l’étape du déploiement de l’API.
**Important**
Avant de pouvoir invoquer une API, vous devez la déployer dans API Gateway. Pour apprendre à déployer une API, consultez[Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md).
**Topics**
+ [
## Obtention de l’URL d’invocation d’une API
](#apigateway-how-to-call-rest-api)
+ [
## Appel d’une API
](#apigateway-call-api)
+ [
# Utilisation de la console API Gateway pour tester une méthode API REST
](how-to-test-method.md)
+ [
# Utilisation d'un kit SDK Java généré par API Gateway pour une API REST
](how-to-call-apigateway-generated-java-sdk.md)
+ [
# Utilisation d’un kit SDK Android généré par API Gateway pour une API REST
](how-to-generate-sdk-android.md)
+ [
# Utiliser un JavaScript SDK généré par API Gateway pour une API REST
](how-to-generate-sdk-javascript.md)
+ [
# Utilisation d’un kit SDK Ruby généré par API Gateway pour une API REST
](how-to-call-sdk-ruby.md)
+ [
# Utilisation d’un kit SDK iOS généré par API Gateway pour une API REST dans Objective-C ou Swift
](how-to-generate-sdk-ios.md)
## Obtention de l’URL d’invocation d’une API
Vous pouvez utiliser la console, l’AWS CLI ou une définition OpenAPI exportée pour obtenir l’URL d’invocation d’une API.
### Obtention de l’URL d’invocation d’une API à l’aide de la console
La procédure suivante montre comment obtenir l’URL d’invocation d’une API dans la console API REST.
**Pour obtenir l’URL d’invocation d’une API à l’aide de la console API REST**
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 déployée.
1. Dans le panneau de navigation principal, choisissez **Étape**.
1. Sous **Détails de l'étape**, choisissez l'icône de copie pour copier l'URL d'invocation de votre API.
Cette URL est destinée à la ressource racine de votre API.
![\[Une fois que vous avez créé votre API REST, la console affiche l’URL d’invocation de votre API.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. Pour obtenir l’URL d’invocation d’une API pour une autre ressource de votre API, développez l’étape sous le volet de navigation secondaire, puis choisissez une méthode.
1. Choisissez l’icône de copie pour copier l’URL d’invocation de votre API au niveau des ressources.
![\[L’URL d’invocation de votre API REST au niveau des ressources se trouve sous le volet de navigation secondaire de l’étape.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/resource-level-invoke-url.png)
#### Obtention de l’URL d’invocation d’une API à l’aide de l’AWS CLI
La procédure suivante montre comment obtenir l’URL d’invocation d’une API à l’aide de l’AWS CLI.
**Pour obtenir l’URL d’invocation d’une API à l’aide de l’AWS CLI**
1. Utilisez la commande suivante pour obtenir la valeur `rest-api-id`. Cette commande renvoie toutes les valeurs `rest-api-id` de votre région. Pour plus d’informations, consultez [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html).
```
aws apigateway get-rest-apis
```
1. Remplacez la valeur `rest-api-id` de l’exemple par votre valeur `rest-api-id`, remplacez la valeur *\$1stage-name\$1* de l’exemple par votre valeur *\$1stage-name\$1*, et remplacez la valeur *\$1region\$1* par votre région.
```
https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
```
##### Obtention de l’URL d’invocation d’une API à l’aide du fichier de définition OpenAPI exporté de l’API
Vous pouvez également construire l’URL racine en combinant les champs `host` et `basePath` d’un fichier de définition OpenAPI exporté de l’API. Pour apprendre à exporter votre API, consultez [Exportation d’une API REST à partir d’API Gateway](api-gateway-export-api.md).
## Appel d’une API
Vous pouvez appeler votre API déployée à l’aide d’un navigateur, de curl ou d’autres applications, telles que [Postman](https://www.postman.com/).
Vous pouvez également utiliser la console API Gateway pour tester un appel d’API. Le test utilise la fonctionnalité `TestInvoke` d’API Gateway, qui permet de tester l’API avant son déploiement. Pour de plus amples informations, consultez [Utilisation de la console API Gateway pour tester une méthode API REST](how-to-test-method.md).
**Note**
Les valeurs de paramètres de chaîne de requêtes d’une URL d’invocation ne peuvent pas contenir `%%`.
### Invocation d’une API à l’aide d’un navigateur Web
Si votre API autorise les accès anonymes, vous pouvez utiliser n’importe quel navigateur web pour invoquer une méthode `GET`. Saisissez l’URL d’invocation complète dans la barre d’adresse du navigateur.
Pour les autres méthodes ou les appels nécessitant une authentification, vous devez spécifier des données utiles ou signer les demandes. Vous pouvez gérer ces appels dans un script sous-jacent d’une page HTML ou dans une application client à l’aide d’un des kits SDK AWS.
#### Invocation d’une API à l’aide de curl
Vous pouvez utiliser un outil tel que [curl](https://curl.se/) dans votre terminal pour appeler votre API. L’exemple de commande curl suivant invoque la méthode GET sur la ressource `getUsers` de l’étape `prod` d’une API.
------
#### [ Linux or Macintosh ]
```
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
------
#### [ Windows ]
```
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"
```
------
# Utilisation de la console API Gateway pour tester une méthode API REST
Utilisez la console API Gateway pour tester une méthode API REST.
**Topics**
+ [
## Prérequis
](#how-to-test-method-prerequisites)
+ [
## Test d’une méthode avec la console API Gateway
](#how-to-test-method-console)
## Prérequis
+ Vous devez spécifier les paramètres des méthodes que vous souhaitez tester. Suivez les instructions de la section [Méthodes pour REST APIs dans API Gateway](how-to-method-settings.md).
## Test d’une méthode avec la console API Gateway
**Important**
Le test des méthodes avec la console API Gateway peut entraîner des modifications de ressources impossibles à annuler. Tester une méthode avec la console API Gateway revient à appeler la méthode en dehors de la console API Gateway. Par exemple, si vous utilisez la console API Gateway pour appeler une méthode qui supprime les ressources d’une API, si l’appel de la méthode aboutit, les ressources de l’API sont supprimées.
**Pour tester une méthode**
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 REST.
1. Dans le volet **Resources**, sélectionnez la méthode à tester.
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
![\[Utilisez l’onglet Test pour tester votre API. Il se trouve à côté de l’onglet Réponse de méthode.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/api-gateway-test-new-console.png)
Entrez des valeurs dans les zones affichées (par exemple, **Chaînes de requête**, **En-têtes** et **Corps de la demande**). La console inclut ces valeurs dans le formulaire application/json par défaut de la demande de méthode.
Pour obtenir des options supplémentaires, vous devrez peut-être spécifier ou contacter le propriétaire de l’API.
1. Sélectionnez **Test**. Les informations suivantes s’affichent alors :
+ **Request** est le chemin de la ressource qui a été appelée pour la méthode.
+ **Status** est le code de statut HTTP de la réponse.
+ **Latence (ms)** correspond au temps écoulé entre la réception de la demande de l’appelant et l’envoi de la réponse.
+ **Corps de la réponse** correspond au corps de la réponse HTTP.
+ Le paramètre **En-têtes de réponse** correspond aux en-têtes de réponse HTTP.
**Astuce**
Selon le mappage, le code de statut HTTP, le corps de la réponse et les en-têtes de réponse peuvent être différents de ceux envoyés depuis la Fonction Lambda, un proxy HTTP ou un proxy de service AWS.
+ Les valeurs **Logs (Journaux)** correspondent aux entrées Amazon CloudWatch Logs simulées qui auraient été écrites si cette méthode avait été appelée en dehors de la console API Gateway.
**Note**
Bien que les entrées CloudWatch Logs soient simulées, les résultats de l’appel de la méthode sont réels.
En plus de la console API Gateway, vous pouvez utiliser la AWS CLI ou un kit AWS SDK pour API Gateway afin de tester l’appel d’une méthode. Pour utiliser l’AWS CLI, consultez la section [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html).
# Utilisation d'un kit SDK Java généré par API Gateway pour une API REST
Dans cette section, nous présentons les étapes relatives à l'utilisation d'un kit SDK Java généré par API Gateway pour une API REST en utilisant l'API [Simple Calculator](simple-calc-lambda-api-swagger-definition.md) comme exemple. Avant de poursuivre, vous devez suivre la procédure indiquée dans [Générer SDKs pour REST APIs dans API Gateway](how-to-generate-sdk.md).
**Pour installer et utiliser un kit SDK Java généré par API Gateway**
1. Extrayez le contenu du fichier .zip généré par API Gateway que vous avez téléchargé plus tôt.
1. Téléchargez et installez [Apache Maven](https://maven.apache.org/) (version 3.5 ou ultérieure).
1. Téléchargez et installez le kit [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html).
1. Définissez la variable d’environnement `JAVA_HOME`.
1. Accédez au dossier SDK décompressé où se trouve le fichier pom.xml. Ce dossier est `generated-code` par défaut. Exécutez la commande **mvn install** pour installer les fichiers d'artefact compilés dans votre référentiel Maven local. Cela crée un dossier `target` contenant la bibliothèque de kits SDK compilés.
1. Entrez la commande suivante dans un répertoire vide pour créer un stub de projet client et appeler l'API à l'aide de la bibliothèque de kit SDK installée.
```
mvn -B archetype:generate \
-DarchetypeGroupdId=org.apache.maven.archetypes \
-DgroupId=examples.aws.apig.simpleCalc.sdk.app \
-DartifactId=SimpleCalc-sdkClient
```
**Note**
Le séparateur `\` de la commande précédente est inclus pour faciliter la lecture. La commande entière doit figurer sur une seule ligne sans le séparateur.
Cette commande crée un stub d'application. Le stub de l'application contient un fichier `pom.xml` et un dossier `src` sous le répertoire racine du projet (*SimpleCalc-sdkClient* dans la commande précédente). A l'origine, il existe deux fichiers sources : `src/main/java/{package-path}/App.java` et `src/test/java/{package-path}/AppTest.java`. Dans cet exemple, le *\$1chemin d'accès au package\$1* est `examples/aws/apig/simpleCalc/sdk/app`. Ce chemin d'accès au package provient de la valeur `DarchetypeGroupdId`. Vous pouvez utiliser le fichier `App.java` comme modèle pour votre application cliente et vous pouvez en ajouter d'autres dans le même dossier si nécessaire. Vous pouvez utiliser le fichier `AppTest.java` comme modèle de test unitaire pour votre application et vous pouvez ajouter d'autres fichiers de code de test dans le même dossier de test si nécessaire.
1. Mettez à jour les dépendances de package dans le fichier `pom.xml` généré avec ce qui suit, en remplaçant les propriétés `groupId`, `artifactId`, `version` et `name` de votre projet si nécessaire :
```
4.0.0examples.aws.apig.simpleCalc.sdk.appSimpleCalc-sdkClientjar1.0-SNAPSHOTSimpleCalc-sdkClienthttp://maven.apache.orgcom.amazonawsaws-java-sdk-core1.11.94my-apig-api-examplessimple-calc-sdk1.0.0junitjunit4.12testcommons-iocommons-io2.5org.apache.maven.pluginsmaven-compiler-plugin3.5.11.81.8
```
**Note**
Lorsqu'une version plus récente de l'artéfact dépendant de `aws-java-sdk-core` n'est pas compatible avec la version indiquée ci-dessus (`1.11.94`), vous devez mettre à jour la balise `` vers la nouvelle version.
1. Ensuite, nous montrons comment appeler l'API à l'aide du kit SDK en appelant les méthodes `getABOp(GetABOpRequest req)`, `getApiRoot(GetApiRootRequest req)` et `postApiRoot(PostApiRootRequest req)` du kit SDK. Ces méthodes correspondent aux méthodes `GET /{a}/{b}/{op}`, `GET /?a={x}&b={y}&op={operator}`, et `POST /`, avec, respectivement, la charge utile des demandes d'API `{"a": x, "b": y, "op": "operator"}`.
Mettez à jour le fichier `App.java` comme suit :
```
package examples.aws.apig.simpleCalc.sdk.app;
import java.io.IOException;
import com.amazonaws.opensdk.config.ConnectionConfiguration;
import com.amazonaws.opensdk.config.TimeoutConfiguration;
import examples.aws.apig.simpleCalc.sdk.*;
import examples.aws.apig.simpleCalc.sdk.model.*;
import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*;
public class App
{
SimpleCalcSdk sdkClient;
public App() {
initSdk();
}
// The configuration settings are for illustration purposes and may not be a recommended best practice.
private void initSdk() {
sdkClient = SimpleCalcSdk.builder()
.connectionConfiguration(
new ConnectionConfiguration()
.maxConnections(100)
.connectionMaxIdleMillis(1000))
.timeoutConfiguration(
new TimeoutConfiguration()
.httpRequestTimeout(3000)
.totalExecutionTimeout(10000)
.socketTimeout(2000))
.build();
}
// Calling shutdown is not necessary unless you want to exert explicit control of this resource.
public void shutdown() {
sdkClient.shutdown();
}
// GetABOpResult getABOp(GetABOpRequest getABOpRequest)
public Output getResultWithPathParameters(String x, String y, String operator) {
operator = operator.equals("+") ? "add" : operator;
operator = operator.equals("/") ? "div" : operator;
GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator));
return abopResult.getResult().getOutput();
}
public Output getResultWithQueryParameters(String a, String b, String op) {
GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op));
return rootResult.getResult().getOutput();
}
public Output getResultByPostInputBody(Double x, Double y, String o) {
PostApiRootResult postResult = sdkClient.postApiRoot(
new PostApiRootRequest().input(new Input().a(x).b(y).op(o)));
return postResult.getResult().getOutput();
}
public static void main( String[] args )
{
System.out.println( "Simple calc" );
// to begin
App calc = new App();
// call the SimpleCalc API
Output res = calc.getResultWithPathParameters("1", "2", "-");
System.out.printf("GET /1/2/-: %s\n", res.getC());
// Use the type query parameter
res = calc.getResultWithQueryParameters("1", "2", "+");
System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC());
// Call POST with an Input body.
res = calc.getResultByPostInputBody(1.0, 2.0, "*");
System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC());
}
}
```
Dans l'exemple précédent, les paramètres de configuration utilisés pour instancier le client du kit SDK le sont à titre d'illustration et ne sont pas nécessairement la bonne pratique recommandée. En outre, l'appel de `sdkClient.shutdown()`est facultatif, surtout si vous avez besoin d'un contrôle précis du moment où libérer des ressources.
Nous avons montré les modèles essentiels pour appeler une API à l'aide d'un kit SDK Java. Vous pouvez étendre les instructions à l'appel d'autres méthodes de l'API.
# Utilisation d’un kit SDK Android généré par API Gateway pour une API REST
Dans cette section, nous décrivons les étapes pour utiliser un kit SDK Android généré par API Gateway pour une API REST. Avant de continuer, vous devez avoir déjà suivi la procédure de [Générer SDKs pour REST APIs dans API Gateway](how-to-generate-sdk.md).
**Note**
Le kit SDK généré n’est pas compatible avec Android 4.4 et versions antérieures. Pour de plus amples informations, consultez [Remarques importantes concernant Amazon API Gateway](api-gateway-known-issues.md).
**Pour installer et utiliser un kit SDK Android généré par API Gateway**
1. Extrayez le contenu du fichier .zip généré par API Gateway que vous avez téléchargé plus tôt.
1. Téléchargez et installez [Apache Maven](https://maven.apache.org/) (de préférence version 3.x).
1. Téléchargez et installez le kit [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html).
1. Définissez la variable d’environnement `JAVA_HOME`.
1. Exécutez la commande **mvn install** pour installer les fichiers d’artefact compilés dans votre référentiel Maven local. Cela crée un dossier `target` contenant la bibliothèque de kits SDK compilés.
1. Copiez le fichier du kit SDK (dont le nom est dérivé des valeurs que vous avez spécifiées dans les champs **ID d’artefact** et **Version d’artifact** lors de la génération du kit SDK, par exemple,`simple-calcsdk-1.0.0.jar` ) du dossier `target`, ainsi que toutes les autres bibliothèques du dossier `target/lib`, dans le dossier `lib` de votre projet.
Si vous utilisez Android Studio, créez un dossier `libs` sous le module de votre application client et copiez le fichier .jar requis dans ce dossier. Vérifiez que la section des dépendances dans le fichier gradle du module contient le code suivant.
```
compile fileTree(include: ['*.jar'], dir: 'libs')
compile fileTree(include: ['*.jar'], dir: 'app/libs')
```
Assurez-vous qu’aucun fichier .jar dupliqué n’est déclaré.
1. Utilisez la classe `ApiClientFactory` pour initialiser le kit SDK généré par API Gateway. Exemples :
```
ApiClientFactory factory = new ApiClientFactory();
// Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway.
final SimpleCalcClient client = factory.build(SimpleCalcClient.class);
// Invoke a method:
// For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method:
Result output = client.rootGet("1", "2", "+");
// where the Result class of the SDK corresponds to the Result model of the API.
//
// For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request,
Result output = client.aBOpGet(a, b, c);
// where a, b, c can be "1", "2", "add", respectively.
// For the following API method:
// POST /
// host: ...
// Content-Type: application/json
//
// { "a": 1, "b": 2, "op": "+" }
// you can call invoke it by calling the rootPost method of the SDK as follows:
Input body = new Input();
input.a=1;
input.b=2;
input.op="+";
Result output = client.rootPost(body);
// where the Input class of the SDK corresponds to the Input model of the API.
// Parse the result:
// If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as
String result=output.c;
```
1. Pour utiliser un fournisseur d’informations d’identification Amazon Cognito afin d’autoriser les appels à votre API, utilisez la classe `ApiClientFactory` pour transmettre un ensemble d’informations d’identification AWS à l’aide du kit SDK généré par API Gateway, comme illustré dans l’exemple suivant.
```
// Use CognitoCachingCredentialsProvider to provide AWS credentials
// for the ApiClientFactory
AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(
context, // activity context
"identityPoolId", // Cognito identity pool id
Regions.US_EAST_1 // region of Cognito identity pool
);
ApiClientFactory factory = new ApiClientFactory()
.credentialsProvider(credentialsProvider);
```
1. Pour définir une clé d’API à l’aide du kit SDK généré par API Gateway, utilisez un code similaire au code suivant.
```
ApiClientFactory factory = new ApiClientFactory()
.apiKey("YOUR_API_KEY");
```
# Utiliser un JavaScript SDK généré par API Gateway pour une API REST
La procédure suivante montre comment utiliser un JavaScript SDK généré par API Gateway.
**Note**
Ces instructions supposent que vous avez déjà suivi les instructions de [Générer SDKs pour REST APIs dans API Gateway](how-to-generate-sdk.md).
**Important**
Si seules des méthodes ANY sont définies pour votre API, le kit SDK généré ne contient aucun fichier `apigClient.js` et vous devez définir les méthodes ANY vous-même.
**Pour installer, lancer et appeler un JavaScript SDK généré par API Gateway pour une API REST**
1. Extrayez le contenu du fichier .zip généré par API Gateway que vous avez précédemment téléchargé.
1. Activez le partage des ressources entre origines multiples (CORS) pour toutes les méthodes que le kit SDK généré par API Gateway appelle. Pour obtenir des instructions, veuillez consulter [CORS pour REST APIs dans API Gateway](how-to-cors.md).
1. Dans votre page web, incluez des références aux scripts suivants.
```
```
1. Dans votre code, initialisez le kit SDK généré par API Gateway à l’aide d’un code similaire à ce qui suit.
```
var apigClient = apigClientFactory.newClient();
```
Pour initialiser le SDK généré par API Gateway avec des AWS informations d'identification, utilisez un code similaire au suivant. Si vous utilisez des AWS informations d'identification, toutes les demandes adressées à l'API seront signées.
```
var apigClient = apigClientFactory.newClient({
accessKey: 'ACCESS_KEY',
secretKey: 'SECRET_KEY',
});
```
Pour utiliser une clé d’API avec le kit SDK généré par API Gateway, vous pouvez transmettre la clé d’API à l’objet `Factory` en tant que paramètre à l’aide d’un code similaire à ce qui suit. Si vous utilisez une clé d’API, elle est spécifiée dans l’en-tête `x-api-key` et toutes les demandes envoyées à l’API sont signées. Cela signifie que vous devez définir les en-têtes CORS Accept appropriés pour chaque demande.
```
var apigClient = apigClientFactory.newClient({
apiKey: 'API_KEY'
});
```
1. Appelez les méthodes d’API dans API Gateway à l’aide d’un code similaire à ce qui suit. Chaque appel renvoie une promesse avec des rappels de réussite et d’échec.
```
var params = {
// This is where any modeled request parameters should be added.
// The key is the parameter name, as it is defined in the API in API Gateway.
param0: '',
param1: ''
};
var body = {
// This is where you define the body of the request,
};
var additionalParams = {
// If there are any unmodeled query parameters or headers that must be
// sent with the request, add them here.
headers: {
param0: '',
param1: ''
},
queryParams: {
param0: '',
param1: ''
}
};
apigClient.methodName(params, body, additionalParams)
.then(function(result){
// Add success callback code here.
}).catch( function(result){
// Add error callback code here.
});
```
Ici, le *methodName* est construit à partir du chemin de ressource de la demande de méthode et du verbe HTTP. Pour l' SimpleCalc API, les méthodes du SDK pour les méthodes d'API de
```
1. GET /?a=...&b=...&op=...
2. POST /
{ "a": ..., "b": ..., "op": ...}
3. GET /{a}/{b}/{op}
```
les méthodes de kit SDK correspondantes sont les suivantes :
```
1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters
2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...}
3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters
```
# Utilisation d’un kit SDK Ruby généré par API Gateway pour une API REST
La procédure suivante montre comment utiliser un kit SDK Ruby généré par API Gateway.
**Note**
Ces instructions supposent que vous avez déjà suivi les instructions de [Générer SDKs pour REST APIs dans API Gateway](how-to-generate-sdk.md).
**Pour installer, instancier et appeler un kit SDK Ruby généré par API Gateway pour une API REST**
1. Décompressez le fichier du kit SDK Ruby téléchargé. La source du kit SDK généré est affichée comme suit.
![\[Décompressez le fichier du kit SDK Ruby téléchargé dans un module Ruby\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png)
1. Créez un gem Ruby à partir de la source du kit SDK généré, à l’aide des commandes shell suivantes dans une fenêtre de terminal :
```
# change to /simplecalc-sdk directory
cd simplecalc-sdk
# build the generated gem
gem build simplecalc-sdk.gemspec
```
Ensuite, **simplecalc-sdk-1.0.0.gem** devient disponible.
1. Installation du gem :
```
gem install simplecalc-sdk-1.0.0.gem
```
1. Créez une application client. Instanciez et initialisez le client du kit SDK Ruby dans l’application :
```
require 'simplecalc-sdk'
client = SimpleCalc::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50
)
```
Si l'API dispose d'une autorisation du `AWS_IAM` type configuré, vous pouvez inclure les informations d' AWS identification de l'appelant en fournissant `accessKey` et `secretKey` lors de l'initialisation :
```
require 'pet-sdk'
client = Pet::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50,
access_key_id: 'ACCESS_KEY',
secret_access_key: 'SECRET_KEY'
)
```
1. Effectuez des appels d’API via le kit SDK dans l’application.
**Astuce**
Si vous n’êtes pas familiarisé avec les conventions d’appel de méthode de kit SDK, vous pouvez consulter le fichier `client.rb` dans le dossier `lib` du kit SDK généré. Le dossier contient la documentation de chaque appel de méthode d’API pris en charge.
Pour connaître les opérations prises en charge :
```
# to show supported operations:
puts client.operation_names
```
Cela génère l’affichage suivant, qui correspond aux méthodes d’API de `GET /?a={.}&b={.}&op={.}`, `GET /{a}/{b}/{op}` et `POST /`, ainsi qu’une charge utile au format `{a:"…", b:"…", op:"…"}`, respectivement :
```
[:get_api_root, :get_ab_op, :post_api_root]
```
Pour appeler la méthode d’API `GET /?a=1&b=2&op=+`, appelez la méthode de kit SDK Ruby suivante :
```
resp = client.get_api_root({a:"1", b:"2", op:"+"})
```
Pour appeler la méthode d’API `POST /` avec une charge utile de `{a: "1", b: "2", "op": "+"}`, appelez la méthode de kit SDK Ruby suivante :
```
resp = client.post_api_root(input: {a:"1", b:"2", op:"+"})
```
Pour appeler la méthode d’API `GET /1/2/+`, appelez la méthode de kit SDK Ruby suivante :
```
resp = client.get_ab_op({a:"1", b:"2", op:"+"})
```
Les appels de méthode de kit SDK réussies renvoient la réponse suivante :
```
resp : {
result: {
input: {
a: 1,
b: 2,
op: "+"
},
output: {
c: 3
}
}
}
```
# Utilisation d’un kit SDK iOS généré par API Gateway pour une API REST dans Objective-C ou Swift
Dans ce didacticiel, nous vous expliquons comment utiliser un kit SDK iOS généré à l’aide d’API Gateway pour une API REST dans une application Objective-C ou Swift pour appeler l’API sous-jacente. Nous utiliserons l'[SimpleCalc API](simple-calc-lambda-api.md) comme exemple pour illustrer les sujets suivants :
+ Comment installer les composants du SDK AWS mobile requis dans votre projet Xcode
+ Création de l’objet de client d’API avant d’appeler les méthodes de l’API
+ Appel des méthodes d’API via les méthodes de kit SDK correspondantes sur l’objet de client d’API
+ Préparation d’une entrée de méthode et analyse de son résultat à l’aide des classes de modèle correspondantes du kit SDK
**Topics**
+ [
## Utilisation d'un kit SDK iOS généré (Objective-C) pour appeler une API
](#how-to-use-sdk-ios-objc)
+ [
## Utilisation d'un kit SDK iOS généré (Swift) pour appeler une API
](#how-to-generate-sdk-ios-swift)
## Utilisation d'un kit SDK iOS généré (Objective-C) pour appeler une API
Avant de commencer la procédure suivante, vous devez suivre la procédure décrite dans [Générer SDKs pour REST APIs dans API Gateway](how-to-generate-sdk.md) pour iOS dans Objective-C et télécharger le fichier .zip du kit SDK généré.
### Installer le SDK AWS mobile et un SDK iOS générés par API Gateway dans un projet Objective-C
La procédure suivante décrit comment installer le kit SDK.
**Pour installer et utiliser un kit SDK iOS généré par API Gateway dans Objective-C**
1. Extrayez le contenu du fichier .zip généré par API Gateway que vous avez précédemment téléchargé. À l'aide de l'[SimpleCalc API](simple-calc-lambda-api.md), vous souhaiterez peut-être renommer le dossier du SDK décompressé comme suit. **sdk\$1objc\$1simple\$1calc** Dans ce dossier de kit SDK se trouvent un fichier `README.md` et un fichier `Podfile`. Le fichier `README.md` contient les instructions pour installer et utiliser le kit SDK. Ce didacticiel fournit les détails de ces instructions. L'installation s'appuie sur [CocoaPods](https://cocoapods.org)l'importation des bibliothèques API Gateway requises et d'autres composants du SDK AWS mobile dépendants. Vous devez le mettre `Podfile` à jour pour l'importer SDKs dans le projet Xcode de votre application. Le dossier de kit SDK décompressé contient également un dossier `generated-src` qui contient le code source du kit SDK généré de votre API.
1. Lancez Xcode et créez un projet iOS Objective-C. Notez la cible du projet. Vous en avez besoin pour la définir dans le fichier `Podfile`.
![\[Recherchez la cible dans Xcode.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)
1. Pour l'importer Applications mobiles AWS SDK for iOS dans le projet Xcode à l'aide de CocoaPods, procédez comme suit :
1. Installez CocoaPods en exécutant la commande suivante dans une fenêtre de terminal :
```
sudo gem install cocoapods
pod setup
```
1. Copiez le fichier `Podfile` à partir du dossier de kit SDK extrait dans le même répertoire contenant votre fichier de projet Xcode. Remplacez le bloc suivant :
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
avec le nom cible de votre projet :
```
target 'app_objc_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Si votre projet Xcode contient déjà un fichier nommé `Podfile`, ajoutez-lui la ligne de code suivante :
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. Ouvrez une fenêtre de terminal et exécutez la commande suivante :
```
pod install
```
Cela installe le composant API Gateway et les autres composants du SDK AWS mobile dépendants.
1. Fermez le projet Xcode et ouvrez le fichier `.xcworkspace` pour relancer Xcode.
1. Ajoutez tous les fichiers `.h` et `.m` du répertoire `generated-src` du kit SDK extrait dans votre projet Xcode.
![\[Les fichiers .h et .m se trouvent dans generated-src.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)
*Pour importer l' Applications mobiles AWS SDK for iOS Objective-C dans votre projet en téléchargeant explicitement le SDK AWS mobile ou en utilisant [Carthage](https://github.com/Carthage/Carthage#installing-carthage), suivez les instructions du fichier README.md.* Veillez à n'utiliser qu'une seule de ces options pour importer le SDK AWS mobile.
### Appel des méthodes d’API à l’aide du kit SDK iOS généré par API Gateway dans un projet Objective-C
Lorsque vous avez généré le SDK avec le préfixe `SIMPLE_CALC` for this [SimpleCalc API](simple-calc-lambda-api.md) avec deux modèles pour l'entrée (`Input`) et la sortie (`Result`) des méthodes, dans le SDK, la classe client d'API résultante devient `SIMPLE_CALCSimpleCalcClient` et, respectivement, les `SIMPLE_CALCInput` classes de données correspondantes. `SIMPLE_CALCResult` Les demandes et réponses d'API sont mappées aux méthodes de kit SDK comme suit :
+ La demande d'API
```
GET /?a=...&b=...&op=...
```
devient la méthode du kit SDK
```
(AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
```
La propriété `AWSTask.result` est de type `SIMPLE_CALCResult` si le modèle `Result` a été ajouté à la réponse de méthode. Sinon, la propriété est de type `NSDictionary`.
+ Cette demande d'API
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
devient la méthode du kit SDK
```
(AWSTask *)rootPost:(SIMPLE_CALCInput *)body
```
+ La demande d'API
```
GET /{a}/{b}/{op}
```
devient la méthode du kit SDK
```
(AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
```
La procédure suivante décrit comment appeler les méthodes d’API dans le code source de l’application Objective-C, par exemple, comme faisant partie du délégué `viewDidLoad` dans un fichier `ViewController.m`.
**Pour appeler l'API via le kit SDK iOS généré par API Gateway**
1. Importez le fichier d’en-tête de la classe de client d’API pour que la classe de client d’API puisse être appelée dans l’application :
```
#import "SIMPLE_CALCSimpleCalc.h"
```
La déclaration `#import` importe également `SIMPLE_CALCInput.h` et `SIMPLE_CALCResult.h` pour les deux classes de modèle.
1. Instanciez la classe de client d'API :
```
SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
```
Pour utiliser Amazon Cognito avec l’API, définissez la propriété `defaultServiceConfiguration` sur l’objet `AWSServiceManager` par défaut, comme illustré ci-après, avant d’appeler la méthode `defaultClient` pour créer l’objet de client d’API (comme illustré dans l’exemple précédent) :
```
AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
```
1. Appelez la méthode `GET /?a=1&b=2&op=+` pour exécuter `1+2` :
```
[[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField1.text = [self handleApiResponse:task];
return nil;
}];
```
où `handleApiResponse:task` de la fonction d’assistant formate le résultat sous forme de chaîne pour l’afficher dans un champ de texte (`_textField1`).
```
- (NSString *)handleApiResponse:(AWSTask *)task {
if (task.error != nil) {
return [NSString stringWithFormat: @"Error: %@", task.error.description];
} else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
}
return nil;
}
```
Le résultat qui s'affiche est `1 + 2 = 3`.
1. Appelez la méthode `POST /` avec une charge utile pour exécuter `1-2` :
```
SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
input.a = [NSNumber numberWithInt:1];
input.b = [NSNumber numberWithInt:2];
input.op = @"-";
[[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField2.text = [self handleApiResponse:task];
return nil;
}];
```
Le résultat qui s'affiche est `1 - 2 = -1`.
1. Appelez la méthode `GET /{a}/{b}/{op}` pour exécuter `1/2` :
```
[[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField3.text = [self handleApiResponse:task];
return nil;
}];
```
Le résultat qui s'affiche est `1 div 2 = 0.5`. Ici, `div` est utilisé à la place de `/`, car la [fonction Lambda simple](simple-calc-nodejs-lambda-function.md) du backend ne gère pas les variables de chemin d'URL codée.
## Utilisation d'un kit SDK iOS généré (Swift) pour appeler une API
Avant de commencer la procédure suivante, vous devez suivre les étapes décrites dans [Générer SDKs pour REST APIs dans API Gateway](how-to-generate-sdk.md) pour iOS dans Swift et téléchargez le fichier .zip du kit SDK généré.
**Topics**
+ [
### Installation du SDK AWS mobile et du SDK généré par API Gateway dans un projet Swift
](#use-sdk-ios-swift-install-sdk)
+ [
### Appel des méthodes d’API via le kit SDK iOS généré par API Gateway dans un projet Swift
](#use-sdk-ios-swift-call-api)
### Installation du SDK AWS mobile et du SDK généré par API Gateway dans un projet Swift
La procédure suivante décrit comment installer le kit SDK.
**Pour installer et utiliser un kit SDK iOS généré par API Gateway dans Swift**
1. Extrayez le contenu du fichier .zip généré par API Gateway que vous avez précédemment téléchargé. À l'aide de l'[SimpleCalc API](simple-calc-lambda-api.md), vous souhaiterez peut-être renommer le dossier du SDK décompressé comme suit. **sdk\$1swift\$1simple\$1calc** Dans ce dossier de kit SDK se trouvent un fichier `README.md` et un fichier `Podfile`. Le fichier `README.md` contient les instructions pour installer et utiliser le kit SDK. Ce didacticiel fournit les détails de ces instructions. L'installation s'appuie sur l'importation [CocoaPods](https://cocoapods.org)des composants du SDK AWS mobile requis. Vous devez le mettre `Podfile` à jour pour l'importer SDKs dans le projet Xcode de votre application Swift. Le dossier de kit SDK décompressé contient également un dossier `generated-src` qui contient le code source du kit SDK généré de votre API.
1. Lancez Xcode et créez un projet iOS Swift. Notez la cible du projet. Vous en avez besoin pour la définir dans le fichier `Podfile`.
![\[Recherchez la cible dans Xcode.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)
1. Pour importer les composants du SDK AWS mobile requis dans le projet Xcode à l'aide de CocoaPods, procédez comme suit :
1. S'il n'est pas installé, installez-le CocoaPods en exécutant la commande suivante dans une fenêtre de terminal :
```
sudo gem install cocoapods
pod setup
```
1. Copiez le fichier `Podfile` à partir du dossier de kit SDK extrait dans le même répertoire contenant votre fichier de projet Xcode. Remplacez le bloc suivant :
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
avec le nom cible de votre projet comme indiqué :
```
target 'app_swift_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Si votre fichier de projet Xcode contient un fichier nommé `Podfile` avec la cible correcte, vous pouvez simplement ajouter la ligne de code suivante à la boucle `do ... end` :
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. Ouvrez une fenêtre de terminal et exécutez la commande suivante dans le répertoire de l’application :
```
pod install
```
Cela installe le composant API Gateway et tous les composants du SDK AWS mobile dépendants dans le projet de l'application.
1. Fermez le projet Xcode et ouvrez le fichier `*.xcworkspace` pour relancer Xcode.
1. Ajoutez tous les fichiers d’en-tête du kit SDK (`.h`) et les fichiers de code source Swift (`.swift`) du répertoire `generated-src` extrait à votre projet Xcode.
![\[Les fichiers .h et .swift se trouvent dans generated-src.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)
1. Pour permettre d'appeler les bibliothèques Objective-C du SDK AWS mobile à partir de votre projet de code Swift, définissez le chemin du `Bridging_Header.h` fichier sur la propriété **Objective-C Bridging Header** sous le **compilateur Swift - Paramètre général** de la configuration de votre projet Xcode :
![\[Définissez le chemin du fichier Bridging_Header.h sous Compilateur Swift - Général.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**Astuce**
Vous pouvez saisir **bridging** dans la zone de recherche de Xcode pour localiser la propriété **Objective-C Bridging Header (En-tête de transition Objective-C)**.
1. Créez le projet Xcode pour vérifier qu’il est correctement configuré avant de continuer. Si votre Xcode utilise une version de Swift plus récente que celle prise en charge par le SDK AWS mobile, vous obtiendrez des erreurs de compilation Swift. Dans ce cas, définissez la propriété **Use Legacy Swift Language Version** sur **Yes** sous le paramètre **Swift Compiler - Version** :
![\[Définissez la propriété Version héritée du langage Swift sur Oui.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)
Pour importer le SDK AWS mobile pour iOS dans Swift dans votre projet en téléchargeant explicitement AWS le SDK mobile ou en [utilisant](https://github.com/Carthage/Carthage#installing-carthage) Carthage, suivez les instructions du fichier fourni avec `README.md` le package du SDK. Veillez à n'utiliser qu'une seule de ces options pour importer le SDK AWS mobile.
### Appel des méthodes d’API via le kit SDK iOS généré par API Gateway dans un projet Swift
Lorsque vous avez généré le SDK avec le préfixe `SIMPLE_CALC` for this [SimpleCalc API](simple-calc-lambda-api.md) avec deux modèles pour décrire l'entrée (`Input`) et la sortie (`Result`) des demandes et réponses de l'API, dans le SDK, la classe client d'API résultante devient `SIMPLE_CALCSimpleCalcClient` et, respectivement, les classes de données correspondantes sont `SIMPLE_CALCInput` et`SIMPLE_CALCResult`. Les demandes et réponses d'API sont mappées aux méthodes de kit SDK comme suit :
+ La demande d'API
```
GET /?a=...&b=...&op=...
```
devient la méthode du kit SDK
```
public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
```
La propriété `AWSTask.result` est de type `SIMPLE_CALCResult` si le modèle `Result` a été ajouté à la réponse de méthode. Sinon, elle est de type `NSDictionary`.
+ Cette demande d'API
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
devient la méthode du kit SDK
```
public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
```
+ La demande d'API
```
GET /{a}/{b}/{op}
```
devient la méthode du kit SDK
```
public func aBOpGet(a: String, b: String, op: String) -> AWSTask
```
La procédure suivante décrit comment appeler les méthodes d’API dans le code source de l’application Swift, par exemple, comme faisant partie du délégué `viewDidLoad()` dans un fichier `ViewController.m`.
**Pour appeler l'API via le kit SDK iOS généré par API Gateway**
1. Instanciez la classe de client d'API :
```
let client = SIMPLE_CALCSimpleCalcClient.default()
```
Pour utiliser Amazon Cognito avec l'API, définissez une configuration de AWS service par défaut (illustrée ci-dessous) avant d'obtenir la `default` méthode (illustrée précédemment) :
```
let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")
let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)
AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
```
1. Appelez la méthode `GET /?a=1&b=2&op=+` pour exécuter `1+2` :
```
client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
où `self.showResult(task)` de la fonction d’assistant imprime le résultat ou l’erreur vers la console ; par exemple :
```
func showResult(task: AWSTask) {
if let error = task.error {
print("Error: \(error)")
} else if let result = task.result {
if result is SIMPLE_CALCResult {
let res = result as! SIMPLE_CALCResult
print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
} else if result is NSDictionary {
let res = result as! NSDictionary
print("NSDictionary: \(res)")
}
}
}
```
Dans une application de production, vous pouvez afficher le résultat ou l’erreur dans un champ de texte. Le résultat qui s'affiche est `1 + 2 = 3`.
1. Appelez la méthode `POST /` avec une charge utile pour exécuter `1-2` :
```
let body = SIMPLE_CALCInput()
body.a=1
body.b=2
body.op="-"
client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
Le résultat qui s’affiche est `1 - 2 = -1`.
1. Appelez la méthode `GET /{a}/{b}/{op}` pour exécuter `1/2` :
```
client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
Le résultat qui s'affiche est `1 div 2 = 0.5`. Ici, `div` est utilisé à la place de `/`, car la [fonction Lambda simple](simple-calc-nodejs-lambda-function.md) du backend ne gère pas les variables de chemin d'URL codée.
# Développez REST APIs à l'aide d'OpenAPI dans API Gateway
Vous pouvez utiliser API Gateway pour importer une API REST à partir d’un fichier de définition externe dans API Gateway. Actuellement, API Gateway prend en charge les fichiers de définition [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) et [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) avec les exceptions répertoriées dans [Remarques importantes relatives à Amazon API Gateway pour REST APIs](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). Vous pouvez mettre à jour une API en la remplaçant par une nouvelle définition, ou vous pouvez fusionner une définition avec une API existante. Vous précisez les options grâce à un paramètre de requête `mode` dans l’URL de demande.
Pour consulter un didacticiel sur l’utilisation de la fonction d’importation d’API à partir de la console API Gateway, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
**Topics**
+ [
# Importation d’une API optimisée pour la périphérie dans API Gateway
](import-edge-optimized-api.md)
+ [
# Importation d’une API régionale dans API Gateway
](import-export-api-endpoints.md)
+ [
# Importation d’un fichier OpenAPI pour mettre à jour une définition d’API existante
](api-gateway-import-api-update.md)
+ [
# Définition de la propriété `basePath` OpenAPI
](api-gateway-import-api-basePath.md)
+ [
# AWS variables pour l'importation d'OpenAPI
](import-api-aws-variables.md)
+ [
# Erreurs et avertissements liés à l’importation de votre API dans API Gateway
](api-gateway-import-api-errors-warnings.md)
+ [
# Exportation d’une API REST à partir d’API Gateway
](api-gateway-export-api.md)
# Importation d’une API optimisée pour la périphérie dans API Gateway
Vous pouvez importer un fichier de définition d’API OpenAPI pour créer une API optimisée pour la périphérie en spécifiant le type de point de terminaison `EDGE` sous la forme d’une entrée supplémentaire, en plus du fichier OpenAPI, dans l’opération d’importation. Vous pouvez le faire à l'aide de la console API Gateway ou d'un AWS SDK. AWS CLI
Pour consulter un didacticiel sur l’utilisation de la fonction d’importation d’API à partir de la console API Gateway, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
**Topics**
+ [
## Importation d’une API optimisée pour la périphérie à l’aide de la console API Gateway
](#import-edge-optimized-api-with-console)
+ [
## Importez une API optimisée pour les périphériques à l'aide du AWS CLI
](#import-edge-optimized-api-with-awscli)
## Importation d’une API optimisée pour la périphérie à l’aide de la console API Gateway
Pour importer une API optimisée pour la périphérie à l’aide de la console API Gateway, procédez comme suit :
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Create API (Créer une API)**.
1. Sous **API REST**, choisissez **Importer**.
1. Copiez une définition OpenAPI d’API et collez-la dans l’éditeur de code ou choisissez **Choisir un fichier** pour charger un fichier OpenAPI à partir d’un lecteur local.
1. Pour **Type de point de terminaison d’API**, sélectionnez **Optimisé pour la périphérie**.
1. Choisissez **Créer une API** pour importer les définitions OpenAPI.
## Importez une API optimisée pour les périphériques à l'aide du AWS CLI
La [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)commande suivante importe une API depuis un fichier de définition OpenAPI pour créer une nouvelle API optimisée pour les périphériques :
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
ou en spécifiant explicitement le paramètre de chaîne de requête `endpointConfigurationTypes` à `EDGE` :
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# Importation d’une API régionale dans API Gateway
Lors de l’importation d’une API, vous pouvez choisir la configuration de points de terminaison régionaux pour l’API. Vous pouvez utiliser la console API Gateway AWS CLI, le ou un AWS SDK.
Lorsque vous exportez une API, sa configuration de point de terminaison ne figure pas dans les définitions d’API exportées.
Pour consulter un didacticiel sur l’utilisation de la fonction d’importation d’API à partir de la console API Gateway, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md).
**Topics**
+ [
## Importation d’une API régionale à l’aide de la console API Gateway
](#import-regional-api-with-console)
+ [
## Importez une API régionale à l'aide du AWS CLI
](#import-regional-api-with-awscli)
## Importation d’une API régionale à l’aide de la console API Gateway
Pour importer une API d’un point de terminaison régional à l’aide de la console API Gateway, procédez comme suit :
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Create API (Créer une API)**.
1. Sous **API REST**, choisissez **Importer**.
1. Copiez une définition OpenAPI d’API et collez-la dans l’éditeur de code ou choisissez **Choisir un fichier** pour charger un fichier OpenAPI à partir d’un lecteur local.
1. Pour **Type de point de terminaison d’API**, sélectionnez **Régional**.
1. Choisissez **Créer une API** pour importer les définitions OpenAPI.
## Importez une API régionale à l'aide du AWS CLI
La [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)commande suivante importe un fichier de définition OpenAPI et définit le type de point de terminaison sur Regional :
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# Importation d’un fichier OpenAPI pour mettre à jour une définition d’API existante
Vous pouvez importer des définitions d’API uniquement pour mettre à jour une API existante, sans modifier la configuration de son point de terminaison, ainsi que ses étapes et variables d’étapes ou ses références à des clés d’API.
L' import-to-updateopération peut se produire selon deux modes : fusion ou remplacement.
Lorsqu'une API (`A`) est fusionnée avec une autre (`B`), l'API résultante conserve les définitions des deux `A` et `B` si les deux APIs ne partagent aucune définition contradictoire. Lorsque des conflits surviennent, les définitions de méthode de l’API fusionnante (`A`) remplacent les définitions de méthode correspondantes de l’API fusionnée (`B`). Par exemple, supposons que `B` déclare les méthodes suivantes pour renvoyer les réponses `200` et `206` :
```
GET /a
POST /a
```
et `A` déclare la méthode suivante pour renvoyer les réponses `200` et `400` :
```
GET /a
```
Lorsque `A` est fusionnée avec `B`, l’API résultante génère les méthodes suivantes :
```
GET /a
```
qui retourne les réponses `200` et `400`, et
```
POST /a
```
qui retourne les réponses `200` et `206`.
La fusion d’une API s’avère utile lorsque vous avez décomposé vos définitions d’API externes en plusieurs parties plus petites et souhaitez seulement appliquer les modifications à partir d’une de ces parties à la fois. Cela peut être le cas, par exemple, si plusieurs équipes sont responsables de différentes parties d’une API et que leurs modifications deviennent disponibles à des rythmes différents. Dans ce mode, les éléments de l’API existante qui ne sont pas spécifiquement définis dans la définition importée seront conservés.
Lorsqu’une API (`A`) remplace une autre (`B`), l’API résultante prend les définitions de l’API remplaçante (`A`). Le remplacement d’une API est utile lorsqu’une définition d’API externe contient la définition complète d’une API. Dans ce mode, les éléments d’une API existante qui ne sont pas spécifiquement définis dans la définition importée sont supprimés.
Pour fusionner une API, envoyez une requête `PUT` à `https://apigateway..amazonaws.com/restapis/?mode=merge`. La valeur du paramètre de chemin `restapi_id` spécifie l’API avec laquelle la définition d’API fournie va être fusionnée.
L’extrait de code suivant présente un exemple de requête `PUT` pour fusionner une définition d’API OpenAPI dans JSON en tant que charge utile, avec l’API spécifiée déjà présente dans API Gateway.
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
L’opération de mise à jour par fusion prend deux définitions d’API complètes et les fusionne ensemble. Pour une petite modification incrémentielle, vous pouvez utiliser l’opération de [mise à jour des ressources](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html).
Pour remplacer une API, envoyez une requête `PUT` à `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. Le paramètre de chemin `restapi_id` spécifie l’API qui sera remplacée par les définitions d’API fournies.
L’extrait de code suivant présente un exemple de requête de remplacement avec la charge utile d’une définition OpenAPI au format JSON :
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
Lorsque le paramètre `mode` de la requête n’est pas spécifié, le mode de fusion est sélectionné par défaut.
**Note**
Les opérations `PUT` sont idempotentes, mais pas atomiques. Cela signifie que si une erreur système se produit au cours du traitement, l’état final de l’API peut être incorrect. Cependant, la réussite de la répétition de l’opération fera passer l’API au même état final que si la première opération avait réussi.
# Définition de la propriété `basePath` OpenAPI
Dans [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), vous pouvez utiliser la propriété `basePath` pour fournir une ou plusieurs parties de chemin précédant chaque chemin défini dans la propriété `paths`. API Gateway peut exprimer le chemin d’une ressource de plusieurs façons. Par conséquent, la fonction d’importation d’API propose les options ci-après pour interpréter la propriété `basePath` au cours d’une importation : ignorer, préfixer et fractionner.
Dans [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` n’est plus une propriété de niveau supérieur. Au lieu de cela, API Gateway utilise une [variable serveur](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) en tant que convention. La fonction d’importation d’une API fournit les mêmes options pour interpréter le chemin de base lors de l’importation. Le chemin de base est identifié comme suit :
+ Si l’API ne contient pas de variables `basePath`, la fonction d’importation d’API vérifie la chaîne `server.url` pour voir si elle contient un chemin au-delà de `"/"`. Si c’est le cas, ce chemin est utilisé comme chemin de base.
+ Si l’API contient une seule variable `basePath`, la fonction d’importation d’API l’utilise comme chemin de base, même si elle n’est pas référencée dans la chaîne `server.url`.
+ Si l’API contient plusieurs variables `basePath`, la fonction d’importation d’API utilise uniquement la première comme chemin de base.
## Ignorer
Si le fichier OpenAPI comporte une valeur `basePath` `/a/b/c` et si la propriété `paths` contient `/e` et `/f`, la demande `POST` ou `PUT` suivante :
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
génère les ressources suivantes dans l'API :
+ `/`
+ `/e`
+ `/f`
Cela revient à traiter la propriété `basePath` comme si elle n’était pas présente, et toutes les ressources API déclarées sont traitées par rapport à l’hôte. Vous pouvez utiliser cette option, par exemple, lorsque vous avez un nom de domaine personnalisé avec un mappage d’API qui n’inclut pas de propriété *Base Path* et de valeur *Stage* faisant référence à votre étape de production.
**Note**
API Gateway crée automatiquement une ressource racine, même si elle n’est pas explicitement déclarée dans votre fichier de définition.
Lorsqu’elle n’est pas spécifiée, la propriété `basePath` prend la valeur `ignore` par défaut.
## Prepend
Si le fichier OpenAPI comporte une valeur `basePath` `/a/b/c` et si la propriété `paths` contient `/e` et `/f`, la demande `POST` ou `PUT` suivante :
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
génère les ressources suivantes dans l'API :
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
Cela revient à traiter la propriété `basePath` comme des ressources supplémentaires de spécification (sans méthode) et à ajouter celles-ci à l’ensemble de ressources déclarées. Vous pouvez utiliser cette option, par exemple, lorsque différentes équipes sont responsables des différentes parties d’une API et que la propriété `basePath` peut faire référence à l’emplacement du chemin de la partie d’API de chaque équipe.
**Note**
API Gateway crée automatiquement les ressources intermédiaires, même si elles ne sont pas explicitement déclarées dans votre définition.
## Split
Si le fichier OpenAPI comporte une valeur `basePath` `/a/b/c` et si la propriété `paths` contient `/e` et `/f`, la demande `POST` ou `PUT` suivante :
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
génère les ressources suivantes dans l'API :
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
Cela revient à traiter la partie supérieure du chemin, `/a`, comme le début du chemin de chaque ressource et à créer des ressources supplémentaires (sans méthode) au sein de l’API proprement dite. Vous pouvez utiliser cette option, par exemple, lorsque `a` est un nom d’étape que vous souhaitez exposer dans votre API.
# AWS variables pour l'importation d'OpenAPI
Vous pouvez utiliser les AWS variables suivantes dans les définitions d'OpenAPI. API Gateway résout les variables lorsque l’API est importée. Pour spécifier une variable, utilisez `${variable-name}`. Le tableau suivant décrit les AWS variables disponibles.
| Nom de la variable | Description |
| --- | --- |
| AWS::AccountId | L'ID du AWS compte qui importe l'API. Par exemple, 123456789012. |
| AWS::Partition | AWS Partition dans laquelle l'API est importée. Pour les AWS régions standard, la partition estaws. |
| AWS::Region | AWS Région dans laquelle l'API est importée. Par exemple, us-east-2. |
## AWS exemple de variables
L'exemple suivant utilise des AWS variables pour spécifier une AWS Lambda fonction pour une intégration.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# Erreurs et avertissements liés à l’importation de votre API dans API Gateway
Lorsque vous importez votre fichier de définition externe dans API Gateway, des avertissements et des erreurs peuvent être générés. Les sections suivantes décrivent les erreurs et les avertissements susceptibles de se produire lors de l’importation.
## Erreurs lors de l’importation
Lors de l’importation, des erreurs peuvent être générées pour les principaux problèmes, comme un document OpenAPI non valide. Les erreurs sont renvoyées en tant qu’exceptions (par exemple, `BadRequestException`) dans une réponse infructueuse. Lorsqu’une erreur se produit, la nouvelle définition d’API est ignorée et aucune modification n’est apportée à l’API existante.
## Avertissements lors de l’importation
Lors de l’importation, des avertissements peuvent être générés pour les problèmes mineurs, tels que l’absence d’une référence de modèle. En cas d’avertissement, l’opération continue si l’expression de requête `failonwarnings=false` est ajoutée à l’URL de la demande. Sinon, les mises à jour sont annulées. Par défaut, la propriété `failonwarnings` a la valeur `false`. Dans ce cas, les avertissements sont renvoyés sous forme de champ dans la [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource résultante. Sinon, les avertissements sont renvoyés sous la forme d’un message dans l’exception.
# Exportation d’une API REST à partir d’API Gateway
Une fois que vous avez créé et configuré une API REST dans API Gateway à l’aide de la console API Gateway ou par tout autre moyen, vous pouvez l’exporter dans un fichier OpenAPI à l’aide de la fonction d’exportation d’API API Gateway, qui fait partie du service de contrôle Amazon API Gateway. Pour utiliser l’API d’exportation d’API Gateway, vous devez signer vos demandes d’API. Pour plus d'informations sur les demandes de signature, consultez [la section Signing AWS API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) du *Guide de l'utilisateur IAM*. Des options vous permettent d’inclure les extensions d’intégration API Gateway, ainsi que les extensions [Postman](https://www.postman.com) dans le fichier de définition OpenAPI exporté.
**Note**
Lorsque vous exportez l'API à l'aide de AWS CLI, veillez à inclure le paramètre extensions comme indiqué dans l'exemple suivant, afin de garantir que l'`x-amazon-apigateway-request-validator`extension est incluse :
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
Vous ne pouvez pas exporter une API si ses charges utiles ne sont pas de type `application/json`. Si vous essayez, vous obtenez un message d’erreur indiquant que les modèles de corps JSON sont introuvables.
## Demande d’exportation d’une API REST
Avec l'API d'exportation, vous exportez une API REST existante en soumettant une requête GET, en spécifiant l' to-be-exportedAPI dans le cadre des chemins d'URL. L’URL de la requête est au format suivant :
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
Vous pouvez ajouter la chaîne de requête `extensions` pour spécifier si vous souhaitez inclure les extensions API Gateway (avec la valeur `integration`) ou les extensions Postman (avec la valeur `postman`).
En outre, vous pouvez affecter à l’en-tête `Accept` la valeur `application/json` ou `application/yaml` pour recevoir la définition d’API au format JSON ou YAML, respectivement.
Pour plus d'informations sur la soumission de requêtes GET à l'aide de l'API API Gateway Export, consultez [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html).
**Note**
Si vous définissez des modèles dans votre API, ils doivent être définis pour le type de contenu « application/json » pour qu’API Gateway les exporte. Sinon, API Gateway lance une exception avec le message d’erreur « Only found non-JSON body models for... » (Seuls des modèles de corps non-JSON ont été détectés pour...).
Les modèles doivent contenir des propriétés ou être définis comme un JSONSchema type particulier.
## Téléchargement d’une définition OpenAPI d’API REST au format JSON
Pour exporter et télécharger une API REST dans des définitions OpenAPI au format JSON :
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
Ici, `` pourrait être `us-east-1`, par exemple. Pour connaître toutes les régions où API Gateway est disponible, consultez [Régions et points de terminaison](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region).
## Téléchargement d’une définition OpenAPI d’API REST au format YAML
Pour exporter et télécharger une API REST dans des définitions OpenAPI au format YAML :
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Téléchargement d’une définition OpenAPI d’API REST avec les extensions Postman au format JSON
Pour exporter et télécharger une API REST dans des définitions OpenAPI avec Postman au format JSON :
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## Téléchargement d’une définition OpenAPI d’API REST avec intégration API Gateway au format YAML
Pour exporter et télécharger une API REST dans des définitions OpenAPI avec intégration API Gateway au format YAML :
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Exportation d'une API REST à l'aide de la console API Gateway
Après [avoir déployé votre API REST dans une étape](set-up-deployments.md#create-deployment), vous pouvez passer à l’exportation de cette API dans l’étape dans un fichier OpenAPI à l’aide de la console API Gateway.
Dans le volet **Étapes** de la console API Gateway, choisissez **Actions d’étape**, **Exporter**.
![\[Exportation d'une API REST à l'aide de la console API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/export-new-console.png)
Spécifiez un **type de spécification d’API**, un **format** et des **extensions** pour télécharger la définition OpenAPI de votre API.