Функции HTTP

Статья
11/11/2024

Устойчивые функции имеет несколько возможностей, которые упрощают внедрение устойчивых оркестраций и сущностей в рабочие процессы HTTP. В этой статье подробно рассматриваются некоторые из этих функций.

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

Оркестрации и сущности могут вызываться и управляться с помощью HTTP-запросов. Расширение "Устойчивые функции" предоставляет встроенные API HTTP. Оно также предоставляет интерфейсы API для взаимодействия с оркестрациями и сущностями из функций, активируемых HTTP.

Встроенные API HTTP

Расширение "Устойчивые функции" автоматически добавляет набор API-интерфейсов HTTP к узлу Функций Azure. С помощью этих API-интерфейсов можно взаимодействовать и управлять согласованиями и сущностями без написания кода.

Поддерживаются следующие встроенные API-интерфейсы HTTP.

Полное описание всех встроенных API HTTP, предоставляемых расширением "Устойчивые функции", см. в статье об API-интерфейсах HTTP.

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

Привязка клиента оркестрации предоставляет API, которые могут создавать удобные полезные данные ответа HTTP. Например, может создаваться ответ, содержащий ссылки на API управления для конкретного экземпляра оркестрации. В следующих примерах показана функция HTTP-триггера, которая демонстрирует использование этого API для нового экземпляра оркестрации.

// 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);
        }
    }
}

/// <summary>
/// HTTP-triggered function that starts the <see cref="HelloCitiesUntyped"/> orchestration.
/// </summary>
/// <param name="req">The HTTP request that was used to trigger this function.</param>
/// <param name="client">The DurableTask client that is used to start and manage orchestration instances.</param>
/// <param name="executionContext">The Azure Functions execution context, which is available to all function types.</param>
/// <returns>Returns an HTTP response with more information about the started orchestration instance.</returns>
[Function(nameof(StartHelloCitiesUntyped))]
public static async Task<HttpResponseData> StartHelloCitiesUntyped(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    [DurableClient] DurableTaskClient client,
    FunctionContext executionContext)
{
    ILogger logger = executionContext.GetLogger(nameof(StartHelloCitiesUntyped));

    string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(nameof(HelloCitiesUntyped));
    logger.LogInformation("Created new orchestration with instance ID = {instanceId}", instanceId);

    // Returns an HTTP response with a payload that includes links to built-in HTTP management payloads
    return client.CreateCheckStatusResponse(req, instanceId);
}

Примечание.

В CreateCheckStatusResponse настоящее время api и связанные с ними интерфейсы поддерживают HttpRequestData только типы и HttpResponseData типы при работе с функциями, активировав HTTP. ГАДЮКА. В настоящее время определяемые NET типы не поддерживаются.

index.js

const df = require("durable-functions");

module.exports = async function (context, req) {
    const client = df.getClient(context);
    const instanceId = await client.startNew(req.params.functionName, undefined, req.body);

    context.log(`Started orchestration with ID = '${instanceId}'.`);

    return client.createCheckStatusResponse(context.bindingData.req, instanceId);
};

function.json

{
    "bindings": [
      {
        "authLevel": "anonymous",
        "name": "req",
        "type": "httpTrigger",
        "direction": "in",
        "route": "orchestrators/{functionName}",
        "methods": ["post"]
      },
      {
        "name": "$return",
        "type": "http",
        "direction": "out"
      },
      {
        "name": "starter",
        "type": "orchestrationClient",
        "direction": "in"
      }
    ],
    "disabled": false
  }

init.py

import logging
import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    function_name = req.route_params['functionName']
    event_data = req.get_body()

    instance_id = await client.start_new(function_name, instance_id, event_data)
    
    logging.info(f"Started orchestration with ID = '{instance_id}'.")
    return client.create_check_status_response(req, instance_id)

function.json

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{functionName}",
      "methods": [
        "post",
        "get"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "orchestrationClient",
      "direction": "in"
    }
  ]
}

run.ps1

$FunctionName = $Request.Params.FunctionName
$InstanceId = Start-NewOrchestration -FunctionName $FunctionName
Write-Host "Started orchestration with ID = '$InstanceId'"

$Response = New-OrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
Push-OutputBinding -Name Response -Value $Response

function.json

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{FunctionName}",
      "methods": [
        "post",
        "get"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "name": "starter",
      "type": "orchestrationClient",
      "direction": "in"
    }
  ]
}

@FunctionName("HttpStart")
public HttpResponseMessage httpStart(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("functionName") String functionName,
        final ExecutionContext context) {

    DurableTaskClient client = durableContext.getClient();
    String instanceId = client.scheduleNewOrchestrationInstance(functionName);
    context.getLogger().info("Created new Java orchestration with instance ID = " + instanceId);
    return durableContext.createCheckStatusResponse(req, instanceId);
}

Запуск функции оркестратора с помощью функций HTTP-триггеров, показанных выше, можно выполнить с помощью любого клиента HTTP. Следующая команда cURL запускает функцию оркестратора с именем DoWork:

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

Далее приведен пример ответа для оркестрации с идентификатором abc123. Некоторые сведения были удалены для ясности.

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. Эти API можно использовать для управления целевым экземпляром оркестрации.

Примечание.

Формат URL-адресов веб-перехватчиков зависит от того, какая версия узла Функций Azure выполняется. Описанный выше пример предназначен для узла Функций Azure 2.0.

Описание всех встроенных API HTTP см. в справочнике по API HTTP.

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

Упомянутый ранее HTTP-ответ предназначен для помощи в реализации долго выполняющихся асинхронных API-интерфейсов HTTP с устойчивыми функциями. Такой шаблон иногда называется шаблоном опрашивающего объекта-получателя. Поток клиента или сервера работает следующим образом:

Клиент отправляет запрос HTTP для запуска длительного процесса, например функции оркестратора.
Целевой триггер HTTP возвращает ответ HTTP 202 с заголовком Location со значением "statusQueryGetUri".
Клиент отправляет URL-адрес в заголовке Location. Он продолжает просматривать ответы HTTP 202 с заголовком Location.
При завершении (или сбое) экземпляра конечная точка в заголовке Location возвращает ответ HTTP 200.

Этот протокол позволяет согласовать долго выполняющиеся процессы с помощью внешних клиентов или служб, которые могут отправлять запрос конечной точки HTTP и используют заголовок Location. Серверные и клиентские реализации этого шаблона встроены в API-интерфейсы HTTP службы "Устойчивые функции".

Примечание.

По умолчанию все действия на основе HTTP, предоставляемые Azure Logic Apps, поддерживают стандартную модель асинхронных операций. Эта возможность позволяет внедрять долго выполняющиеся устойчивые функции в рамках рабочего процесса Logic Apps. Дополнительные сведения о поддержке Logic Apps для асинхронных шаблонов HTTP см. в документации по действиям рабочих процессов и триггерам Azure Logic Apps.

Примечание.

Взаимодействие с оркестрациями можно осуществлять из любого типа функции, а не только с помощью функций, активируемых HTTP.

Дополнительные сведения об управлении оркестрациями и сущностями с помощью клиентских API см. в статье об управлении экземплярами.

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

Как описано в статье об ограничениях кода функции оркестратора, функции оркестрации не могут выполнять операции ввода-вывода напрямую. Вместо этого они обычно вызывают функции действий, которые выполняют операции ввода-вывода.

Начиная с версии 2.0 службы "Устойчивые функции", оркестрации могут использовать API-интерфейсы HTTP с помощью привязки триггера оркестрации.

В следующем примере кода показана функция оркестратора, выполняющая исходящий HTTP-запрос:

[FunctionName(nameof(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
    }
}

Примечание.

Вы можете задаться вопросом, почему эта функция использует типы DurableHttpRequest и DurableHttpResponse вместо встроенных типов HttpRequestMessage и HttpResponseMessage.

Такое поведение реализовано намеренно. Основная причина заключается в том, что пользовательские типы помогают убедиться в том, что пользователи не делают неправильные предположения о поддерживаемых поведениях внутреннего HTTP-клиента. Типы, характерные для Устойчивых функций, позволяют упростить разработку API. Они также могут упростить доступ к специальным функциям, таким как Интеграция управляемой идентификации и шаблон опрашивающего объекта-получателя.

[Function(nameof(CheckSiteAvailable))]
public static async Task CheckSiteAvailable(
    [OrchestrationTrigger] TaskOrchestrationContext 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 >= HttpStatusCode.BadRequest)
    {
        // handling of error codes goes here
    }
}

Примечание.

Такое поведение реализовано намеренно. Основная причина заключается в том, что пользовательские типы помогают убедиться в том, что пользователи не делают неправильные предположения о поддерживаемых поведениях внутреннего HTTP-клиента. Типы, характерные для Устойчивых функций, позволяют упростить разработку API. Кроме того, они могут сделать доступными специальные функции, которые не являются частью встроенных типов платформ.

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context){
    const url = context.df.getInput();
    const response = yield context.df.callHttp("GET", url)

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

import azure.functions as func
import azure.durable_functions as df
from datetime import datetime, timedelta

def orchestrator_function(context: df.DurableOrchestrationContext):
    url = context.get_input()
    response = yield context.call_http('GET', url)
    
    if response["statusCode"] >= 400:
        # handling of error codes goes here

main = df.Orchestrator.create(orchestrator_function)

С помощью действия "вызов HTTP" можно выполнять следующие действия в функциях оркестратора:

Вызывать API HTTP непосредственно из функций оркестрации с некоторыми ограничениями, упомянутыми ниже.
Автоматически поддерживать шаблоны опроса состояния HTTP 202 на стороне клиента.
Использовать управляемые удостоверения Azure для выполнения санкционированных вызовов HTTP к другим конечным точкам Azure.

Возможность использования API-интерфейсов HTTP непосредственно из функций оркестратора предназначена для удобства работы с определенным набором распространенных сценариев. Все эти функции можно реализовать самостоятельно с помощью функций действий. Во многих случаях функции действий могут обеспечить большую гибкость.

Обработка HTTP 202 (только в процессе.NET)

API "вызов HTTP" может автоматически реализовать клиентскую сторону шаблона опрашивающего объекта-получателя. Если вызываемый API возвращает ответ HTTP 202 с заголовком Location, функция оркестратора автоматически опрашивает ресурс расположения, пока не получит ответ, отличный от 202. Ответ будет возвращен в код функции оркестратора.

Примечание.

Функции оркестратора также изначально поддерживают шаблон опрашивающего объекта-получателя на стороне сервера, как описано в разделе Отслеживание асинхронных операций. Такая поддержка означает, что согласование в одном приложении-функции может легко координировать функции оркестратора в других приложениях-функциях. Это похоже на концепцию вложенной оркестрации, но с поддержкой взаимодействия между приложениями. Эта поддержка особенно полезна при разработке приложений в стиле микрослужб.
Встроенный шаблон опроса HTTP в настоящее время доступен только в узле внутрипроцессного процесса .NET.

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

Устойчивые функции изначально поддерживает вызовы API, которые принимают маркеры Microsoft Entra для авторизации. Эта поддержка использует управляемые удостоверения Azure для получения этих маркеров.

Следующий код является примером функции оркестратора. Функция выполняет проверку подлинности вызовов для перезапуска виртуальной машины с помощью REST API виртуальных машин Azure Resource Manager.

[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/.default
    // 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/.default"));
    DurableHttpResponse restartResponse = await context.CallHttpAsync(restartRequest);
    if (restartResponse.StatusCode != HttpStatusCode.OK)
    {
        throw new ArgumentException($"Failed to restart VM: {restartResponse.StatusCode}: {restartResponse.Content}");
    }
}

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const subscriptionId = "mySubId";
    const resourceGroup = "myRG";
    const vmName = "myVM";
    const apiVersion = "2019-03-01";
    const tokenSource = new df.ManagedIdentityTokenSource("https://management.core.windows.net/.default");

    // get a list of the Azure subscriptions that I have access to
    const restartResponse = yield context.df.callHttp(
        "POST",
        `https://management.azure.com/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.Compute/virtualMachines/${vmName}/restart?api-version=${apiVersion}`,
        undefined, // no request content
        undefined, // no request headers (besides auth which is handled by the token source)
        tokenSource);

    return restartResponse;
});

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    subscription_id = "mySubId"
    resource_group = "myRg"
    vm_name = "myVM"
    api_version = "2019-03-01"
    token_source = df.ManagedIdentityTokenSource("https://management.core.windows.net/.default")

    # get a list of the Azure subscriptions that I have access to
    restart_response = yield context.call_http("POST", 
        f"https://management.azure.com/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Compute/virtualMachines/{vm_name}/restart?api-version={api_version}",
        None,
        None,
        token_source)
    return restart_response

main = df.Orchestrator.create(orchestrator_function)

В предыдущем примере tokenSource параметр настроен для получения токенов Microsoft Entra для Azure Resource Manager. Маркеры идентифицируются с помощью URI ресурса https://management.core.windows.net/.default. В этом примере предполагается, что текущее приложение-функция выполняется локально или развернуто как приложение-функция с управляемым удостоверением. Предполагается, что локальным удостоверениям или управляемым удостоверениям предоставлено разрешение на управление виртуальными машинами в указанной группе ресурсов myRG.

Во время выполнения настроенный источник маркера автоматически возвращает маркер доступа OAuth 2.0. Затем источник добавляет маркер в качестве маркера носителя в заголовок авторизации исходящего запроса. Эта модель является улучшением по сравнению с добавлением заголовков авторизации вручную в HTTP-запросы по следующим причинам.

Обновление маркера обрабатывается автоматически. Вам не нужно беспокоиться о маркерах с истекшим сроком действия.
Маркеры никогда не хранятся в состоянии устойчивой оркестрации.
Вам не нужно писать код для управления получением маркера.

Более полный пример можно найти в предварительно скомпилированном примере C# RestartVMs.

Управляемые удостоверения не ограничиваются управлением ресурсами Azure. Управляемые удостоверения можно использовать для доступа к любому API, который принимает маркеры носителя Microsoft Entra, включая службы Azure из Майкрософт и веб-приложений от партнеров. Партнерское веб-приложение может даже быть другим приложением-функцией. Список служб Azure от Майкрософт, поддерживающих проверку подлинности с помощью идентификатора Microsoft Entra, см . в службах Azure, поддерживающих проверку подлинности Microsoft Entra.

Ограничения

Встроенная поддержка вызова API-интерфейсов HTTP — это вспомогательная функция. Она подходит не для всех сценариев.

HTTP-запросы, отправленные функциями оркестратора, и ответы на них сериализуются и сохраняются как сообщения в поставщике хранилища устойчивых функций. Такое постоянное поведение очередей гарантирует, что HTTP-вызовы надежны и безопасны при воспроизведении оркестрации. Однако постоянное поведение очереди также имеет ограничения.

Каждый HTTP-запрос требует дополнительной задержки по сравнению с собственным HTTP-клиентом.
В зависимости от настроенного поставщика хранилища большие сообщения запроса или ответа могут значительно снизить производительность оркестрации. Например, при использовании службы хранилища Azure полезные данные HTTP, которые слишком велики для размещения в сообщениях очереди Azure, сжимаются и сохраняются в хранилище BLOB-объектов Azure.
Потоковая передача, фрагментированность и двоичные данные не поддерживаются.
Возможность настройки поведения клиента HTTP ограничена.

Если какое-либо из этих ограничений может повлиять на ваш вариант использования, вместо этого следует использовать функции действий и клиентские библиотеки HTTP, зависящие от языка, для выполнения исходящих вызовов HTTP.

Расширяемость (только для .NET в процессе)

Настройка поведения внутреннего HTTP-клиента оркестрации возможна с помощью внедрения Функции Azure зависимостей .NET для рабочей роли в процессе. Эта возможность может быть полезной для внесения небольших изменений в поведение. Она также может быть полезна для модульного тестирования HTTP-клиента путем внедрения макетов объектов.

В следующем примере демонстрируется использование внедрения зависимостей для отключения проверки сертификата TLS/SSL для функций оркестратора, вызывающих внешние конечные точки HTTP.

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 TLS/SSL certificate validation (not recommended in production!)
        return new HttpClientHandler
        {
            ServerCertificateCustomValidationCallback =
                HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
        };
    }
}

Следующие шаги

Подробнее об устойчивых сущностях

Поделиться через

Функции HTTP

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

Встроенные API HTTP

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

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

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

Обработка HTTP 202 (только в процессе.NET)

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

Ограничения

Расширяемость (только для .NET в процессе)

Следующие шаги

Обратная связь

Дополнительные ресурсы