Praca z serwerów proxy usługi Azure FunctionsWork with Azure Functions Proxies

W tym artykule wyjaśniono, jak skonfigurować i pracować z serwerów proxy usługi Azure Functions.This article explains how to configure and work with Azure Functions Proxies. Dzięki tej funkcji można określić punkty końcowe na aplikację funkcji, które są implementowane przez inny zasób.With this feature, you can specify endpoints on your function app that are implemented by another resource. Te serwery proxy można użyć do dzielenia dużych interfejsu API na wiele aplikacji funkcyjnych (tak jak w architekturze mikrousług), przy jednoczesnym prezentowaniu jednej powierzchni interfejsu API dla klientów.You can use these proxies to break a large API into multiple function apps (as in a microservice architecture), while still presenting a single API surface for clients.

Jest to informacje dla deweloperów usługi Azure Functions.This is reference information for Azure Functions developers. Jeśli jesteś nowym użytkownikiem usługi Azure Functions, należy uruchomić z następującymi zasobami:If you're new to Azure Functions, start with the following resources:

Uwaga

Standardowe funkcje rozliczeń mają zastosowanie do wykonania serwera proxy.Standard Functions billing applies to proxy executions. Aby uzyskać więcej informacji, zobacz cennika usługi Azure Functions.For more information, see Azure Functions pricing.

Tworzenie serwera proxyCreate a proxy

W tej sekcji dowiesz się, jak utworzyć serwer proxy w portalu usługi Functions.This section shows you how to create a proxy in the Functions portal.

  1. Otwórz Azure Portal, a następnie przejdź do aplikacji funkcji.Open the Azure portal, and then go to your function app.
  2. W okienku po lewej stronie wybierz nowego serwera proxy.In the left pane, select New proxy.
  3. Podaj nazwę serwera proxy.Provide a name for your proxy.
  4. Skonfiguruj punkt końcowy, który jest udostępniany w tej aplikacji funkcji, określając szablon trasy i metod HTTP.Configure the endpoint that's exposed on this function app by specifying the route template and HTTP methods. Parametry te zachowują się zgodnie z regułami dla wyzwalaczy HTTP.These parameters behave according to the rules for HTTP triggers.
  5. Ustaw URL wewnętrznej bazy danych do innego punktu końcowego.Set the backend URL to another endpoint. Ten punkt końcowy może być funkcją w innej aplikacji funkcji lub może być dowolnym interfejsem API.This endpoint could be a function in another function app, or it could be any other API. Wartość nie musi być statyczna i może się odwoływać do ustawienia aplikacji i Parametry z oryginalne żądanie klienta.The value does not need to be static, and it can reference application settings and parameters from the original client request.
  6. Kliknij pozycję Utwórz.Click Create.

Twój serwer proxy obecnie istnieje jako nowy punkt końcowy na aplikację funkcji.Your proxy now exists as a new endpoint on your function app. Z perspektywy klienta jest odpowiednikiem HttpTrigger w usłudze Azure Functions.From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. Twój nowy serwer proxy można wypróbować, kopiując adres URL serwera Proxy i testowanie go za pomocą swojego ulubionego klienta HTTP.You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.

Modyfikowanie żądań i odpowiedziModify requests and responses

Za pomocą usługi Azure Functions Proxies można modyfikować żądań i odpowiedzi z zapleczem.With Azure Functions Proxies, you can modify requests to and responses from the back-end. Te przekształcenia można używać zmiennych, zgodnie z definicją w Używanie zmiennych.These transformations can use variables as defined in Use variables.

Zmodyfikować żądanie zapleczaModify the back-end request

Domyślnie żądania zaplecza jest inicjowany jako kopię oryginalne żądanie.By default, the back-end request is initialized as a copy of the original request. Oprócz skonfigurowania adresu URL zaplecza, można wprowadzić zmiany do metody HTTP, nagłówki i parametry ciągu zapytania.In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. Zmodyfikowane wartości może odwoływać się ustawienia aplikacji i Parametry z oryginalne żądanie klienta.The modified values can reference application settings and parameters from the original client request.

Żądania zaplecza można modyfikować w portalu expading przesłonięcie żądania sekcji na stronie szczegółów serwera proxy.Back-end requests can be modified in the portal by expading the request override section of the proxy detail page.

Modyfikowanie odpowiedziModify the response

Domyślnie odpowiedź klienta jest inicjowany jako kopię odpowiedzi zaplecza.By default, the client response is initialized as a copy of the back-end response. Można wprowadzić zmiany, aby kod stanu odpowiedzi, frazę przyczyny, nagłówki i treść.You can make changes to the response's status code, reason phrase, headers, and body. Zmodyfikowane wartości może odwoływać się ustawienia aplikacji, Parametry z oryginalne żądanie klienta, i Parametry z odpowiedzi zaplecza.The modified values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Żądania zaplecza można modyfikować w portalu expading przesłonięcie odpowiedzi sekcji na stronie szczegółów serwera proxy.Back-end requests can be modified in the portal by expading the response override section of the proxy detail page.

Używanie zmiennychUse variables

Konfiguracja serwera proxy nie musi być statyczne.The configuration for a proxy does not need to be static. Można warunku go do korzystania ze zmiennych z oryginalnego żądania klienta, serwer zaplecza w odpowiedzi lub ustawień aplikacji.You can condition it to use variables from the original client request, the back-end response, or application settings.

Dokumentacja funkcji lokalnychReference local functions

Możesz użyć localhost k odkazu funkcji wewnątrz ta sama aplikacja funkcji bezpośrednio, bez żądania serwera proxy w obie strony.You can use localhost to reference a function inside the same function app directly, without a roundtrip proxy request.

"backendurl": "https://localhost/api/httptriggerC#1" będzie odwoływać się do funkcji wyzwalanej przez protokół HTTP lokalnej na trasie /api/httptriggerC#1"backendurl": "https://localhost/api/httptriggerC#1" will reference a local HTTP triggered function at the route /api/httptriggerC#1

Uwaga

Jeśli korzysta z funkcji funkcji, administratora lub sys poziomów dostępu, należy podać kod i clientId, zgodnie z oryginalny adres URL funkcji.If your function uses function, admin or sys authorization levels, you will need to provide the code and clientId, as per the original function URL. W tym przypadku będzie wyglądać odwołania: "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>"In this case the reference would look like: "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>"

Parametry żądania odwołaniaReference request parameters

Parametry żądania można użyć jako danych wejściowych do właściwości adres URL zaplecza lub jako część modyfikowanie żądań i odpowiedzi.You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. Niektóre parametry mogą być powiązane z szablonu trasy, który jest określony w konfiguracji podstawowej serwera proxy, a inne mogą pochodzić z właściwości żądania przychodzącego.Some parameters can be bound from the route template that's specified in the base proxy configuration, and others can come from properties of the incoming request.

Parametry szablonu trasyRoute template parameters

Parametry, które są używane w szablonie trasy dostępnych może być przywoływane przez nazwę.Parameters that are used in the route template are available to be referenced by name. Nazwy parametrów są ujęte w nawiasy klamrowe ({}).The parameter names are enclosed in braces ({}).

Na przykład, jeśli serwer proxy ma szablon trasy, takie jak /pets/{petId}, adres URL zaplecza może zawierać wartości {petId}, jak w https://<AnotherApp>.azurewebsites.net/api/pets/{petId}.For example, if a proxy has a route template, such as /pets/{petId}, the back-end URL can include the value of {petId}, as in https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Jeśli szablon trasy przerywa w symbolu wieloznacznego, takich jak /api/{*restOfPath}, wartość {restOfPath} jest ciąg reprezentujący pozostałe segmenty ścieżki z żądania przychodzącego.If the route template terminates in a wildcard, such as /api/{*restOfPath}, the value {restOfPath} is a string representation of the remaining path segments from the incoming request.

Dodatkowe parametry żądaniaAdditional request parameters

Oprócz parametrów szablonu trasy następujące wartości może służyć w wartości konfiguracji:In addition to the route template parameters, the following values can be used in config values:

  • {Request.method wartość} : Metoda HTTP, która jest używana na oryginalne żądanie.{request.method}: The HTTP method that's used on the original request.
  • {request.headers. <HeaderName>}: nagłówek, który może zostać odczytany z oryginalnego żądania.{request.headers.<HeaderName>}: A header that can be read from the original request. Zastąp <HeaderName> o nazwie nagłówka, który chcesz odczytać.Replace <HeaderName> with the name of the header that you want to read. Jeśli nagłówek nie jest uwzględniony w żądaniu, wartość będzie pusty ciąg.If the header is not included on the request, the value will be the empty string.
  • {request.querystring. <ParameterName>}: parametr ciągu zapytania, który może zostać odczytany z oryginalnego żądania.{request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. Zastąp <ParameterName> o nazwie parametru, który chcesz odczytać.Replace <ParameterName> with the name of the parameter that you want to read. Jeśli parametr nie jest uwzględniony w żądaniu, wartość będzie pusty ciąg.If the parameter is not included on the request, the value will be the empty string.

Parametry odpowiedzi zaplecza odwołaniaReference back-end response parameters

Parametrów odpowiedzi może służyć jako część modyfikowania odpowiedzi do klienta.Response parameters can be used as part of modifying the response to the client. Następujące wartości może służyć w wartości konfiguracji:The following values can be used in config values:

  • {backend.response.statusCode} : Kod stanu HTTP, który jest zwracany w odpowiedzi zaplecza.{backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason} : Fraza przyczyny HTTP, który jest zwracany w odpowiedzi zaplecza.{backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {backend.response.headers. <HeaderName>}: nagłówek, który może zostać odczytany z odpowiedzi zaplecza.{backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. Zastąp <HeaderName> o nazwie nagłówka chcesz odczytać.Replace <HeaderName> with the name of the header you want to read. Jeśli nagłówek nie jest uwzględniony w odpowiedzi, wartość będzie pusty ciąg.If the header is not included on the response, the value will be the empty string.

Dokumentacja ustawień aplikacjiReference application settings

Możesz też przywołać ustawienia aplikacji określone dla aplikacji funkcji wpisując nazwę ustawienia w znaki procentu (%).You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).

Na przykład serwer zaplecza w adresie URL https://%ORDER_PROCESSING_HOST%/api/orders miałby "% ORDER_PROCESSING_HOST %" zastąpione przez ustawienie ORDER_PROCESSING_HOST.For example, a back-end URL of https://%ORDER_PROCESSING_HOST%/api/orders would have "%ORDER_PROCESSING_HOST%" replaced with the value of the ORDER_PROCESSING_HOST setting.

Porada

Użyj ustawień aplikacji dla hostów zaplecza, jeśli masz wielu wdrożeń i środowisk testowych.Use application settings for back-end hosts when you have multiple deployments or test environments. W ten sposób można upewnij się, że zawsze mówimy prawo zaplecze dla danego środowiska.That way, you can make sure that you are always talking to the right back-end for that environment.

Rozwiązywanie problemów z serwerów proxyTroubleshoot Proxies

Dodając flagi "debug":true do dowolnego serwera proxy w swojej proxies.json spowoduje włączenie rejestrowania debugowania.By adding the flag "debug":true to any proxy in your proxies.json you will enable debug logging. Dzienniki są przechowywane w D:\home\LogFiles\Application\Proxies\DetailedTrace i jest dostępny za pośrednictwem narzędzia zaawansowane (kudu).Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). Wszystkie odpowiedzi HTTP będzie również zawierać Proxy-Trace-Location nagłówka przy użyciu adresu URL dostępu do pliku dziennika.Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.

Serwer proxy po stronie klienta można debugować, dodając Proxy-Trace-Enabled wartość nagłówka true.You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. To będzie również rejestrowania danych śledzenia w systemie plików, a jako nagłówek odpowiedzi na adres zwrotny URL śledzenia.This will also log a trace to the file system, and return the trace URL as a header in the response.

Blok proxy śladówBlock proxy traces

Ze względów bezpieczeństwa może nie chcieć zezwala wszystkim podczas wywoływania usługi w celu wygenerowania śledzenia.For security reasons you may not want to allow anyone calling your service to generate a trace. Nie będą mogli uzyskać dostęp do zawartości śledzenia bez poświadczeń logowania, ale Trwa generowanie śladu wykorzystuje zasoby i ujawnia, że jest używana funkcja serwerów proxy.They will not be able to access the trace contents without your login credentials, but generating the trace consumes resources and exposes that you are using Function Proxies.

Całkowicie wyłączyć ślady, dodając "debug":false dowolnego określonego serwera proxy w swojej proxies.json.Disable traces altogether by adding "debug":false to any particular proxy in your proxies.json.

Konfiguracja zaawansowanaAdvanced configuration

Serwery proxy, które można skonfigurować, są przechowywane w proxies.json pliku, który znajduje się w folderze głównym katalogu aplikacji funkcji.The proxies that you configure are stored in a proxies.json file, which is located in the root of a function app directory. Można ręcznie edytować ten plik i wdrożyć go jako część aplikacji przy użyciu jednej z metody wdrażania obsługiwanych przez funkcje.You can manually edit this file and deploy it as part of your app when you use any of the deployment methods that Functions supports.

Porada

Jeśli nie zdefiniowano jednej z metod wdrażania, można również pracować proxies.json pliku w portalu.If you have not set up one of the deployment methods, you can also work with the proxies.json file in the portal. Przejdź do aplikacji funkcji, wybierz opcję funkcje platformy, a następnie wybierz pozycję Edytor usługi App Service.Go to your function app, select Platform features, and then select App Service Editor. W ten sposób możesz wyświetlić strukturę cały plik aplikację funkcji, a następnie dokonaj zmian.By doing so, you can view the entire file structure of your function app and then make changes.

Plik proxies.JSON jest definiowany przez obiekt serwery proxy, który składa się z o nazwie proxy i ich definicje.Proxies.json is defined by a proxies object, which is composed of named proxies and their definitions. Opcjonalnie, jeśli edytor obsługuje tę funkcję, możesz odwoływać się do schematu JSON do uzupełniania kodu.Optionally, if your editor supports it, you can reference a JSON schema for code completion. Przykładowy plik może wyglądać następująco:An example file might look like the following:

{
    "$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.Each proxy has a friendly name, such as proxy1 in the preceding example. Odpowiedni obiekt serwera proxy w definicji jest definiowany przez następujące właściwości:The corresponding proxy definition object is defined by the following properties:

  • matchCondition: wymagane — obiekt definiujący żądań, które wywołać ich wykonanie tego serwera proxy.matchCondition: Required--an object defining the requests that trigger the execution of this proxy. Zawiera on dwie właściwości, które są współużytkowane z wyzwalaczy HTTP:It contains two properties that are shared with HTTP triggers:
    • metody: szereg metod HTTP, które odpowiada serwera proxy.methods: An array of the HTTP methods that the proxy responds to. Jeśli nie zostanie określony, serwer proxy odpowiada na wszystkich metod HTTP na trasie.If it is not specified, the proxy responds to all HTTP methods on the route.
    • trasy: wymagane — definiuje szablon trasy kontrolowanie, które adresów URL żądań na serwerze proxy odpowiada.route: Required--defines the route template, controlling which request URLs your proxy responds to. W odróżnieniu od w wyzwalaczy HTTP ma wartości domyślnej.Unlike in HTTP triggers, there is no default value.
  • backendUri: adres URL zasobu zaplecza, do której żądanie powinno być serwerem proxy.backendUri: The URL of the back-end resource to which the request should be proxied. Ta wartość może przywoływać ustawień aplikacji i parametry, z oryginalnego żądania klienta.This value can reference application settings and parameters from the original client request. Jeśli ta właściwość nie jest dołączony, usługi Azure Functions odpowiada za pomocą protokołu HTTP 200 OK.If this property is not included, Azure Functions responds with an HTTP 200 OK.
  • requestOverrides: obiekt, który definiuje przekształcenia na żądanie zaplecza.requestOverrides: An object that defines transformations to the back-end request. Zobacz Zdefiniuj obiekt requestOverrides.See Define a requestOverrides object.
  • responseOverrides: obiekt, który definiuje przekształcenia odpowiedzi klienta.responseOverrides: An object that defines transformations to the client response. Zobacz Zdefiniuj obiekt responseOverrides.See Define a responseOverrides object.

Uwaga

Trasy właściwości w usłudze Azure Functions Proxies nie uznaje routePrefix właściwość konfiguracji hosta aplikacji funkcji.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. Jeśli chcesz uwzględnić prefiks takie jak /api, muszą być zawarte w trasy właściwości.If you want to include a prefix such as /api, it must be included in the route property.

Wyłączyć poszczególne serwery proxyDisable individual proxies

Można wyłączyć poszczególne serwery proxy, dodając "disabled": true serwer proxy w proxies.json pliku.You can disable individual proxies by adding "disabled": true to the proxy in the proxies.json file. To spowoduje, że wszelkie żądania spotkania matchCondidtion zwrócić kod 404.This will cause any requests meeting the matchCondidtion to return 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "www.example.com"
        }
    }
}

Zdefiniuj obiekt requestOverridesDefine a requestOverrides object

Obiekt requestOverrides definiuje zmiany wprowadzone do żądania, gdy wywoływana jest zasobów zaplecza.The requestOverrides object defines changes made to the request when the back-end resource is called. Obiekt jest zdefiniowany przez następujące właściwości:The object is defined by the following properties:

  • backend.Request.Method: metoda HTTP, który służy do wywoływania zaplecza.backend.request.method: The HTTP method that's used to call the back-end.
  • backend.Request.QueryString. <ParameterName>: parametr ciągu zapytania, który można ustawić dla wywołania do zaplecza.backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. Zastąp <ParameterName> o nazwie parametru, który chcesz ustawić.Replace <ParameterName> with the name of the parameter that you want to set. Jeśli podano pusty ciąg, parametr nie jest uwzględniony w żądaniu zaplecza.If the empty string is provided, the parameter is not included on the back-end request.
  • backend.Request.headers. <HeaderName>: nagłówek, który można ustawić dla wywołania do zaplecza.backend.request.headers.<HeaderName>: A header that can be set for the call to the back-end. Zastąp <HeaderName> o nazwie nagłówka, który chcesz ustawić.Replace <HeaderName> with the name of the header that you want to set. Jeśli podasz pusty ciąg, nagłówka nie jest uwzględniony w żądaniu zaplecza.If you provide the empty string, the header is not included on the back-end request.

Wartości może przywoływać ustawień aplikacji i parametry, z oryginalnego żądania klienta.Values can reference application settings and parameters from the original client request.

Przykładowa konfiguracja może wyglądać następująco:An example configuration might look like the following:

{
    "$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%"
            }
        }
    }
}

Zdefiniuj obiekt responseOverridesDefine a responseOverrides object

Obiekt requestOverrides definiuje zmiany wprowadzone do odpowiedzi, który jest przekazywany z powrotem do klienta.The requestOverrides object defines changes that are made to the response that's passed back to the client. Obiekt jest zdefiniowany przez następujące właściwości:The object is defined by the following properties:

  • response.statusCode: kod stanu HTTP zwracany do klienta.response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: fraza przyczyny HTTP do zwrócenia do klienta.response.statusReason: The HTTP reason phrase to be returned to the client.
  • Response.body: ciąg reprezentujący treść do zwrócenia do klienta.response.body: The string representation of the body to be returned to the client.
  • Response.headers. <HeaderName>: nagłówek, który można ustawić dla odpowiedzi do klienta.response.headers.<HeaderName>: A header that can be set for the response to the client. Zastąp <HeaderName> o nazwie nagłówka, który chcesz ustawić.Replace <HeaderName> with the name of the header that you want to set. Jeśli podasz pusty ciąg, nagłówka nie znajduje się w odpowiedzi.If you provide the empty string, the header is not included on the response.

Wartości można odwoływać się ustawienia aplikacji, parametrami oryginalne żądanie klienta i parametry, z odpowiedzi zaplecza.Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

Przykładowa konfiguracja może wyglądać następująco:An example configuration might look like the following:

{
    "$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 ustawiony bezpośrednio, więc nie backendUri właściwość jest wymagana.In this example, the response body is set directly, so no backendUri property is needed. W przykładzie pokazano, jak można wykorzystać usługi Azure Functions Proxies dla pozorowanie interfejsów API.The example shows how you might use Azure Functions Proxies for mocking APIs.