Transformace požadavků a odpovědí YARP

Článek
2025-04-08

Úvod

Při proxyování požadavku je běžné upravit části požadavku nebo odpověď tak, aby se přizpůsobily požadavkům cílového serveru, nebo aby zahrnoval tok dalších dat, například původní IP adresu klienta. Tento proces se implementuje prostřednictvím transformací. Typy transformací jsou definovány globálně pro aplikaci a jednotlivé trasy poskytují parametry pro povolení a konfiguraci těchto transformací. Původní objekty požadavku nejsou těmito transformacemi změněny, pouze požadavky proxy serveru.

Technologie YARP neposkytuje transformace textu požadavku a odpovědi, ale můžete k tomu napsat middleware.

Výchozí nastavení

Pro všechny trasy jsou ve výchozím nastavení povoleny následující transformace. Můžete je nakonfigurovat nebo zakázat, jak je znázorněno dále v tomto dokumentu.

Host – Potlačí hlavičku "Host" příchozího požadavku. Požadavek proxy serveru se ve výchozím nastavení nastaví na název hostitele zadaný v adrese cílového serveru. Viz RequestHeaderOriginalHost níže.
X-Forwarded-For – Nastaví hlavičku X-Forwarded-For na IP adresu klienta. Viz X-Forwarded níže.
X-Forwarded-Proto – Nastaví původní schéma požadavku (http/https) do hlavičky X-Forwarded-Proto. Viz X-Forwarded níže.
X-Forwarded-Host – Nastaví původního hostitele požadavku v hlavičce X-Forwarded-Host. Viz X-Forwarded níže.
X-Forwarded-Prefix – nastaví požadavek tak, že původní PathBase (pokud existuje) se stanoví na hlavičku X-Forwarded-Prefix. Viz X-Forwarded níže.

Například následující příchozí požadavek na http://IncomingHost:5000/path:

GET /path HTTP/1.1
Host: IncomingHost:5000
Accept: */*
header1: foo

pomocí těchto výchozích hodnot by se transformovaly a proxiovaly na cílový server https://DestinationHost:6000/ následujícím způsobem:

GET /path HTTP/1.1
Host: DestinationHost:6000
Accept: */*
header1: foo
X-Forwarded-For: 5.5.5.5
X-Forwarded-Proto: http
X-Forwarded-Host: IncomingHost:5000

Přeměnit kategorie

Transformace spadají do několika kategorií: Žádost, Odpověď a Dodatečné informace v odpovědi. HTTP trailery nejsou podporovány, protože nejsou podporovány podkladovým klientem HttpClient.

Pokud předdefinovaná sada transformací není dostatečná, je možné vlastní transformace přidat prostřednictvím rozšiřitelnosti.

Přidání transformací

Transformace je možné přidat do tras prostřednictvím konfigurace nebo prostřednictvím kódu programu.

Z nastavení konfigurace

Transformace je možné nakonfigurovat v souboru RouteConfig.Transforms a mohou být vázány z Routes oddílů konfiguračního souboru. Můžete je upravit a znovu načíst bez restartování proxy serveru. Transformace se konfiguruje pomocí jedné nebo více párů řetězců klíč-hodnota.

Tady je příklad běžných transformací:

{
  "ReverseProxy": {
    "Routes": {
      "route1" : {
        "ClusterId": "cluster1",
        "Match": {
          "Hosts": [ "localhost" ]
        },
        "Transforms": [
          { "PathPrefix": "/apis" },
          {
            "RequestHeader": "header1",
            "Append": "bar"
          },
          {
            "ResponseHeader": "header2",
            "Append": "bar",
            "When": "Always"
          },
          { "ClientCert": "X-Client-Cert" },
          { "RequestHeadersCopy": "true" },
          { "RequestHeaderOriginalHost": "true" },
          {
            "X-Forwarded": "Append",
            "HeaderPrefix": "X-Forwarded-"
          }
        ]
      },
      "route2" : {
        "ClusterId": "cluster1",
        "Match": {
          "Path": "/api/{plugin}/stuff/{**remainder}"
        },
        "Transforms": [
          { "PathPattern": "/foo/{plugin}/bar/{**remainder}" },
          {
            "QueryValueParameter": "q",
            "Append": "plugin"
          }
        ]
      }
    },
    "Clusters": {
      "cluster1": {
        "Destinations": {
          "cluster1/destination1": {
            "Address": "https://localhost:10001/Path/Base"
          }
        }
      }
    }
  }
}

Všechny položky konfigurace se považují za nerozlišující velká a malá písmena, i když cílový server může s výslednými hodnotami zacházet jako s citlivými na velikost písmen nebo necitlivými, například v případě cesty.

Podrobnosti o těchto transformacích jsou popsány dále v tomto dokumentu.

Vývojáři, kteří chtějí integrovat vlastní transformace s Transforms částí konfigurace, to můžou udělat pomocí ITransformFactory následujícího popisu.

Z kódu

Transformace lze do tras přidat programově voláním Metody AddTransforms .

AddTransforms lze volat po AddReverseProxy pro poskytnutí zpětného volání pro konfiguraci transformací. Toto zpětné volání se vyvolá pokaždé, když se trasa sestaví nebo znovu sestaví a umožní vývojáři zkontrolovat informace RouteConfig a podmíněně přidat transformace.

Zpětné AddTransforms volání poskytuje TransformBuilderContext , kde lze přidat nebo nakonfigurovat transformace. Většina transformací poskytuje TransformBuilderContext rozšiřující metody, které usnadňují jejich přidání. Toto jsou rozšíření zdokumentovaná níže s popisy jednotlivých transformací.

Zahrnuje také TransformBuilderContext pro přístup ke všem potřebným službám IServiceProvider.

services.AddReverseProxy()
    .LoadFromConfig(_configuration.GetSection("ReverseProxy"))
    .AddTransforms(builderContext =>
    {
        // Added to all routes.
        builderContext.AddPathPrefix("/prefix");

        // Conditionally add a transform for routes that require auth.
        if (!string.IsNullOrEmpty(builderContext.Route.AuthorizationPolicy))
        {
            builderContext.AddRequestTransform(async transformContext =>
            {
                transformContext.ProxyRequest.Headers.Add("CustomHeader", "CustomValue");
            });
        }
    });

Pokročilejší ovládací prvky najdete ITransformProvider níže.

Sdílet prostřednictvím