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

In diesem Abschnitt wird erklärt, wie Datenzuordnungen von Methodenanforderungsdaten eines API Benutzers, einschließlich anderer in utilVariablen gespeicherter Daten contextstage, zu den entsprechenden Integrationsanforderungsparametern und von Daten 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.

Themen

• Zuweisen von Methodenanforderungsdaten zu Integrationsanforderungs-Parametern
• Zuweisen von Integrationsantwortdaten zu Methodenantwort-Headern
• Zuweisen von Anforderungs- und Antwortnutzlasten zwischen Methode und Integration
• Integrations-Pass-Through-Verhalten

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.

Anmerkung

Das "$" ist in dieser Syntax ausgelassen.

Zugeordnete Datenquelle	Zuordnungsausdruck
Methodenanforderungspfad	method.request.path.PARAM_NAME
Abfragezeichenfolge der Methodenanforderung	method.request.querystring.PARAM_NAME
Mehrwertmethode Abfrage Abfrage Zeichenfolge	method.request.multivaluequerystring.PARAM_NAME
Methodenanforderungs-Header	method.request.header.PARAM_NAME
Mehrfachmethodenanforderungs-Header	method.request.multivalueheader.PARAM_NAME
Methodenanforderungstext	method.request.body
Hauptteil der Methodenanforderung (JsonPath)	method.request.body.JSONPath_EXPRESSION.
Stufenvariablen	stageVariables.VARIABLE_NAME
Kontextvariablen	context.VARIABLE_NAME, wobei die Variable zu den unterstützten Kontextvariablen gehören muss.
Statischer Wert	'STATIC_VALUE'. Das STATIC_VALUE ist ein Zeichenkettenliteral und muss in zwei einfache Anführungszeichen eingeschlossen werden.

Beispiel Zuordnungen aus dem Methodenanforderungsparameter in Open API

Das folgende Beispiel zeigt ein API Open-Snippet, das eine Zuordnung ermöglicht:

• den Header der Methodenanforderung mit dem Namen methodRequestHeaderParam in den Pfad des Integration Request-ParametersintegrationPathParam zuweist

• den Multi-Wert der Abfragezeichenfolge der Methodenanforderung mit Namen methodRequestQueryParam, der Abfragezeichenfolge der Integrationsanforderung namens integrationQueryParamzuweist

...
"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.

Beispiel Zuordnung aus dem Hauptteil der Methodenanfrage in Open API

Das folgende Beispiel zeigt ein API Open-Snippet, das 1) den Hauptteil der Methodenanforderung dem Header der Integrationsanforderung, benanntbody-header, und 2) ein JSON Feld des Hauptteils, wie es durch einen JSON Ausdruck (, ohne $. Präfix) ausgedrückt wirdpetstore.pets[0].name, zuordnet.

...
"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.

Zugewiesene Datenquelle	Mapping-Ausdruck
Integrationsantwort-Header	integration.response.header.PARAM_NAME
Integrationsantwort-Header	integration.response.multivalueheader.PARAM_NAME
Integrationsantworttext	integration.response.body
Hauptteil der Integrationsantwort (JsonPath)	integration.response.body.JSONPath_EXPRESSION
Stufenvariable	stageVariables.VARIABLE_NAME
Kontextvariable	context.VARIABLE_NAME, wobei die Variable zu den unterstützten Kontextvariablen gehören muss.
Statischer Wert	'STATIC_VALUE'. Das STATIC_VALUE ist ein Zeichenkettenliteral und muss in zwei einfache Anführungszeichen eingeschlossen werden.

Beispiel Datenzuordnung aus der Integrationsantwort in Open API

Das folgende Beispiel zeigt ein API Open-Snippet, das 1) das JSONPath Feld der Integrationsantwort dem Header der Anforderungsantwort und 2) den location Header der Integrationsantwort dem x-app-id Header der Methodenantwort zuordnet. redirect.url id

...
"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 Grundvorlage als Hilfsmittel 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 fehlt, geht API Gateway davon aus, dass sein Standardwert istapplication/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.