Transformieren von API-Anforderungen und -Antworten

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

Transformieren von API-Anforderungen

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.

Parameter-Mapping-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.

Anforderungsparameter-Mapping-Werte
Typ	Syntax	Hinweise
Header-Wert	$request.header.name oder ${request.header.name}	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden. API Gateway kombiniert mehrere Headerwerte mit Kommas, z. B. "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. API Gateway kombiniert mehrere Werte mit Kommas, z. B. "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, schneidet API Gateway den Anfragetext auf 100 KB ab 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.
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. Beispielsweise ${request.path.name} ${request.path.id}.

Transformieren von API-Antworten

Sie verwenden Antwortparameter, um die HTTP-Antwort einer Backend-Integration zu transformieren, bevor Sie die Antwort an Clients zurückgeben. Sie können Header oder den Statuscode einer Antwort ändern, bevor API Gateway die Antwort an 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.

Antwortparameter-Mapping-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.

Antwortparameter-Mapping-Werte
Typ	Syntax	Hinweise
Header-Wert	$response.header.Name oder $ {response.header.name}	Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden. API Gateway kombiniert mehrere Headerwerte mit Kommas, z. B. "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. Beispielsweise ${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

Mit den folgenden AWS CLI-Beispielen werden Parameter-Mappings konfiguriert. AWS CloudFormation-Beispielvorlagen finden Sie auf GitHub.

Hinzufügen eines Headers zu einer API-Anforderung

Im folgenden Beispiel wird eine Kopfzeile mit dem Namen header1 zu einer API-Anforderung hinzugefügt, bevor sie Ihre Backend-Integration erreicht. API Gateway füllt den Header mit der Anforderungs-ID auf.

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 Integrationen einen 500-Statuscode zurückgeben, ändert API Gateway den Statuscode auf 403 und fügt der Antwort header11 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-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters {"append:header.header1" : ""} \ 
    --response-parameters {"200" : {}}