Referenz zur Zuordnung von Amazon API API Gateway-Anforderungs- und Antwortdaten

In diesem Abschnitt wird erklärt, wie Datenzuordnungen von den Methodenanforderungsdaten einer API Person, einschließlich anderer in utilVariablen gespeicherten Daten contextstage, zu den entsprechenden Integrationsanforderungsparametern und von den Antwortdaten einer Integrationsantwort, einschließlich der anderen Daten, zu den Antwortparametern der Methode eingerichtet werden. Die Methodenanforderungsdaten umfassen Anforderungsparameter (Pfad, Abfragezeichenfolge, Header) und den Text. Die Integrationsantwortdaten enthalten Antwortparameter (Header) und den Text. Weitere Informationen zur Verwendung von "stage"-Variablen finden Sie unter APIReferenz für REST APIs Gateway-Stufenvariablen in Gateway API.

Zuweisen von Methodenanforderungsdaten zu Integrationsanforderungs-Parametern

Integrationsanforderungs-Parameter in Form von Pfadvariablen, Abfragezeichenfolgen oder Headern können aus allen definierten Methodenanforderungs-Parametern und der Nutzlast zugewiesen werden.

In der folgenden Tabelle PARAM_NAME ist der Name eines Methodenanforderungsparameters des angegebenen Parametertyps. Er muss dem regulären Ausdruck '^[a-zA-Z0-9._$-]+$]' entsprechen. Er muss definiert worden sein, bevor er referenziert werden kann. JSONPath_EXPRESSION ist ein JSONPath Ausdruck für ein JSON Feld im Hauptteil einer Anfrage oder Antwort.

...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...
                
            

Parameter für Integrationsanfragen können mithilfe eines Ausdrucks auch Feldern im JSON Anfragetext zugeordnet werden. JSONPath Die folgende Tabelle zeigt die Zuordnungsausdrücke für den Hauptteil einer Methodenanforderung und ihre JSON Felder.

...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...
                
            

Zuweisen von Integrationsantwortdaten zu Methodenantwort-Headern

Methodenantwort-Header-Parameter können aus allen Integrationsantwort-Headern oder Integrationsantworttexten, $context-Variablen oder statischen Werten zugewiesen werden. In der folgenden Tabelle werden die Ausdrücke für die Zuordnung des Headers der Methodenantwort beschrieben.

...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...
                
            

Zuweisen von Anforderungs- und Antwortnutzlasten zwischen Methode und Integration

APIGateway verwendet die Velocity Template Language (VTL) Engine, um Body-Mapping-Vorlagen für die Integrationsanfrage und die Integrationsantwort zu verarbeiten. Die Mapping-Vorlagen übersetzen Methodenanforderungsnutzlasten in die entsprechenden Integrationsanforderungsnutzlasten und Integrationsantworttexte in Methodenantworttexte.

Die VTL Vorlagen verwenden JSONPath Ausdrücke, andere Parameter wie Aufrufkontexte und Stage-Variablen sowie Hilfsfunktionen zur Verarbeitung der JSON Daten.

Wenn ein Modell zur Beschreibung der Datenstruktur einer Nutzlast definiert ist, kann API Gateway das Modell verwenden, um eine Skelett-Mapping-Vorlage für eine Integrationsanfrage oder Integrationsantwort zu generieren. Sie können die Skelett-Vorlage als Hilfe verwenden, um das VTL Mapping-Skript anzupassen und zu erweitern. Sie können aber auch eine vollständig neue Mapping-Vorlage erstellen, ohne ein Modell für die Datenstruktur der Nutzlast zu definieren.

Wählen Sie eine VTL Zuordnungsvorlage

APIGateway verwendet die folgende Logik, um eine Mapping-Vorlage in Velocity Template Language (VTL) auszuwählen, um die Payload aus einer Methodenanforderung der entsprechenden Integrationsanforderung zuzuordnen oder um die Payload aus einer Integrationsantwort der entsprechenden Methodenantwort zuzuordnen.

Für eine Anforderungs-Payload verwendet API Gateway den Content-Type Header-Wert der Anfrage als Schlüssel, um die Zuordnungsvorlage für die Anforderungs-Payload auszuwählen. Für eine Antwort-Payload verwendet API Gateway den Accept Header-Wert der eingehenden Anfrage als Schlüssel zur Auswahl der Zuordnungsvorlage.

Wenn der Content-Type Header in der Anfrage nicht vorhanden ist, geht API Gateway davon aus, dass sein Standardwert lautetapplication/json. Für eine solche Anfrage verwendet API Gateway application/json als Standardschlüssel die Zuordnungsvorlage, sofern eine definiert ist. Wenn keine Vorlage mit diesem Schlüssel übereinstimmt, leitet API Gateway die Payload über unmapped weiter, sofern die passthroughBehaviorEigenschaft auf oder gesetzt ist. WHEN_NO_MATCH WHEN_NO_TEMPLATES

Wenn der Accept Header in der Anfrage nicht angegeben ist, geht API Gateway davon aus, dass sein Standardwert lautet. application/json In diesem Fall wählt API Gateway eine vorhandene Zuordnungsvorlage aus, application/json um die Antwortnutzlast zuzuordnen. Wenn keine Vorlage für definiert istapplication/json, wählt API Gateway die erste vorhandene Vorlage aus und verwendet sie als Standard für die Zuordnung der Antwortnutzlast. In ähnlicher Weise verwendet API Gateway die erste vorhandene Vorlage, wenn der angegebene Accept Header-Wert mit keinem vorhandenen Vorlagenschlüssel übereinstimmt. Wenn keine Vorlage definiert ist, leitet API Gateway die Antwortnutzlast einfach über unmapped weiter.

Nehmen wir zum Beispiel an, dass für eine application/json Vorlage API eine Vorlage für eine Anforderungsnutzlast und eine application/xml Vorlage für die Antwortnutzlast definiert ist. Wenn der Client die "Content-Type : application/json"- und "Accept : application/xml"-Header in der Anforderung festlegt, werden sowohl die Anforderungs- als auch die Antwortnutzlasten mit den entsprechenden Mapping-Vorlagen verarbeitet. Wenn der Accept:application/xml-Header fehlt, wird die application/xml-Mapping-Vorlage für die Zuweisung der Antwortnutzlast verwendet. Wenn Sie stattdessen eine Antwortnutzlast ohne Zuweisung zurückgeben möchten, richten Sie eine leere Vorlage für ei application/json.

Bei der Auswahl einer Zuordnungsvorlage wird nur der MIME Typ aus den Content-Type Headern Accept und verwendet. Beispiel: Für einen "Content-Type: application/json; charset=UTF-8"-Header wird eine Anforderungsvorlage mit dem application/json-Schlüssel ausgewählt.