Work with Azure Functions Proxies – Microsoft Docs
Work with proxies in Azure Functions | Microsoft Docs
Skip to main content
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Feedback
Edit
01/22/2018
10 minutes to read
In this article
This article explains how to configure and work with Azure Functions Proxies. With this feature, you can specify endpoints on your function app that are implemented by another resource. 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.
Standard Functions billing applies to proxy executions. For more information, see Azure Functions pricing.
This is reference information for Azure Functions developers. If you’re new to Azure Functions, start with the following resources:
Create your first function: C#, JavaScript, Java, or Python.
Azure Functions developer reference.
Language-specific reference: C#, C# script, F#, Java, JavaScript, or Python.
Azure Functions triggers and bindings concepts.
Code and test Azure Functions locally.
Note
You should also consider using Azure API Management for your application. It provides the same capabilities as Functions Proxies as well as other tools for building and maintaining APIs, such as OpenAPI integration, rate limiting, and advanced policies.
Create a proxy
This section shows you how to create a proxy in the Functions portal.
Open the Azure portal, and then go to your function app.
In the left pane, select New proxy.
Provide a name for your proxy.
Configure the endpoint that’s exposed on this function app by specifying the route template and HTTP methods. These parameters behave according to the rules for HTTP triggers.
Set the backend URL to another endpoint. This endpoint could be a function in another function app, or it could be any other API. The value does not need to be static, and it can reference application settings and parameters from the original client request.
Click Create.
Your proxy now exists as a new endpoint on your function app. From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.
Modify requests and responses
With Azure Functions Proxies, you can modify requests to and responses from the back-end. These transformations can use variables as defined in Use variables.
Modify the back-end request
By default, the back-end request is initialized as a copy of the original request. In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. The modified values can reference application settings and parameters from the original client request.
Back-end requests can be modified in the portal by expanding the request override section of the proxy detail page.
Modify the response
By default, the client response is initialized as a copy of the back-end response. You can make changes to the response’s status code, reason phrase, headers, and body. The modified values can reference application settings, parameters from the original client request, and parameters from the back-end response.
Back-end requests can be modified in the portal by expanding the response override section of the proxy detail page.
Use variables
The configuration for a proxy does not need to be static. You can condition it to use variables from the original client request, the back-end response, or application settings.
Reference local functions
You can use localhost to reference a function inside the same function app directly, without a roundtrip proxy request.
“backendUri”: “localhost/api/triggerC#1” will reference a local HTTP triggered function at the route /api/triggerC#1
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. In this case the reference would look like: “backendUri”: “localhost/api/triggerC#1? code=
Reference request parameters
You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. 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.
Route template parameters
Parameters that are used in the route template are available to be referenced by name. The parameter names are enclosed in braces ({}).
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
Additional request parameters
In addition to the route template parameters, the following values can be used in config values:
{}: The HTTP method that’s used on the original request.
{request. headers.
{request. querystring.
Reference back-end response parameters
Response parameters can be used as part of modifying the response to the client. The following values can be used in config values:
{atusCode}: The HTTP status code that’s returned on the back-end response.
{atusReason}: The HTTP reason phrase that’s returned on the back-end response.
{sponse.
Reference application settings
You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).
For example, a back-end URL of%ORDER_PROCESSING_HOST%/api/orders would have “%ORDER_PROCESSING_HOST%” replaced with the value of the ORDER_PROCESSING_HOST setting.
Tip
Use application settings for back-end hosts when you have multiple deployments or test environments. That way, you can make sure that you are always talking to the right back-end for that environment.
Troubleshoot Proxies
By adding the flag “debug”:true to any proxy in your you will enable debug logging. Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.
You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. This will also log a trace to the file system, and return the trace URL as a header in the response.
Block proxy traces
For security reasons you may not want to allow anyone calling your service to generate a trace. 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.
Disable traces altogether by adding “debug”:false to any particular proxy in your
Advanced configuration
The proxies that you configure are stored in a file, which is located in the root of a function app directory. 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.
If you have not set up one of the deployment methods, you can also work with the file in the portal. Go to your function app, select Platform features, and then select App Service Editor. By doing so, you can view the entire file structure of your function app and then make changes.
is defined by a proxies object, which is composed of named proxies and their definitions. Optionally, if your editor supports it, you can reference a JSON schema for code completion. An example file might look like the following:
{
“$schema”: “,
“proxies”: {
“proxy1”: {
“matchCondition”: {
“methods”: [ “GET”],
“route”: “/api/{test}”},
“backendUri”: “
Each proxy has a friendly name, such as proxy1 in the preceding example. The corresponding proxy definition object is defined by the following properties:
matchCondition: Required–an object defining the requests that trigger the execution of this proxy. It contains two properties that are shared with HTTP triggers:
methods: An array of the HTTP methods that the proxy responds to. If it is not specified, the proxy responds to all HTTP methods on the route.
route: Required–defines the route template, controlling which request URLs your proxy responds to. Unlike in HTTP triggers, there is no default value.
backendUri: The URL of the back-end resource to which the request should be proxied. This value can reference application settings and parameters from the original client request. If this property is not included, Azure Functions responds with an HTTP 200 OK.
requestOverrides: An object that defines transformations to the back-end request. See Define a requestOverrides object.
responseOverrides: An object that defines transformations to the client response. See Define a responseOverrides object.
The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. If you want to include a prefix such as /api, it must be included in the route property.
Disable individual proxies
You can disable individual proxies by adding “disabled”: true to the proxy in the file. This will cause any requests meeting the matchCondition to return 404.
“Root”: {
“disabled”:true,
“route”: “/example”},
Application Settings
The proxy behavior can be controlled by several app settings. They are all outlined in the Functions App Settings reference
AZURE_FUNCTION_PROXY_DISABLE_LOCAL_CALL
AZURE_FUNCTION_PROXY_BACKEND_URL_DECODE_SLASHES
Reserved Characters (string formatting)
Proxies read all strings out of a JSON file, using \ as an escape symbol. Proxies also interpret curly braces. See a full set of examples below.
Character
Escaped Character
Example
{ or}
{{ or}}
{{ example}} –> { example}
\
\\
\\ –> \
”
\”
