Réponses de passerelle dans API Gateway - Amazon 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.

Réponses de passerelle dans API Gateway

Un 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 de statut HTTP, d'un ensemble d'en-têtes supplémentaires qui sont spécifiés par des mappages de paramètres et une charge utile qui est générée par un modèle de mappage non-VTL.

Dans l'API REST API Gateway, une réponse de passerelle est représentée par GatewayResponse. Dans OpenAPI, une instance GatewayResponse est décrite par l'extension x-amazon-apigateway-gateway-responses.gatewayResponse.

Pour activer une réponse de passerelle, vous configurez une réponse de passerelle pour un type de réponse pris en charge 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 sert d'intermédiaire entre un échange externe et le Cloud AWS, vous utilisez des modèles de mappage VTL pour une demande d'intégration ou une réponse 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 $contextVariables pour les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès. Pour plus d'informations sur $stageVariables, consultez $stageVariables. Pour plus d'informations sur les paramètres de demande de méthode, reportez-vous à la section Variables $input.