Transformer les demandes et les réponses d'API

Vous pouvez modifier les demandes d'API des clients avant qu'elles n'atteignent vos intégrations backend. Vous pouvez également modifier la réponse des intégrations avant qu'API Gateway ne la renvoie aux clients. Le mappage de paramètres vous permet de modifier les demandes et les réponses d'API pour les API HTTP. Pour utiliser le mappage de paramètres, spécifiez les paramètres de demande ou de réponse d'API à modifier, et indiquez comment modifier ces paramètres.

Transformation des demandes d'API

Les paramètres de demande vous permettent de modifier les demandes avant qu'elles n'atteignent vos intégrations backend. Vous pouvez modifier les en-têtes, les chaînes de la demande ou le chemin de la demande.

Les paramètres de demande sont représentés par un mappage clé-valeur. La clé identifie l'emplacement du paramètre de demande à modifier, ainsi que la façon de le modifier. La valeur spécifie les nouvelles données pour le paramètre.

Le tableau suivant présente les clés prises en charge.

Clés de mappage de paramètres
Type	Syntaxe
En-tête	append|overwrite|remove:header.headername
Chaîne de requête	append|overwrite|remove:querystring.querystring-name
Chemin	overwrite:path

Le tableau suivant présente les valeurs prises en charge que vous pouvez mapper aux paramètres.

Valeurs de mappage des paramètres de demande
Type	Syntaxe	Remarques
Valeur d’en-tête	$request.header.name ou ${request.header.name}	Les noms d’en-tête ne sont pas sensibles à la casse. API Gateway combine plusieurs valeurs d'en-tête avec des virgules, par exemple "header1": "value1,value2". Certains en-têtes sont réservés. Pour en savoir plus, consultez la section En-têtes réservés.
Valeur de chaîne de requête	$request.querystring.name ou ${request.querystring.name}	Les noms de chaîne de requête sont sensibles à la casse. API Gateway combine plusieurs valeurs avec des virgules, par exemple "querystring1" "Value1,Value2".
Corps de la demande	$request.body.name ou ${request.body.name}	Expression de chemin JSON. La descente récursive ($request.body..name) et les expressions de filtre (?(expression)) ne sont pas prises en charge. Note Lorsque vous spécifiez un chemin JSON, API Gateway tronque le corps de la requête à 100 Ko, puis applique l'expression de sélection. Pour envoyer des charges utiles supérieures à 100 Ko, spécifiez $request.body.
Chemin de la demande.	$request.path ou ${request.path}	Chemin de la demande, sans le nom de l'étape.
Paramètre de chemin	$request.path.name ou ${request.path.name}	Valeur d'un paramètre de chemin dans la demande. Par exemple, si la route est /pets/{petId}, vous pouvez mapper le paramètre petId de la demande avec $request.path.petId.
Variable de contexte	$context.variableName ou ${context.variableName}	Valeur d'une variable de contexte. Note Seuls les caractères spéciaux . et _ sont pris en charge.
Variable d’étape	$stageVariables.variableName ou ${stageVariables.variableName}	Valeur d’une variable d’étape.
Valeur statique	string	Valeur constante.

Note

Pour utiliser plusieurs variables dans une expression de sélection, placez la variable entre crochets. Par exemple, ${request.path.name} ${request.path.id}.

Transformation des réponses d'API

Les paramètres de réponse vous permettent de transformer la réponse HTTP à partir d'une intégration backend avant de retourner la réponse aux clients. Vous pouvez modifier les en-têtes ou le code d'état d'une réponse avant qu'API Gateway ne renvoie la réponse aux clients.

Vous configurez les paramètres de réponse pour chaque code d'état renvoyé par votre intégration. Les paramètres de réponse sont représentés par un mappage clé-valeur. La clé identifie l'emplacement du paramètre de demande à modifier, ainsi que la façon de le modifier. La valeur spécifie les nouvelles données pour le paramètre.

Le tableau suivant présente les clés prises en charge.

Clés de mappage des paramètres de réponse
Type	Syntaxe
En-tête	append|overwrite|remove:header.headername
Code d'état	overwrite:statuscode

Le tableau suivant présente les valeurs prises en charge que vous pouvez mapper aux paramètres.

Valeurs de mappage des paramètres de réponse
Type	Syntaxe	Remarques
Valeur d’en-tête	$response.header.nom ou ${response.header.nom}	Les noms d’en-tête ne sont pas sensibles à la casse. API Gateway combine plusieurs valeurs d'en-tête avec des virgules, par exemple "header1": "value1,value2". Certains en-têtes sont réservés. Pour en savoir plus, consultez la section En-têtes réservés.
Corps de la réponse	$response.body.name ou ${response.body.name}	Expression de chemin JSON. La descente récursive ($response.body..name) et les expressions de filtre (?(expression)) ne sont pas prises en charge. Note Lorsque vous spécifiez un chemin JSON, API Gateway tronque le corps de la réponse à 100 Ko, puis applique l'expression de sélection. Pour envoyer des charges utiles supérieures à 100 Ko, spécifiez $response.body.
Variable de contexte	$context.variableName ou ${context.variableName}	Valeur d'une variable de contexte prise en charge.
Variable d’étape	$stageVariables.variableName ou ${stageVariables.variableName}	Valeur d’une variable d’étape.
Valeur statique	string	Valeur constante.

Note

Pour utiliser plusieurs variables dans une expression de sélection, placez la variable entre crochets. Par exemple, ${request.path.name} ${request.path.id}.

En-têtes réservés

Les en-têtes suivants sont réservés. Vous ne pouvez pas configurer les mappages de demande ou de réponse pour ces en-têtes.

• access-control-*

• apigw-*

• Autorisation

• Connection

• Encodage-Contenu

• Content-Length

• Content-Location

• Forwarded

• Keep-Alive

• Origin

• Proxy-Authenticate

• Proxy-Authorization

• TE

• Trailers

• Transfer-Encoding

• Upgrade

• x-amz-*

• x-amzn-*

• X-Forwarded-For

• X-Forwarded-Host

• X-Forwarded-Proto

• Via

Exemples

Les exemples AWS CLI suivants configurent les mappages de paramètres. Pour des exemples de modèles AWS CloudFormation, veuillez consulter GitHub.

Ajouter un en-tête à une demande d'API

L'exemple suivant ajoute un en-tête nommé header1 à une demande d'API avant qu'elle n'atteigne votre intégration backend. API Gateway remplit l'en-tête avec l'ID de demande.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }' 

Renommer un en-tête de demande

L'exemple suivant renomme un en-tête de demande header1 en header2.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'

Modifier la réponse d'une intégration

L'exemple suivant configure les paramètres de réponse pour une intégration. Lorsque les intégrations renvoient un code d'état 500, API Gateway modifie le code d'état en 403 et ajoute header11 à la réponse. Lorsque l'intégration renvoie un code d'état 404, API Gateway ajoute un en-tête error à la réponse.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'

Supprimer les mappages de paramètres configurés

L'exemple de commande suivant supprime les paramètres de demande précédemment configurés pour append:header.header1. Il supprime également les paramètres de réponse précédemment configurés pour un code d'état 200.

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'