Praca ze starszymi serwerami proxy

Artykuł
02/28/2024

Ważne

Serwery proxy usługi Azure Functions to starsza funkcja dla wersji 1.x do 3.x środowiska uruchomieniowego usługi Azure Functions. Obsługę serwerów proxy można ponownie włączyć w wersji 4.x, aby pomyślnie uaktualnić aplikacje funkcji do najnowszej wersji środowiska uruchomieniowego. Jak najszybciej należy przełączyć się na integrację aplikacji funkcji z usługą Azure API Management. Usługa API Management umożliwia korzystanie z pełniejszego zestawu funkcji do definiowania i zabezpieczania interfejsów API opartych na usłudze Functions oraz zarządzania nimi i zarabiania na nich. Aby uzyskać więcej informacji, zobacz Integracja usługi API Management.

Aby dowiedzieć się, jak ponownie włączyć obsługę serwerów proxy w usłudze Functions w wersji 4.x, zobacz Ponowne włączanie serwerów proxy w usłudze Functions w wersji 4.x.

Aby ułatwić migrację z istniejących implementacji serwera proxy, ten artykuł zawiera linki do równoważnej zawartości usługi API Management, jeśli są dostępne.

W tym artykule opisano sposób konfigurowania i pracy z serwerami proxy usługi Azure Functions. Dzięki tej funkcji można określić punkty końcowe w aplikacji funkcji, które są implementowane przez inny zasób. Te serwery proxy umożliwiają podzielenie dużego interfejsu API na wiele aplikacji funkcji (jak w architekturze mikrousług), a jednocześnie prezentowanie pojedynczej powierzchni interfejsu API dla klientów.

Rozliczenia usługi Functions w warstwie Standardowa dotyczą wykonywania serwera proxy. Aby uzyskać więcej informacji, zobacz Cennik usługi Azure Functions.

Ponowne włączanie serwerów proxy w usłudze Functions w wersji 4.x

Po przeprowadzeniu migracji aplikacji funkcji do wersji 4.x środowiska uruchomieniowego usługi Functions konieczne będzie ponowne ponowne włączanie serwerów proxy. Nadal należy przełączyć się na integrację aplikacji funkcji z usługą Azure API Management tak szybko, jak to możliwe, a nie tylko na serwerach proxy.

Ponowne włączanie serwerów proxy wymaga ustawienia flagi w AzureWebJobsFeatureFlags ustawieniu aplikacji na jeden z następujących sposobów:

AzureWebJobsFeatureFlags Jeśli ustawienie jeszcze nie istnieje, dodaj to ustawienie do aplikacji funkcji z wartością EnableProxies.
Jeśli to ustawienie już istnieje, dodaj ,EnableProxies wartość na końcu istniejącej wartości.

AzureWebJobsFeatureFlags to rozdzielana przecinkami tablica flag używanych do włączania wersji zapoznawczej i innych funkcji tymczasowych. Aby dowiedzieć się więcej na temat tworzenia i modyfikowania ustawień aplikacji, zobacz Praca z ustawieniami aplikacji.

Uwaga

Nawet w przypadku ponownego włączenia flagi EnableProxies nie można pracować z serwerami proxy w witrynie Azure Portal. Zamiast tego należy pracować bezpośrednio z plikiem proxies.json dla aplikacji funkcji. Aby uzyskać więcej informacji, zobacz Konfiguracja zaawansowana.

Tworzenie serwera proxy

Ważne

Aby uzyskać równoważną zawartość przy użyciu usługi API Management, zobacz Uwidacznianie bezserwerowych interfejsów API z punktów końcowych HTTP przy użyciu usługi Azure API Management.

Serwery proxy są definiowane w pliku proxies.json w katalogu głównym aplikacji funkcji. W krokach w tej sekcji pokazano, jak utworzyć ten plik w aplikacji funkcji za pomocą witryny Azure Portal. Nie wszystkie języki i kombinacje systemu operacyjnego obsługują edycję w portalu. Jeśli nie możesz zmodyfikować plików aplikacji funkcji w portalu, możesz zamiast tego utworzyć i wdrożyć odpowiedni proxies.json plik z katalogu głównego lokalnego projektu. Aby dowiedzieć się więcej na temat obsługi edytowania portalu, zobacz Szczegóły obsługi języka.

Otwórz witrynę Azure Portal, a następnie przejdź do aplikacji funkcji.
W okienku po lewej stronie wybierz pozycję Serwery proxy , a następnie wybierz pozycję +Dodaj.
Podaj nazwę serwera proxy.
Skonfiguruj punkt końcowy uwidoczniony w tej aplikacji funkcji, określając szablon trasy i metody HTTP. Te parametry zachowują się zgodnie z regułami wyzwalaczy HTTP.
Ustaw adres URL zaplecza na inny punkt końcowy. Ten punkt końcowy może być funkcją w innej aplikacji funkcji lub może być dowolnym innym interfejsem API. Wartość nie musi być statyczna i może odwoływać się do ustawień aplikacji i parametrów z oryginalnego żądania klienta.
Wybierz pozycję Utwórz.

Serwer proxy istnieje teraz jako nowy punkt końcowy w aplikacji funkcji. Z perspektywy klienta jest ona taka sama jak funkcja HttpTrigger w usłudze Functions. Możesz wypróbować nowy serwer proxy, kopiując adres URL serwera proxy i testując go przy użyciu ulubionego klienta HTTP.

Modyfikowanie żądań i odpowiedzi

Ważne

Usługa API Management umożliwia zmianę zachowania interfejsu API za pomocą konfiguracji przy użyciu zasad. Zasady to zbiór instrukcji, które są uruchamiane sekwencyjnie na żądanie lub odpowiedź interfejsu API. Aby uzyskać więcej informacji na temat zasad usługi API Management, zobacz Zasady w usłudze Azure API Management.

Za pomocą serwerów proxy można modyfikować żądania do zaplecza i odpowiedzi. Te przekształcenia mogą używać zmiennych zdefiniowanych w temacie Używanie zmiennych.

Modyfikowanie żądania zaplecza

Domyślnie żądanie zaplecza jest inicjowane jako kopia oryginalnego żądania. Oprócz ustawiania adresu URL zaplecza można wprowadzać zmiany w metodzie HTTP, nagłówkach i parametrach ciągu zapytania. Zmodyfikowane wartości mogą odwoływać się do ustawień aplikacji i parametrów z oryginalnego żądania klienta.

Żądania zaplecza można modyfikować w portalu, rozwijając sekcję przesłaniania żądania na stronie szczegółów serwera proxy.

Modyfikowanie odpowiedzi

Domyślnie odpowiedź klienta jest inicjowana jako kopia odpowiedzi zaplecza. Możesz wprowadzić zmiany w kodzie stanu odpowiedzi, frazie przyczyny, nagłówkach i treści. Zmodyfikowane wartości mogą odwoływać się do ustawień aplikacji, parametrów z oryginalnego żądania klienta i parametrów z odpowiedzi zaplecza.

Odpowiedzi zaplecza można modyfikować w portalu, rozwijając sekcję zastępowania odpowiedzi na stronie szczegółów serwera proxy.

Używanie zmiennych

Konfiguracja serwera proxy nie musi być statyczna. Można użyć zmiennych z oryginalnego żądania klienta, odpowiedzi zaplecza lub ustawień aplikacji.

Odwołania do funkcji lokalnych

Możesz użyć localhost metody , aby odwoływać się do funkcji wewnątrz tej samej aplikacji funkcji bezpośrednio bez żądania serwera proxy w obie strony.

"backendUri": "https://localhost/api/httptriggerC#1" metoda odwołuje się do lokalnej funkcji wyzwalanej przez protokół HTTP na trasie /api/httptriggerC#1

Uwaga

Jeśli funkcja używa poziomów funkcji, administratora lub autoryzacji systemu , należy podać kod i identyfikator clientId zgodnie z oryginalnym adresem URL funkcji. W takim przypadku odwołanie będzie wyglądać następująco: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" zalecamy przechowywanie tych kluczy w ustawieniach aplikacji i odwoływanie się do nich w serwerach proxy. Pozwala to uniknąć przechowywania wpisów tajnych w kodzie źródłowym.

Parametry żądania odwołania

Parametry żądania można użyć jako danych wejściowych do właściwości adresu URL zaplecza lub w ramach modyfikowania żądań i odpowiedzi. Niektóre parametry można powiązać z szablonu trasy określonego w podstawowej konfiguracji serwera proxy, a inne mogą pochodzić z właściwości żądania przychodzącego.

Parametry szablonu trasy

Parametry używane w szablonie trasy są dostępne do przywołowania według nazwy. Nazwy parametrów są ujęte w nawiasy klamrowe ({}).

Jeśli na przykład serwer proxy ma szablon trasy, taki jak /pets/{petId}, adres URL zaplecza może zawierać wartość {petId}, jak w https://<AnotherApp>.azurewebsites.net/api/pets/{petId}pliku . Jeśli szablon trasy zakończy się symbolem wieloznacznymi, takim jak /api/{*restOfPath}, wartość {restOfPath} jest ciągiem reprezentującym pozostałe segmenty ścieżki z żądania przychodzącego.

Dodatkowe parametry żądania

Oprócz parametrów szablonu trasy w wartościach konfiguracji można użyć następujących wartości:

{request.method}: metoda HTTP używana w oryginalnym żądaniu.
{request.headers.<HeaderName>}: nagłówek, który można odczytać z oryginalnego żądania. Zastąp ciąg <HeaderName> nazwą nagłówka, który chcesz odczytać. Jeśli nagłówek nie jest uwzględniony w żądaniu, wartość będzie pustym ciągiem.
{request.querystring.<ParameterName>}: parametr ciągu zapytania, który można odczytać z oryginalnego żądania. Zastąp ciąg <ParameterName> nazwą parametru, który chcesz odczytać. Jeśli parametr nie jest uwzględniony w żądaniu, wartość będzie pustym ciągiem.

Odwołania do parametrów odpowiedzi zaplecza

Parametry odpowiedzi mogą być używane w ramach modyfikowania odpowiedzi na klienta. Następujące wartości mogą być używane w wartościach konfiguracji:

{backend.response.statusCode}: kod stanu HTTP zwrócony w odpowiedzi zaplecza.
{backend.response.statusReason}: fraza przyczyny HTTP zwrócona w odpowiedzi zaplecza.
{backend.response.headers.<HeaderName>}: nagłówek, który można odczytać z odpowiedzi zaplecza. Zastąp ciąg <HeaderName> nazwą nagłówka, który chcesz odczytać. Jeśli nagłówek nie jest uwzględniony w odpowiedzi, wartość będzie pustym ciągiem.

Odwołania do ustawień aplikacji

Możesz również odwoływać się do ustawień aplikacji zdefiniowanych dla aplikacji funkcji, otaczając nazwę ustawienia znakami procentu (%).

Na przykład adres URL zaplecza elementu https://%ORDER_PROCESSING_HOST%/api/orders "%ORDER_PROCESSING_HOST%" zostałby zastąpiony wartością ustawienia ORDER_PROCESSING_HOST.

Napiwek

Użyj ustawień aplikacji dla hostów zaplecza, gdy masz wiele wdrożeń lub środowisk testowych. Dzięki temu możesz mieć pewność, że zawsze rozmawiasz z odpowiednim zapleczem dla tego środowiska.

Rozwiązywanie problemów z serwerami proxy

Dodając flagę "debug":true do dowolnego serwera proxy w usłudze proxies.json, włączysz rejestrowanie debugowania. Dzienniki są przechowywane i D:\home\LogFiles\Application\Proxies\DetailedTrace dostępne za pośrednictwem zaawansowanych narzędzi (kudu). Wszystkie odpowiedzi HTTP będą również zawierać Proxy-Trace-Location nagłówek z adresem URL umożliwiającym dostęp do pliku dziennika.

Serwer proxy można debugować po stronie klienta, dodając Proxy-Trace-Enabled nagłówek ustawiony na true. Spowoduje to również zarejestrowanie śladu w systemie plików i zwrócenie adresu URL śledzenia jako nagłówka w odpowiedzi.

Blokuj ślady serwera proxy

Ze względów bezpieczeństwa możesz nie zezwalać każdemu, kto dzwoni do usługi w celu wygenerowania śladu. Nie będą oni mogli uzyskać dostępu do zawartości śledzenia bez poświadczeń logowania, ale generowanie śladu zużywa zasoby i uwidacznia używane serwery proxy funkcji.

Całkowicie wyłącz ślady, dodając "debug":false do dowolnego określonego serwera proxy w pliku proxies.json.

Konfiguracja zaawansowana

Konfigurowane serwery proxy są przechowywane w pliku proxies.json , który znajduje się w katalogu głównym katalogu aplikacji funkcji. Możesz ręcznie edytować ten plik i wdrożyć go w ramach aplikacji, gdy używasz dowolnej z metod wdrażania obsługiwanych przez usługę Functions.

Napiwek

Jeśli nie skonfigurowaliśmy jednej z metod wdrażania, możesz również pracować z plikiem proxies.json w portalu. Przejdź do aplikacji funkcji, wybierz pozycję Funkcje platformy, a następnie wybierz pozycję Edytor usługi App Service. Dzięki temu można wyświetlić całą strukturę plików aplikacji funkcji, a następnie wprowadzić zmiany.

Proxies.json jest definiowany przez obiekt serwerów proxy, który składa się z nazwanych serwerów proxy i ich definicji. Opcjonalnie, jeśli edytor go obsługuje, możesz odwołać się do schematu JSON na potrzeby uzupełniania kodu. Przykładowy plik może wyglądać następująco:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Każdy serwer proxy ma przyjazną nazwę, taką jak proxy1 w poprzednim przykładzie. Odpowiedni obiekt definicji serwera proxy jest definiowany przez następujące właściwości:

matchCondition: Wymagany obiekt definiujący żądania, które wyzwalają wykonywanie tego serwera proxy. Zawiera ona dwie właściwości, które są współużytkowane z wyzwalaczami HTTP:
- methods: tablica metod HTTP, na które odpowiada serwer proxy. Jeśli nie zostanie określony, serwer proxy odpowiada na wszystkie metody HTTP na trasie.
- route: Wymagane — definiuje szablon trasy, kontrolując adresy URL żądań, na które odpowiada serwer proxy. W przeciwieństwie do wyzwalaczy HTTP nie ma wartości domyślnej.
backendUri: adres URL zasobu zaplecza, do którego powinno być oparte żądanie. Ta wartość może odwoływać się do ustawień aplikacji i parametrów z oryginalnego żądania klienta. Jeśli ta właściwość nie jest dołączona, usługa Azure Functions odpowiada za pomocą protokołu HTTP 200 OK.
requestOverrides: obiekt definiujący przekształcenia żądania zaplecza. Zobacz Definiowanie obiektu requestOverrides.
responseOverrides: obiekt definiujący przekształcenia odpowiedzi klienta. Zobacz Definiowanie obiektu responseOverrides.

Uwaga

Właściwość route w serwerach proxy usługi Azure Functions nie obsługuje właściwości routePrefix konfiguracji hosta aplikacji funkcji. Jeśli chcesz uwzględnić prefiks, taki jak /api, musi zostać uwzględniony we właściwości route .

Wyłączanie poszczególnych serwerów proxy

Poszczególne serwery proxy można wyłączyć, dodając "disabled": true do serwera proxy w proxies.json pliku. Spowoduje to zwrócenie 404 żądań spełniających kryteria matchCondition.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Ustawienia aplikacji

Zachowanie serwera proxy może być kontrolowane przez kilka ustawień aplikacji. Wszystkie te opisano w dokumentacji ustawień aplikacji funkcji

Zastrzeżone znaki (formatowanie ciągu)

Serwery proxy odczytują wszystkie ciągi z pliku JSON przy użyciu znaku \ jako symbolu ucieczki. Serwery proxy interpretują również nawiasy klamrowe. Zobacz pełny zestaw przykładów poniżej.

Znak	Znak ucieczki	Przykład
{ lub }	{{ lub }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

Definiowanie obiektu requestOverrides

Obiekt requestOverrides definiuje zmiany wprowadzone w żądaniu po wywołaniu zasobu zaplecza. Obiekt jest definiowany przez następujące właściwości:

backend.request.method: metoda HTTP używana do wywoływania zaplecza.
backend.request.querystring.<ParameterName>: parametr ciągu zapytania, który można ustawić dla wywołania zaplecza. Zastąp ciąg <ParameterName> nazwą parametru, który chcesz ustawić. Jeśli zostanie podany pusty ciąg, parametr jest nadal dołączany do żądania zaplecza.
backend.request.headers.<HeaderName>: nagłówek, który można ustawić dla wywołania zaplecza. Zastąp ciąg <HeaderName> nazwą nagłówka, który chcesz ustawić. Jeśli zostanie podany pusty ciąg, parametr jest nadal dołączany do żądania zaplecza.

Wartości mogą odwoływać się do ustawień i parametrów aplikacji z oryginalnego żądania klienta.

Przykładowa konfiguracja może wyglądać następująco:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

Definiowanie obiektu responseOverrides

Obiekt requestOverrides definiuje zmiany wprowadzone w odpowiedzi przekazanej z powrotem do klienta. Obiekt jest definiowany przez następujące właściwości:

response.statusCode: kod stanu HTTP, który ma zostać zwrócony do klienta.
response.statusReason: fraza przyczyny HTTP, która ma zostać zwrócona do klienta.
response.body: ciąg reprezentujący treść, która ma zostać zwrócona do klienta.
response.headers.<HeaderName>: nagłówek, który można ustawić dla odpowiedzi na klienta. Zastąp ciąg <HeaderName> nazwą nagłówka, który chcesz ustawić. Jeśli podasz pusty ciąg, nagłówek nie zostanie uwzględniony w odpowiedzi.

Wartości mogą odwoływać się do ustawień aplikacji, parametrów z oryginalnego żądania klienta i parametrów z odpowiedzi zaplecza.

Przykładowa konfiguracja może wyglądać następująco:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

Uwaga

W tym przykładzie treść odpowiedzi jest ustawiana bezpośrednio, więc nie backendUri jest wymagana żadna właściwość. W przykładzie pokazano, jak można używać serwerów proxy usługi Azure Functions do pozorowania interfejsów API.

Udostępnij za pośrednictwem

Praca ze starszymi serwerami proxy

Ponowne włączanie serwerów proxy w usłudze Functions w wersji 4.x

Tworzenie serwera proxy

Modyfikowanie żądań i odpowiedzi

Modyfikowanie żądania zaplecza

Modyfikowanie odpowiedzi

Używanie zmiennych

Odwołania do funkcji lokalnych

Parametry żądania odwołania

Parametry szablonu trasy

Dodatkowe parametry żądania

Odwołania do parametrów odpowiedzi zaplecza

Odwołania do ustawień aplikacji

Rozwiązywanie problemów z serwerami proxy

Blokuj ślady serwera proxy

Konfiguracja zaawansowana

Wyłączanie poszczególnych serwerów proxy

Ustawienia aplikacji

Zastrzeżone znaki (formatowanie ciągu)

Definiowanie obiektu requestOverrides

Definiowanie obiektu responseOverrides

Opinia

Dodatkowe zasoby