Work with Azure Functions Proxies

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.

This is reference information for Azure Functions developers. If you're new to Azure Functions, start with the following resources:

Note

Standard Functions billing applies to proxy executions. For more information, see Azure Functions pricing.

Create a proxy

This section shows you how to create a proxy in the Functions portal.

  1. Open the Azure portal, and then go to your function app.
  2. In the left pane, select New proxy.
  3. Provide a name for your proxy.
  4. 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.
  5. 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.
  6. 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.

Currently, there is no portal experience for modifying back-end requests. To learn how to apply this capability from proxies.json, see Define a requestOverrides object.

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.

Currently, there is no portal experience for modifying responses. To learn how to apply this capability from proxies.json, see Define a responseOverrides object.

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 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 https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. 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.

Additional request parameters

In addition to the route template parameters, the following values can be used in config values:

  • {request.method}: The HTTP method that's used on the original request.
  • {request.headers.<HeaderName>}: A header that can be read from the original request. Replace <HeaderName> with the name of the header that you want to read. If the header is not included on the request, the value will be the empty string.
  • {request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. Replace <ParameterName> with the name of the parameter that you want to read. If the parameter is not included on the request, the value will be the empty string.

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:

  • {backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. Replace <HeaderName> with the name of the header you want to read. If the header is not included on the request, the value will be the empty string.

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 https://%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.

Advanced configuration

The proxies that you configure are stored in a proxies.json 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. The feature must be enabled for the file to be processed.

Tip

If you have not set up one of the deployment methods, you can also work with the proxies.json 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.

Proxies.json 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": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

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.

Note

The route property Azure Functions Proxies does not honor the routePrefix property of the Functions host configuration. If you want to include a prefix such as /api, it must be included in the route property.

Define a requestOverrides object

The requestOverrides object defines changes made to the request when the back-end resource is called. The object is defined by the following properties:

  • backend.request.method: The HTTP method that's used to call the back-end.
  • backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back-end. Replace <ParameterName> with the name of the parameter that you want to set. If the empty string is provided, the parameter is not included on the back-end request.
  • backend.request.headers.<HeaderName>: A header that can be set for the call to the back-end. Replace <HeaderName> with the name of the header that you want to set. If you provide the empty string, the header is not included on the back-end request.

Values can reference application settings and parameters from the original client request.

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

Define a responseOverrides object

The requestOverrides object defines changes that are made to the response that's passed back to the client. The object is defined by the following properties:

  • response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: The HTTP reason phrase to be returned to the client.
  • response.body: The string representation of the body to be returned to the client.
  • response.headers.<HeaderName>: A header that can be set for the response to the client. Replace <HeaderName> with the name of the header that you want to set. If you provide the empty string, the header is not included on the response.

Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

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"
            }
        }
    }
}

Note

In this example, the body is being set directly, so no backendUri property is needed. The example shows how you might use Azure Functions Proxies for mocking APIs.

Enable Azure Functions Proxies

Proxies are now enabled by default! If you were using an older version of the proxies preview and disabled proxies, you will need to manually enable proxies once in order for proxies to execute.

  1. Open the Azure portal, and then go to your function app.
  2. Select Function app settings.
  3. Switch Enable Azure Functions Proxies (preview) to On.

You can also return here to update the proxy runtime as new features become available.