Configuration des mappages de données de demande et de réponse à l'aide de la console 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.

Configuration des mappages de données de demande et de réponse à l'aide de la console API Gateway

Pour utiliser la console API Gateway pour définir la demande/réponse d'intégration de l'API, suivez ces instructions.

Note

Ces instructions supposent que vous avez déjà réalisé les étapes de Configuration d'une demande d'intégration d'API à l'aide de la console API Gateway.

  1. Dans le volet Ressources, choisissez votre méthode.

  2. Dans l’onglet Requête d’intégration, sous Paramètres de requête d’intégration, choisissez Modifier.

  3. Choisissez une option pour le transfert du corps de la requête afin de configurer la manière dont le corps de la demande de méthode d'un type de contenu non mappé sera transmis à travers la demande d'intégration sans transformation vers la fonction Lambda, le proxy HTTP ou le proxy de service. AWS Trois options sont disponibles :

    • Sélectionnez Quand aucun modèle ne correspond à l’en-tête de requête Content-Type si vous voulez que le corps de la requête de méthode soit transmis au backend via la requête d’intégration sans transformation lorsque le type de contenu de la requête de méthode ne correspond à aucun type de contenu associé aux modèles de mappage, tel que défini à l’étape suivante.

      Note

      Lorsque vous appelez l'API API Gateway, vous sélectionnez cette option en affectant la valeur WHEN_NO_MATCH à la propriété passthroughBehavior sur la ressource d'intégration.

    • Sélectionnez When there are no templates defined (recommended) 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 d'un type de contenu non mappé est rejetée en renvoyant une réponse HTTP 415 Type de support non pris en charge.

      Note

      Lorsque vous appelez l'API API Gateway, vous sélectionnez cette option en affectant la valeur WHEN_NO_TEMPLATE à la propriété passthroughBehavior sur la ressource d'intégration.

    • Sélectionnez Never si vous ne souhaitez pas que la demande de méthode soit transmise lorsque le type de contenu de la demande de méthode ne correspond à aucun type de contenu associé aux modèles de mappage définis dans la demande d'intégration ou lorsqu'aucun modèle de mappage n'est défini dans la demande d'intégration. 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.

      Note

      Lorsque vous appelez l'API API Gateway, vous sélectionnez cette option en affectant la valeur NEVER à la propriété passthroughBehavior sur la ressource d'intégration.

    Pour plus d'informations sur les comportements de transfert d'intégration, consultez Comportements de transfert direct.

  4. Pour un proxy HTTP ou un proxy de AWS service, pour associer un paramètre de chemin, un paramètre de chaîne de requête ou un paramètre d'en-tête défini dans la demande d'intégration à un paramètre de chemin, un paramètre de chaîne de requête ou un paramètre d'en-tête correspondant dans la demande de méthode du proxy HTTP ou du proxy de AWS service, procédez comme suit :

    1. Choisissez respectivement Paramètres du chemin de l’URL, Paramètres de la chaîne de requêtes de l’URL ou En-têtes de requête HTTP, puis choisissez respectivement Ajouter un chemin, Ajouter une chaîne de requête ou Ajouter un en-tête.

    2. Pour Nom, tapez le nom du paramètre de chemin, du paramètre de chaîne de requête ou du paramètre d'en-tête dans le proxy HTTP ou le proxy AWS de service.

    3. Pour Mappage à partir de, saisissez la valeur de mappage du paramètre de chemin, du paramètre de chaîne de requête ou du paramètre d’en-tête. Utilisez l'un des formats suivants :

      • method.request.path.parameter-name pour un paramètre de chemin nommé parameter-name, tel que défini dans la page Requête de méthode.

      • method.request.querystring.parameter-name pour un paramètre de chaîne de requête nommé parameter-name, tel que défini dans la page Requête de méthode.

      • method.request.multivaluequerystring.parameter-name pour un paramètre de chaîne de requête multi-valeurs nommé parameter-name, tel que défini dans la page Requête de méthode.

      • method.request.header.parameter-name pour un paramètre d’en-tête nommé parameter-name, tel que défini dans la page Requête de méthode.

        Sinon, vous pouvez affecter une valeur de chaîne littérale (délimitée par une paire de guillemets simples) à un en-tête d'intégration.

      • method.request.multivalueheader.parameter-name pour un paramètre d’en-tête multi-valeurs nommé parameter-name, tel que défini dans la page Requête de méthode.

    4. Pour ajouter un autre paramètre, cliquez sur le bouton Ajouter.

  5. Pour ajouter un modèle de mappage, choisissez Modèles de mappage.

  6. Pour définir un modèle de mappage pour une requête entrante, choisissez Ajouter un modèle de mappage. Pour Type de contenu, saisissez un type de contenu (par exemple, application/json). Entrez ensuite le modèle de mappage. Pour plus d’informations, consultez Modèles de mappage pour les API REST.

  7. Choisissez Enregistrer.

  8. Vous pouvez mapper une réponse d'intégration du backend à une réponse de méthode de l'API renvoyée à l'application appelante. Cela implique de renvoyer au client les en-têtes de réponse sélectionnés à partir de ceux disponibles sur le backend, en convertissant le format de données de la charge utile de la réponse du backend dans un format spécifié par l'API. Vous pouvez définir le mappage en configurant les champs Réponse de méthode et Réponses d’intégration.

    Pour que la méthode reçoive un format de données de réponse personnalisé basé sur le code d'état HTTP renvoyé par la fonction Lambda, le proxy HTTP ou le proxy de AWS service, procédez comme suit :

    1. Choisissez Réponses d’intégration. Choisissez Modifier sur Par défaut - Réponse, pour spécifier les paramètres d’un code de réponse HTTP 200 renvoyé par la méthode, ou sélectionnez Créer une réponse pour spécifier les paramètres de tout autre code de statut de réponse HTTP renvoyé par la méthode.

    2. Pour l'expression régulière d'erreur Lambda (pour une fonction Lambda) ou l'expression régulière d'état HTTP (pour un proxy HTTP ou un proxy de AWS service), entrez une expression régulière pour spécifier quelles chaînes d'erreur de fonction Lambda (pour une fonction Lambda) ou quels codes d'état de réponse HTTP (pour un proxy HTTP ou un proxy de service) correspondent à ce mappage de sortie. AWS Par exemple, pour mapper tous les codes d'état de réponse HTTP 2xx d'un proxy HTTP à ce mappage de sortie, saisissez 2\d{2} dans le champ HTTP status regex (Expressions régulières de l'erreur HTTP). Pour renvoyer un message d’erreur contenant « Requête non valide » à partir d’une fonction Lambda à une réponse 400 Bad Request, saisissez « .*Invalid request.* » comme Expressions régulières de l’erreur Lambda. En revanche, pour renvoyer 400 Bad Request pour tous les messages d’erreur non mappés à partir de Lambda, saisissez « (\n|.)+ » dans le champ Expressions régulières de l’erreur Lambda. Cette dernière expression régulière peut être utilisée pour la réponse d'erreur par défaut d'une API.

      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 dans la documentation Oracle.

      Les modèles d'erreur sont mis en correspondance avec toute la chaîne de la propriété errorMessage dans la réponse Lambda, qui est renseignée par callback(errorMessage) dans Node.js ou par throw new MyException(errorMessage) en Java. De plus, les caractères d’échappement sont sans séquence d'échappement avant l'application d'une expression régulière.

      Si vous utilisez « + » comme modèle de sélection pour filtrer les réponses, sachez qu'il est possible que ce modèle ne corresponde pas à une réponse contenant un caractère de nouvelle ligne.

    3. Si l’option est activée, pour Statut de la réponse de méthode, sélectionnez le code de statut de réponse HTTP que vous avez défini dans la page Réponse de méthode.

    4. Pour Mappages d’en-tête, pour chaque en-tête que vous avez défini pour le code de statut de réponse HTTP dans la page Réponse de méthode, spécifiez une valeur de mappage. Pour Mapping value (Valeur de mappage), utilisez l'un des formats suivants :

      • integration.response.multivalueheaders.header-name, où header-name est le nom d'un en-tête de réponse multi-valeurs du backend.

        Par exemple, pour renvoyer l'en-tête Date de la réponse du backend en tant qu'en-tête Timestamp de la réponse de méthode d'une API, la colonne Response header (En-tête de réponse) doit contenir une entrée Timestamp (Horodatage) et la valeur associée du champ Mapping value (Valeur de mappage) doit être integration.response.multivalueheaders.Date.

      • integration.response.header.header-name, où header-name est le nom d'un en-tête de réponse à valeur unique du backend.

        Par exemple, pour renvoyer l'en-tête Date de la réponse du backend en tant qu'en-tête Timestamp de la réponse de méthode d'une API, la colonne Response header (En-tête de réponse) doit contenir une entrée Timestamp (Horodatage) et la valeur associée du champ Mapping value (Valeur de mappage) doit être integration.response.header.Date.

    5. Choisissez Modèles de mappage, puis choisissez Ajouter un modèle de mappage. Dans le champ Type de contenu, entrez le type de contenu des données qui seront transmises par la fonction Lambda, le proxy HTTP ou le proxy de AWS service à la méthode. Entrez ensuite le modèle de mappage. Pour plus d’informations, consultez Modèles de mappage pour les API REST.

    6. Choisissez Enregistrer.