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