Функции HTTPHTTP Features

Устойчивые функции имеет несколько функций, которые упрощают внедрение устойчивых оркестрации и сущностей в рабочие процессы HTTP.Durable Functions has several features that make it easy to incorporate durable orchestrations and entities into HTTP workflows. В этой статье подробно рассматриваются некоторые из этих функций.This article goes into detail about some of those features.

Предоставление API-интерфейсов HTTPExposing HTTP APIs

Оркестрации и сущности могут вызываться и управляться с помощью HTTP-запросов.Orchestrations and entities can be invoked and managed using HTTP requests. Расширение Устойчивые функции предоставляет встроенные API HTTP.The Durable Functions extension exposes built-in HTTP APIs. Он также предоставляет интерфейсы API для взаимодействия с оркестрации и сущностями из функций, активируемых HTTP.It also provides APIs for interacting with orchestrations and entities from within HTTP-triggered functions.

Встроенные API HTTPBuilt-in HTTP APIs

Расширение Устойчивые функции автоматически добавляет набор API-интерфейсов HTTP к узлу функций Azure.The Durable Functions extension automatically adds a set of HTTP APIs to the Azure Functions host. С помощью этих API-интерфейсов можно взаимодействовать и управлять согласованиями и сущностями без написания кода.With these APIs, you can interact with and manage orchestrations and entities without writing any code.

Поддерживаются следующие встроенные API HTTP.The following built-in HTTP APIs are supported.

Полное описание всех встроенных API HTTP, предоставляемых расширением Устойчивые функции, см. в статье API-интерфейсы HTTP .See the HTTP APIs article for a full description of all the built-in HTTP APIs exposed by the Durable Functions extension.

Обнаружение URL-адреса API HTTPHTTP API URL discovery

Привязка клиента оркестрации предоставляет интерфейсы API, которые могут создавать удобные полезные данные ответа HTTP.The orchestration client binding exposes APIs that can generate convenient HTTP response payloads. Например, он может создать ответ, содержащий ссылки на API управления для конкретного экземпляра оркестрации.For example, it can create a response containing links to management APIs for a specific orchestration instance. В следующих примерах показана функция HTTP-триггера, которая демонстрирует использование этого API для нового экземпляра оркестрации:The following examples show an HTTP-trigger function that demonstrates how to use this API for a new orchestration instance:

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See LICENSE in the project root for license information.

using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace VSSample
{
    public static class HttpStart
    {
        [FunctionName("HttpStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}")] HttpRequestMessage req,
            [DurableClient] IDurableClient starter,
            string functionName,
            ILogger log)
        {
            // Function input comes from the request content.
            object eventData = await req.Content.ReadAsAsync<object>();
            string instanceId = await starter.StartNewAsync(functionName, eventData);

            log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

            return starter.CreateCheckStatusResponse(req, instanceId);
        }
    }
}

Запуск функции Orchestrator с помощью функций HTTP-триггеров, показанных выше, можно выполнить с помощью любого клиента HTTP.Starting an orchestrator function by using the HTTP-trigger functions shown previously can be done using any HTTP client. В следующей фигурной команде запускается функция Orchestrator с именем DoWork:The following cURL command starts an orchestrator function named DoWork:

curl -X POST https://localhost:7071/orchestrators/DoWork -H "Content-Length: 0" -i

Далее приведен пример ответа для оркестрации, имеющего abc123 в качестве идентификатора.Next is an example response for an orchestration that has abc123 as its ID. Некоторые сведения были удалены для ясности.Some details have been removed for clarity.

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX
Retry-After: 10

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX"
}

В предыдущем примере каждое из полей, оканчивающихся на Uri, соответствует встроенному API HTTP.In the previous example, each of the fields ending in Uri corresponds to a built-in HTTP API. Эти API можно использовать для управления целевым экземпляром оркестрации.You can use these APIs to manage the target orchestration instance.

Примечание

Формат URL-адресов веб перехватчика зависит от версии используемого узла функций Azure.The format of the webhook URLs depends on which version of the Azure Functions host you are running. Предыдущий пример относится к узлу функции Azure 2,0.The previous example is for the Azure Functions 2.0 host.

Описание всех встроенных API HTTP см. в справочнике по API HTTP.For a description of all built-in HTTP APIs, see the HTTP API reference.

Отслеживание асинхронных операцийAsync operation tracking

Упомянутый ранее HTTP-ответ предназначен для помощи в реализации долго выполняющихся асинхронных API-интерфейсов HTTP с устойчивыми функциями.The HTTP response mentioned previously is designed to help implement long-running HTTP async APIs with Durable Functions. Этот шаблон иногда называют шаблоном объекта-получателя опроса.This pattern is sometimes referred to as the polling consumer pattern. Поток клиента или сервера работает следующим образом:The client/server flow works as follows:

  1. Клиент отправляет запрос HTTP для запуска длительного процесса, например, функции Orchestrator.The client issues an HTTP request to start a long-running process like an orchestrator function.
  2. Целевой триггер HTTP возвращает ответ HTTP 202 с заголовком Location со значением "statusQueryGetUri".The target HTTP trigger returns an HTTP 202 response with a Location header that has the value "statusQueryGetUri".
  3. Клиент опрашивает URL-адрес в заголовке Location.The client polls the URL in the Location header. Клиент продолжит видеть ответы HTTP 202 с заголовком Location.The client continues to see HTTP 202 responses with a Location header.
  4. Когда экземпляр завершается или завершается ошибкой, конечная точка в заголовке Location возвращает HTTP 200.When the instance finishes or fails, the endpoint in the Location header returns HTTP 200.

Этот протокол обеспечивает координацию длительно выполняющихся процессов с внешними клиентами или службами, которые могут опрашивать конечную точку HTTP и следовать заголовку Location.This protocol allows coordination of long-running processes with external clients or services that can poll an HTTP endpoint and follow the Location header. Серверные и клиентские реализации этого шаблона встроены в API-интерфейсы Устойчивые функции HTTP.Both the client and server implementations of this pattern are built into the Durable Functions HTTP APIs.

Примечание

По умолчанию все действия на основе HTTP, предоставляемые Azure Logic Apps, поддерживают стандартную модель асинхронных операций.By default, all HTTP-based actions provided by Azure Logic Apps support the standard asynchronous operation pattern. Эта возможность позволяет внедрять долго выполняющиеся устойчивые функции в рамках рабочего процесса Logic Apps.This capability makes it possible to embed a long-running durable function as part of a Logic Apps workflow. Дополнительные сведения о Logic Apps поддержки для асинхронных шаблонов HTTP см. в документации по действиям и триггерам рабочего процесса Azure Logic Apps.You can find more details on Logic Apps support for asynchronous HTTP patterns in the Azure Logic Apps workflow actions and triggers documentation.

Примечание

Взаимодействие с оркестрации можно выполнять из любого типа функции, а не только с помощью функций, активируемых HTTP.Interactions with orchestrations can be done from any function type, not just HTTP-triggered functions.

Дополнительные сведения об управлении согласованиями и сущностями с помощью клиентских API см. в статье Управление экземплярами.For more information on how to manage orchestrations and entities using client APIs, see the Instance management article.

Использование API-интерфейсов HTTPConsuming HTTP APIs

Как описано в статье ограничения кода функции Orchestrator, функции Orchestrator не могут выполнять операции ввода-вывода напрямую.As described in the orchestrator function code constraints, orchestrator functions can't do I/O directly. Вместо этого они обычно вызывают функции действий , которые выполняют операции ввода-вывода.Instead, they typically call activity functions that do I/O operations.

Начиная с Устойчивые функции 2,0, оркестрации могут использовать API-интерфейсы HTTP с помощью привязки триггера оркестрации.Starting with Durable Functions 2.0, orchestrations can natively consume HTTP APIs by using the orchestration trigger binding.

В следующем примере кода показана функция Orchestrator, выполняющая исходящий HTTP-запрос:The following example code shows an orchestrator function making an outbound HTTP request:

[FunctionName("CheckSiteAvailable")]
public static async Task CheckSiteAvailable(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    Uri url = context.GetInput<Uri>();

    // Makes an HTTP GET request to the specified endpoint
    DurableHttpResponse response = 
        await context.CallHttpAsync(HttpMethod.Get, url);

    if (response.StatusCode >= 400)
    {
        // handling of error codes goes here
    }
}

С помощью действия Call HTTP можно выполнять следующие действия в функциях Orchestrator:By using the "call HTTP" action, you can do the following actions in your orchestrator functions:

  • Вызывайте API HTTP непосредственно из функций оркестрации с некоторыми ограничениями, упомянутыми позже.Call HTTP APIs directly from orchestration functions, with some limitations that are mentioned later.
  • Автоматически поддерживает шаблоны опроса состояния HTTP 202 на стороне клиента.Automatically support client-side HTTP 202 status polling patterns.
  • Используйте управляемые удостоверения Azure для выполнения санкционированных вызовов HTTP к другим конечным точкам Azure.Use Azure Managed Identities to make authorized HTTP calls to other Azure endpoints.

Возможность использования API-интерфейсов HTTP непосредственно из функций Orchestrator предназначена для удобства работы с определенным набором распространенных сценариев.The ability to consume HTTP APIs directly from orchestrator functions is intended as a convenience for a certain set of common scenarios. Все эти функции можно реализовать самостоятельно с помощью функций действий.You can implement all of these features yourself using activity functions. Во многих случаях функции действий могут обеспечить большую гибкость.In many cases, activity functions might give you more flexibility.

Обработка HTTP 202HTTP 202 handling

API "Call HTTP" может автоматически реализовать клиентскую сторону шаблона опрашивающего потребителя.The "call HTTP" API can automatically implement the client side of the polling consumer pattern. Если вызываемый API возвращает ответ HTTP 202 с заголовком Location, функция Orchestrator автоматически опрашивает ресурс расположения, пока не получит ответ, отличный от 202.If a called API returns an HTTP 202 response with a Location header, the orchestrator function automatically polls the Location resource until receiving a response other than 202. Ответ будет возвращен в код функции Orchestrator.This response will be the response returned to the orchestrator function code.

Примечание

Функции Orchestrator также изначально поддерживают клиентский шаблон опроса на стороне сервера, как описано в разделе Отслеживание асинхронных операций.Orchestrator functions also natively support the server-side polling consumer pattern, as described in Async operation tracking. Такая поддержка означает, что согласование в одном приложении функции может легко координировать функции Orchestrator в других приложениях функций.This support means that orchestrations in one function app can easily coordinate the orchestrator functions in other function apps. Это похоже на концепцию подсистемы оркестрации , но с поддержкой взаимодействия между приложениями.This is similar to the sub-orchestration concept, but with support for cross-app communication. Эта поддержка особенно полезна при разработке приложений в стиле микрослужб.This support is particularly useful for microservice-style app development.

Управляемые удостоверенияManaged identities

Устойчивые функции изначально поддерживает вызовы API, которые принимают маркеры Azure Active Directory (Azure AD) для авторизации.Durable Functions natively supports calls to APIs that accept Azure Active Directory (Azure AD) tokens for authorization. Эта поддержка использует управляемые удостоверения Azure для получения этих маркеров.This support uses Azure managed identities to acquire these tokens.

Следующий код является примером функции .NET Orchestrator.The following code is an example of a .NET orchestrator function. Функция выполняет проверку подлинности вызовов для перезапуска виртуальной машины с помощью Azure Resource Manager виртуальных машин REST API.The function makes authenticated calls to restart a virtual machine by using the Azure Resource Manager virtual machines REST API.

[FunctionName("RestartVm")]
public static async Task RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string subscriptionId = "mySubId";
    string resourceGroup = "myRG";
    string vmName = "myVM";
    string apiVersion = "2019-03-01";
    
    // Automatically fetches an Azure AD token for resource = https://management.core.windows.net
    // and attaches it to the outgoing Azure Resource Manager API call.
    var restartRequest = new DurableHttpRequest(
        HttpMethod.Post, 
        new Uri($"https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Compute/virtualMachines/{vmName}/restart?api-version={apiVersion}"),
        tokenSource: new ManagedIdentityTokenSource("https://management.core.windows.net"));
    DurableHttpResponse restartResponse = await context.CallHttpAsync(restartRequest);
    if (restartResponse.StatusCode != HttpStatusCode.OK)
    {
        throw new ArgumentException($"Failed to restart VM: {restartResponse.StatusCode}: {restartResponse.Content}");
    }
}

В предыдущем примере параметр tokenSource настроен для получения маркеров Azure AD для Azure Resource Manager.In the previous example, the tokenSource parameter is configured to acquire Azure AD tokens for Azure Resource Manager. Токены идентифицируются https://management.core.windows.netURI ресурса.The tokens are identified by the resource URI https://management.core.windows.net. В этом примере предполагается, что текущее приложение-функция выполняется локально или развернуто как приложение-функция с управляемым удостоверением.The example assumes that the current function app either is running locally or was deployed as a function app with a managed identity. Предполагается, что локальным удостоверением или управляемым удостоверением предоставлено разрешение на управление виртуальными машинами в указанной группе ресурсов myRG.The local identity or the managed identity is assumed to have permission to manage VMs in the specified resource group myRG.

Во время выполнения настроенный источник токена автоматически возвращает маркер доступа OAuth 2,0.At runtime, the configured token source automatically returns an OAuth 2.0 access token. Затем источник добавляет маркер в качестве токена носителя в заголовок авторизации исходящего запроса.The source then adds the token as a bearer token to the Authorization header of the outgoing request. Эта модель является улучшением по сравнению с добавлением заголовков авторизации вручную в HTTP-запросы по следующим причинам.This model is an improvement over manually adding authorization headers to HTTP requests for the following reasons:

  • Обновление токена обрабатывается автоматически.Token refresh is handled automatically. Вам не нужно беспокоиться о токенах с истекшим сроком действия.You don't need to worry about expired tokens.
  • Токены никогда не хранятся в состоянии устойчивого оркестрации.Tokens are never stored in the durable orchestration state.
  • Вам не нужно писать код для управления получением маркера.You don't need to write any code to manage token acquisition.

Более полный пример можно найти в примере предварительно C# скомпилированного рестартвмс.You can find a more complete example in the precompiled C# RestartVMs sample.

Управляемые удостоверения не ограничиваются управлением ресурсами Azure.Managed identities aren't limited to Azure resource management. Управляемые удостоверения можно использовать для доступа к любому API, который принимает токены носителя Azure AD, включая службы Azure из Майкрософт и веб-приложения от партнеров.You can use managed identities to access any API that accepts Azure AD bearer tokens, including Azure services from Microsoft and web apps from partners. Веб-приложение партнера может даже быть другим приложением-функцией.A partner's web app can even be another function app. Список служб Azure, которые поддерживают проверку подлинности в Azure AD, см. в статье службы Azure, поддерживающие аутентификацию Azure AD.For a list of Azure services from Microsoft that support authentication with Azure AD, see Azure services that support Azure AD authentication.

ОграниченияLimitations

Встроенная поддержка вызова API-интерфейсов HTTP является удобной функцией.The built-in support for calling HTTP APIs is a convenience feature. Это не подходит для всех сценариев.It's not appropriate for all scenarios.

HTTP-запросы, отправленные функциями Orchestrator и их ответами, сериализуются и сохраняются как сообщения очереди.HTTP requests sent by orchestrator functions and their responses are serialized and persistent as queue messages. Такое поведение очередей гарантирует надежность и безопасность HTTP-вызовов при воспроизведении оркестрации.This queueing behavior ensures HTTP calls are reliable and safe for orchestration replay. Однако поведение очереди также имеет ограничения.However, the queuing behavior also has limitations:

  • Каждый HTTP-запрос требует дополнительной задержки по сравнению с собственным HTTP-клиентом.Each HTTP request involves additional latency when compared to a native HTTP client.
  • Большие сообщения запроса или ответа, которые не могут поместиться в очередь, могут значительно снизить производительность оркестрации.Large request or response messages that can't fit into a queue message can significantly degrade orchestration performance. Накладные расходы на разгрузку полезных данных сообщений в хранилище BLOB-объектов могут привести к снижению производительности.The overhead of offloading message payloads to blob storage can cause potential performance degradation.
  • Потоковая передача, фрагментированность и двоичные данные не поддерживаются.Streaming, chunked, and binary payloads aren't supported.
  • Возможность настройки поведения клиента HTTP ограничена.The ability to customize the behavior of the HTTP client is limited.

Если какое-либо из этих ограничений может повлиять на ваш вариант использования, вместо этого следует использовать функции действий и клиентские библиотеки HTTP, зависящие от языка, для выполнения исходящих вызовов HTTP.If any of these limitations might affect your use case, consider instead using activity functions and language-specific HTTP client libraries to make outbound HTTP calls.

Примечание

Если вы являетесь разработчиком .NET, то можете спросить, почему эта функция использует типы дураблехттпрекуест и дураблехттпреспонсе вместо встроенных типов .NET HttpRequestMessage и HttpResponseMessage .If you are a .NET developer, you might wonder why this feature uses the DurableHttpRequest and DurableHttpResponse types instead of the built-in .NET HttpRequestMessage and HttpResponseMessage types.

Такое поведение реализовано намеренно.This design choice is intentional. Основная причина заключается в том, что пользовательские типы помогают убедиться в том, что пользователи не делают неправильные предположения о поддерживаемых поведениях внутреннего HTTP-клиента.The primary reason is that custom types help ensure users don't make incorrect assumptions about the supported behaviors of the internal HTTP client. Типы, характерные для Устойчивые функции, позволяют упростить разработку API.Types specific to Durable Functions also make it possible to simplify API design. Они также могут упростить доступ к специальным функциям, таким как Интеграция управляемой идентификации и шаблон опрашивающего потребителя.They also can more easily make available special features like managed identity integration and the polling consumer pattern.

Расширяемость (только .NET)Extensibility (.NET only)

Настройка поведения внутреннего HTTP-клиента оркестрации возможна с помощью внедрения зависимостей .NET для функций Azure.Customizing the behavior of the orchestration's internal HTTP client is possible using Azure Functions .NET dependency injection. Эта возможность может быть полезной для внесения небольших изменений в поведение.This ability can be useful for making small behavioral changes. Он также может быть полезен для модульного тестирования HTTP-клиента путем внедрения макетов объектов.It can also be useful for unit testing the HTTP client by injecting mock objects.

В следующем примере демонстрируется использование внедрения зависимостей для отключения проверки SSL-сертификата для функций Orchestrator, вызывающих внешние конечные точки HTTP.The following example demonstrates using dependency injection to disable SSL certificate validation for orchestrator functions that call external HTTP endpoints.

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        // Register own factory
        builder.Services.AddSingleton<
            IDurableHttpMessageHandlerFactory,
            MyDurableHttpMessageHandlerFactory>();
    }
}

public class MyDurableHttpMessageHandlerFactory : IDurableHttpMessageHandlerFactory
{
    public HttpMessageHandler CreateHttpMessageHandler()
    {
        // Disable SSL certificate validation (not recommended in production!)
        return new HttpClientHandler
        {
            ServerCertificateCustomValidationCallback =
                HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
        };
    }
}

Дальнейшие действияNext steps