Exemple 1 : association d’un paramètre de demande de méthode à un paramètre de demande d’intégration Exemple 2 : association de plusieurs paramètres de requête de méthode à différents paramètres de demande d’intégration Exemple 3 : mappage de champs du corps de la demande JSON aux paramètres de la demande d’intégration Exemple 4 : mappage de la réponse d’intégration à la réponse de méthode

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 Partage des ressources entre origines multiples pour les API REST dans API Gateway.

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.

the console

Pour mapper le paramètre de la demande de méthode

Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.
Choisissez une API REST.
Choisissez une méthode.

Votre méthode doit avoir une intégration sans proxy.
Pour Paramètres de requête de méthode, choisissez Modifier.
Développez En-têtes de demande HTTP.
Sélectionnez Add header.
Pour Nom, saisissez puppies.
Choisissez Enregistrer.
Choisissez l’onglet Requête d’intégration, puis dans la section Paramètres de requête d’intégration, choisissez Modifier.

Ajoute the 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.
Pour Nom, saisissez DogsAge0.
Choisissez Enregistrer.
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.

Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
Pour les en-têtes, saisissez puppies:true.
Sélectionnez Tester).

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 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.

the console

Pour mapper les paramètres de requête de méthode

Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.
Choisissez une API REST.
Choisissez une méthode.

Votre méthode doit avoir une intégration sans proxy.
Pour Paramètres de requête de méthode, choisissez Modifier.
Choisissez Paramètres de chaîne de requête d’URL.
Sélectionnez Add query string (Ajouter une chaîne de requêtes).
Pour Nom, saisissez methodRequestQueryParam.
Développez En-têtes de demande HTTP.
Sélectionnez Add header.
Pour Nom, saisissez methodRequestHeaderParam.
Choisissez Enregistrer.
Choisissez l’onglet Requête d’intégration, puis dans la section Paramètres de requête d’intégration, choisissez Modifier.
Choisissez paramètres de chemin d’URL.
Choisissez Ajouter un paramètre de chemin.
Pour Nom, saisissez integrationPathParam.
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.
Choisissez Paramètres de chaîne de requête d’URL.
Sélectionnez Add query string (Ajouter une chaîne de requêtes).
Pour Nom, saisissez integrationQueryParam.
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.
Choisissez Enregistrer.
Redéployez l’API pour que les modifications prennent effet.

CloudFormation

Dans cet exemple, vous allez utiliser la propriété 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. 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 
  }
]

the console

Pour mapper les paramètres de requête de méthode

Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.
Choisissez une API REST.
Choisissez la méthode POST, PUT, PATCH ou ANY.

Votre méthode doit avoir une intégration sans proxy.
Pour Paramètres de requête d’intégration, choisissez Modifier.
Sélectionnez Paramètres des en-têtes de requête d’URL.
Sélectionnez Ajouter un paramètre d’en-tête de requête.
Pour Nom, saisissez body-header.
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.
Sélectionnez Ajouter un paramètre d’en-tête de requête.
Pour Nom, saisissez pet-price.
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.
Choisissez Enregistrer.
Redéployez l’API pour que les modifications prennent effet.

CloudFormation

Dans cet exemple, vous allez utiliser la propriété 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.

the console

Pour mapper la réponse d’intégration

Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.
Choisissez une API REST.
Choisissez une méthode.

Votre méthode doit avoir une intégration sans proxy.
Choisissez l’onglet Méthode de réponse, puis pour Réponse 200, sélectionnez Modifier.
Sous Nom de l’en-tête, choisissez Ajouter un en-tête.
Créez trois en-têtes nommés id, item et location.
Choisissez Enregistrer.
Choisissez l’onglet Réponse d’intégration, puis pour Par défaut - Réponse, choisissez Modifier.
Sous Mappages d’en-tête, saisissez ce qui suit.
1. Sous ID, saisissez integration.response.header.x-app-id.
2. Sous Élément, saisissez integration.response.multivalueheader.item.
3. Sous Emplacement, saisissez integration.response.body.redirect.url.
Choisissez Enregistrer.
Redéployez l’API pour que les modifications prennent effet.

CloudFormation

Dans cet exemple, vous allez utiliser la propriété 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
        }
      }
    }
  }
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Mappage de paramètres

Référence de la source du mappage de paramètres