Modèles de mappage pour REST APIs - APIPasserelle Amazon
Exemple de modèle de mappageExemples de 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.

Modèles de mappage pour REST APIs

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

Vous pouvez transformer vos données pour :

  • Faites correspondre la charge utile à un format API spécifié.

  • Remplacez les paramètres API de demande et de réponse et les codes d'état d'un utilisateur.

  • 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 HTTP proxy ou du Service AWS proxy.

  • 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é dans le langage de modèle Velocity (VTL) et appliqué à la charge utile à l'aide JSONPathde.

Cette section décrit les informations conceptuelles relatives aux modèles de mappage. Pour obtenir des instructions sur la création d'un modèle de mappage pour une API passerelle RESTAPI, consultezConfigurer les transformations de données dans API Gateway.

Exemple de modèle de mappage

L'exemple suivant montre les données d'entrée d'une demande d'intégration.

[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

L'exemple suivant est un modèle de mappage permettant de transformer les données de la demande d'intégration.

#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]

L'exemple suivant montre les données de sortie de la transformation.

[
  {
    "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 $inputRoot variable représente l'objet racine dans les JSON données d'origine de la section précédente. Les directives commencent par le symbole #.

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

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

  4. askingPricepriceest le prix indiqué sur la base des JSON données 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. Sur la ligne 1, la $inputRoot variable représente l'objet racine dans les JSON données d'origine de la section précédente. Les directives commencent par le symbole #.

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

  3. À la ligne 5, description il s'agit d'une concaténation des données des animaux de compagnie id et des données type d'origine. JSON

  4. À la ligne 6, askingPrice se price trouve le prix indiqué sur la base des JSON données d'origine.

Pour plus d'informations sur le langage de modèle Velocity, voir Apache Velocity - VTL Reference. Pour plus d'informations surJSONPath, voir JSONPath- XPath pour JSON.

Le modèle de mappage suppose que les données sous-jacentes sont celles d'un JSON objet. 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 Modèles de données pour REST APIs.

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

L'exemple suivant montre les données d'entrée d'une demande d'intégration.

[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

L'exemple suivant est un modèle de mappage permettant de transformer les données de la demande d'intégration.

#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
]

L'exemple suivant montre les données de sortie de la transformation.

[
  {
    "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
  }  
]

Vous pouvez également voir des modèles de données plus complexes. Consultez Exemples de modèles de données et de modèles de mappage pour API Gateway.