Présentation des modèles de mappage - Amazon API Gateway
Modèles de mappage complexes

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.

Présentation des modèles de mappage

Dans API Gateway, la demande ou la réponse de méthode d'une API peut accepter une charge utile dans un format différent de celui de la demande ou réponse d'intégration.

Vous pouvez transformer vos données pour :

  • Faire correspondre la charge utile à un format spécifié par l'API.

  • Remplacer les codes de statut et les paramètres de demande et réponse d'une API.

  • Renvoyer les en-têtes de réponse sélectionnés par le client.

  • Associez des paramètres de chemin, des paramètres de chaîne de requête ou des paramètres d'en-tête dans la demande de méthode du proxy ou du Service AWS proxy HTTP.

  • Sélectionnez les données à envoyer à l'aide de l'intégration Services AWS, telles que les fonctions Amazon DynamoDB ou Lambda, ou les points de terminaison HTTP.

Vous pouvez utiliser des modèles de mappage pour transformer vos données. Un modèle de mappage est un script exprimé en langage VTL (Velocity Template Language) et appliqué à la charge utile à l'aide de JSONPath.

L'exemple suivant montre des données d'entrée, un modèle de mappage et des données de sortie pour une transformation des PetStore données.

Données d'entrée 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
Modèle de mappage 
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]
Données de sortie 
[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]

Le schéma suivant présente les détails de ce modèle de mappage.

exemple de modèle de mappage

  1. La variable $inputRoot représente l'objet racine dans les données JSON d'origine de la section précédente. Les directives commencent par le symbole #.

  2. Une boucle foreach parcourt chaque objet des données JSON d'origine.

  3. La description est une concaténation des paramètres id et type de l'animal de compagnie, issus des données JSON d'origine.

  4. askingPrice correspond au paramètre price de prix issu des données JSON d'origine.

1 #set($inputRoot = $input.path('$'))
2 [
3 #foreach($elem in $inputRoot)
4  {
5    "description" : "Item $elem.id is a $elem.type.",
6    "askingPrice" : $elem.price
7  }#if($foreach.hasNext),#end
8 #end
9 ]

Dans ce modèle de mappage :

  1. Ligne 1, la variable $inputRoot représente l'objet racine dans les données JSON d'origine de la section précédente. Les directives commencent par le symbole #.

  2. Ligne 3, une boucle foreach parcourt chaque objet des données JSON d'origine.

  3. Ligne 5,  la description est une concaténation des paramètres id et type de l'animal de compagnie, issus des données JSON d'origine.

  4. Ligne 6, askingPrice correspond au paramètre price de prix issu des données JSON d'origine.

Pour plus d'informations sur le langage VTL, consultez Apache Velocity - VTL Reference. Pour plus d'informations sur JSONPath, consultez JSONPath - XPath for JSON.

Le modèle de mappage suppose que les données sous-jacentes sont issues d'un objet JSON. Il n'a pas besoin qu'un modèle soit défini pour les données. Toutefois, un modèle pour les données de sortie permet de renvoyer les données précédentes sous la forme d'un objet spécifique à la langue. Pour de plus amples informations, veuillez consulter Comprendre les modèles de données.

Modèles de mappage complexes

Vous pouvez aussi créer des modèles de mappage plus complexes. L’exemple suivant montre la concaténation de références et un seuil de 100 pour déterminer si un animal de compagnie est abordable.

Données d'entrée 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
Modèle de mappage 
#set($inputRoot = $input.path('$'))
#set($cheap = 100)
[
#foreach($elem in $inputRoot)
  {
#set($name = "${elem.type}number$elem.id")
    "name" : $name,
    "description" : "Item $elem.id is a $elem.type.",
    #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end
"askingPrice" : $afford
  }#if($foreach.hasNext),#end
  
#end
]
Données de sortie 
[
  {
    "name" : dognumber1,
    "description" : "Item 1 is a dog.",
    "askingPrice" : too much!
  },  
  {
    "name" : catnumber2,
    "description" : "Item 2 is a cat.",
    "askingPrice" : too much!
  },  
  {
    "name" : fishnumber3,
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }  
]

Consultez l'exemple d'album photo Exemple de photos pour étudier un modèle plus compliqué.