modelli di mappatura per API REST - Amazon API Gateway
Modelli di mappatura complessi

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

modelli di mappatura per API REST

In Gateway Amazon API, una richiesta di metodo dell'API o una risposta può accettare un payload in un formato diverso dal payload della richiesta di integrazione o della risposta.

È possibile trasformare i tuoi dati con le seguenti finalità:

  • Abbinare il payload a un formato specificato dall'API.

  • Sostituire i parametri della richiesta e della risposta e i codici di stato di un'API.

  • Restituire le intestazioni di risposta selezionate dal client.

  • Associa i parametri del percorso, i parametri della stringa di query o i parametri di intestazione nella richiesta del metodo del proxy o del proxy HTTP. Servizio AWS

  • Seleziona i dati da inviare utilizzando l'integrazione Servizi AWS, ad esempio le funzioni Amazon DynamoDB o Lambda o gli endpoint HTTP.

È possibile usare modelli di mappatura per trasformare i dati. Un modello di mappatura è uno script espresso in Velocity Template Language (VTL) e applicato al payload tramite JSONPath.

L'esempio seguente mostra i dati di input, un modello di mappatura e i dati di output per una trasformazione dei dati. PetStore

Dati di input 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
Modello di mappatura 
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]
Dati di output 
[
  {
    "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
  }
]

Il diagramma seguente mostra i dettagli di questo modello di mappatura.

Esempio di modello di mappatura

  1. La variabile $inputRoot rappresenta l'oggetto radice nei dati JSON originali della sezione precedente. Le direttive iniziano con il simbolo #.

  2. Un loop foreach esegue iterazioni su ogni oggetto nei dati JSON originali.

  3. La descrizione è una concatenazione di valori id e type dai dati JSON originali.

  4. askingPrice rappresenta il prezzo (price) derivato dai dati JSON originali.

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 ]

In questo modello di mappatura:

  1. Alla riga 1, la variabile $inputRoot rappresenta l'oggetto root nei dati JSON originali della sezione precedente. Le direttive iniziano con il simbolo #.

  2. Alla riga 3, viene eseguita l'iterazione di un loop foreach in ogni oggetto nei dati JSON originali.

  3. Alla riga 5, la descrizione (description) è una concatenazione di valori id e type dai dati JSON originali.

  4. Alla riga 6, askingPrice rappresenta il prezzo (price) derivato dai dati JSON originali.

Per ulteriori informazioni su Velocity Template Language, consulta Riferimento ad Apache Velocity - VTL. Per ulteriori informazioni su JSONPath, consulta JSONPath - XPath per JSON.

Il modello di mappatura presuppone che i dati sottostanti siano di un oggetto JSON. Non è richiesta la definizione di un modello per i dati. Tuttavia, un modello per i dati di output consente di restituire i dati precedenti come oggetto specifico del linguaggio. Per ulteriori informazioni, consulta Modelli di dati per le API REST.

Modelli di mappatura complessi

Puoi anche creare modelli di mappatura più complessi. L'esempio seguente mostra la concatenazione dei riferimenti e il limite di 100 per determinare se un animale domestico è conveniente.

Dati di input 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
Modello di mappatura 
#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
]
Dati di output 
[
  {
    "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
  }  
]

Puoi anche vedere modelli di dati più complicati. Per informazioni, consulta Esempi di modelli di dati e modelli di mappatura per API Gateway.