Jak używać filtrów tras usługi VMware Spring Cloud Gateway z planem Usługi Azure Spring Apps Enterprise

Artykuł
01/31/2024

Uwaga

Azure Spring Apps to nowa nazwa usługi Azure Spring Cloud. Mimo że usługa ma nową nazwę, stara nazwa będzie widoczna w niektórych miejscach przez pewien czas, ponieważ pracujemy nad aktualizowaniem zasobów, takich jak zrzuty ekranu, filmy wideo i diagramy.

Ten artykuł dotyczy:❌ Podstawowa/Standardowa ✔️ Enterprise

W tym artykule wyjaśniono, jak używać filtrów tras usługi VMware Spring Cloud Gateway z planem usługi Azure Spring Apps Enterprise w celu kierowania żądań do aplikacji.

VMware Spring Cloud Gateway to komercyjny składnik VMware Tanzu oparty na projekcie Spring Cloud Gateway typu open source. Usługa Spring Cloud Gateway obsługuje wielociągowe obawy dotyczące zespołów programistycznych interfejsów API, takich jak logowanie jednokrotne, kontrola dostępu, ograniczanie szybkości, odporność, zabezpieczenia i nie tylko. Dostarczanie interfejsu API można przyspieszyć przy użyciu nowoczesnych wzorców natywnych dla chmury i dowolnego języka programowania wybranego do tworzenia interfejsu API.

Usługa VMware Spring Cloud Gateway obejmuje następujące funkcje:

Konfiguracja routingu dynamicznego, niezależna od poszczególnych aplikacji, które można stosować i zmieniać bez ponownej kompilacji.
Filtry tras komercyjnego interfejsu API do transportu autoryzowanych oświadczeń tokenu internetowego JSON (JWT) do usług aplikacji.
Autoryzacja certyfikatu klienta.
Podejścia ograniczające szybkość.
Konfiguracja wyłącznika.
Obsługa uzyskiwania dostępu do usług aplikacji za pośrednictwem poświadczeń uwierzytelniania podstawowego PROTOKOŁU HTTP.

Aby zintegrować się z portalem interfejsu API dla oprogramowania VMware Tanzu, brama VMware Spring Cloud Gateway automatycznie generuje dokumentację interfejsu OpenAPI w wersji 3 po dodaniu lub zmianie konfiguracji trasy. Aby uzyskać więcej informacji, zobacz Use API Portal for VMware Tanzu (Korzystanie z portalu interfejsu API dla programu VMware Tanzu).

Wymagania wstępne

Już aprowizowane wystąpienie usługi azure Spring Apps Enterprise z włączoną usługą Spring Cloud Gateway. Aby uzyskać więcej informacji, zobacz Szybki start: tworzenie i wdrażanie aplikacji w usłudze Azure Spring Apps przy użyciu planu Enterprise.
Interfejs wiersza polecenia platformy Azure w wersji 2.0.67 lub nowszej. Użyj następującego polecenia, aby zainstalować rozszerzenie Azure Spring Apps: az extension add --name spring.

Używanie filtrów

Filtry w konfiguracji usługi Spring Cloud Gateway służą do działania na żądanie przychodzące lub wychodzące odpowiedzi na konfigurację trasy.

Możesz na przykład użyć filtru, aby dodać nagłówek HTTP lub odmówić dostępu na podstawie tokenu autoryzacji.

Korzystanie z filtrów typu open source

System operacyjny Spring Cloud Gateway zawiera kilka GatewayFilter fabryk używanych do tworzenia filtrów tras. W poniższych sekcjach opisano te fabryki.

AddRequestHeader

Fabryka AddRequestHeader dodaje nagłówek do nagłówków żądania podrzędnego dla wszystkich pasujących żądań.

Ta fabryka akceptuje następujące parametry konfiguracji:

name
value

Poniższy przykład umożliwia skonfigurowanie AddRequestHeader fabryki, która dodaje nagłówek X-Request-red:blue do nagłówków żądania podrzędnego dla wszystkich pasujących żądań:

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

Fabryka AddRequestHeader ma dostęp do zmiennych identyfikatora URI używanych do dopasowania ścieżki lub hosta. Zmienne identyfikatora URI można używać w wartości, a zmienne są rozszerzane w czasie wykonywania.

Poniższy przykład konfiguruje fabrykę AddRequestHeader , która używa zmiennej:

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

AddRequestHeadersIfNotPresent

Fabryka AddRequestHeadersIfNotPresent dodaje nagłówki, jeśli nie są obecne w oryginalnym żądaniu.

Ta fabryka akceptuje następujący parametr konfiguracji:

headers: Rozdzielona przecinkami lista par klucz-wartość (nazwa nagłówka, wartość nagłówka).

Poniższy przykład umożliwia skonfigurowanie AddRequestHeadersIfNotPresent fabryki:

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

AddRequestParameter

Fabryka AddRequestParameter dodaje parametr do ciągu zapytania żądania podrzędnego dla wszystkich pasujących żądań.

Ta fabryka akceptuje następujące parametry konfiguracji:

name
value

Poniższy przykład umożliwia skonfigurowanie AddRequestParameter fabryki, która dodaje red=blue parametr do ciągu zapytania żądania podrzędnego dla wszystkich pasujących żądań:

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

Fabryka AddRequestParameter ma dostęp do zmiennych identyfikatora URI używanych do dopasowania ścieżki lub hosta. Zmienne identyfikatora URI można używać w wartości, a zmienne są rozszerzane w czasie wykonywania.

Poniższy przykład konfiguruje fabrykę AddRequestParameter , która używa zmiennej:

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

AddResponseHeader

Fabryka AddResponseHeader dodaje nagłówek do nagłówków odpowiedzi podrzędnej dla wszystkich pasujących żądań.

Ta fabryka akceptuje następujące parametry konfiguracji:

name
value

Poniższy przykład konfiguruje fabrykę AddResponseHeaderX-Response-Red:Blue , która dodaje nagłówek do nagłówków odpowiedzi podrzędnej dla wszystkich pasujących żądań:

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

Fabryka AddResponseHeader ma dostęp do zmiennych identyfikatora URI używanych do dopasowania ścieżki lub hosta. Zmienne identyfikatora URI można używać w wartości, a zmienne są rozszerzane w czasie wykonywania.

Poniższy przykład konfiguruje fabrykę AddResponseHeader , która używa zmiennej:

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

Wyłącznik obwodowy

Fabryka CircuitBreaker opakowuje trasy w wyłączniku.

Ta fabryka akceptuje następujące parametry konfiguracji:

name: nazwa wyłącznika.
fallbackUri: identyfikator URI przekierowania, który może być trasą lokalną lub zewnętrzną procedurą obsługi.
status codes (opcjonalnie): rozdzielona dwukropkami lista kodów stanu, które mają być zgodne, w formacie liczbowym lub tekstowym.
failure rate (opcjonalnie): Próg powyżej którego zostanie otwarty wyłącznik. Wartość domyślna to 50%.
duration (opcjonalnie): czas oczekiwania przed ponownym zamknięciem. Wartość domyślna to 60 sekund.

Poniższy przykład umożliwia skonfigurowanie fabryki CircuitBreaker :

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

DeDupeResponseHeader

Fabryka DeDupeResponseHeader usuwa zduplikowane wartości nagłówków odpowiedzi.

Ta fabryka akceptuje następujące parametry konfiguracji:

name: rozdzielona spacjami lista nazw nagłówków.
strategy (opcjonalnie): akceptowane wartości to RETAIN_FIRST, RETAIN_LASTi RETAIN_UNIQUE. Domyślna wartość to RETAIN_FIRST.

W poniższym przykładzie skonfigurowana DeDupeResponseHeader jest fabryka, która usuwa zduplikowane wartości nagłówków Access-Control-Allow-Credentials i Access-Control-Allow-Origin odpowiedzi, gdy obie wartości są dodawane przez logikę CORS bramy i logikę podrzędną:

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

FallbackHeaders

Fabryka FallbackHeaders dodaje do nagłówka wyjątek wyłącznika. Ten filtr wymaga użycia filtru CircuitBreaker w innej trasie.

Brak parametrów dla tej fabryki.

Poniższy przykład konfiguruje fabrykę z typem FallbackHeaders wyjątku, komunikatem i (jeśli jest dostępny) głównym typem wyjątku i komunikatem, który FallbackHeaders filtr dodaje do żądania:

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

Nazwy nagłówków w konfiguracji można zastąpić, ustawiając wartości następujących parametrów (wymienionych przy użyciu ich wartości domyślnych):

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

JSONToGRPC

Fabryka JSONToGRPCFilter konwertuje ładunek JSON na żądanie gRPC.

Ta fabryka akceptuje następujący parametr konfiguracji:

protoDescriptor: plik deskryptora proto.

Możesz wygenerować ten plik przy użyciu polecenia protoc i określić flagę --descriptor_set_out , jak pokazano w poniższym przykładzie:

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

Uwaga

Parametr streaming nie jest obsługiwany.

Poniższy przykład umożliwia skonfigurowanie JSONToGRPCFilter fabryki przy użyciu danych wyjściowych z protocpliku :

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

LocalResponseCache

Fabryka LocalResponseCache zastępuje konfigurację lokalnej pamięci podręcznej odpowiedzi dla określonych tras po aktywowaniu globalnej pamięci podręcznej.

Ta fabryka akceptuje następujące parametry konfiguracji:

size: maksymalny dozwolony rozmiar wpisów pamięci podręcznej dla tej trasy przed rozpoczęciem eksmisji pamięci podręcznej (w KB, MB i GB).
timeToLive: dozwolona żywotność wpisu pamięci podręcznej przed wygaśnięciem. Użyj sufiksu s czasu trwania dla sekund, m minut lub h godzin.

Poniższy przykład umożliwia skonfigurowanie fabryki LocalResponseCache :

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

MapRequestHeader

Fabryka MapRequestHeader dodaje nagłówek do żądania podrzędnego ze zaktualizowanymi wartościami z nagłówka przychodzącego żądania HTTP.

Ta fabryka akceptuje następujące parametry konfiguracji:

fromHeader
toHeader

Ta fabryka tworzy nowy nazwany nagłówek (toHeader), a wartość jest wyodrębniona z istniejącego nazwanego nagłówka (fromHeader) z przychodzącego żądania HTTP. Jeśli nagłówek wejściowy nie istnieje, filtr nie ma efektu. Jeśli nowy nazwany nagłówek już istnieje, jego wartości zostaną rozszerzone o nowe wartości.

Poniższy przykład umożliwia skonfigurowanie MapRequestHeader fabryki, która dodaje X-Request-Red:<values> nagłówek do żądania podrzędnego ze zaktualizowanymi wartościami z nagłówka Blue przychodzącego żądania HTTP:

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

PrefiksPath

Fabryka PrefixPath dodaje prefiks do ścieżki wszystkich żądań.

Ta fabryka akceptuje następujący parametr konfiguracji:

prefix

W poniższym przykładzie skonfigurowano fabrykę PrefixPath , która dodaje prefiks do ścieżki /api wszystkich żądań, tak aby żądanie zostało /catalog wysłane do elementu /api/catalog:

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

PreserveHostHeader

Fabryka PreserveHostHeader ustawia atrybut żądania, który filtr routingu sprawdza w celu określenia, czy wysłać oryginalny nagłówek hosta, czy nagłówek hosta określony przez klienta HTTP.

Brak parametrów dla tej fabryki.

Poniższy przykład umożliwia skonfigurowanie fabryki PreserveHostHeader :

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

RedirectTo

Fabryka RedirectTo dodaje przekierowanie do oryginalnego adresu URL.

Ta fabryka akceptuje następujące parametry konfiguracji:

status: Kod HTTP przekierowania serii 300, taki jak 301.
url: wartość nagłówka Location . Musi być prawidłowym identyfikatorem URI. W przypadku przekierowań względnych należy użyć uri: no://op jako identyfikatora URI definicji trasy.

Poniższy przykład umożliwia skonfigurowanie RedirectTo fabryki, która wysyła stan 302 z nagłówkiem Location:https://acme.org w celu wykonania przekierowania:

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

RemoveJsonAttributesResponseBody

Fabryka RemoveJsonAttributesResponseBody usuwa atrybuty JSON i ich wartości z treści odpowiedzi JSON.

Ta fabryka akceptuje następujące parametry konfiguracji:

attribute names: rozdzielona przecinkami lista nazw atrybutów do usunięcia z odpowiedzi JSON.
delete recursively (opcjonalnie, wartość logiczna): konfiguracja, która usuwa atrybuty tylko na poziomie głównym (false) lub rekursywnie (true). Domyślna wartość to false.

Poniższy przykład umożliwia skonfigurowanie fabryki RemoveJsonAttributesResponseBody :

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

RemoveRequestHeader

Fabryka RemoveRequestHeader usuwa nagłówek z żądania podrzędnego.

Ta fabryka akceptuje następujący parametr konfiguracji:

name: nazwa nagłówka, który ma zostać usunięty.

Poniższa lista konfiguruje X-Request-Foo fabrykęRemoveRequestHeader, która usuwa nagłówek przed wysłaniem go podrzędnego:

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

RemoveRequestParameter

Fabryka RemoveRequestParameter usuwa parametr, zanim zostanie wysłany podrzędny.

Ta fabryka akceptuje następujący parametr konfiguracji:

name: nazwa parametru zapytania, który ma zostać usunięty.

W poniższym przykładzie skonfigurowano fabrykę RemoveRequestParameter , która usuwa red parametr przed wysłaniem go podrzędnego:

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

RemoveResponseHeader

Fabryka RemoveResponseHeader usuwa nagłówek z odpowiedzi, zanim zostanie zwrócony do klienta bramy.

Ta fabryka akceptuje następujący parametr konfiguracji:

name: nazwa nagłówka, który ma zostać usunięty.

Poniższa lista konfiguruje X-Response-Foo fabrykęRemoveResponseHeader, która usuwa nagłówek z odpowiedzi przed zwróceniem go do klienta bramy:

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

RequestHeaderSize

Fabryka RequestHeaderSize określa rozmiar nagłówka żądania.

Ta fabryka akceptuje następujące parametry konfiguracji:

maxSize: maksymalny rozmiar danych dozwolony przez nagłówek żądania, w tym klucz i wartość.
errorHeaderName: nazwa nagłówka odpowiedzi zawierającego komunikat o błędzie. Domyślnie nazwa nagłówka odpowiedzi to errorMessage.

Poniższa lista konfiguruje fabrykę RequestHeaderSize , która wysyła stan 431 , jeśli rozmiar nagłówka żądania jest większy niż 1000 bajtów:

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

Ponowne zapisywanieLocationResponseHeader

Fabryka RewriteLocationResponseHeader modyfikuje wartość nagłówka Location odpowiedzi, zwykle w celu pozbycia się szczegółów specyficznych dla zaplecza.

Ta fabryka akceptuje następujące parametry konfiguracji:

stripVersionMode: Ten parametr ma następujące możliwe wartości: NEVER_STRIP, AS_IN_REQUESTi ALWAYS_STRIP. Domyślna wartość to AS_IN_REQUEST.
- NEVER_STRIP: Wersja nie jest usuwana, nawet jeśli oryginalna ścieżka żądania nie zawiera żadnej wersji.
- AS_IN_REQUEST: Wersja jest usuwana tylko wtedy, gdy oryginalna ścieżka żądania nie zawiera wersji.
- ALWAYS_STRIP: Wersja jest zawsze usuwana, nawet jeśli oryginalna ścieżka żądania zawiera wersję.
hostValue: Ten parametr służy do zastępowania host:port części nagłówka odpowiedzi Location , gdy jest podana. Jeśli nie zostanie podana, zostanie użyta wartość nagłówka Host żądania.
protocolsRegex: prawidłowy regex String, względem którego jest zgodna nazwa protokołu. Jeśli nie jest ona zgodna, filtr nie działa. Domyślna wartość to http|https|ftp|ftps.
locationHeaderName

Poniższa lista konfiguruje fabrykę RewriteLocationResponseHeader :

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

W tym przykładzie dla wartości POSTapi.example.com/some/object/nameLocation żądania wartość , wartość nagłówka object-service.prod.example.net/v2/some/object/id odpowiedzi jest zastępowana jako .api.example.com/some/object/id

Ponowne zapisywanie ścieżki

Fabryka RewritePath używa wyrażeń regularnych Języka Java do elastycznego sposobu ponownego zapisywania ścieżki żądania.

Ta fabryka akceptuje następujące parametry konfiguracji:

regexp
replacement

Poniższa lista konfiguruje fabrykę RewritePath :

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

W tym przykładzie dla ścieżki żądania parametru /red/blueta konfiguracja ustawia ścieżkę do /blue przed wykonaniem żądania podrzędnego.

Ponowne zapisywanieResponseHeader

Fabryka RewriteResponseHeader używa wyrażeń regularnych Języka Java do elastycznego sposobu ponownego zapisywania wartości nagłówka odpowiedzi.

Ta fabryka akceptuje następujące parametry konfiguracji:

name
regexp
replacement

Poniższy przykład umożliwia skonfigurowanie fabryki RewriteResponseHeader :

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

W tym przykładzie dla wartości nagłówka /42?user=ford&password=omg!what&flag=trueparametru konfiguracja jest ustawiona na /42?user=ford&password=***&flag=true wartość po wykonaniu żądania podrzędnego.

SetPath

Fabryka SetPath oferuje prosty sposób manipulowania ścieżką żądania, umożliwiając szablonowe segmenty ścieżki. Ten filtr używa szablonów identyfikatorów URI z platformy Spring Framework i zezwala na wiele pasujących segmentów.

Ta fabryka akceptuje następujący parametr konfiguracji:

template

Poniższy przykład umożliwia skonfigurowanie fabryki SetPath :

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

W tym przykładzie dla ścieżki żądania parametru /red/blueta konfiguracja ustawia ścieżkę do /blue przed wykonaniem żądania podrzędnego.

SetRequestHeader

Fabryka SetRequestHeader zastępuje (zamiast dodawać) wszystkie nagłówki o podanej nazwie.

Ta fabryka akceptuje następujące parametry konfiguracji:

name
value

Poniższa lista konfiguruje fabrykę SetRequestHeader :

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

W tym przykładzie serwer podrzędny X-Request-Red:1234odpowiedział na element i został zastąpiony elementem X-Request-Red:Blue.

Fabryka SetRequestHeader ma dostęp do zmiennych identyfikatora URI używanych do dopasowania ścieżki lub hosta. Zmienne identyfikatora URI można używać w wartości, a zmienne są rozszerzane w czasie wykonywania.

Poniższy przykład konfiguruje fabrykę SetRequestHeader , która używa zmiennej:

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

SetResponseHeader

Fabryka SetResponseHeader zastępuje (zamiast dodawać) wszystkie nagłówki o podanej nazwie.

Ta fabryka akceptuje następujące parametry konfiguracji:

name
value

Poniższa lista konfiguruje fabrykę SetResponseHeader :

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

W tym przykładzie serwer podrzędny X-Response-Red:1234odpowiedział na element i został zastąpiony elementem X-Response-Red:Blue.

Fabryka SetResponseHeader ma dostęp do zmiennych identyfikatora URI używanych do dopasowania ścieżki lub hosta. Zmienne identyfikatora URI można używać w wartości, a zmienne są rozszerzane w czasie wykonywania.

Poniższy przykład konfiguruje fabrykę SetResponseHeader , która używa zmiennej:

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

SetStatus

Fabryka SetStatus konfiguruje stan odpowiedzi żądania serwera.

Ta fabryka akceptuje następujący parametr konfiguracji:

status: prawidłowa wartość spring HttpStatus , która może być wartością całkowitą, taką jak 404, lub reprezentacją ciągu wyliczenia, taką jak NOT_FOUND.

Poniższa lista konfiguruje fabrykę SetStatus :

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

StripPrefix

Fabryka StripPrefix usuwa prefiks z żądania przed wysłaniem go podrzędnego.

Ta fabryka akceptuje następujący parametr konfiguracji:

parts: liczba części w ścieżce do usuwania z żądania przed wysłaniem go podrzędnego. Domyślna wartość wynosi 1.

Poniższy przykład umożliwia skonfigurowanie fabryki StripPrefix :

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

W tym przykładzie żądanie jest wykonywane za pośrednictwem bramy do /name/blue/red. Żądanie, które zostanie wykonane, nameservice jest wyświetlane jako nameservice/red.

Ponów próbę

Fabryka Retry określa liczbę ponownych prób.

Ta fabryka akceptuje następujące parametry konfiguracji:

retries: liczba ponownych prób, które należy podjąć.
statuses: kody stanu HTTP, które powinny zostać ponowione, reprezentowane za pomocą polecenia org.springframework.http.HttpStatus.
methods: Metody HTTP, które należy ponowić, reprezentowane za pomocą polecenia org.springframework.http.HttpMethod.
series: serię kodów stanu, które mają zostać ponowione, reprezentowane za pomocą polecenia org.springframework.http.HttpStatus.Series.
exceptions: lista zgłaszanych wyjątków, które powinny zostać ponowione.
backoff: Skonfigurowane wycofywanie wykładnicze dla ponownych prób. Ponowne próby są wykonywane po interwale wycofywania firstBackoff * (factor ^ n)elementu , gdzie n jest iteracją. Jeśli maxBackoff skonfigurowano, maksymalna liczba zastosowanych operacji wycofywania jest ograniczona do maxBackoff. Jeśli basedOnPreviousValue wartość ma wartość true, backoff parametr jest obliczany przy użyciu polecenia prevBackoff * factor.

Następujące wartości domyślne są konfigurowane dla filtru po włączeniu Retry :

retries: trzy razy.
series: seria 5XX.
methods: METODA GET.
exceptions: IOException i TimeoutException.
backoff:Wyłączone.

Poniższy przykład umożliwia skonfigurowanie fabryki Retry :

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

RequestSize

Fabryka RequestSize może ograniczyć żądanie dotarcia do usługi podrzędnej, gdy rozmiar żądania jest większy niż dopuszczalny limit.

Ta fabryka akceptuje następujący parametr konfiguracji:

maxSizeDataSize: typ, w którym wartości są definiowane jako liczba, po której następuje opcjonalny DataUnit sufiks, taki jak KB lub MB. Wartość sufiksu domyślnego dotyczy B bajtów. Jest to dopuszczalny limit rozmiaru żądania zdefiniowanego w bajtach.

Poniższy przykład umożliwia skonfigurowanie fabryki RequestSize :

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

W tym przykładzie, gdy żądanie zostanie odrzucone z powodu rozmiaru, RequestSize fabryka ustawia stan odpowiedzi na 413 Payload Too Large przy użyciu innego nagłówka errorMessage.

W poniższym przykładzie przedstawiono element errorMessage:

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

TokenRelay

Fabryka TokenRelay przekazuje OAuth2 token dostępu do zasobów podrzędnych. Ten filtr jest skonfigurowany jako boolean wartość w definicji trasy, a nie jawny filtr.

Poniższy przykład umożliwia skonfigurowanie fabryki TokenRelay :

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

Korzystanie z filtrów komercyjnych

Usługa Spring Cloud Gateway dla platformy Kubernetes udostępnia również wiele fabryk niestandardowych GatewayFilter . W poniższych sekcjach opisano te fabryki.

AllowedRequestCookieCount

Fabryka AllowedRequestCookieCount określa, czy zgodne żądanie może być kontynuowane na podstawie liczby plików cookie.

Ta fabryka akceptuje następujący parametr konfiguracji:

amount: liczba dozwolonych plików cookie.

Poniższy przykład umożliwia skonfigurowanie fabryki AllowedRequestCookieCount :

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

AllowedRequestHeadersCount

Fabryka AllowedRequestHeadersCount określa, czy zgodne żądanie może kontynuować na podstawie liczby nagłówków.

Ta fabryka akceptuje następujący parametr konfiguracji:

amount: liczba dozwolonych nagłówków.

Poniższy przykład umożliwia skonfigurowanie fabryki AllowedRequestHeadersCount :

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

AllowedRequestQueryParamsCount

Fabryka AllowedRequestQueryParamsCount określa, czy zgodne żądanie może być kontynuowane na podstawie parametrów zapytania liczbowego.

Ta fabryka akceptuje następujący parametr konfiguracji:

amount: liczba dozwolonych parametrów.

Poniższy przykład umożliwia skonfigurowanie fabryki AllowedRequestQueryParamsCount :

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

Uwierzytelnianie podstawowe

Fabryka BasicAuth dodaje BasicAuthAuthorization nagłówek do żądań.

Brak parametrów dla tej fabryki.

Poniższy przykład umożliwia skonfigurowanie fabryki BasicAuth :

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

ClaimHeader

Fabryka ClaimHeader kopiuje dane z oświadczenia JWT do nagłówka HTTP.

Ta fabryka akceptuje następujące parametry konfiguracji:

Claim name: nazwa wrażliwa na wielkość liter oświadczenia do przekazania.
Header name: nazwa nagłówka HTTP.

Poniższy przykład umożliwia skonfigurowanie fabryki ClaimHeader :

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

ClientCertificateHeader

Fabryka ClientCertificateHeader weryfikuje certyfikat nagłówka X-Forwarded-Client-Cert .

Ta fabryka akceptuje następujące parametry konfiguracji:

domain pattern: Wartość zgodna X-Forwarded-Client-Cert z możliwością rozpoznawania urzędu certyfikacji certyfikatu klienta przez platformę Kubernetes.
certificate fingerprint(opcjonalnie): odcisk palca certyfikatu TLS/SSL.

Poniższy przykład umożliwia skonfigurowanie fabryki ClientCertificateHeader :

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

Cors

Fabryka Cors aktywuje weryfikacje mechanizmu CORS na trasie.

Ta fabryka akceptuje następujące parametry konfiguracji uporządkowane jako pary klucz-wartość dla opcji CORS:

allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns

Poniższy przykład umożliwia skonfigurowanie fabryki Cors :

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

JsonToXml

Fabryka JsonToXml przekształca treść odpowiedzi JSON w treść odpowiedzi XML.

Ta fabryka akceptuje następujący parametr konfiguracji:

wrapper: nazwa tagu głównego odpowiedzi XML, jeśli do wygenerowania prawidłowego kodu XML jest wymagany inny tag główny. Domyślna wartość to response.

Poniższy przykład umożliwia skonfigurowanie fabryki JsonToXml :

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

RateLimit

Fabryka RateLimit określa, czy zgodne żądanie może być kontynuowane na podstawie woluminu żądania.

Ta fabryka akceptuje następujące parametry konfiguracji:

request limit: maksymalna liczba żądań akceptowanych w oknie.
window duration: czas trwania okna w milisekundach. Alternatywnie możesz użyć sm sufiksów lub h , aby określić czas trwania w sekundach, minutach lub godzinach.
partition source (opcjonalnie): lokalizacja klucza partycji (claim, headerlub IPs).
partition key (opcjonalnie): wartość używana do partycjonowania liczników żądań.

Poniższy przykład umożliwia skonfigurowanie fabryki RateLimit :

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

W poniższych przykładach przedstawiono inne RateLimit konfiguracje:

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

Fabryka RestrictRequestHeaders określa, czy zgodne żądanie może być kontynuowane na podstawie nagłówków.

Jeśli istnieją nagłówki HTTP, które nie znajdują się w konfiguracji bez uwzględniania headerList wielkości liter, odpowiedź 431 Forbidden error jest zwracana do klienta.

Ta fabryka akceptuje następujący parametr konfiguracji:

headerList: bez uwzględniania wielkości liter lista nazw dozwolonych nagłówków.

Poniższy przykład umożliwia skonfigurowanie fabryki RestrictRequestHeaders :

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

RewriteAllResponseHeaders

Fabryka RewriteAllResponseHeaders ponownie zapisuje wiele nagłówków odpowiedzi jednocześnie.

Ta fabryka akceptuje następujące parametry konfiguracji:

pattern to match: wyrażenie regularne zgodne z wartościami nagłówka.
replacement: wartość zastępcza.

Poniższy przykład umożliwia skonfigurowanie fabryki RewriteAllResponseHeaders :

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

RewriteResponseBody

Fabryka RewriteResponseBody modyfikuje treść odpowiedzi.

Ta fabryka akceptuje następujące parametry konfiguracji uporządkowane jako rozdzielona przecinkami lista par klucz-wartość, gdzie każda para akceptuje formularz pattern to match:replacement:

pattern to match: wyrażenie regularne pasujące do tekstu w treści odpowiedzi.
replacement: wartość zastępcza.

Poniższy przykład umożliwia skonfigurowanie fabryki RewriteResponseBody :

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

RewriteJsonAttributesResponseBody

Fabryka RewriteJsonAttributesResponseBody ponownie zapisuje atrybuty JSON przy użyciu JSONPath notacji.

Ta fabryka akceptuje następujące parametry konfiguracji uporządkowane jako rozdzielona przecinkami lista par klucz-wartość, gdzie każda para akceptuje formularz jsonpath:replacement:

jsonpathJSONPath: wyrażenie, które ma być zgodne z treścią odpowiedzi.
replacement: wartość zastępcza.

Poniższy przykład umożliwia skonfigurowanie fabryki RewriteJsonAttributesResponseBody :

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

Role

Fabryka Roles autoryzuje żądania zawierające jedną ze skonfigurowanych ról.

Ta fabryka akceptuje następujący parametr konfiguracji:

roles: rozdzielona przecinkami lista autoryzowanych ról.

Poniższy przykład umożliwia skonfigurowanie fabryki Roles :

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

Zakresy

Fabryka Scopes autoryzuje żądania zawierające jeden ze skonfigurowanych OAuth zakresów.

Ta fabryka akceptuje następujący parametr konfiguracji:

scopes: rozdzielona przecinkami lista autoryzowanych OAuth zakresów.

Poniższy przykład umożliwia skonfigurowanie fabryki Scopes :

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

StoreIpAddress

Fabryka StoreIPAddress jest używana tylko do tworzenia rozszerzeń i w kontekście aplikacji.

Ta fabryka akceptuje następujący parametr konfiguracji:

attribute name: nazwa używana do przechowywania adresu IP jako atrybutu wymiany.

Poniższy przykład umożliwia skonfigurowanie fabryki StoreIPAddress :

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

Fabryka SSO login przekierowuje do uwierzytelniania, jeśli nie ma prawidłowego tokenu autoryzacji. Ta fabryka jest skonfigurowana jako boolean wartość w definicji trasy, a nie jawny filtr.

Poniższy przykład umożliwia skonfigurowanie fabryki SSO login :

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

StoreHeader

Fabryka StoreHeader przechowuje wartość nagłówka w kontekście aplikacji. Ten filtr jest używany tylko do programowania rozszerzeń.

Ta fabryka akceptuje następujące parametry konfiguracji:

headers: lista nagłówków do sprawdzenia. Pierwszy znaleziony jest używany.
attribute name: nazwa używana do przechowywania wartości nagłówka jako atrybutu wymiany.

Poniższy przykład umożliwia skonfigurowanie fabryki StoreHeader :

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

XmlToJson

Fabryka XmlToJson przekształca treść odpowiedzi XML w treść odpowiedzi JSON.

Brak parametrów dla tej fabryki.

Poniższy przykład umożliwia skonfigurowanie fabryki XmlToJson :

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

Share via

Jak używać filtrów tras usługi VMware Spring Cloud Gateway z planem Usługi Azure Spring Apps Enterprise

Wymagania wstępne

Używanie filtrów

Korzystanie z filtrów typu open source

AddRequestHeader

AddRequestHeadersIfNotPresent

AddRequestParameter

AddResponseHeader

Wyłącznik obwodowy

DeDupeResponseHeader

FallbackHeaders

JSONToGRPC

LocalResponseCache

MapRequestHeader

PrefiksPath

PreserveHostHeader

RedirectTo

RemoveJsonAttributesResponseBody

RemoveRequestHeader

RemoveRequestParameter

RemoveResponseHeader

RequestHeaderSize

Ponowne zapisywanieLocationResponseHeader

Ponowne zapisywanie ścieżki

Ponowne zapisywanieResponseHeader

SetPath

SetRequestHeader

SetResponseHeader

SetStatus

StripPrefix

Ponów próbę

RequestSize

TokenRelay

Korzystanie z filtrów komercyjnych

AllowedRequestCookieCount

AllowedRequestHeadersCount

AllowedRequestQueryParamsCount

Uwierzytelnianie podstawowe

ClaimHeader

ClientCertificateHeader

Cors

JsonToXml

RateLimit

RestrictRequestHeaders

RewriteAllResponseHeaders

RewriteResponseBody

RewriteJsonAttributesResponseBody

Role

Zakresy

StoreIpAddress

Logowanie jednokrotne

StoreHeader

XmlToJson

Następne kroki

Dodatkowe zasoby