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.
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. Vous utilisez le mappage de paramètres pour modifier les demandes et réponses d'API pour le protocole HTTP APIs. 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.
| Type | Syntaxe |
|---|---|
| En-tête | append|overwrite|remove:header. |
| Chaîne de requête | append|overwrite|remove:querystring. |
| 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. nameou $ {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. nameou $ {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. nameou $ {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. NoteLorsque 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 |
| 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. nameou $ {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. variableNameou $ {context. variableName} |
Valeur d’une variable de contexte. NoteSeuls les caractères spéciaux |
| Variable d’étape | $StageVariables. variableNameou $ {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 de statut 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 de statut 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. |
| Code de statut | 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. nameou $ {response.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. |
| Corps de la réponse | $response.body. nameou $ {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. NoteLorsque 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 |
| Variable de contexte | $contexte. variableNameou $ {context. variableName} |
Valeur d'une variable de contexte prise en charge. |
| Variable d'étape | $StageVariables. variableNameou $ {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 demande d’API
La commande create-integration suivante crée un en-tête nommé header1 pour une demande d'API avant qu'elle n'atteigne votre intégration principale. 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
La commande create-integration suivante renomme un en-tête de demande en : header1 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
La commande create-integration suivante configure les paramètres de réponse pour une intégration. Lorsque les intégrations renvoient un code de statut 500, API Gateway modifie le code de statut en 403 et ajoute header11 à la réponse. Lorsque l’intégration renvoie un code de statut 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
La commande update-integration suivante 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 de statut 200.
aws apigatewayv2 update-integration \ --api-id abcdef123 \ --integration-id hijk456 \ --request-parameters '{"append:header.header1" : ""}' \ --response-parameters '{"200" : {}}'
