Datentransformationen für REST-APIs in API Gateway

Anmerkung

In diesem Abschnitt werden die Features erläutert, die Sie mit einer Nicht-Proxy-Integration verwenden. Wir empfehlen jedoch, wann immer möglich, eine Proxy-Integration für Ihre REST-API zu verwenden. Eine Proxy-Integration bietet eine vereinfachte Integrationskonfiguration und kann sich gemeinsam mit dem Backend weiterentwickeln, ohne die bestehende Einrichtung zu beeinträchtigen. Weitere Informationen finden Sie unter Auswählen eines API Gateway-API-Integration.

Wenn Sie eine Nicht-Proxy-Integration verwenden, können Sie zwei Features von API Gateway nutzen, um Ihre Methodenanforderung und Ihre Integrationsantwort zu transformieren. Sie können die Methodenanforderung transformieren, wenn sie ein anderes Format der Nutzdaten als die Integrationsanforderung verwendet. Sie können die Integrationsantwort transformieren, wenn sie ein anderes Format der Nutzdaten zurückliefert als das Format, das Sie in der Methodenantwort zurückgeben müssen. Weitere Informationen zum Lebenszyklus einer Anfrage finden Sie unter Beispielressource für eine REST-API.

Im folgenden Beispiel wird eine Daten­transformation dargestellt: Für den Header "x-version:beta" wird der Header-Parameter x-version in den Header-Parameter app-version transformiert. Diese Transformation von x-version in app-version erfolgt in der Integrationsanforderung. Auf diese Weise empfängt das Integrationsendpunkt den transformierten Header-Parameterwert. Wenn der Integrationsendpunkt einen Statuscode zurückgibt, wird dieser von 200 in 204 transformiert, bevor er als Methodenantwort zurückgegeben wird.

Um eine Datentransformation zu erstellen, können Sie die folgenden Features verwenden:

Parameterzuweisung

Bei der Zuweisung von Parametern können Sie die URL-Pfadparameter, die URL-Abfragezeichenfolgenparameter oder die HTTP-Header-Werte der Integrationsanforderung ändern, aber nicht die Nutzdaten der Integrationsanforderung. Sie können auch die Header-Werte der HTTP-Antwort ändern. Verwenden Sie die Parameterzuweisung, um statische Header-Werte für Cross-Origin Resource Sharing (CORS) zu erstellen.

Sie können die Zuweisung von Parametern in Ihrer Integrationsanforderung sowohl für Proxy- als auch für Nicht-Proxy-Integrationen verwenden. Um jedoch die Zuweisung von Parametern für eine Integrationsantwort zu nutzen, benötigen Sie eine Nicht-Proxy-Integration. Die Zuweisung von Parametern erfordert kein Scripting in der Velocity Template Language (VTL). Weitere Informationen finden Sie unter Parameterzuweisung für REST-APIs in API Gateway.

Transformationen mit Zuweisungsvorlagen

Bei Transformationen mit Zuweisungsvorlagen verwenden Sie eine Vorlage, um URL-Pfadparameter, URL-Abfragezeichenfolgenparameter, HTTP-Header sowie den Body der Integrationsanforderung oder Integrationsantwort zuzuweisen. Eine Zuweisungsvorlage ist ein Skript in der Velocity Template Language (VTL), das JSONPath-Ausdrücke nutzt und auf die Nutzdaten angewendet wird, basierend auf dem Content-type-Header.

Mit einer Zuweisungsvorlage können Sie Folgendes tun:

• Auswählen, welche Daten mithilfe der Integration mit AWS-Services gesendet werden sollen, z. B. mit Amazon-DynamoDB- oder Lambda-Funktionen oder HTTP-Endpunkten Weitere Informationen finden Sie unter Tutorial: Ändern der Integrationsanforderung und -antwort für Integrationen mit AWS-Services.

• Bedingt die Parameter einer Integrationsanforderung und -antwort einer API überschreiben, neue Header-Werte erstellen und Statuscodes überschreiben. Weitere Informationen finden Sie unter Überschreiben der Anforderungs- und Antwortparameter sowie Statuscodes Ihrer API für REST-APIs in API Gateway.

Das Verhalten Ihrer API festlegen, wenn die Nutzdaten einer Integrationsanforderung einen Content-type-Header enthalten, für den keine passenden Zuweisungsvorlagen vorhanden sind. Dies wird als Integrations-Passthrough-Verhalten bezeichnet. Weitere Informationen finden Sie unter Verhalten der Methodenanforderung für Nutzdaten ohne Zuweisungsvorlagen für REST-APIs in API Gateway.

Auswahl zwischen Zuweisung von Parametern und Transformationen mit Zuweisungsvorlagen

Wir empfehlen, die Zuweisung von Parametern zu verwenden, um Daten nach Möglichkeit zu transformieren. Wenn Ihre API jedoch erfordert, dass Sie den Body ändern oder bedingte Überschreibungen und Modifikationen basierend auf der eingehenden Integrationsanforderung oder Integrationsantwort vornehmen und Sie keine Proxy-Integration verwenden können, sollten Sie Transformationen mit Zuweisungsvorlagen einsetzen.