Zuweisungsvorlagen für REST-APIs - Amazon API Gateway
Beispiel einer ZuweisungsvorlageBeispiele für komplexe Zuweisungsvorlagen

Zuweisungsvorlagen für REST-APIs

In API Gateway kann die Methodenanforderung oder -antwort einer API eine Nutzlast in einem anderen Format als die Integrationsanfrage oder -antwort annehmen.

Sie können Ihre Daten folgendermaßen transformieren:

  • Anpassung der Nutzlast an ein API-spezifiziertes Format

  • Überschreiben der Anforderungs- und Antwortparameter und Statuscodes einer API-Anfrage

  • Rückgabe der vom Client ausgewählten Antwort-Header

  • Zuordnung der Pfadparameter, Abfragezeichenfolgenparameter oder Header-Parameter in der Methodenanfrage des HTTP-Proxys oder AWS-Service-Proxys

  • Auswählen, welche Daten mithilfe der Integration mit AWS-Services gesendet werden sollen, z. B. mit Amazon-DynamoDB- oder Lambda-Funktionen oder HTTP-Endpunkten

Sie können Zuweisungsvorlagen verwenden, um Ihre Daten zu transformieren. Eine Zuweisungsvorlage ist ein in Velocity Template Language (VTL) ausgedrücktes Skript, das mithilfe von JSONPath-Ausdrücken auf die Nutzlast angewendet wird.

In diesem Abschnitt werden konzeptionelle Informationen zu Zuweisungsvorlagen beschrieben. Anleitungen zum Erstellen einer Zuweisungsvorlage für eine API-Gateway-REST-API finden Sie unter Einrichten von Datentransformationen in API Gateway.

Beispiel einer Zuweisungsvorlage

Im folgenden Beispiel sehen Sie die Eingabedaten für eine Integrationsanforderung.

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

Im folgenden Beispiel sehen Sie eine Zuweisungsvorlage für die Transformation der Integrationsanforderungsdaten.

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

#end
]

Im folgenden Beispiel sehen Sie die Ausgabedaten aus der 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
  }
]

Das folgende Diagramm zeigt Details dieser Zuweisungsvorlage.

Beispiel einer Zuweisungsvorlage

  1. Die Variable $inputRoot stellt in den ursprünglichen JSON-Daten aus dem vorherigen Abschnitt das Stammobjekt dar. Richtlinien beginnen mit dem #-Symbol.

  2. Eine foreach-Schleife durchläuft jedes Objekt in den ursprünglichen JSON-Daten.

  3. Die Beschreibung ist eine Verkettung der Pet-id und des type der ursprünglichen  JSON-Daten.

  4. askingPrice ist der price aus den ursprünglichen JSON-Daten.

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 dieser Zuweisungsvorlage gilt:

  1. Die Variable $inputRoot in Zeile 1 stellt das Stammobjekt in den ursprünglichen JSON-Daten aus dem vorherigen Abschnitt dar. Richtlinien beginnen mit dem #-Symbol.

  2. In Zeile 3 durchläuft eine foreach-Schleife jedes Objekt in den ursprünglichen JSON-Daten.

  3. In Zeile 5 ist die description eine Verkettung der Pet-id und der ursprünglichen type-JSON-Daten.

  4. In Zeile 6 ist askingPrice der price aus den ursprünglichen JSON-Daten.

Weitere Informationen zur Velocity Template Language finden Sie in der Apache Velocity – VTL-Reference. Weitere Informationen zu JSONPath finden Sie unter JSONPath – XPath for JSON.

Die Mapping-Vorlage geht davon aus, dass die zugrundeliegenden Daten zu einem JSON-Objekt gehören. Es ist nicht erforderlich, ein Modell für die Daten zu definieren. Ein Modell für die Ausgabedaten ermöglicht es jedoch, vorherige Daten als sprachspezifisches Objekt zurückzugeben. Weitere Informationen finden Sie unter Datenmodelle für REST-APIs.

Beispiele für komplexe Zuweisungsvorlagen

Sie können auch kompliziertere Zuordnungsvorlagen erstellen. Das folgende Beispiel zeigt die Verkettung von Referenzen und einen Grenzwert von 100, um festzustellen, ob Sie sich ein Haustier leisten können.

Im folgenden Beispiel sehen Sie die Eingabedaten für eine Integrationsanforderung.

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

Im folgenden Beispiel sehen Sie eine Zuweisungsvorlage für die Transformation der Integrationsanforderungsdaten.

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

Im folgenden Beispiel sehen Sie die Ausgabedaten aus der 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
  }  
]

Hier sehen Sie auch kompliziertere Datenmodelle. Siehe Beispiele für Datenmodelle und Zuweisungsvorlagen für API Gateway.