Transformez les API demandes et les réponses HTTP APIs dans API Gateway - APIPasserelle Amazon
Transformation API des demandesTransformation API des réponsesEn-têtes réservésExemples

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.

Transformez les API demandes et les réponses HTTP APIs dans API Gateway

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

Transformation API des demandes

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.

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.

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. APIGateway 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. APIGateway combine plusieurs valeurs avec des virgules, par exemple"querystring1" "Value1,Value2".
Corps de la demande $request.body.name ou $ {request.body.name} Une expression de JSON chemin. 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 JSON chemin, API Gateway tronque le corps de la demande à 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 $contexte.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 API des réponses

Vous utilisez les paramètres de réponse pour transformer la HTTP réponse d'une intégration principale avant de la renvoyer aux clients. Vous pouvez modifier les en-têtes ou le code d'état d'une réponse avant que 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.

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.

Type Syntaxe Remarques
Valeur d'en-tête $response.en-tête.name ou $ {response.header.name} Les noms d'en-tête ne sont pas sensibles à la casse. APIGateway 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} Une expression de JSON chemin. 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 JSON chemin, 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 $contexte.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 AWS CLI exemples suivants configurent les mappages de paramètres. Pour des exemples AWS CloudFormation de modèles, voir GitHub.

Ajouter un en-tête à une API demande

L'exemple suivant ajoute un en-tête nommé header1 à une API demande avant qu'elle n'atteigne votre intégration principale. APIGateway 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 change le code d'état en 403 et ajoute header1 1 à la réponse. Lorsque l'intégration renvoie un code d'état 404, API Gateway ajoute un error en-tête à 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" : {}}'