|
| 1 | +--- |
| 2 | +title: Azure Functions HTTP output bindings |
| 3 | +description: Learn how to return HTTP responses in Azure Functions. |
| 4 | +author: craigshoemaker |
| 5 | + |
| 6 | +ms.topic: reference |
| 7 | +ms.date: 02/21/2020 |
| 8 | +ms.author: cshoe |
| 9 | +--- |
| 10 | + |
| 11 | +# Azure Functions HTTP output bindings |
| 12 | + |
| 13 | +Use the HTTP output binding to respond to the HTTP request sender. This binding requires an HTTP trigger and allows you to customize the response associated with the trigger's request. |
| 14 | + |
| 15 | +The default return value for an HTTP-triggered function is: |
| 16 | + |
| 17 | +- `HTTP 204 No Content` with an empty body in Functions 2.x and higher |
| 18 | +- `HTTP 200 OK` with an empty body in Functions 1.x |
| 19 | + |
| 20 | +## Configuration |
| 21 | + |
| 22 | +The following table explains the binding configuration properties that you set in the *function.json* file. For C# class libraries, there are no attribute properties that correspond to these *function.json* properties. |
| 23 | + |
| 24 | +|Property |Description | |
| 25 | +|---------|---------| |
| 26 | +| **type** |Must be set to `http`. | |
| 27 | +| **direction** | Must be set to `out`. | |
| 28 | +| **name** | The variable name used in function code for the response, or `$return` to use the return value. | |
| 29 | + |
| 30 | +## Usage |
| 31 | + |
| 32 | +To send an HTTP response, use the language-standard response patterns. In C# or C# script, make the function return type `IActionResult` or `Task<IActionResult>`. In C#, a return value attribute isn't required. |
| 33 | + |
| 34 | +For example responses, see the [trigger example](./functions-bindings-http-webhook-trigger.md#example). |
| 35 | + |
| 36 | +## host.json settings |
| 37 | + |
| 38 | +This section describes the global configuration settings available for this binding in versions 2.x and higher. The example host.json file below contains only the version 2.x+ settings for this binding. For more information about global configuration settings in versions 2.x and beyond, see [host.json reference for Azure Functions](functions-host-json.md). |
| 39 | + |
| 40 | +> [!NOTE] |
| 41 | +> For a reference of host.json in Functions 1.x, see [host.json reference for Azure Functions 1.x](functions-host-json-v1.md#http). |
| 42 | +
|
| 43 | +```json |
| 44 | +{ |
| 45 | + "extensions": { |
| 46 | + "http": { |
| 47 | + "routePrefix": "api", |
| 48 | + "maxOutstandingRequests": 200, |
| 49 | + "maxConcurrentRequests": 100, |
| 50 | + "dynamicThrottlesEnabled": true, |
| 51 | + "hsts": { |
| 52 | + "isEnabled": true, |
| 53 | + "maxAge": "10" |
| 54 | + }, |
| 55 | + "customHeaders": { |
| 56 | + "X-Content-Type-Options": "nosniff" |
| 57 | + } |
| 58 | + } |
| 59 | + } |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +|Property |Default | Description | |
| 64 | +|---------|---------|---------| |
| 65 | +| customHeaders|none|Allows you to set custom headers in the HTTP response. The previous example adds the `X-Content-Type-Options` header to the response to avoid content type sniffing. | |
| 66 | +|dynamicThrottlesEnabled|true<sup>\*</sup>|When enabled, this setting causes the request processing pipeline to periodically check system performance counters like `connections/threads/processes/memory/cpu/etc` and if any of those counters are over a built-in high threshold (80%), requests will be rejected with a `429 "Too Busy"` response until the counter(s) return to normal levels.<br/><sup>\*</sup>The default in a Consumption plan is `true`. The default in a Dedicated plan is `false`.| |
| 67 | +|hsts|not enabled|When `isEnabled` is set to `true`, the [HTTP Strict Transport Security (HSTS) behavior of .NET Core](/aspnet/core/security/enforcing-ssl?view=aspnetcore-3.0&tabs=visual-studio#hsts) is enforced, as defined in the [`HstsOptions` class](/dotnet/api/microsoft.aspnetcore.httpspolicy.hstsoptions?view=aspnetcore-3.0). The above example also sets the [`maxAge`](/dotnet/api/microsoft.aspnetcore.httpspolicy.hstsoptions.maxage?view=aspnetcore-3.0#Microsoft_AspNetCore_HttpsPolicy_HstsOptions_MaxAge) property to 10 days. Supported properties of `hsts` are: <table><tr><th>Property</th><th>Description</th></tr><tr><td>excludedHosts</td><td>A string array of host names for which the HSTS header isn't added.</td></tr><tr><td>includeSubDomains</td><td>Boolean value that indicates whether the includeSubDomain parameter of the Strict-Transport-Security header is enabled.</td></tr><tr><td>maxAge</td><td>String that defines the max-age parameter of the Strict-Transport-Security header.</td></tr><tr><td>preload</td><td>Boolean that indicates whether the preload parameter of the Strict-Transport-Security header is enabled.</td></tr></table>| |
| 68 | +|maxConcurrentRequests|100<sup>\*</sup>|The maximum number of HTTP functions that are executed in parallel. This value allows you to control concurrency, which can help manage resource utilization. For example, you might have an HTTP function that uses a large number of system resources (memory/cpu/sockets) such that it causes issues when concurrency is too high. Or you might have a function that makes outbound requests to a third-party service, and those calls need to be rate limited. In these cases, applying a throttle here can help. <br/><sup>*</sup>The default for a Consumption plan is 100. The default for a Dedicated plan is unbounded (`-1`).| |
| 69 | +|maxOutstandingRequests|200<sup>\*</sup>|The maximum number of outstanding requests that are held at any given time. This limit includes requests that are queued but have not started executing, as well as any in progress executions. Any incoming requests over this limit are rejected with a 429 "Too Busy" response. That allows callers to employ time-based retry strategies, and also helps you to control maximum request latencies. This only controls queuing that occurs within the script host execution path. Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. <br/><sup>\*</sup>The default for a Consumption plan is 200. The default for a Dedicated plan is unbounded (`-1`).| |
| 70 | +|routePrefix|api|The route prefix that applies to all routes. Use an empty string to remove the default prefix. | |
| 71 | + |
| 72 | +## Next steps |
| 73 | + |
| 74 | +- [Run a function from an HTTP request](./functions-bindings-http-webhook-trigger.md) |
0 commit comments