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.
# Exemples de mappage de paramètres pour REST APIs dans API Gateway
Les exemples suivants montrent comment créer des expressions de mappage de paramètres à l’aide de la console API Gateway, d’OpenAPI et de modèles CloudFormation . Pour voir un exemple d’utilisation du mappage de paramètres dans le but de créer les en-têtes CORS requis, consultez [CORS pour REST APIs dans API Gateway](how-to-cors.md).
## Exemple 1 : association d’un paramètre de demande de méthode à un paramètre de demande d’intégration
L’exemple suivant mappe le paramètre d’en-tête `puppies` de la demande de méthode au paramètre d’en-tête `DogsAge0` de la demande d’intégration.
------
#### [ AWS Management Console ]
**Pour mapper le paramètre de la demande de méthode**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Développez **En-têtes de demande HTTP**.
1. Sélectionnez **Add header**.
1. Pour **Nom**, saisissez **puppies**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
Ajoute AWS Management Console automatiquement un mappage de paramètres de `method.request.header.puppies ` à `puppies` pour vous, mais vous devez modifier le **nom** pour qu'il corresponde au paramètre d'en-tête de demande attendu par votre point de terminaison d'intégration.
1. Pour **Nom**, saisissez **DogsAge0**.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
Les étapes suivantes montrent comment vérifier que votre mappage de paramètres a été effectué avec succès.
**(Facultatif) Testez votre mappage de paramètres.**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour les en-têtes, saisissez **puppies:true**.
1. Sélectionnez **Tester)**.
1. Dans **Journaux**, le résultat doit se présenter comme suit :
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
Le paramètre d’en-tête de la demande est passé de `puppies` à `DogsAge0`.
------
#### [ 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: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
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 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Exemple 2 : association de plusieurs paramètres de requête de méthode à différents paramètres de demande d’intégration
L’exemple suivant mappe le paramètre `methodRequestQueryParam` de la chaîne de requête de méthode à valeurs multiples au paramètre `integrationQueryParam` de la chaîne de requête de demande d’intégration, et mappe le paramètre d’en-tête `methodRequestHeaderParam` de la demande de méthode au paramètre de chemin `integrationPathParam` de la demande d’intégration.
------
#### [ AWS Management Console ]
**Pour mapper les paramètres de requête de méthode**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **Paramètres de chaîne de requête d’URL**.
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **methodRequestQueryParam**.
1. Développez **En-têtes de demande HTTP**.
1. Sélectionnez **Add header**.
1. Pour **Nom**, saisissez **methodRequestHeaderParam**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Choisissez **paramètres de chemin d’URL**.
1. Choisissez **Ajouter un paramètre de chemin**.
1. Pour **Nom**, saisissez **integrationPathParam**.
1. Pour **Mappage à partir de**, entrez **method.request.header.methodRequestHeaderParam**.
Cette opération mappe l’en-tête de demande de méthode que vous avez spécifié dans la demande de méthode à un nouveau paramètre de chemin de la demande d’intégration.
1. Choisissez **Paramètres de chaîne de requête d’URL**.
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **integrationQueryParam**.
1. Pour **Mappage à partir de**, entrez **method.request.multivaluequerystring.methodRequestQueryParam**.
Cette opération mappe le paramètre de chaîne de requête à valeurs multiples à un nouveau paramètre de chaîne de requête de demande d’intégration à valeur unique.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ 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.
La définition OpenAPI suivante crée les mappages de paramètres suivants pour une intégration HTTP :
+ l’en-tête de la demande de méthode, nommé `methodRequestHeaderParam`, avec le paramètre de chemin de la demande d’intégration, nommé `integrationPathParam` ;
+ la chaîne de requête de la demande de méthode à valeurs multiples, nommée `methodRequestQueryParam`, avec la chaîne de requête de la demande d’intégration, nommée `integrationQueryParam`.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 les mappages de paramètres suivants pour une intégration HTTP :
+ l’en-tête de la demande de méthode, nommé `methodRequestHeaderParam`, avec le paramètre de chemin de la demande d’intégration, nommé `integrationPathParam` ;
+ la chaîne de requête de la demande de méthode à valeurs multiples, nommée `methodRequestQueryParam`, avec la chaîne de requête de la demande d’intégration, nommée `integrationQueryParam`.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemple 3 : mappage de champs du corps de la demande JSON aux paramètres de la demande d’intégration
Vous pouvez également mapper les paramètres de demande d'intégration à partir des champs du corps de la demande JSON à l'aide d'une [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). L’exemple suivant mappe le corps de la demande de méthode à un en-tête de la demande d’intégration nommé `body-header`, et mappe une partie du corps de la demande, tel qu’il est exprimé par une expression JSON, à un en-tête de la demande d’intégration nommé `pet-price`.
Pour tester cet exemple, fournissez une entrée contenant une catégorie de prix, par exemple :
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS Management Console ]
**Pour mapper les paramètres de requête de méthode**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Choisissez la méthode `POST`, `PUT`, `PATCH` ou `ANY`.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Sélectionnez **Paramètres des en-têtes de requête d’URL**.
1. Sélectionnez **Ajouter un paramètre d’en-tête de requête**.
1. Pour **Nom**, saisissez **body-header**.
1. Pour **Mappage à partir de**, entrez **method.request.body**.
Cette opération mappe le corps de la demande de méthode à un nouveau paramètre d’en-tête de la demande d’intégration.
1. Sélectionnez **Ajouter un paramètre d’en-tête de requête**.
1. Pour **Nom**, saisissez **pet-price**.
1. Pour **Mappage à partir de**, entrez ** method.request.body[0].price**.
Cette opération mappe une partie du corps de la demande de méthode à un nouveau paramètre d’en-tête de la demande d’intégration.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ 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: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 mappe les paramètres de la demande d’intégration à partir des champs du corps de la demande JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemple 4 : mappage de la réponse d’intégration à la réponse de méthode
Vous pouvez également mapper la réponse d’intégration à la réponse de méthode. L’exemple suivant mappe le corps de la réponse d’intégration à un en-tête de la réponse de méthode nommé `location`, mappe l’en-tête `x-app-id` de la réponse d’intégration à l’en-tête `id` de la réponse de méthode, et mappe l’en-tête à valeurs multiples `item` de la réponse d’intégration à l’en-tête `items` de la réponse de méthode.
------
#### [ AWS Management Console ]
**Pour mapper 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. Choisissez une API REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Choisissez l’onglet **Méthode de réponse**, puis pour **Réponse 200**, sélectionnez **Modifier**.
1. Sous **Nom de l’en-tête**, choisissez **Ajouter un en-tête**.
1. Créez trois en-têtes nommés **id**, **item** et **location**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Réponse d’intégration**, puis pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Sous **Mappages d’en-tête**, saisissez ce qui suit.
1. Sous **ID**, saisissez **integration.response.header.x-app-id**.
1. Sous **Élément**, saisissez **integration.response.multivalueheader.item**.
1. Sous **Emplacement**, saisissez **integration.response.body.redirect.url**.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ 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: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
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 d’OpenAPI suivante mappe la réponse d’intégration à la réponse de méthode.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------