Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway - Amazon API Gateway
Exemple 1 : remplacement du code d’état en fonction du corps de la réponse d’intégrationExemple 2 : remplacement de l’en-tête de la demande et création de nouveaux en-têtes

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

  2. Sélectionnez Create API (Créer une API).

  3. Sous API REST, choisissez Création.

  4. Sous Détails sur l’API, choisissez Exemple d’API.

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

  6. Dans l’arborescence Ressources, sous GET, choisissez la méthode sous /{petId}.

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

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

  9. Dans l’onglet Réponse d’intégration, pour Par défaut - Réponse, choisissez Modifier.

  10. Choisissez Modèles de mappage.

  11. Sélectionnez Add mapping template.

  12. Pour Type de contenu, entrez application/json.

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

  14. Choisissez Enregistrer.

  15. Choisissez l’onglet Test.

  16. Pour petId, saisissez -1.

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

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

  2. Choisissez l’exemple d’API que vous avez créé dans le tutoriel précédent. Le nom de l'API doit être PetStore.

  3. Dans l’arborescence Ressources, sous GET, choisissez la méthode sous /pet.

  4. Dans l’onglet Requête de méthode, pour Paramètres de requête de méthode, choisissez Modifier.

  5. Choisissez En-têtes de demande HTTP, puis Ajouter un en-tête.

  6. Pour Nom, saisissez header1.

  7. Choisissez Ajouter un en-tête, puis créez un second en-tête appelé header2.

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

  9. Dans l’onglet Demande d’intégration, pour Paramètres de requête d’intégration, choisissez Modifier.

  10. Pour Transmission du corps de requête, sélectionnez Lorsqu’aucun modèle n’est défini (recommandé).

  11. Choisissez Modèles de mappage, puis procédez comme suit :

    1. Sélectionnez Add mapping template.

    2. Pour Type de contenu, entrez application/json.

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

  12. Choisissez Enregistrer.

  13. Choisissez l’onglet Test.

  14. Sous En-têtes, copiez le code suivant :

    header1:header1Val
header2:header2Val

  15. 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}
AWS 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: 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.