Daten-Mapping-Referenz für Amazon API Gateway-API-Anfragen und Antworten

In diesem Abschnitt wird die Einrichtung von Daten-Mappings von Methodenanforderungsdaten einer API – einschließlich anderer, in context-, stage- oder util-Variablen gespeicherter Daten – zu den entsprechenden Integrationsanforderungs-Parametern und von Integrationsantwortdaten – einschließlich der anderen Daten – zu den Methodenantwortparametern beschrieben. 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 Referenz für Amazon API Gateway-Stufenvariablen.

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 Methodenanforderungs-Parameters des angegebenen Parametertyps. Er muss dem regulären Ausdruck '^[a-zA-Z0-9._$-]+$]' entsprechen. Es muss definiert worden sein, bevor es referenziert werden kann. JSONPath_EXPRESSION ist ein JSONPath-Ausdruck für ein JSON-Feld des Hauptteils einer Anforderung oder Antwort.

Anmerkung

Das "$" ist in dieser Syntax ausgelassen.

Zuweisungsausdrücke für Integrationsanforderungsdaten
Zugewiesene Datenquelle	Zuweisungsausdruck
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
Methodenanforderungstext (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'. STATIC_VALUE ist ein Zeichenfolgenliteral, das in einfache Anführungszeichen eingeschlossen werden muss.

Beispiel Zuweisen von Methoden-Mapping-Parametern in OpenAPI

Das folgende Beispiel zeigt einen OpenAPI-Ausschnitt, der:

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

Integrationsanforderungs-Parameter können mithilfe eines JSONPath-Ausdrucks auch von Feldern im JSON-Anforderungstext zugewiesen werden. Die folgende Tabelle zeigt die Mapping-Ausdrücke für einen Methodenanforderungstext und dessen JSON-Felder.

Beispiel Mapping vom Methodenanforderungstext in OpenAPI

Das folgende Beispiel zeigt einen OpenAPI-Ausschnitt, der 1) den Methodenanforderungstext dem Integrationsanforderungs-Header namens body-header und 2) ein JSON-Feld des Texts, wie durch einen JSON-Ausdruck dargestellt (petstore.pets[0].name, ohne das $.-Präfix) zuweist.

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

Mapping-Ausdrücke für Methodenantwort-Header
Zugewiesene Datenquelle	Mapping-Ausdruck
Integrationsantwort-Header	integration.response.header.PARAM_NAME
Integrationsantwort-Header	integration.response.multivalueheader.PARAM_NAME
Integrationsantworttext	integration.response.body
Integrationsantworttext (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'. STATIC_VALUE ist ein Zeichenfolgenliteral, das in einfache Anführungszeichen eingeschlossen werden muss.

Beispiel Daten-Mapping aus Integrationsantworten in OpenAPI

Das folgende Beispiel zeigt einen OpenAPI-Ausschnitt, der 1) das redirect.url-"JSONPath"-Feld der Integrationsantwort dem location-Header der Anforderungsantwort und 2) den x-app-id-Header der Integrationsantwort dem id-Header der Methodenantwort zuweist.

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

Amazon API Gateway nutzt das VTL-Modul (Velocity Template Language) zur Verarbeitung von Mapping-Vorlagen in Texten für die Integrationsanforderung und Integrationsantwort. 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 Stufenvariablen sowie Hilfsprogrammfunktionen, um die JSON-Daten zu verarbeiten.

Wenn ein Modell zur Beschreibung der Datenstruktur einer Nutzlast definiert ist, kann Amazon API Gateway anhand dieses Modells ein Mapping-Vorlagenskelett für eine Integrationsanforderung oder -antwort erstellen. Sie können das Vorlagenskelett als Hilfe bei der Anpassung und Erweiterung des VTL-Mapping-Skripts verwenden. Sie können aber auch eine vollständig neue Mapping-Vorlage erstellen, ohne ein Modell für die Datenstruktur der Nutzlast zu definieren.

Auswählen einer VTL-Mapping-Vorlage

Amazon API Gateway verwendet die folgende Logik zur Auswahl einer Mapping-Vorlage in Velocity Template Language (VTL), um den Payload aus einer Methodenanforderung der entsprechenden Integrationsanforderung oder die Nutzlast aus einer Integrationsantwort der entsprechenden Methodenantwort zuzuweisen.

Für einen Anfrage-Payload verwendet API Gateway den Content-Type-Header-Wert der Anfrage als Schlüssel zur Auswahl der Mapping-Vorlage für den Anfrage-Payload. Bei Payload-Antworten verwendet API Gateway den Accept-Header-Wert der eingehenden Anfrage als Schlüssel für die Auswahl der Mapping-Vorlage für den Payload.

Wenn der Content-Type-Header nicht in der Anfrage vorhanden ist, nimmt API Gateway an, dass sein Standardwert application/json ist. Für eine solche Anfrage verwendet API Gateway application/json als Standardschlüssel zur Auswahl der Mapping-Vorlage, falls eine solche definiert ist. Wenn keine Vorlage mit diesem Schlüssel übereinstimmt, übergibt API Gateway die Nutzlast ohne Zuweisung, wenn die Eigenschaft passthroughBehavior auf WHEN_NO_MATCH oder WHEN_NO_TEMPLATES eingestellt ist.

Wenn der Accept-Header nicht in der Anfrage angegeben ist, geht API Gateway davon aus, dass sein Standardwert application/json ist. In diesem Fall wählt API Gateway eine vorhandene Mapping-Vorlage für application/json aus, um den Payload der Antwort zuzuordnen. Wenn keine Vorlage für application/json definiert ist, wählt API Gateway die erste vorhandene Vorlage aus und verwendet sie als Standard für das Mapping des Payloads der Antwort. Genauso verwendet API Gateway die erste vorhandene Vorlage, wenn der angegebene Accept-Header-Wert nicht mit einem vorhandenen Vorlagenschlüssel übereinstimmt. Wenn keine Vorlage definiert ist, leitet API Gateway den Payload der Antwort einfach nicht zugeordnet weiter.

Angenommen, eine API verfügt über eine für eine Anforderungsnutzlast definierte application/json-Vorlage und eine für die Antwortnutzlast definierte application/xml-Vorlage. 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.

Die Accept- und Content-Type-Header verwenden bei der Auswahl der Mapping-Vorlage nur den MIME-Typ. Beispiel: Für einen "Content-Type: application/json; charset=UTF-8"-Header wird eine Anforderungsvorlage mit dem application/json-Schlüssel ausgewählt.