Transformieren Sie API Anfragen und Antworten für HTTP APIs in API Gateway

Sie können API Anfragen von Kunden ändern, bevor sie Ihre Backend-Integrationen erreichen. Sie können auch die Antwort von Integrationen ändern, bevor API Gateway die Antwort an die Clients zurücksendet. Sie verwenden die Parameterzuordnung, um API Anfragen und Antworten für HTTP APIs zu ändern. Um die Parameterzuordnung zu verwenden, geben Sie die zu ändernden API Anforderungs- oder Antwortparameter an und geben an, wie diese Parameter geändert werden sollen.

APIAnfragen transformieren

Sie verwenden Anforderungsparameter, um Anforderungen zu ändern, bevor sie Ihre Backend-Integrationen erreichen. Sie können Header, Abfragezeichenfolgen oder den Anforderungspfad ändern.

Anforderungsparameter sind eine Schlüssel-Wert-Zuordnung. Der Schlüssel gibt den Speicherort des zu ändernden Anforderungsparameters und an, wie er geändert werden soll. Der Wert gibt die neuen Daten für den Parameter an.

Die folgende Tabelle zeigt unterstützte Schlüssel.

Typ	Syntax
Header	append|overwrite|remove:header.headername
Abfragezeichenfolge	append|overwrite|remove:querystring.querystring-name
Pfad	overwrite:path

Die folgende Tabelle zeigt unterstützte Werte, die Sie Parametern zuordnen können.

Typ	Syntax	Hinweise
Header-Wert	$request.header.name oder $ {request.header.name}	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden. APIGateway kombiniert beispielsweise mehrere Header-Werte mit Kommas. "header1": "value1,value2" Einige Header sind reserviert. Weitere Informationen hierzu finden Sie unter Reservierte Header.
Abfragezeichenfolgenwert	$request.querystring.name oder $ {request.querystring.name}	Abfragezeichenfolgennamen unterscheiden zwischen Groß- und Kleinschreibung. APIGateway kombiniert beispielsweise mehrere Werte mit Kommas. "querystring1" "Value1,Value2"
Anforderungstext	$request.body.name oder $ {request.body.name}	Ein JSON Pfadausdruck. Rekursiver Abstieg ($request.body..name)) und Filterausdrücke (?(expression)) werden nicht unterstützt. Anmerkung Wenn Sie einen JSON Pfad angeben, kürzt API Gateway den Anforderungstext auf 100 KB und wendet dann den Auswahlausdruck an. Um Payloads mit mehr als 100 KB zu senden, geben Sie an $request.body.
Anforderungspfad	$request.path oder ${request.path}	Der Anforderungspfad ohne den Namen der Stufe.
Path-Parameter	$request.path.name oder $ {request.path.name}	Der Wert eines Pfadparameters in der Anforderung. Beispiel: Wenn die Route /pets/{petId} ist, können Sie den Parameter petId aus der Anforderung mit $request.path.petId zuordnen.
Kontextvariable	$context.variableName oder $ {context.variableName}	Der Wert einer Kontextvariablen. Anmerkung NEs werden ausschließlich die Sonderzeichen . und _ unterstützt.
Stufenvariable	$stageVariables.variableName oder $ {stageVariables.variableName}	Der Wert einer Stufenvariablen.
Statischer Wert	string	Ein konstanter Wert.

Anmerkung

Um mehrere Variablen in einem Auswahlausdruck zu verwenden, schließen Sie die Variable in Klammern ein. z. B. ${request.path.name} ${request.path.id}.

APIAntworten transformieren

Sie verwenden Antwortparameter, um die HTTP Antwort aus einer Backend-Integration zu transformieren, bevor Sie die Antwort an die Clients zurückgeben. Sie können Header oder den Statuscode einer Antwort ändern, bevor API Gateway die Antwort an die Clients zurückgibt.

Sie konfigurieren die Antwortparameter für jeden Statuscode, den Ihre Integration zurückgibt. Antwortparameter sind eine Schlüssel-Wert-Zuordnung. Der Schlüssel gibt den Speicherort des zu ändernden Anforderungsparameters und an, wie er geändert werden soll. Der Wert gibt die neuen Daten für den Parameter an.

Die folgende Tabelle zeigt unterstützte Schlüssel.

Typ	Syntax
Header	append|overwrite|remove:header.headername
Statuscode	overwrite:statuscode

Die folgende Tabelle zeigt unterstützte Werte, die Sie Parametern zuordnen können.

Typ	Syntax	Hinweise
Header-Wert	$response.header.name oder $ {response.header.name}	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden. APIGateway kombiniert beispielsweise mehrere Header-Werte mit Kommas. "header1": "value1,value2" Einige Header sind reserviert. Weitere Informationen hierzu finden Sie unter Reservierte Header.
Antworttext	$response.body.name oder $ {response.body.name}	Ein JSON Pfadausdruck. Rekursiver Abstieg ($response.body..name) und Filterausdrücke (?(expression)) werden nicht unterstützt. Anmerkung Wenn Sie einen JSON Pfad angeben, kürzt API Gateway den Antworttext auf 100 KB und wendet dann den Auswahlausdruck an. Um Payloads mit mehr als 100 KB zu senden, geben Sie an $response.body.
Kontextvariable	$context.variableName oder $ {context.variableName}	Der Wert einer unterstützten Kontextvariablen.
Stufenvariable	$stageVariables.variableName oder $ {stageVariables.variableName}	Der Wert einer Stufenvariablen.
Statischer Wert	string	Ein konstanter Wert.

Anmerkung

Um mehrere Variablen in einem Auswahlausdruck zu verwenden, schließen Sie die Variable in Klammern ein. z. B. ${request.path.name} ${request.path.id}.

Reservierte Header

Die folgenden Header sind reserviert. Sie können keine Anforderungs- oder Antwort-Mappings für diese Header konfigurieren.

• access-control-*

• apigw-*

• Autorisierung

• Verbindung

• Content-Encoding

• Content-Length

• Content-Location

• Forwarded

• Keep-Alive

• Urspung

• Proxy-Authenticate

• Proxy-Authorization

• TE

• Trailers

• Transfer-Encoding

• Upgrade

• x-amz-*

• x-amzn-*

• X-Forwarded-For

• X-Forwarded-Host

• X-Forwarded-Proto

• Via

Beispiele

In den folgenden AWS CLI Beispielen werden Parameterzuordnungen konfiguriert. AWS CloudFormation Beispielvorlagen finden Sie unter. GitHub

Fügen Sie einer API Anfrage einen Header hinzu

Im folgenden Beispiel wird einer API Anfrage ein Header mit header1 dem Namen hinzugefügt, bevor sie Ihre Backend-Integration erreicht. APIGateway füllt den Header mit der Anforderungs-ID.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }' 

Umbenennen eines Anforderungsheaders

Im folgenden Beispiel wird ein Anforderungsheader von header1 in header2 umbenannt.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'

Ändern der Antwort aus einer Integration

Im folgenden Beispiel werden Antwortparameter für eine Integration konfiguriert. Wenn die Integration einen Statuscode 500 zurückgibt, ändert API Gateway den Statuscode auf 403 und fügt der Antwort header1 1 hinzu. Wenn die Integration einen 404-Statuscode zurückgibt, fügt API Gateway der Antwort einen error Header hinzu.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'

Entfernen konfigurierter Parameter-Mappings

Der folgende Beispielbefehl entfernt zuvor konfigurierte Anforderungsparameter für append:header.header1. Außerdem werden zuvor konfigurierte Antwortparameter für einen 200-Statuscode entfernt.

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'