Configuration d’une demande de méthode dans API Gateway

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.

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.

La configuration d'une demande de méthode implique l'exécution des tâches suivantes, après avoir créé une RestApiressource :

Vous pouvez effectuer ces tâches à l’aide des méthodes suivantes :

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) 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 {api-id} 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.

Pour l'PetStore exemple d'API, 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 suivante permet de récupérer 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 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 de chemin gourmand.

La commande create-resource suivante crée une ressource proxy sous le root () /{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'prodétape d'une API.

ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog

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 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 suivante crée une demande de méthode pour le ANY verbe 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.

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 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 GET /pets méthode utilise un paramètre de chaîne de requête facultatif de type et un paramètre d'en-tête facultatif deage, vous pouvez les déclarer à l'aide de la commande put-method 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 interroger les animaux par type :

GET /pets?type=dog

Et le client peut interroger 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 les API REST dans API Gateway.

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 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, générer un kit SDK 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, consultez Comprendre les modèles de données.

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 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 Model 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é 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 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_IAM. 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 :

{
    "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.

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:Invokeaction. Pour plus d’informations sur les autorisations entre comptes, consultez Utilisation des rôles IAM.

Vous pouvez utiliser AWS CLI un AWS SDK ou un client d'API REST, tel que Postman, qui implémente la signature Signature Version 4 (SigV4).

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 authorizer-id sur la valeur de propriété 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.

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 authorizer-id sur la valeur de propriété 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ôle de l’accès aux API REST à l’aide de groupes d’utilisateurs Amazon Cognito en tant que mécanisme d’autorisation.

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. Vous devez d'abord créer un validateur de demande. La create-request-validatorcommande 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 des demandes dans le cadre de la configuration des demandes de méthode. La commande put-method suivante crée une demande de méthode qui nécessite que le corps de la demande entrante corresponde à celui PetModel et comporte deux paramètres de demande qui ne sont pas obligatoires :

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 sur validateRequestParameters true pour le validateur de demande et définir le paramètre de demande spécifique sur true dans la put-method commande.