Триггеры и привязки HTTP в службе "Функции Azure"Azure Functions HTTP triggers and bindings

В этой статье объясняется, как использовать триггеры и выходные привязки в службе "Функции Azure".This article explains how to work with HTTP triggers and output bindings in Azure Functions.

Триггер HTTP можно настроить на ответ веб-перехватчикам.An HTTP trigger can be customized to respond to webhooks.

Это справочные сведения для разработчиков функций Azure.This is reference information for Azure Functions developers. Если вы новичок в функциях Azure, начните со следующих ресурсов:If you're new to Azure Functions, start with the following resources:

Совет

Если вы планируете использовать привязки HTTP или веб-перехватчика, спланируйте работу так, чтобы избежать нехватки портов, которая может возникнуть в результате неправильной установки HttpClient.If you plan to use the HTTP or WebHook bindings, plan to avoid port exhaustion that can be caused by improper instantiation of HttpClient. См. дополнительные сведения об управлении подключениями в службе "Функции Azure".For more information, see How to manage connections in Azure Functions.

Для кода в этой статье по умолчанию используется синтаксис Функций 2.x, который применяется в .NET Core.The code in this article defaults to Functions 2.x syntax which uses .NET Core. Сведения о синтаксисе версии 1.x см. на странице с соответствующими шаблонами функций.For information on the 1.x syntax, see the 1.x functions templates.

Пакеты — Функции 1.xPackages - Functions 1.x

Привязки служебной шины доступны в пакете NuGet Microsoft.Azure.WebJobs.Extensions.Http, версия 1.х.The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 1.x. Исходный код для пакета находится в репозитории GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Поддержка этой привязки автоматически предоставляется во всех средах разработки.Support for this binding is automatically provided in all development environments. Не нужно вручную устанавливать пакет или регистрировать расширение.You don't have to manually install the package or register the extension.

Пакеты — Функции 2.xPackages - Functions 2.x

Привязки служебной шины доступны в пакете NuGet Microsoft.Azure.WebJobs.Extensions.Http, версия 3.х.The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 3.x. Исходный код для пакета находится в репозитории GitHub azure-webjobs-sdk-extensions.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Поддержка этой привязки автоматически предоставляется во всех средах разработки.Support for this binding is automatically provided in all development environments. Не нужно вручную устанавливать пакет или регистрировать расширение.You don't have to manually install the package or register the extension.

ТриггерTrigger

Триггер HTTP позволяет вызвать функцию с помощью HTTP-запроса.The HTTP trigger lets you invoke a function with an HTTP request. Триггер HTTP можно использовать для создания независимых от сервера API-интерфейсов и для ответа веб-перехватчикам.You can use an HTTP trigger to build serverless APIs and respond to webhooks.

По умолчанию в Функциях версии 1.x триггер HTTP возвращает ответ HTTP "200 — OK" с пустым текстом, а в Функциях версии 2.x — ответ "204 — содержимое отсутствует" с пустым текстом.By default, an HTTP trigger returns HTTP 200 OK with an empty body in Functions 1.x, or HTTP 204 No Content with an empty body in Functions 2.x. Чтобы изменить ответ, настройте выходную привязку HTTP.To modify the response, configure an HTTP output binding.

Пример триггераTrigger - example

В следующем примере показана функция C#, выполняющая поиск параметра name в строке запроса или в тексте HTTP-запроса.The following example shows a C# function that looks for a name parameter either in the query string or the body of the HTTP request. Обратите внимание, что возвращаемое значение используется для привязки выходных данных, но атрибут возвращаемого значения не является обязательным.Notice that the return value is used for the output binding, but a return value attribute isn't required.

[FunctionName("HttpTriggerCSharp")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] 
    HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    return name != null
        ? (ActionResult)new OkObjectResult($"Hello, {name}")
        : new BadRequestObjectResult("Please pass a name on the query string or in the request body");
}

Атрибуты триггераTrigger - attributes

В C# библиотеках классов и Java атрибут HttpTrigger доступен для настройки функции.In C# class libraries and Java, the HttpTrigger attribute is available to configure the function.

Можно задать уровень авторизации и допустимые методы HTTP в параметрах конструктора атрибутов, типе веб-перехватчика и шаблоне маршрута.You can set the authorization level and allowable HTTP methods in attribute constructor parameters, webhook type, and a route template. Дополнительные сведения об этих параметрах см. в разделе Конфигурация триггера.For more information about these settings, see Trigger - configuration.

В этом примере показано, как использовать атрибут HttpTrigger .This example demonstrates how to use the HttpTrigger attribute.

[FunctionName("HttpTriggerCSharp")]
public static Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req)
{
    ...
}

Полный пример см. в примере триггера.For a complete example, see the trigger example.

Конфигурация триггераTrigger - configuration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте HttpTrigger.The following table explains the binding configuration properties that you set in the function.json file and the HttpTrigger attribute.

свойство function.jsonfunction.json property Свойство атрибутаAttribute property ОПИСАНИЕDescription
typetype Недоступноn/a Обязательное. Необходимо задать значение httpTrigger.Required - must be set to httpTrigger.
directiondirection Недоступноn/a Обязательное. Необходимо задать значение in.Required - must be set to in.
namename Недоступноn/a Обязательное. Имя переменной, из которой в коде функции можно получить запрос или текст запроса.Required - the variable name used in function code for the request or request body.
authLevelauthLevel AuthLevelAuthLevel Определяет, какие ключи (если они требуются) должны присутствовать в запросе, чтобы вызвать функцию.Determines what keys, if any, need to be present on the request in order to invoke the function. Уровень авторизации может принимать одно из следующих значений:The authorization level can be one of the following values:
  • anonymous— — ключи API не требуются.anonymous—No API key is required.
  • function— — требуется ключ API для конкретной функции.function—A function-specific API key is required. Это значение используется по умолчанию, если не указано иное.This is the default value if none is provided.
  • admin— — требуется главный ключ.admin—The master key is required.
Дополнительные сведения см. в разделе Ключи авторизации.For more information, see the section about authorization keys.
methodsmethods МетодыMethods Массив методов HTTP, на которые отвечает функция.An array of the HTTP methods to which the function responds. Если свойство не указано, функция отвечает на все методы HTTP.If not specified, the function responds to all HTTP methods. Ознакомьтесь с разделом о настройке конечной точки HTTP.See customize the http endpoint.
routeroute RouteRoute Шаблон маршрута, определяющий URL-адреса запросов, на которые отвечает функция.Defines the route template, controlling to which request URLs your function responds. Если значение не указано, по умолчанию используется <functionname>.The default value if none is provided is <functionname>. Дополнительные сведения см. в разделе о настройке конечной точки HTTP.For more information, see customize the http endpoint.
webHookTypewebHookType WebHookTypeWebHookType Поддерживается только для среды выполнения версии 1.x.Supported only for the version 1.x runtime.

Указывает, что триггер HTTP должен выступать в качестве получателя веб-перехватчика для указанного поставщика.Configures the HTTP trigger to act as a webhook receiver for the specified provider. Если вы установите это свойство, не устанавливайте свойство methods.Don't set the methods property if you set this property. Тип веб-перехватчика может принимать одно из следующих значений:The webhook type can be one of the following values:
  • genericJson— — конечная точка веб-перехватчика общего назначения без логики для конкретного поставщика.genericJson—A general-purpose webhook endpoint without logic for a specific provider. Этот параметр определяет, что принимаются только запросы HTTP POST с содержимым типа application/json.This setting restricts requests to only those using HTTP POST and with the application/json content type.
  • github— — функция отвечает на вызовы веб-перехватчиков GitHub.github—The function responds to GitHub webhooks. Не используйте свойство authLevel вместе с веб-перехватчиками GitHub.Do not use the authLevel property with GitHub webhooks. Дополнительные сведения см. в этой статье, в разделе веб-перехватчики GitHub.For more information, see the GitHub webhooks section later in this article.
  • slack— — функция отвечает на вызовы веб-перехватчиков Slack.slack—The function responds to Slack webhooks. Не используйте свойство authLevel вместе с веб-перехватчиками Slack.Do not use the authLevel property with Slack webhooks. Дополнительные сведения см. в разделе о веб-перехватчиках Slack далее в этой статье.For more information, see the Slack webhooks section later in this article.

Использование триггераTrigger - usage

Тип входных данных триггера объявлен как HttpRequest или пользовательский тип.The trigger input type is declared as either HttpRequest or a custom type. Если вы выберете HttpRequest, то получите полный доступ к объекту запроса.If you choose HttpRequest, you get full access to the request object. При объявлении пользовательского типа среда выполнения попытается проанализировать текст запроса JSON для задания свойств объекта.For a custom type, the runtime tries to parse the JSON request body to set the object properties.

Настройка конечной точки HTTPCustomize the HTTP endpoint

По умолчанию при создании функции для триггера HTTP маршрут для ее адресации имеет следующий вид:By default when you create a function for an HTTP trigger, the function is addressable with a route of the form:

http://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>

Этот маршрут можно настроить с помощью дополнительного свойства route привязки для вывода триггера HTTP.You can customize this route using the optional route property on the HTTP trigger's input binding. Например, приведенный ниже файл function.json определяет свойство route для триггера HTTP.As an example, the following function.json file defines a route property for an HTTP trigger:

{
    "bindings": [
    {
        "type": "httpTrigger",
        "name": "req",
        "direction": "in",
        "methods": [ "get" ],
        "route": "products/{category:alpha}/{id:int?}"
    },
    {
        "type": "http",
        "name": "res",
        "direction": "out"
    }
    ]
}

При такой конфигурации функция доступна по приведенному ниже маршруту вместо исходного.Using this configuration, the function is now addressable with the following route instead of the original route.

http://<APP_NAME>.azurewebsites.net/api/products/electronics/357

Это позволяет использовать в коде функции два параметра, передаваемых в адресе, — category и id.This allows the function code to support two parameters in the address, category and id.

Для параметров можно использовать любое ограничение маршрута веб-API.You can use any Web API Route Constraint with your parameters. Приведенный ниже код функции C# используют оба параметра.The following C# function code makes use of both parameters.

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;

public static IActionResult Run(HttpRequest req, string category, int? id, ILogger log)
{
    var message = String.Format($"Category: {category}, ID: {id}");
    return (ActionResult)new OkObjectResult(message);
}

По умолчанию все маршруты функций начинаются с префикса api.By default, all function routes are prefixed with api. Вы можете настроить или удалить этот префикс с помощью свойства http.routePrefix в файле host.json.You can also customize or remove the prefix using the http.routePrefix property in your host.json file. В следующем примере префикс маршрута api удаляется. Он заменяется пустой строкой в файле host.json.The following example removes the api route prefix by using an empty string for the prefix in the host.json file.

{
    "http": {
    "routePrefix": ""
    }
}

Работа с удостоверениями клиентовWorking with client identities

Если в приложении-функции используется аутентификация и авторизация Службы приложений, сведения об аутентифицированных клиентах можно посмотреть прямо в коде.If your function app is using App Service Authentication / Authorization, you can view information about authenticated clients from your code. Эта информация доступна в виде заголовков запросов, которые вставляет платформа.This information is available as request headers injected by the platform.

Эти сведения также можно считывать из данных привязки.You can also read this information from binding data. Эта возможность доступна только в среде выполнения Функций версии 2.x.This capability is only available to the Functions 2.x runtime. Кроме того, сейчас она доступна только для языков .NET.It is also currently only available for .NET languages.

Сведения о клиентах, прошедших проверку подлинности, доступны в виде ClaimsPrincipal.Information regarding authenticated clients is available as a ClaimsPrincipal. ClaimsPrincipal доступен как часть контекста запроса, как показано в следующем примере:The ClaimsPrincipal is available as part of the request context as shown in the following example:

using System.Net;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;

public static IActionResult Run(HttpRequest req, ILogger log)
{
    ClaimsPrincipal identities = req.HttpContext.User;
    // ...
    return new OkObjectResult();
}

Кроме того, ClaimsPrincipal можно включить как дополнительный параметр в сигнатуру функции:Alternatively, the ClaimsPrincipal can simply be included as an additional parameter in the function signature:

using System.Net;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;
using Newtonsoft.Json.Linq;

public static void Run(JObject input, ClaimsPrincipal principal, ILogger log)
{
    // ...
    return;
}

Ключи авторизацииAuthorization keys

Служба "Функции" позволяет использовать ключи, чтобы затруднить несанкционированный доступ к конечным точкам функции HTTP во время развертывания.Functions lets you use keys to make it harder to access your HTTP function endpoints during development. Стандартному триггеру HTTP может потребоваться, чтобы такой ключ API был в запросе.A standard HTTP trigger may require such an API key be present in the request.

Важно!

Хотя ключи могут помочь в маскировке конечных точек HTTP во время развертывания, они не предназначены для защиты триггера HTTP в рабочей среде.While keys may help obfuscate your HTTP endpoints during development, they are not intended as a way to secure an HTTP trigger in production. Дополнительные сведения см. в разделе Защита конечной точки HTTP в рабочей среде.To learn more, see Secure an HTTP endpoint in production.

Примечание

В среде выполнения службы "Функции" версии 1.х веб-перехватчик может использовать ключи для авторизации запросов различными способами, в зависимости от поддерживаемых поставщиком технологий.In the Functions 1.x runtime, webhook providers may use keys to authorize requests in a variety of ways, depending on what the provider supports. Это рассматривается в разделе Веб-перехватчики и ключи.This is covered in Webhooks and keys. Среда выполнения версии 2.x не включает встроенную поддержку поставщиков веб-перехватчика.The version 2.x runtime does not include built-in support for webhook providers.

Существует два типа ключей.There are two types of keys:

  • Ключи узла, которые являются общими для всех функций в приложении-функции.Host keys: These keys are shared by all functions within the function app. Если такой ключ используется в качестве ключа API, он предоставляет доступ к любой функции в приложении-функции.When used as an API key, these allow access to any function within the function app.
  • Ключи функции, которые применяются только для конкретных функций, в которых они определены.Function keys: These keys apply only to the specific functions under which they are defined. Если такой ключ используется в качестве ключа API, он предоставляет доступ только к определенной функции.When used as an API key, these only allow access to that function.

Каждый ключ имеет имя для удобства использования, а один из ключей (с именем default) используется как ключ по умолчанию на уровне узла и функции.Each key is named for reference, and there is a default key (named "default") at the function and host level. Ключи функций имеют приоритет над ключами узла.Function keys take precedence over host keys. Если определены два ключа с одним именем, всегда используется ключ функции.When two keys are defined with the same name, the function key is always used.

Каждое приложение-функция также имеет специальный главный ключ.Each function app also has a special master key. Это ключ узла с именем _master, который предоставляет административный доступ к API среды выполнения.This key is a host key named _master, which provides administrative access to the runtime APIs. Его невозможно отозвать.This key cannot be revoked. При задании уровня авторизации admin запросы должны использовать главный ключ. Использование любого другого ключа приведет к ошибке авторизации.When you set an authorization level of admin, requests must use the master key; any other key results in authorization failure.

Внимание!

Главный ключ предоставляет высокий уровень разрешений в приложении-функции, поэтому никогда не передавайте этот ключ третьим лицам и не включайте его в состав клиентских приложений.Due to the elevated permissions in your function app granted by the master key, you should not share this key with third parties or distribute it in native client applications. Соблюдайте осторожность при выборе уровня авторизации для администратора.Use caution when choosing the admin authorization level.

Получение ключейObtaining keys

Ключи хранятся в Azure в составе приложения-функции в зашифрованном виде.Keys are stored as part of your function app in Azure and are encrypted at rest. Чтобы просмотреть ключи, создать новые или сменить значения ключей, откройте на портале Azure нужную функцию, активируемую по HTTP, и выберите Управление.To view your keys, create new ones, or roll keys to new values, navigate to one of your HTTP-triggered functions in the Azure portal and select Manage.

Управляйте ключами функций на портале.

Ключи функций можно получить программно с помощью API управления ключами.You may obtain function keys programmatically by using Key management APIs.

Проверка подлинности с помощью ключа APIAPI key authorization

Большинству шаблонов триггеров HTTP требуется ключ API в запросе.Most HTTP trigger templates require an API key in the request. Поэтому HTTP-запрос обычно выглядит как следующий URL-адрес:So your HTTP request normally looks like the following URL:

https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?code=<API_KEY>

Ключ можно передать в переменной строки запроса с именем code, как показано выше.The key can be included in a query string variable named code, as above. Его также можно включить в заголовок HTTP x-functions-key.It can also be included in an x-functions-key HTTP header. Значением ключа может быть любой ключ функции, определенный для запрашиваемой функции, или любой ключ узла.The value of the key can be any function key defined for the function, or any host key.

Вы можете разрешить анонимные запросы, не требующие наличие ключей.You can allow anonymous requests, which do not require keys. Вы также можете указать, чтобы использовался главный ключ.You can also require that the master key be used. Уровень авторизации по умолчанию можно изменить с помощью свойства authLevel в объекте JSON для привязки.You change the default authorization level by using the authLevel property in the binding JSON. Дополнительные сведения см. в разделе Конфигурация триггера.For more information, see Trigger - configuration.

Примечание

При выполнении функций локально авторизация отключается независимо от указанного параметра уровня аутентификации.When running functions locally, authorization is disabled regardless of the specified authentication level setting. После публикации в Azure в триггере применяется параметр authLevel.After publishing to Azure, the authLevel setting in your trigger is enforced. Ключи по-прежнему требуются при локальном запуске в контейнере.Keys are still required when running locally in a container.

Защита конечной точки HTTP в рабочей средеSecure an HTTP endpoint in production

Чтобы полностью защитить функции конечных точек в рабочей среде, необходимо реализовать один из следующих вариантов безопасности на уровне приложения-функции:To fully secure your function endpoints in production, you should consider implementing one of the following function app-level security options:

  • Включить аутентификацию и авторизацию в Службе приложений для приложения-функции.Turn on App Service Authentication / Authorization for your function app. Платформа службы приложений позволяет использовать Azure Active Directory (AAD) и несколько сторонних поставщиков удостоверений для аутентификации клиентов.The App Service platform lets use Azure Active Directory (AAD) and several third-party identity providers to authenticate clients. Эта возможность позволяет реализовать пользовательские правила авторизации для функций и работать с информацией пользователя из кода функции.You can use this to implement custom authorization rules for your functions, and you can work with user information from your function code. Дополнительные сведения см. в разделе Работа с удостоверениями клиентов и статье Проверка подлинности и авторизация в службе приложений Azure.To learn more, see Authentication and authorization in Azure App Service and Working with client identities.

  • Используйте службу управления API Azure (APIM) для аутентификации запросов.Use Azure API Management (APIM) to authenticate requests. APIM предоставляет широкий набор параметров безопасности API для входящих запросов.APIM provides a variety of API security options for incoming requests. Дополнительные сведения см. в статье о политиках аутентификации службы "Управление API".To learn more, see API Management authentication policies. С помощью службы "Управление API" можно настроить приложение-функцию на прием запросов только с IP-адреса вашего экземпляра этой службы.With APIM in place, you can configure your function app to accept requests only from the IP address of your APIM instance. Дополнительные сведения см. в разделе Ограничения IP-адресов.To learn more, see IP address restrictions.

  • Разверните приложение-функцию в среде службы приложений Azure (ASE).Deploy your function app to an Azure App Service Environment (ASE). ASE предоставляет выделенную среду размещения, в которой можно выполнять функции.ASE provides a dedicated hosting environment in which to run your functions. ASE позволяет настроить один интерфейсный шлюз, который можно использовать для аутентификации всех входящих запросов.ASE lets you configure a single front-end gateway that you can use to authenticate all incoming requests. Дополнительные сведения см. в статье Настройка брандмауэра веб-приложения (WAF) для среды службы приложений.For more information, see Configuring a Web Application Firewall (WAF) for App Service Environment.

При использовании одного из этих методов обеспечения безопасности на уровне приложения-функции необходимо задать для функции, активируемой по HTTP, уровень аутентификации anonymous.When using one of these function app-level security methods, you should set the HTTP-triggered function authentication level to anonymous.

Объекты WebhookWebhooks

Примечание

Режим веб-перехватчика доступен только для версии 1.x среды выполнения функций.Webhook mode is only available for version 1.x of the Functions runtime. Это изменение внесено для повышения производительности триггеров HTTP в версии 2.x.This change was made to improve the performance of HTTP triggers in version 2.x.

В версии 1.x шаблоны веб-перехватчика обеспечивают дополнительную проверку полезных данных веб-перехватчика.In version 1.x, webhook templates provide additional validation for webhook payloads. В версии 2.x базовый HTTP-триггер по-прежнему работает и является рекомендуемым подходом для веб-перехватчиков.In version 2.x, the base HTTP trigger still works and is the recommended approach for webhooks.

Веб-перехватчики GitHubGitHub webhooks

Чтобы настроить ответ на вызовы веб-перехватчика GitHub, прежде всего создайте функцию с триггером HTTP, для которого свойство webHookType будет иметь значение github.To respond to GitHub webhooks, first create your function with an HTTP Trigger, and set the webHookType property to github. Затем скопируйте его URL-адрес и ключ API в репозиторий GitHub, используя страницу Добавить веб-перехватчик.Then copy its URL and API key into the Add webhook page of your GitHub repository.

Веб-перехватчики SlackSlack webhooks

Webhook Slack создает маркер автоматически и не позволяет вам задать его, поэтому необходимо настроить ключ для конкретной функции с использованием маркера, предоставленного Slack.The Slack webhook generates a token for you instead of letting you specify it, so you must configure a function-specific key with the token from Slack. Ознакомьтесь с разделом Ключи авторизации.See Authorization keys.

Веб-перехватчики и ключиWebhooks and keys

Авторизация веб-перехватчика обрабатывается компонентом получателя веб-перехватчика, который входит в состав триггера HTTP. Механизм обработки различается в зависимости от типа веб-перехватчика.Webhook authorization is handled by the webhook receiver component, part of the HTTP trigger, and the mechanism varies based on the webhook type. Каждый из этих механизмов зависит от ключей.Each mechanism does rely on a key. По умолчанию используется ключ функции с именем default.By default, the function key named "default" is used. Чтобы использовать другой ключ, необходимо настроить поставщик веб-перехватчика так, чтобы он отправлял имя ключа в составе запроса одним из следующих способов.To use a different key, configure the webhook provider to send the key name with the request in one of the following ways:

  • В строке запроса: поставщик передает имя ключа в параметре clientid строки запроса, например https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.Query string: The provider passes the key name in the clientid query string parameter, such as https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • В заголовке запроса: поставщик передает имя ключа в заголовке x-functions-clientid.Request header: The provider passes the key name in the x-functions-clientid header.

Триггер — ограниченияTrigger - limits

Длина HTTP-запроса ограничена 100 МБ (104 857 600 байт), а длина URL-адреса — 4 КБ (4096 байт).The HTTP request length is limited to 100 MB (104,857,600 bytes), and the URL length is limited to 4 KB (4,096 bytes). Эти ограничения задает элемент httpRuntime файла Web.config среды выполнения.These limits are specified by the httpRuntime element of the runtime's Web.config file.

Если функция, которая использует триггер HTTP, выполняется дольше 2,5 минут, будет превышено время ожидания шлюза и шлюз вернет ошибку HTTP 502.If a function that uses the HTTP trigger doesn't complete within about 2.5 minutes, the gateway will time out and return an HTTP 502 error. Функция продолжит работу, но вернуть ответ HTTP будет невозможно.The function will continue running but will be unable to return an HTTP response. Для долго выполняющихся функций рекомендуем следовать асинхронным шаблонам и возвращать расположение, в котором можно проверить состояние запроса.For long-running functions, we recommend that you follow async patterns and return a location where you can ping the status of the request. Чтобы узнать, как долго может выполняться функция, см. раздел Масштабирование и размещение — план.For information about how long a function can run, see Scale and hosting - Consumption plan.

Выходные данныеOutput

Привязка для вывода HTTP используется для ответа отправителю запроса HTTP.Use the HTTP output binding to respond to the HTTP request sender. Эта привязка требует наличия триггера HTTP и позволяет настроить ответ, возвращаемый на запрос этого триггера.This binding requires an HTTP trigger and allows you to customize the response associated with the trigger's request. Если привязка выходных данных HTTP не указана, в Функциях версии 1.x триггер HTTP возвращает ответ HTTP "200 — OK" с пустым текстом, а в Функциях версии 2.x — ответ "204 — содержимое отсутствует" с пустым текстом.If an HTTP output binding is not provided, an HTTP trigger returns HTTP 200 OK with an empty body in Functions 1.x, or HTTP 204 No Content with an empty body in Functions 2.x.

Выходная конфигурацияOutput - configuration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json.The following table explains the binding configuration properties that you set in the function.json file. Для библиотек класса C# свойства атрибута, соответствующие этим свойствам function.json, отсутствуют.For C# class libraries, there are no attribute properties that correspond to these function.json properties.

СвойствоProperty ОПИСАНИЕDescription
typetype Нужно задать значение http.Must be set to http.
directiondirection Нужно задать значение out.Must be set to out.
namename Имя переменной, используемое в коде функции для ответа, или $return для использования возвращаемого значения.The variable name used in function code for the response, or $return to use the return value.

Использование выходной привязкиOutput - usage

Чтобы отправить ответ HTTP, используйте шаблоны ответов языкового стандарта.To send an HTTP response, use the language-standard response patterns. В C# или скрипте C# задайте тип возвращаемого значения функции IActionResult или Task<IActionResult>.In C# or C# script, make the function return type IActionResult or Task<IActionResult>. В C# атрибут возвращаемого значения не является обязательным.In C#, a return value attribute isn't required.

Примеры ответов см. в разделе с примером триггера.For example responses, see the trigger example.

Параметры файла host.jsonhost.json settings

В этом разделе описываются глобальные параметры конфигурации, доступные для этой привязки в версии 2.x.This section describes the global configuration settings available for this binding in version 2.x. В приведенном ниже примере файла host.json содержатся только параметры версии 2.x для этой привязки.The example host.json file below contains only the version 2.x settings for this binding. Дополнительные сведения о глобальных параметрах конфигурации в версии 2.x см. в статье Справочник по файлу host.json для Функций Azure.For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.

Примечание

Чтобы получить дополнительные сведения о файле host.json в Функции 1.x, см. статью host.json reference for Azure Functions 1.x(Справочник по файлу host.json для службы "Функции Azure" версии 1.x.).For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "extensions": {
        "http": {
            "routePrefix": "api",
            "maxOutstandingRequests": 200,
            "maxConcurrentRequests": 100,
            "dynamicThrottlesEnabled": true,
            "hsts": {
                "isEnabled": true,
                "maxAge": "10"
            },
            "customHeaders": {
                "X-Content-Type-Options": "nosniff"
            }
        }
    }
}
СвойствоProperty значение по умолчаниюDefault ОПИСАНИЕDescription
кустомхеадерсcustomHeaders Nonenone Позволяет задавать пользовательские заголовки в HTTP-ответе.Allows you to set custom headers in the HTTP response. В предыдущем примере в ответ добавляется заголовок X-Content-Type-Options, чтобы избежать перехвата типа содержимого.The previous example adds the X-Content-Type-Options header to the response to avoid content type sniffing.
dynamicThrottlesEnableddynamicThrottlesEnabled true*true* Если этот параметр включен, он заставляет конвейер обработки запросов периодически проверять счетчики производительности системы (подключений, потоков, процессов, памяти, ЦП и т. д.). При превышении встроенного порогового высокого значения (80 %) любого из этих счетчиков запросы будут отклоняться с ответом "429 — cлишком много запросов" до тех пор, пока счетчики не вернутся к нормальному уровню.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.
* По умолчанию в плане потребления true.*The default in a consumption plan is true. Значение по умолчанию в выделенном плане — false.The default in a dedicated plan is false.
HSTShsts не включеноnot enabled Если для параметра isEnabled задано значение true, то принудительное поведение протокола HTTP (HSTS) в .NET Core применяется, как определено в классеHstsOptions.When isEnabled is set to true, the HTTP Strict Transport Security (HSTS) behavior of .NET Core is enforced, as defined in the HstsOptions class. Приведенный выше пример также задает для свойства maxAge значение 10 дней.The above example also sets the maxAge property to 10 days. Поддерживаемые свойства hsts:Supported properties of hsts are:
СвойствоPropertyОПИСАНИЕDescription
ексклудедхостсexcludedHostsМассив строк имен узлов, для которого заголовок HSTS не добавляется.A string array of host names for which the HSTS header isn't added.
includeSubDomainsincludeSubDomainsЛогическое значение, указывающее, включен ли параметр Инклудесубдомаин заголовка с уровнем безопасности "Долгосрочный транспорт — Безопасность".Boolean value that indicates whether the includeSubDomain parameter of the Strict-Transport-Security header is enabled.
maxAgemaxAgeСтрока, определяющая параметр max-age заголовка с ограничением транспорта по безопасности.String that defines the max-age parameter of the Strict-Transport-Security header.
УстановкаpreloadЛогическое значение, указывающее, включен ли параметр предварительной загрузки заголовка с уровнем безопасности "Долгосрочный транспорт — Безопасность".Boolean that indicates whether the preload parameter of the Strict-Transport-Security header is enabled.
maxConcurrentRequestsmaxConcurrentRequests 100*100* Максимальное число функций HTTP, выполняемых параллельно.The maximum number of http functions that are executed in parallel. Это позволяет регулировать параллелизм, что может помочь в управлении использованием ресурсов.This allows you to control concurrency, which can help manage resource utilization. Например, у вас может быть HTTP-функция, использующая много системных ресурсов (памяти, ЦП или сокетов) таким образом, что при слишком высоком параллелизме это вызывает проблемы.For example, you might have an http function that uses a lot 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.
* Значение по умолчанию для плана потребления — 100.*The default for a consumption plan is 100. Значение по умолчанию для выделенного плана не ограничено (-1).The default for a dedicated plan is unbounded (-1).
maxOutstandingRequestsmaxOutstandingRequests 200*200* Максимальное число невыполненных запросов, которое хранится в любой отдельно взятый момент времени.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. Все входящие запросы, превышающие это ограничение, отклоняются с ответом 429 "Too Busy" (Перегрузка).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. Она не влияет на другие очереди, такие как очередь запросов ASP.NET.Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting.
*\се по умолчанию для плана потребления 200.*\The default for a consumption plan is 200. Значение по умолчанию для выделенного плана не ограничено (-1).The default for a dedicated plan is unbounded (-1).
routePrefixroutePrefix apiapi Префикс маршрута, который применяется ко всем маршрутам.The route prefix that applies to all routes. Используйте пустую строку, чтобы удалить префикс по умолчанию.Use an empty string to remove the default prefix.

Дополнительная информацияNext steps

Основные понятия триггеров и привязок в Функциях AzureLearn more about Azure functions triggers and bindings