Transformations de modèles de mappage pour les API REST dans API Gateway

Une transformation de modèle de mappage utilise un modèle de mappage pour modifier votre demande d’intégration ou votre réponse d’intégration. Un modèle de mappage est un script exprimé en langage VTL (Velocity Template Language) appliqué à des données utiles à l’aide d’expressions JSONPath en fonction de l’en-tête Content-type. Vous utilisez des modèles de mappage lorsque vous transformez des modèles de mappage. Cette section décrit les informations conceptuelles relatives aux modèles de mappage.

Le schéma suivant montre le cycle de vie d’une demande pour une ressource POST /pets intégrée à un point de terminaison d’intégration PetStore. Dans cette API, un utilisateur envoie des données sur un animal de compagnie, et le point de terminaison d’intégration renvoie les frais d’adoption relatifs à cet animal. Dans le cycle de vie de cette demande, les transformations du modèle de mappage filtrent le corps de la demande vers le point de terminaison d’intégration, et filtrent le corps de réponse provenant du point de terminaison d’intégration.

Les sections suivantes expliquent le cycle de vie des demandes et réponses.

Demande de méthode et demande d’intégration

Voici le corps de la demande envoyé à la demande de méthode dans l’exemple précédent :

POST /pets
    HTTP/1.1
    Host:abcd1234.us-west-2.amazonaws.com
    Content-type: application/json
    
  {
    "id": 1,
    "type": "dog",
    "Age": 11,
  }

Le corps de cette demande n’est pas au format approprié pour être utilisé par le point de terminaison d’intégration. API Gateway transforme donc le modèle de mappage. API Gateway transforme le modèle de mappage uniquement parce qu’un modèle de mappage est défini pour le Content-Type application/json. Si vous ne définissez pas de modèle de mappage pour Content-Type, API Gateway transmet par défaut le corps au point de terminaison d’intégration par le biais de la demande d’intégration. Pour modifier ce comportement, consultez Comportement des demandes de méthode pour les données utiles sans modèle de mappage pour les API REST dans API Gateway.

Le modèle de mappage suivant transforme les données de la demande de méthode dans la demande d’intégration avant qu’elles ne soient envoyées au point de terminaison d’intégration :

#set($inputRoot = $input.path('$'))
  {
    "dogId" : "dog_"$elem.id,
    "Age": $inputRoot.Age
  }

La sortie suivante est ensuite transmise au point de terminaison d’intégration :

{
    "dogId" : "dog_1",
    "Age": 11
  }

Réponse d’intégration et réponse de méthode

Une fois la demande envoyée avec succès au point de terminaison d’intégration, celui-ci envoie une réponse à la réponse d’intégration d’API Gateway. Voici un exemple de données de sortie provenant du point de terminaison d’intégration :

{
    "dogId" : "dog_1",
    "adoptionFee": 19.95,
}

La réponse de méthode attend des données utiles différentes de celles renvoyées par la réponse d’intégration. API Gateway transforme le modèle de mappage. API Gateway transforme le modèle de mappage uniquement parce qu’un modèle de mappage est défini pour le Content-Type application/json. Si vous ne définissez pas de modèle de mappage pour Content-Type, API Gateway transmet par défaut le corps à la réponse de méthode par le biais de la réponse d’intégration. Pour modifier ce comportement, consultez Comportement des demandes de méthode pour les données utiles sans modèle de mappage pour les API REST dans API Gateway.

#set($inputRoot = $input.path('$'))
  {
    "adoptionFee" : $inputRoot.adoptionFee,
  }

La sortie suivante est envoyée à la réponse de méthode :

{"adoptionFee": 19.95}

Ceci conclut l’exemple de transformation de modèle de mappage. Nous vous recommandons, dans la mesure du possible, d’utiliser une intégration de proxy pour transformer vos données au lieu de transformer le modèle de mappage. Pour plus d’informations, consultez Choix d’un type d’intégration d’API API Gateway.