Praca z serwerów proxy Azure FunctionsWork with Azure Functions Proxies

W tym artykule opisano sposób konfigurowania i pracować z serwerów proxy funkcji platformy Azure.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 zostały zaimplementowane przez inny zasób.With this feature, you can specify endpoints on your function app that are implemented by another resource. Umożliwia te serwery proxy Podziel dużych interfejsu API na wiele aplikacji funkcji (tak jak to architektura mikrousługi), prezentując pojedynczą powierzchnię interfejsu API dla klientów jednocześnie.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ń dotyczy wykonaniami serwera proxy.Standard Functions billing applies to proxy executions. Aby uzyskać więcej informacji, zobacz cennik usługi Azure Functions.For more information, see Azure Functions pricing.

Utwórz serwer proxyCreate a proxy

W tej sekcji przedstawiono sposób tworzenia serwera proxy w portalu funkcji.This section shows you how to create a proxy in the Functions portal.

  1. Otwórz portalu Azure, 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 punktu końcowego, która jest widoczna w tym funkcji aplikacji, 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 działają 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ć jakiegokolwiek interfejsu API.This endpoint could be a function in another function app, or it could be any other API. Wartość musi być statyczne i mogą się odwoływać do ustawienia aplikacji i parametrów z żądania klienta oryginalnym.The value does not need to be static, and it can reference application settings and parameters from the original client request.
  6. Kliknij przycisk Utwórz.Click Create.

Serwer proxy obecnie istnieje jako nowy punkt końcowy w aplikacji funkcji.Your proxy now exists as a new endpoint on your function app. Z perspektywy klienta jest odpowiednikiem HttpTrigger w funkcji platformy Azure.From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. Można wypróbować nowego serwera proxy, kopiując adres URL serwera Proxy i testowanie go z ulubionych 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ą proxy funkcji platformy Azure można modyfikować żądania i odpowiedzi z zaplecza.With Azure Functions Proxies, you can modify requests to and responses from the back-end. Przekształcenia te można używać zmiennych, zgodnie z definicją w używać zmiennych.These transformations can use variables as defined in Use variables.

Modyfikowanie żądania zapleczaModify the back-end request

Domyślnie żądania zaplecza został zainicjowany jako kopia oryginalnego żądania.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 parametrów 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 się odwoływać ustawienia aplikacji i parametrów z żądania klienta oryginalnym.The modified values can reference application settings and parameters from the original client request.

Żądania zaplecza może być modyfikowany w portalu przez expading żądania zastąpienie części strony szczegółów serwera proxy.Back-end requests can be modified in the portal by expading the request override section of the proxy detail page.

Modyfikować odpowiedziModify the response

Domyślnie odpowiedzi klienta zostanie zainicjowany jako kopię odpowiedzi zaplecza.By default, the client response is initialized as a copy of the back-end response. Kod stanu odpowiedzi, frazę przyczyny, nagłówki i treści, można wprowadzić zmiany.You can make changes to the response's status code, reason phrase, headers, and body. Zmodyfikowane wartości może się odwoływać ustawienia aplikacji, parametrów z żądania klienta oryginalnym, 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że być modyfikowany w portalu przez expading zastąpienie odpowiedzi części strony 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żywać zmiennychUse variables

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

Odwołanie do funkcji lokalnejReference local functions

Można użyć localhost do odwołania funkcji w tej samej aplikacji funkcja bezpośrednio, bez przesyłania żądania serwera proxy.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 lokalnej HTTP wyzwalane w trasy /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 funkcję, administrator lub sys poziomy autoryzacji, konieczne będzie podanie kodu i clientId, zgodnie z harmonogramem 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 takim 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 dane wejściowe, aby właściwość URL zaplecza lub w ramach modyfikowania żądania 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 został określony w konfiguracji podstawowej serwera proxy, a inne osoby mogą pochodzić z właściwości z żą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 odwoływać się do nazwy.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, takich 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 kończy w symboli wieloznacznych, takich jak /api/{*restOfPath}, wartość {restOfPath} jest reprezentację ciągu pozostałych segmentów ś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 można używać następujących wartości 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 żądanie nie zawiera nagłówka, 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 nazwę parametru, który chcesz odczytać.Replace <ParameterName> with the name of the parameter that you want to read. Jeśli parametr nie jest dostępna na żądanie, wartość będzie pusty ciąg.If the parameter is not included on the request, the value will be the empty string.

Parametry zaplecza odpowiedzi odwołaniaReference back-end response parameters

Parametry odpowiedzi mogą być używane jako część modyfikowania odpowiedzi do klienta.Response parameters can be used as part of modifying the response to the client. W wartości konfiguracji można używać następujących wartości: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 protokołu 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, który chcesz odczytać.Replace <HeaderName> with the name of the header you want to read. Jeśli nie ma nagłówka odpowiedzi, wartość będzie pusty ciąg.If the header is not included on the response, the value will be the empty string.

Odwołanie do ustawienia aplikacjiReference application settings

Można także odwoływać ustawienia aplikacji określone dla aplikacji funkcja przez wpisywania nazwy 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 adres URL zaplecza z https://%ORDER_PROCESSING_HOST%/api/orders byłyby "% 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 ustawienia aplikacji dla hostów zaplecza w przypadku wielu wdrożeń lub środowisk testowych.Use application settings for back-end hosts when you have multiple deployments or test environments. W ten sposób można upewnić się, że zawsze mówimy do prawej zaplecza dla tego ś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 sieci 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 zaawansowanych narzędzi (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 o adresie 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ć przez dodanie 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. Spowoduje to również rejestrowania danych śledzenia w systemie plików i zwraca adres URL śledzenia jako nagłówka w odpowiedzi.This will also log a trace to the file system, and return the trace URL as a header in the response.

Blok serwera proxy śledzeniaBlock proxy traces

Ze względów bezpieczeństwa możesz nie pozwala nikomu wywoływania usługi do generowania śledzenia.For security reasons you may not want to allow anyone calling your service to generate a trace. Nie będą oni mogli uzyskać dostępu do zawartości śledzenia bez poświadczeń logowania, ale generowania śledzenia wykorzystuje zasoby i ujawnia używasz funkcji 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ć śladów, dodając "debug":false do dowolnego określonego serwera proxy w sieci 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 katalogiem 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ługiwane 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żesz także pracować z 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 funkcji aplikacji, wybierz opcję funkcji platformy, a następnie wybierz Edytor usług aplikacji.Go to your function app, select Platform features, and then select App Service Editor. W ten sposób można wyświetlić strukturę całego pliku aplikacji funkcji, a następnie wprowadź zmiany.By doing so, you can view the entire file structure of your function app and then make changes.

Proxies.JSON jest definiowana za pomocą obiektu serwery proxy, który składa się z nazwanym proxy oraz 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 dla 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ę, takich 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 zdefiniowane przez następujących właściwościach:The corresponding proxy definition object is defined by the following properties:

  • matchCondition: wymagany — obiekt definiujący żądań, które wyzwalają wykonanie tego serwera proxy.matchCondition: Required--an object defining the requests that trigger the execution of this proxy. Zawiera dwie właściwości, które są udostępniane wyzwalaczy HTTP:It contains two properties that are shared with HTTP triggers:
    • metody: Tablica 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 reaguje na wszystkie metody HTTP na trasie.If it is not specified, the proxy responds to all HTTP methods on the route.
    • trasy: wymagany — definiuje szablon trasy, kontrolowanie, które adresów URL żądań proxy odpowiada.route: Required--defines the route template, controlling which request URLs your proxy responds to. W odróżnieniu od w HTTP wyzwalaczy, nie ma wartości domyślnej.Unlike in HTTP triggers, there is no default value.
  • backendUri: adres URL zasobu zaplecza, do którego powinien być serwerem proxy żądania.backendUri: The URL of the back-end resource to which the request should be proxied. Ta wartość może odwoływać się parametry i ustawienia aplikacji 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 uwzględniona, usługi Azure Functions odpowiada 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 zdefiniować 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 zdefiniować obiekt responseOverrides.See Define a responseOverrides object.

Uwaga

Trasy właściwości w proxy funkcji Azure honoruje routePrefix właściwości konfiguracji hostów funkcji aplikacji.The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. Jeśli chcesz obejmują takie jak prefiks /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łącz poszczególnych serwerów proxyDisable individual proxies

Można wyłączyć poszczególne serwery proxy, dodając "disabled": true do serwera 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 wszystkie żądania spotkania matchCondidtion do zwrócenia 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 obiektu requestOverridesDefine a requestOverrides object

Obiekt requestOverrides definiuje zmiany wprowadzone do żądania wywołanego zasobów wewnętrznych.The requestOverrides object defines changes made to the request when the back-end resource is called. Obiekt jest zdefiniowane przez następujących właściwościach:The object is defined by the following properties:

  • backend.Request.Method: metody HTTP, które są używane 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óre można ustawić dla wywołania zaplecza.backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. Zastąp <ParameterName> o nazwę parametru, który chcesz ustawić.Replace <ParameterName> with the name of the parameter that you want to set. W przypadku pustego ciągu parametru 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 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órą chcesz ustawić.Replace <HeaderName> with the name of the header that you want to set. Jeśli podasz pustym ciągiem nagłówka nie znajduje się na żądanie zaplecza.If you provide the empty string, the header is not included on the back-end request.

Ustawienia aplikacji i parametrów wartości można odwoływać się 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 obiektu responseOverridesDefine a responseOverrides object

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

  • response.statusCode: kod stanu HTTP ma zostać zwrócona do klienta.response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: fraza przyczyny HTTP ma zostać zwrócona do klienta.response.statusReason: The HTTP reason phrase to be returned to the client.
  • Response.body: reprezentację ciągu treści, która ma zostać zwrócona 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órą chcesz ustawić.Replace <HeaderName> with the name of the header that you want to set. Jeśli podasz pustym ciągiem nagłówka nie jest uwzględniony w odpowiedzi.If you provide the empty string, the header is not included on the response.

Ustawienia aplikacji, parametrów z żądania klienta oryginalnym i parametry wartości można odwoływać się 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 użyć do mocking interfejsów API Azure funkcji z serwerów proxy.The example shows how you might use Azure Functions Proxies for mocking APIs.