Verwenden von VMware Spring Cloud Gateway-Routen-Filtern mit dem Enterprise-Plan von Azure Spring Apps

Hinweis

Die Pläne Basic, Standard und Enterprise gelten ab Mitte März 2025 als veraltet und werden über einen Zeitraum von drei Jahren eingestellt. Es wird empfohlen, auf Azure Container Apps umzustellen. Weitere Informationen finden Sie in der Ankündigung zur Einstellung von Azure Spring Apps.

Der Plan Standardverbrauch und dediziert gilt ab dem 30. September 2024 als veraltet und wird nach sechs Monaten vollständig eingestellt. Es wird empfohlen, auf Azure Container Apps umzustellen. Weitere Informationen finden Sie unter Migrieren des Plans „Standardverbrauch und dediziert“ von Azure Spring Apps zu Azure Container Apps.

Dieser Artikel gilt für: ❎ Basic/Standard ✅ Enterprise

In diesem Artikel erfahren Sie, wie Sie VMware Spring Cloud Gateway mit dem Enterprise-Plan von Azure Spring Apps verwenden, um Anforderungen an Ihre Anwendungen weiterzuleiten.

VMware Spring Cloud Gateway ist eine kommerzielle VMware Tanzu-Komponente, die auf dem Spring Cloud Gateway-Open-Source-Projekt basiert. Spring Cloud Gateway erleichtert die Berücksichtigung übergreifender Aspekte durch API-Entwicklungsteams, z. B. einmaliges Anmelden (SSO), Zugriffssteuerung, Ratenbegrenzung, Resilienz, Sicherheit usw. Sie können die API-Bereitstellung mit modernen cloudnativen Modellen und einer beliebigen Programmiersprache für die API-Entwicklung beschleunigen.

VMware Spring Cloud Gateway umfasst die folgenden Funktionen:

• Dynamische Routingkonfiguration, unabhängig von einzelnen Anwendungen, die ohne Neukompilierung angewendet und geändert werden können.
• Kommerzielle API-Routenfilter für den Transport von autorisierten JWT-Ansprüchen (JSON Web Token) an Anwendungsdienste
• Clientzertifikatautorisierung.
• Ratenbegrenzungsansätze.
• Konfiguration von Trennschaltern (Circuit Breakers)
• Unterstützung für den Zugriff auf Anwendungsdienste über HTTP-Standardauthentifizierungsanmeldeinformationen.

Für die Integration in das API-Portal für VMware Tanzu generiert VMware Spring Cloud Gateway automatisch eine Dokumentation für OpenAPI Version 3, nachdem eine Routenkonfiguration hinzugefügt oder geändert wurde. Weitere Informationen finden Sie unter Verwenden des API-Portals für VMware Tanzu.

Voraussetzungen

• Eine bereits bereitgestellte Azure Spring Apps-Instanz im Enterprise-Plan mit aktiviertem Spring Cloud Gateway. Weitere Informationen finden Sie unter Schnellstart: Erstellen und Bereitstellen von Anwendungen in Azure Spring Apps mit dem Enterprise Plan.
• Azure CLI-Version 2.0.67 oder höher Verwenden Sie den folgenden Befehl, um die Azure Spring Apps-Erweiterung zu installieren: az extension add --name spring.

Filter verwenden

Sie verwenden Filter in Ihrer Spring Cloud Gateway-Konfiguration, um auf eingehende Anforderungen oder ausgehende Antworten auf eine Routenkonfiguration zu reagieren.

Sie können zum Beispiel einen Filter verwenden, um einen HTTP-Header hinzuzufügen oder den Zugriff auf der Grundlage eines Autorisierungs-Tokens zu verweigern.

Verwenden von Open Source-Filtern

Spring Cloud Gateway OSS enthält viele GatewayFilter-Factorys, die zum Erstellen von Filtern für Routen verwendet werden. In den folgenden Abschnitten werden diese Factorys beschrieben.

AddRequestHeader

Die AddRequestHeader-Factory fügt einen Header zu den Headern der nachgeschalteten Anforderung für alle übereinstimmenden Anforderungen hinzu.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name
• value

Im folgenden Beispiel wird eine AddRequestHeader-Factory konfiguriert, die den Header X-Request-red:blue den Headern der nachgeschalteten Anforderung für alle übereinstimmenden Anforderungen hinzufügt:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestHeader=X-Request-red, blue"
        ]
    }
]

Die AddRequestHeader-Factory hat Zugriff auf die URI-Variablen, die zum Abgleichen eines Pfads oder Hosts verwendet werden. Sie können im Wert URI-Variablen verwenden, und die Variablen werden zur Laufzeit erweitert.

Im folgenden Beispiel wird eine AddRequestHeader-Factory konfiguriert, die eine Variable verwendet:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddRequestHeader=X-Request-red, blue-{segment}"
        ]
    }
]

AddRequestHeadersIfNotPresent

Die AddRequestHeadersIfNotPresent-Factory fügt Header hinzu, wenn sie in der ursprünglichen Anforderung nicht vorhanden sind.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• headers: Eine durch Trennzeichen getrennte Liste von Schlüsselwertpaaren (Headername, Headerwert).

Im folgenden Beispiel wird eine AddRequestHeadersIfNotPresent-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
        ]
    }
]

AddRequestParameter

Die AddRequestParameter-Factory fügt einen Parameter zur Abfragezeichenfolge der nachgeschalteten Anforderung für alle übereinstimmenden Anforderungen hinzu.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name
• value

Im folgenden Beispiel wird eine AddRequestParameter-Factory konfiguriert, die den Parameter red=blue der Abfragezeichenfolge der nachgeschalteten Anforderung für alle übereinstimmenden Anforderungen hinzufügt:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestParameter=red, blue"
        ]
    }
]

Die AddRequestParameter-Factory hat Zugriff auf die URI-Variablen, die zum Abgleichen eines Pfads oder Hosts verwendet werden. Sie können im Wert URI-Variablen verwenden, und die Variablen werden zur Laufzeit erweitert.

Im folgenden Beispiel wird eine AddRequestParameter-Factory konfiguriert, die eine Variable verwendet:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddRequestParameter=foo, bar-{segment}"
        ]
    }
]

AddResponseHeader

Die AddResponseHeader-Factory fügt einen Header zu den Headern der nachgeschalteten Antwort für alle übereinstimmenden Anforderungen hinzu.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name
• value

Im folgenden Beispiel wird eine AddResponseHeader-Factory konfiguriert, die einen X-Response-Red:Blue-Header den Headern der nachgeschalteten Antwort für alle übereinstimmenden Anforderungen hinzufügt:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddResponseHeader=X-Response-Red, Blue"
        ]
    }
]

Die AddResponseHeader-Factory hat Zugriff auf die URI-Variablen, die zum Abgleichen eines Pfads oder Hosts verwendet werden. Sie können im Wert URI-Variablen verwenden, und die Variablen werden zur Laufzeit erweitert.

Im folgenden Beispiel wird eine AddResponseHeader-Factory konfiguriert, die eine Variable verwendet:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddResponseHeader=foo, bar-{segment}"
        ]
    }
]

CircuitBreaker

Die CircuitBreaker-Factory umschließt Routen mit einem Trennschalter.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name: Der Name des Trennschalters.
• fallbackUri: Der Umleitungs-URI, der eine lokale Route oder ein externer Handler sein kann.
• status codes (optional): Die durch Doppelpunkt getrennte Liste der Statuscodes, die übereinstimmen sollen, im Zahlen- oder Textformat.
• failure rate (optional): Der Schwellenwert, über dem der Trennschalter geöffnet wird. Der Standardwert ist 50 %.
• duration (optional): Die Wartezeit, bevor er wieder geschlossen wird. Der Standardwert beträgt 60 Sekunden.

Im folgenden Beispiel wird eine CircuitBreaker-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
        ]
    }
]

DeDupeResponseHeader

Die DeDupeResponseHeader Factory entfernt doppelte Werte von Antwortheadern.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name: Eine durch Leerzeichen getrennte Liste von Headernamen.
• strategy (optional): Zulässige Werte sind RETAIN_FIRST, RETAIN_LAST und RETAIN_UNIQUE. Der Standardwert ist RETAIN_FIRST.

Im folgenden Beispiel wird eine DeDupeResponseHeader-Factory konfiguriert, die doppelte Werte von Access-Control-Allow-Credentials- und Access-Control-Allow-Origin-Antwortheadern entfernt, wenn beide Werte von der CORS-Logik des Gateways und der nachgelagerten-Logik hinzugefügt werden:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "DeDupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin"
        ]
    }
]

FallbackHeaders

Die FallbackHeaders-Factory fügt einem Header eine Ausnahme für den Trennschalter hinzu. Für diesen Filter ist die Verwendung des CircuitBreaker-Filters in einer anderen Route erforderlich.

Es gibt keine Parameter für diese Factory.

Im folgenden Beispiel wird eine FallbackHeaders-Factory mit dem Ausnahmetyp, der Meldung und (sofern verfügbar) der Ausnahmeursachentyp und der Meldung konfiguriert, die der FallbackHeaders-Filter der Anforderung hinzufügt:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
        ]
    },
    {
        "predicates": [
            "Path=/inCaseOfFailureUseThis"
        ],
        "filters": [
            "FallbackHeaders"
        ]
    }
]

Sie können die Namen der Header in der Konfiguration überschreiben, indem Sie die Werte der folgenden Parameter festlegen (mit ihren Standardwerten erwähnt):

• executionExceptionTypeHeaderName ("Execution-Exception-Type")
• executionExceptionMessageHeaderName ("Execution-Exception-Message")
• rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")
• rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")

JSONToGRPC

Die JSONToGRPCFilter-Factory konvertiert eine JSON-Nutzlast in eine gRPC-Anforderung.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• protoDescriptor: Eine Protodeskriptordatei.

Sie können diese Datei mithilfe von protoc generieren und das --descriptor_set_out-Flag angeben, wie im folgenden Beispiel gezeigt:

protoc --proto_path=src/main/resources/proto/ \
    --descriptor_set_out=src/main/resources/proto/hello.pb \
    src/main/resources/proto/hello.proto

Hinweis

Der Parameter streaming wird nicht unterstützt.

Im folgenden Beispiel wird eine JSONToGRPCFilter-Factory unter Verwendung der Ausgabe von protoc konfiguriert:

[
    {
        "predicates": [
            "Path=/json/**"
        ],
        "filters": [
            "JsonToGrpc=file:proto/hello.pb,file:proto/hello.proto,HelloService,hello"
        ]
    }
]

LocalResponseCache

Die LocalResponseCache-Factory setzt die Konfiguration des lokalen Antwortcaches für bestimmte Routen außer Kraft, wenn der globale Cache aktiviert wird.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• size: Die maximale zulässige Größe der Cacheeinträge für diese Route, bevor die Cache-Bereinigung beginnt (in KB, MB und GB).
• timeToLive: Die zulässige Lebensdauer eines Cacheeintrags vor Ablauf. Verwenden Sie das Dauersuffix s für Sekunden, m für Minuten oder h für Stunden.

Im folgenden Beispiel wird eine LocalResponseCache-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "LocalResponseCache=3m,1MB"
        ]
    }
]

MapRequestHeader

Die MapRequestHeader-Factory fügt der nachgeschalteten Anforderung einen Header mit aktualisierten Werten aus dem Header der eingehenden HTTP-Anforderung hinzu.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• fromHeader
• toHeader

Diese Factory erstellt einen neuen benannten Header (toHeader), und der Wert wird aus einem vorhandenen benannten Header (fromHeader) aus der eingehenden HTTP-Anforderung extrahiert. Wenn der Eingabeheader nicht vorhanden ist, hat der Filter keine Auswirkung. Wenn der neue benannte Header bereits vorhanden ist, werden die Werte mit den neuen Werten erweitert.

Das folgende Beispiel konfiguriert eine MapRequestHeader-Factory, die den X-Request-Red:<values>-Header der nachgelagerten Anforderung mit aktualisierten Werten aus dem Blue-Header der eingehenden HTTP-Anforderung hinzufügt:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "MapRequestHeader=Blue, X-Request-Red"
        ]
    }
]

PrefixPath

Die PrefixPath-Factory fügt dem Pfad aller Anforderungen ein Präfix hinzu.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• prefix

Im folgenden Beispiel wird eine PrefixPath-Factory konfiguriert, die das Präfix /api zum Pfad aller Anforderungen hinzufügt, sodass eine Anforderung an /catalog an /api/catalog gesendet wird:

[
    {
        "predicates": [
            "Path=/catalog/**"
        ],
        "filters": [
            "PrefixPath=/api"
        ]
    }
]

PreserveHostHeader

Die PreserveHostHeader-Factory legt ein Anforderungsattribut fest, das der Routing-Filter überprüft, um zu bestimmen, ob der ursprüngliche Hostheader oder der vom HTTP-Client festgelegte Hostheader gesendet werden soll.

Es gibt keine Parameter für diese Factory.

Im folgenden Beispiel wird eine PreserveHostHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "PreserveHostHeader"
        ]
    }
]

RedirectTo

Die RedirectTo-Factory fügt eine Umleitung zur ursprünglichen URL hinzu.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• status: HTTP-Code der 300-Reihe umleiten, z. B. 301.
• url: Der Wert des Location-Headers. Muss ein gültiger URI sein. Für relative Umleitungen sollten Sie uri: no://op als URI Ihrer Routendefinition verwenden.

Im folgenden Beispiel wird eine RedirectTo-Factory konfiguriert, die einen 302-Status mit einem Location:https://acme.org-Header sendet, um eine Umleitung auszuführen:

[
    {
        "uri": "https://example.org",
        "filters": [
            "RedirectTo=302, https://acme.org"
        ]
    }
]

RemoveJsonAttributesResponseBody

Die RemoveJsonAttributesResponseBody-Factory entfernt die JSON-Attribute und deren Werte aus JSON-Antworttexten.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• attribute names: Eine durch Trennzeichen getrennte Liste der Namen von Attributen, die aus einer JSON-Antwort entfernt werden sollen.
• delete recursively (optional, boolescher Wert): Eine Konfiguration, die die Attribute nur auf Stammebene (false) oder rekursiv (true) entfernt. Der Standardwert ist false.

Im folgenden Beispiel wird eine RemoveJsonAttributesResponseBody-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveJsonAttributesResponseBody=origin,foo,true"
        ]
    }
]

RemoveRequestHeader

Die RemoveRequestHeader-Factory entfernt einen Header aus der nachfolgenden-Anforderung.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• name: Der Name des zu entfernenden Headers.

In der folgenden Auflistung wird eine RemoveRequestHeader-Factory konfiguriert, die den X-Request-Foo-Header entfernt, bevor er nachgelagert gesendet wird:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveRequestHeader=X-Request-Foo"
        ]
    }
]

RemoveRequestParameter

Die RemoveRequestParameter-Factory entfernt einen Parameter, bevor er nachgelagert gesendet wird.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• name: Der Name des zu entfernenden Abfrageparameters.

Im folgenden Beispiel wird eine RemoveRequestParameter-Factory konfiguriert, die den Parameter red entfernt, bevor er nachgelagert gesendet wird:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveRequestParameter=red"
        ]
    }
]

RemoveResponseHeader

Die RemoveResponseHeader-Factory entfernt einen Header aus der Antwort, bevor sie an den Gatewayclient zurückgegeben wird.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• name: Der Name des zu entfernenden Headers.

Die folgende Auflistung konfiguriert eine RemoveResponseHeader-Factory, die den X-Response-Foo-Header aus der Antwort entfernt, bevor sie an den Gatewayclient zurückgegeben wird:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveResponseHeader=X-Response-Foo"
        ]
    }
]

RequestHeaderSize

Die RequestHeaderSize-Factory bestimmt die Größe des Anforderungsheaders.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• maxSize: Die vom Anforderungsheader zulässige maximale Datengröße, einschließlich Schlüssel und Wert.
• errorHeaderName: Der Name des Antwortheaders, der eine Fehlermeldung enthält. Standardmäßig ist der Name des Antwortheaders errorMessage.

Die folgende Auflistung konfiguriert eine RequestHeaderSize-Factory, die einen Status 431 sendet, wenn die Größe eines Anforderungsheaders größer als 1000 Byte ist:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RequestHeaderSize=1000B"
        ]
    }
]

RewriteLocationResponseHeader

Die RewriteLocationResponseHeader-Factory ändert den Wert des Location-Antwortheaders, normalerweise um Back-End-spezifische Details zu entfernen.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• stripVersionMode: Für diesen Parameter sind die folgenden Werte möglich: NEVER_STRIP, AS_IN_REQUEST und ALWAYS_STRIP. Der Standardwert ist AS_IN_REQUEST.

  • NEVER_STRIP: Die Version wird nicht entfernt, auch wenn der ursprüngliche Anforderungspfad keine Version enthält.
  • AS_IN_REQUEST: Die Version wird nur entfernt, wenn er ursprüngliche Anforderungspfad keine Version enthält.
  • ALWAYS_STRIP: Die Version wird immer entfernt, auch wenn der ursprüngliche Anforderungspfad eine Version enthält.

• hostValue: Dieser Parameter wird verwendet, um den host:port-Teil der Antwort-Location-Header zu ersetzen, wenn angegeben. Wenn er nicht angegeben wird, wird der Wert des Host-Anforderungsheaders verwendet.

• protocolsRegex: Ein gültiger regex-String, mit dem der Protokollname abgeglichen wird. Wenn sie nicht übereinstimmen, funktioniert der Filter nicht. Der Standardwert ist http|https|ftp|ftps.

• locationHeaderName

In der folgenden Auflistung wird eine RewriteLocationResponseHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,"
        ]
    }
]

In diesem Beispiel wird für einen Anforderungswert von POST api.example.com/some/object/name der Antwortheaderwert Location von object-service.prod.example.net/v2/some/object/id als api.example.com/some/object/idumgeschrieben.

RewritePath

Die RewritePath-Factory verwendet reguläre Java-Ausdrücke für eine flexible Möglichkeit zum Umschreiben des Anforderungspfads.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• regexp
• replacement

In der folgenden Auflistung wird eine RewritePath-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/red/**"
        ],
        "filters": [
            "RewritePath=/red/?(?<segment>.*), /$\\{segment}"
        ]
    }
]

In diesem Beispiel legt diese Konfiguration für einen Anforderungspfad von /red/blue den Pfad auf /blue fest, bevor sie die nachgelagerte-Anforderung ausführen.

RewriteResponseHeader

Die RewriteResponseHeader-Factory verwendet reguläre Java-Ausdrücke für eine flexible Möglichkeit zum Umschreiben des Antwortheaderwerts.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name
• regexp
• replacement

Im folgenden Beispiel wird eine RewriteResponseHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/red/**"
        ],
        "filters": [
            "RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=***"
        ]
    }
]

In diesem Beispiel wird für einen Headerwert von /42?user=ford&password=omg!what&flag=truedie Konfiguration auf /42?user=ford&password=***&flag=true festgelegt, nachdem die Downstreamanforderung vorgenommen wurde.

SetPath

Die SetPath-Factory bietet eine einfache Möglichkeit, den Anforderungspfad zu bearbeiten, indem vorlagenbasierte Segmente des Pfads zugelassen werden. Dieser Filter verwendet die URI-Vorlagen aus Spring Framework und ermöglicht mehrere übereinstimmende Segmente.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• template

Im folgenden Beispiel wird eine SetPath-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/red/{segment}"
        ],
        "filters": [
            "SetPath=/{segment}"
        ]
    }
]

In diesem Beispiel legt diese Konfiguration für einen Anforderungspfad von /red/blue den Pfad auf /blue fest, bevor sie die nachgelagerte-Anforderung ausführen.

SetRequestHeader

Die SetRequestHeader-Factory ersetzt alle Kopfzeilen durch den angegebenen Namen (anstatt sie hinzuzufügen).

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name
• value

In der folgenden Auflistung wird eine SetRequestHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "SetRequestHeader=X-Request-Red, Blue"
        ]
    }
]

In diesem Beispiel reagierte der nachgeschaltete Server mit X-Request-Red:1234 und wird durch X-Request-Red:Blue ersetzt.

Die SetRequestHeader-Factory hat Zugriff auf die URI-Variablen, die zum Abgleichen eines Pfads oder Hosts verwendet werden. Sie können im Wert URI-Variablen verwenden, und die Variablen werden zur Laufzeit erweitert.

Im folgenden Beispiel wird eine SetRequestHeader-Factory konfiguriert, die eine Variable verwendet:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "SetRequestHeader=foo, bar-{segment}"
        ]
    }
]

SetResponseHeader

Die SetResponseHeader-Factory ersetzt alle Kopfzeilen durch den angegebenen Namen (anstatt sie hinzuzufügen).

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• name
• value

In der folgenden Auflistung wird eine SetResponseHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "SetResponseHeader=X-Response-Red, Blue"
        ]
    }
]

In diesem Beispiel reagierte der nachgeschaltete Server mit X-Response-Red:1234 und wird durch X-Response-Red:Blue ersetzt.

Die SetResponseHeader-Factory hat Zugriff auf die URI-Variablen, die zum Abgleichen eines Pfads oder Hosts verwendet werden. Sie können im Wert URI-Variablen verwenden, und die Variablen werden zur Laufzeit erweitert.

Im folgenden Beispiel wird eine SetResponseHeader-Factory konfiguriert, die eine Variable verwendet:

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "SetResponseHeader=foo, bar-{segment}"
        ]
    }
]

SetStatus

Die SetStatus Factory konfiguriert den Antwortstatus der Serveranforderung.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• status: Ein gültiger Spring-HttpStatus-Wert, der einen ganzzahligen Wert wie 404 oder die Zeichenfolgendarstellung der Enumeration wie NOT_FOUND annehmen kann.

In der folgenden Auflistung wird eine SetStatus-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/experimental/**"
        ],
        "filters": [
            "SetStatus=UNAUTHORIZED"
        ]
    },
    {
        "predicates": [
            "Path=/unknown/**"
        ],
        "filters": [
            "SetStatus=401"
        ]
    }
]

StripPrefix

Die StripPrefix-Factory entfernt das Präfix aus der Anforderung, bevor sie nachgelagert gesendet wird.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• parts: Die Anzahl der Teile im Pfad, die von der Anforderung entfernt werden sollen, bevor sie nachgelagert gesendet wird. Der Standardwert ist 1.

Im folgenden Beispiel wird eine StripPrefix-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/name/**"
        ],
        "filters": [
            "StripPrefix=2"
        ]
    }
]

In diesem Beispiel wird eine Anforderung über das Gateway an /name/blue/red gestellt. Die an nameservice vorgenommene Anforderung wird als nameservice/red angezeigt.

Wiederholen

Die Retry-Factory bestimmt die Anzahl der Wiederholungen, die versucht wurden.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• retries: Die Anzahl von zu versuchenden Wiederholungen.
• statuses: Die HTTP-Statuscodes, die erneut versucht werden sollen, dargestellt durch org.springframework.http.HttpStatus.
• methods: Die HTTP-Methoden, die erneut versucht werden sollen, dargestellt durch org.springframework.http.HttpMethod.
• series: Die Serien von Statuscodes, die erneut versucht werden sollen, dargestellt durch org.springframework.http.HttpStatus.Series.
• exceptions: Die Liste der ausgelösten Ausnahmen, die wiederholt werden sollten.
• backoff: Der konfigurierte exponentielle Backoff für die Wiederholungen. Wiederholungen werden nach einem Backoffintervall von firstBackoff * (factor ^ n) ausgeführt, wobei n die Iteration ist. Wenn maxBackoff konfiguriert ist, wird der maximal angewendete Backoff auf maxBackoff beschränkt. Wenn basedOnPreviousValue true ist, wird das backoff mithilfe von prevBackoff * factor berechnet.

Die folgenden Standardwerte sind für den Retry-Filter konfiguriert, wenn diese aktiviert sind:

• retries: dreimal
• series: 5XX-Serie.
• methods: GET-Methode
• exceptions: IOException und TimeoutException.
• backoff: deaktiviert

Im folgenden Beispiel wird eine Retry-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false"
        ]
    }
]

RequestSize

Die RequestSize-Factory kann verhindern, dass eine Anforderung den nachgeschalteten Dienst erreicht, wenn die Größe der Anforderung den zulässigen Grenzwert überschreitet.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• maxSize: Ein DataSize-Typ, in dem Werte als Zahl definiert sind, gefolgt von einem optionalen DataUnit-Suffix wie KB oder MB. Der Standardwert des Suffixes ist B für Bytes. Dies ist die zulässige Größenbeschränkung der Anforderung, die in Bytes definiert ist.

Im folgenden Beispiel wird eine RequestSize-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/upload"
        ],
        "filters": [
            "RequestSize=5000000"
        ]
    }
]

Wenn die Anforderung in diesem Beispiel aufgrund der Größe abgelehnt wird, legt die RequestSize-Factory den Antwortstatus mit einem anderen errorMessage-Header auf 413 Payload Too Large fest.

Das folgende Beispiel zeigt eine errorMessage:

errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB

TokenRelay

Die TokenRelay-Factory leitet ein OAuth2-Zugriffstoken an nachgelagerte-Ressourcen weiter. Dieser Filter wird als boolean-Wert in der Routendefinition konfiguriert und nicht als expliziter Filter.

Im folgenden Beispiel wird eine TokenRelay-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "tokenRelay": true
    }
]

Verwenden kommerzieller Filter

Spring Cloud Gateway für Kubernetes bietet auch viele benutzerdefinierte GatewayFilter-Factorys. In den folgenden Abschnitten werden diese Factorys beschrieben.

AllowedRequestCookieCount

Die AllowedRequestCookieCount-Factory bestimmt anhand der Anzahl der Cookies, ob eine entsprechende Anforderung ausgeführt werden darf.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• amount: Die Anzahl der zulässigen Cookies.

Im folgenden Beispiel wird eine AllowedRequestCookieCount-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestCookieCount=2"
        ]
    }
]

AllowedRequestHeadersCount

Die AllowedRequestHeadersCount-Factory bestimmt anhand der Anzahl der Kopfzeilen, ob eine entsprechende Anforderung ausgeführt werden darf.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• amount: Die Anzahl der zulässigen Headers.

Im folgenden Beispiel wird eine AllowedRequestHeadersCount-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestHeadersCount=4"
        ]
    }
]

AllowedRequestQueryParamsCount

Die AllowedRequestQueryParamsCount-Factory bestimmt anhand der Anzahl der Abfrageparameter, ob eine entsprechende Anforderung ausgeführt werden darf.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• amount: Die Anzahl der zulässigen Parameter.

Im folgenden Beispiel wird eine AllowedRequestQueryParamsCount-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestQueryParamsCount=3"
        ]
    }
]

BasicAuth

Die BasicAuth-Factory fügt Anforderungen einen BasicAuth Authorization-Header hinzu.

Es gibt keine Parameter für diese Factory.

Im folgenden Beispiel wird eine BasicAuth-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "BasicAuth"
        ]
    }
]

ClaimHeader

Die ClaimHeader-Factory kopiert Daten aus einem JWT-Anspruch in einen HTTP-Header.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• Claim name: Der Name der zu übergebenden Forderung mit Berücksichtigung von Groß- und Kleinschreibung.
• Header name: Der Name des HTTP-Headers.

Im folgenden Beispiel wird eine ClaimHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "ClaimHeader=sub,X-Claim-Sub"
        ]
    }
]

ClientCertificateHeader

Die ClientCertificateHeader-Factory überprüft das Headerzertifikat X-Forwarded-Client-Cert.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• domain pattern: Der X-Forwarded-Client-Cert-Wert entsprechend der Fähigkeit von Kubernetes, die Zertifizierungsstelle des Clientzertifikats zu erkennen.
• certificate fingerprint(optional): Der Fingerabdruck des TLS/SSL-Zertifikats.

Im folgenden Beispiel wird eine ClientCertificateHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "ClientCertificateHeader=*.example.com,sha-1:aa:bb:00:99"
        ]
    }
]

Cors

Die Cors-Factory aktiviert die CORS-Validierungen auf einer Route.

Diese Factory akzeptiert die folgenden Konfigurationsparameter, die als Schlüsselwertpaare für CORS-Optionen organisiert sind:

• allowedOrigins
• allowedMethods
• allowedHeaders
• maxAge
• allowCredentials
• allowedOriginPatterns

Im folgenden Beispiel wird eine Cors-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Cors=[allowedOrigins:https://origin-1,allowedMethods:GET;POST;DELETE,allowedHeaders:*,maxAge:400,allowCredentials:true,allowedOriginPatterns:https://*.test.com:8080]"
        ]
    }
]

JsonToXml

Die JsonToXml-Factory transformiert JSON-Antworttext in XML-Antworttext.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• wrapper: Der Name des Root-Tags für die XML-Antwort, wenn ein anderes Root-Tag erforderlich ist, um gültiges XML zu erzeugen. Der Standardwert ist response.

Im folgenden Beispiel wird eine JsonToXml-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "JsonToXml=custom-response"
        ]
    }
]

RateLimit

Die RateLimit-Factory bestimmt anhand des Anforderungsvolumens, ob eine entsprechende Anforderung ausgeführt werden darf.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• request limit: Die maximale Anzahl der Anforderungen, die während des Zeitfensters akzeptiert wurden.
• window duration: Die Fensterdauer in Millisekunden. Alternativ können Sie die Suffixe s, m oder h verwenden, um die Dauer in Sekunden, Minuten oder Stunden anzugeben.
• partition source (optional): Der Speicherort des Partitionsschlüssels (claim, header oder IPs).
• partition key (optional): Der Wert, der für Partitionierungsanforderungszähler verwendet wird.

Im folgenden Beispiel wird eine RateLimit-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RateLimit=1,10s"
        ]
    }
]

Die folgenden Beispiele zeigen andere RateLimit-Konfigurationen:

RateLimit=1,10s
RateLimit=1,10s,{claim:client_id}
RateLimit=1,10s,{header:client_id}
RateLimit=2,10s,{IPs:2;127.0.0.1;192.168.0.1}

RestrictRequestHeaders

Die RestrictRequestHeaders-Factory bestimmt anhand der Header, ob eine entsprechende Anforderung ausgeführt werden darf.

Wenn es HTTP-Header gibt, die nicht in der headerList-Konfiguration (wo Groß-/Kleinschreibung nicht berücksichtigt wird) enthalten sind, erhält der Client eine Antwort von 431 Forbidden error.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• headerList: Die von der Groß- und Kleinschreibung unabhängige Liste der Namen der zulässigen Header.

Im folgenden Beispiel wird eine RestrictRequestHeaders-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RestrictRequestHeaders=Content-Type,x-request-temp"
        ]
    }
]

RewriteAllResponseHeaders

Die RewriteAllResponseHeaders-Factory schreibt mehrere Antwortheader gleichzeitig um.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• pattern to match: Der reguläre Ausdruck, der mit Headerwerten abgeglichen werden soll.
• replacement: Der Ersetzungswert.

Im folgenden Beispiel wird eine RewriteAllResponseHeaders-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteAllResponseHeaders=\\d,0"
        ]
    }
]

RewriteResponseBody

Die RewriteResponseBody-Factory ändert den Textkörper einer Antwort.

Diese Factory akzeptiert die folgenden Konfigurationsparameter, die als kommagetrennte Liste von Schlüssel-Wert-Paaren organisiert sind, wobei jedes Paar die Form pattern to match:replacement annimmt:

• pattern to match: Der reguläre Ausdruck, der mit Text im Antworttext abgeglichen werden soll.
• replacement: Der Ersetzungswert.

Im folgenden Beispiel wird eine RewriteResponseBody-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteResponseBody=foo:bar,/path-one/:/path-two/"
        ]
    }
]

RewriteJsonAttributesResponseBody

Die RewriteJsonAttributesResponseBody-Factory schreibt JSON-Attribute mithilfe der JSONPath-Notation neu.

Diese Factory akzeptiert die folgenden Konfigurationsparameter, die als kommagetrennte Liste von Schlüssel-Wert-Paaren organisiert sind, wobei jedes Paar die Form jsonpath:replacement annimmt:

• jsonpath: Der JSONPath-Ausdruck, der mit Text im Antworttext abgeglichen werden soll.
• replacement: Der Ersetzungswert.

Im folgenden Beispiel wird eine RewriteJsonAttributesResponseBody-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteJsonAttributesResponseBody=slides[1].title:Welcome,date:11-11-2022"
        ]
    }
]

Rollen

Die Roles-Factory autorisiert Anforderungen, die eine der konfigurierten Rollen enthalten.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• roles: Eine Liste autorisierter Rollen, die durch Trennzeichen voneinander getrennt sind.

Im folgenden Beispiel wird eine Roles-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Roles=role_01,role_02"
        ]
    }
]

Bereiche

Die Scopes-Factory autorisiert Anforderungen, die einen der konfigurierten OAuth-Bereiche enthalten.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• scopes: Eine Liste autorisierter OAuth-Bereiche, die durch Trennzeichen voneinander getrennt sind.

Im folgenden Beispiel wird eine Scopes-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Scopes=api.read,api.write,user"
        ]
    }
]

StoreIpAddress

Die StoreIPAddress-Factory wird nur für die Erweiterungsentwicklung und im Kontext der Anwendung verwendet.

Diese Factory akzeptiert den folgenden Konfigurationsparameter:

• attribute name: Der Name, der zum Speichern der IP-Adresse als Exchange-Attribut verwendet wird.

Im folgenden Beispiel wird eine StoreIPAddress-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "StoreIpAddress=ip"
        ]
    }
]

SSO-Anmeldung

Die SSO login-Factory wird zur Authentifizierung umgeleitet, wenn kein gültiges Autorisierungstoken vorhanden ist. Diese Factory wird als boolean-Wert in der Routendefinition konfiguriert und nicht als expliziter Filter.

Im folgenden Beispiel wird eine SSO login-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "ssoEnabled": true
    }
]

StoreHeader

Die StoreHeader-Factory speichert einen Headerwert im Kontext der Anwendung. Dieser Filter wird nur für die Erweiterungsentwicklung verwendet.

Diese Factory akzeptiert die folgenden Konfigurationsparameter:

• headers: Eine Liste der zu überprüfenden Header. Die erste, der gefunden wird, wird verwendet.
• attribute name: Der Name, der zum Speichern des Headerwerts als Exchange-Attribut verwendet wird.

Im folgenden Beispiel wird eine StoreHeader-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "StoreHeader=x-tracing-header,custom-id,x-custom-id,tracingParam"
        ]
    }
]

XmlToJson

Die XmlToJson-Factory transformiert XML-Antworttext in JSON-Antworttext.

Es gibt keine Parameter für diese Factory.

Im folgenden Beispiel wird eine XmlToJson-Factory konfiguriert:

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "XmlToJson"
        ]
    }
]

Nächste Schritte

• Azure Spring Apps
• Schnellstart: Erstellen und Bereitstellen von Apps in Azure Spring Apps mithilfe des Enterprise-Plans