Comment mapper les codes d'état de réponse pour les intégrations API Gateway dans les API REST ?

Solution

Lorsque vous souhaitez remplacer les codes d'état de vos réponses d'arrière-plan, utilisez des modèles de mappage API Gateway ou des expressions régulières pour mapper les codes d'état. Vous pouvez le faire dans le cadre d'intégrations proxy et non proxy avec l'API REST.

Les intégrations proxy et non proxy sont utilisées pour mapper les codes d'état de réponse dans l'API REST. En cas de réponse du proxy, API Gateway reçoit les codes d'état tels qu'ils sont envoyés par le backend. Dans le cadre d'une intégration par proxy Lambda, API Gateway a besoin de la fonction Lambda principale pour renvoyer la sortie suivante au format JSON :

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode, 
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": “…”65411
}

Lors d'une intégration par proxy avec une fonction Lambda, un code d'état est transmis directement à API Gateway à partir d'une fonction Lambda principale. Un code d'état ne peut pas être transmis directement à partir de la fonction Lambda dans le cadre d'une intégration sans proxy.

Lorsque API Gateway invoque avec succès une fonction Lambda, le code d'état de réponse par défaut est 200. Les codes d'état sont également renvoyés lorsque Lambda rencontre des erreurs. Vous pouvez personnaliser les codes de réponse d'API Gateway. Utilisez une intégration sans proxy et un modèle de mappage lorsque vous devez créer un code de réponse personnalisé.

Configuration d'une méthode de réponse avec un code personnalisé

Suivez ces étapes pour configurer une méthode permettant de répondre avec un code de réponse personnalisé à partir d'API Gateway :

1.    Dans la console API Gateway, créez une nouvelle API REST.

2.    Créez une ressource et une méthode pour la ressource.

3.    Configurez une réponse de méthode qui inclut le code d'état que vous souhaitez qu'API Gateway renvoie.

4.    Configurez une réponse d'intégration Lambda.

• Pour Lambda Error Regex, fournissez le modèle d'expression régulière pour le message d'erreur renvoyé par la fonction Lambda.
  Remarque : Vous pouvez également trouver la regex d'erreur HTTP pour les réponses HTTP.
• Pour l'état de réponse de la méthode, fournissez le code d'état qui doit être renvoyé par API Gateway.
• Choisissez une option pour Gestion du contenu afin de définir la manière dont le corps de la réponse est traité avant que la réponse ne soit envoyée au client.
• Assurez-vous que le modèle par défaut du code d'état est défini sur 200.

5.    Une fois que vous avez fini de configurer votre réponse d'intégration, enregistrez, testez et déployez vos modifications.

Mappage des codes d'état aux valeurs statiques

Pour qu'API Gateway puisse capturer un groupe de codes d'état renvoyés par votre backend, mappez les codes de statut à des valeurs statiques :

1.    Accédez à la ressource dont vous souhaitez modifier le code de statut.

2.    Configurez une réponse de méthode pour renvoyer 400 en tant que code de réponse API Gateway.

3.    Revenez aux configurations des ressources et configurez une réponse d'intégration.

4.    Les valeurs de la regex de statut HTTP capturent l'état renvoyé par votre backend. L'état est ensuite mappé au code de réponse défini à l'étape 2.

Lorsque la regex d'état HTTP a une valeur par défaut de « - » et est mappée à 200 comme état de réponse de la méthode, tous les codes d'état sont capturés et renvoyés par votre carte principale à 200. Vous pouvez modifier les valeurs regex du statut HTTP sur 2 \ d \ {2 } pour capturer toutes les réponses 2xx et les mapper à 200.

5.    Choisissez Ajouter une réponse d'intégration pour capturer les autres codes de statut.

Pour 4xx, dans la regex de statut HTTP, ajoutez 4 \ d \ {2 }. Pour l'état de réponse de la méthode, choisissez 400. Cela a été défini à l'étape 2.

6.    Déployez votre API. Lorsque l'API renvoie des codes de statut 2xx, ils sont mappés au code de statut 200. Si votre API renvoie des codes de statut 4xx, ils sont mappés au code de statut 400.

Les expressions régulières peuvent être mises en forme de différentes manières. Par exemple :

• .* ([01] [0-9] [0-9] |2 [0-4] [0-9] |25 [0-5]) .* correspond à des codes de statut compris entre 100-199, 200-249 ou 250-255.
• .*5 \ d \ d.* correspond à un code de statut, tel que 5xx.

L'exemple de code suivant permet de tester une fonction Lambda :

def lambda_handler(event, context):
    if "error" not in event or event['error'] == "":
        return("Pass")
    elif event['error'] == 'sample 400':
        raise Exception({"errorMessage": "Error: Raising 400 from within the Lambda function","errorType": "Exception"})
    elif event['error'] == 'sample 500':
        raise Exception({"errorMessage": "Error: Raising 500 from within the Lambda function","errorType": "Exception"})
    else:
        return("Error Value in the json request should either be 400 or 500 to demonstrate")

Dans l'exemple, le code vérifie si la valeur d'erreur envoyée depuis API Gateway est une erreur 400 ou 500. Lorsqu'il s'agit d'une erreur 400 ou 500, le code Lambda déclenche une exception avec un message d'erreur. Lorsque API Gateway reçoit la réponse, le service vérifie si le message d'erreur correspond à un modèle configuré dans la réponse d'intégration. API Gateway répond en conséquence si le modèle de regex Lambda correspond.

7.    Après une configuration réussie, les codes d'état peuvent être testés à l'aide de la console API Gateway.

Mappage des codes d'état avec des modèles

L'exemple précédent utilise des expressions régulières, mais il peut également utiliser des modèles de mappage. L'exemple suivant remplace le code de statut 200 du backend pour appliquer le code de statut 400 :

1.    Créez une fonction Lambda à l'aide de l'exemple de code suivant :

----------------------
def lambda_handler(event, context):
    # TODO implement print(event)
    return { 'statusCode': 200, 'body': "customerror" }
-----------------------

2.    Créez une API avec intégration Lambda sans proxy en utilisant la fonction Lambda précédente pour le backend.

3.    Suivez les étapes 6 à 10 décrites dans le didacticiel Remplacer le code d'état de réponse d'une API par la console API Gateway.

Dans cet exemple, utilisez le modèle de mappage suivant :

----------------------
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("customerror"))
#set($context.responseOverride.status = 400)
#end 
----------------------

4.    Enregistrez, testez et déployez l'API.

---

Informations connexes

Utilisation de modèles et de modèles de mappage

Transformation des requêtes et réponses d'API

Guide du développeur Amazon API Gateway