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.
# Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway
Vous pouvez recourir à la transformation de modèle de mappage pour remplacer n’importe quel type de paramètre de demande, d’en-tête de réponse ou de code d’état de réponse. Vous allez utiliser un modèle de mappage pour :
+ Effectuer des mappages de many-to-one paramètres
+ Remplacer les paramètres une fois que les mappages API Gateway standard ont été appliqués
+ Mapper les paramètres de façon conditionnelle, en fonction du contenu du corps ou d’autres valeurs de paramètres
+ Créer des paramètres par programmation
+ Remplacer les codes de statut renvoyés par votre point de terminaison d’intégration
Les remplacements sont définitifs. Un remplacement ne peut être appliqué qu’une seule fois à chaque paramètre. Si vous tentez de remplacer le même paramètre à plusieurs reprises, API Gateway renvoie une réponse `5XX`. Si vous devez remplacer le même paramètre plusieurs fois tout au long du modèle, nous vous recommandons de créer une variable et d’appliquer le remplacement à la fin du modèle. Le modèle n’est appliqué qu’après l’analyse de l’ensemble du modèle.
## Exemple 1 : remplacement du code d’état en fonction du corps de la réponse d’intégration
L’exemple suivant utilise l’[exemple d’API](api-gateway-create-api-from-example.md) pour remplacer le code d’état en fonction du corps de la réponse d’intégration.
------
#### [ AWS Management Console ]
**Pour remplacer un code d’état en fonction du corps de la réponse d’intégration**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Create API** (Créer une API).
1. Sous **API REST**, choisissez **Création**.
1. Sous **Détails sur l’API**, choisissez **Exemple d’API**.
1. Sélectionnez **Create API** (Créer une API).
API Gateway crée un exemple d’API PetStore. Pour récupérer des informations sur un animal de compagnie, vous allez utiliser la demande de méthode d’API `GET /pets/{petId}`, où `{petId}` est un paramètre de chemin correspondant au numéro d’identification de l’animal.
Dans cet exemple, vous allez remplacer le code de réponse de la méthode `GET` par `400` lorsqu’une condition d’erreur est identifiée.
1. Dans l’arborescence **Ressources**, sous `GET`, choisissez la méthode sous `/{petId}`.
1. Tout d’abord, vous allez tester l’implémentation actuelle de l’API.
Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour **petId**, saisissez **-1**, puis choisissez **Tester**.
Le **corps de la réponse** indique une out-of-range erreur :
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
De plus, la dernière ligne sous **Journaux** se termine par : `Method completed with status: 200`.
L’intégration a été réalisée avec succès, mais une erreur s’est produite. Vous allez maintenant remplacer le code d’état en fonction de la réponse d’intégration.
1. Dans l’onglet **Réponse d’intégration**, pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**.
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Ce modèle de mappage utilise la variable `$context.responseOverride.status` pour remplacer le code d’état par `400` si la réponse d’intégration contient la chaîne `error`.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**.
1. Pour **petId**, saisissez **-1**.
1. Dans les résultats, le **corps de réponse** indique une out-of-range erreur :
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Cependant, la dernière ligne sous **Journaux** se termine maintenant par : `Method completed with status: 400`.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée la ressource `GET pets/{petId}` et remplace le code d’état en fonction du corps de la réponse d’intégration.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Exemple 2 : remplacement de l’en-tête de la demande et création de nouveaux en-têtes
L’exemple suivant utilise l’[exemple d’API](api-gateway-create-api-from-example.md) pour remplacer l’en-tête de la demande et créer de nouveaux en-têtes.
------
#### [ AWS Management Console ]
**Pour remplacer l’en-tête de demande d’une méthode en créant un nouvel en-tête**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez l’exemple d’API que vous avez créé dans le tutoriel précédent. Le nom de l'API doit être **PetStore**.
1. Dans l’arborescence **Ressources**, sous `GET`, choisissez la méthode sous `/pet`.
1. Dans l’onglet **Requête de méthode**, pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **En-têtes de demande HTTP**, puis **Ajouter un en-tête**.
1. Pour **Nom**, saisissez **header1**.
1. Choisissez **Ajouter un en-tête**, puis créez un second en-tête appelé **header2**.
1. Choisissez **Enregistrer**.
Vous pouvez maintenant combiner ces en-têtes en une seule valeur d’en-tête à l’aide d’un modèle de mappage.
1. Dans l’onglet **Demande d’intégration**, pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Pour **Transmission du corps de requête**, sélectionnez **Lorsqu’aucun modèle n’est défini (recommandé)**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Ce modèle de mappage remplace `header1` par la chaîne `pets`, et crée un en-tête à valeurs multiples appelé `$header3Value`, qui combine `header1` et `header2`.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**.
1. Sous **En-têtes**, copiez le code suivant :
```
header1:header1Val
header2:header2Val
```
1. Sélectionnez **Test**.
Dans **Journaux**, vous devriez voir une entrée incluant ce texte :
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée la ressource `GET pets`, remplace l’en-tête de la demande et crée de nouveaux en-têtes.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Pour remplacer un modèle de mappage, ajoutez une ou plusieurs des variables `$context` suivantes. Pour obtenir la liste des variables `$context`, consultez [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference).