Funkcje HTTP

Artykuł
10/18/2023

Rozszerzenie Durable Functions ma kilka funkcji, które ułatwiają dołączanie trwałych aranżacji i jednostek do przepływów pracy HTTP. Ten artykuł zawiera szczegółowe informacje na temat niektórych z tych funkcji.

Uwidacznianie interfejsów API PROTOKOŁU HTTP

Orkiestracje i jednostki mogą być wywoływane i zarządzane przy użyciu żądań HTTP. Rozszerzenie Durable Functions uwidacznia wbudowane interfejsy API HTTP. Udostępnia również interfejsy API umożliwiające interakcję z orkiestracjami i jednostkami z poziomu funkcji wyzwalanych przez protokół HTTP.

Wbudowane interfejsy API HTTP

Rozszerzenie Durable Functions automatycznie dodaje zestaw interfejsów API HTTP do hosta usługi Azure Functions. Te interfejsy API umożliwiają interakcję z orkiestracjami i jednostkami oraz zarządzanie nimi bez konieczności pisania kodu.

Obsługiwane są następujące wbudowane interfejsy API HTTP.

Zobacz artykuł dotyczący interfejsów API HTTP, aby uzyskać pełny opis wszystkich wbudowanych interfejsów API HTTP udostępnianych przez rozszerzenie Durable Functions.

Odnajdywanie adresów URL interfejsu API HTTP

Powiązanie klienta orkiestracji uwidacznia interfejsy API, które mogą generować wygodne ładunki odpowiedzi HTTP. Może na przykład utworzyć odpowiedź zawierającą linki do interfejsów API zarządzania dla określonego wystąpienia aranżacji. W poniższych przykładach pokazano funkcję wyzwalacza HTTP, która pokazuje, jak używać tego interfejsu API dla nowego wystąpienia aranżacji:

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

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

Uruchamianie funkcji orkiestratora przy użyciu funkcji wyzwalacza HTTP pokazanych wcześniej można wykonać przy użyciu dowolnego klienta HTTP. Następujące polecenie cURL uruchamia funkcję orkiestratora o nazwie DoWork:

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

Następnie jest to przykładowa odpowiedź na aranżację, która ma abc123 identyfikator. Niektóre szczegóły zostały usunięte w celu zapewnienia przejrzystości.

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

W poprzednim przykładzie każde z pól kończących się na Uri końcu odpowiada wbudowanemu interfejsowi API HTTP. Za pomocą tych interfejsów API można zarządzać docelowym wystąpieniem orkiestracji.

Uwaga

Format adresów URL elementu webhook zależy od wersji uruchomionego hosta usługi Azure Functions. Poprzedni przykład dotyczy hosta usługi Azure Functions 2.0.

Aby uzyskać opis wszystkich wbudowanych interfejsów API PROTOKOŁU HTTP, zobacz dokumentację interfejsu API PROTOKOŁU HTTP.

Śledzenie operacji asynchronicznych

Wcześniej wymieniona odpowiedź HTTP została zaprojektowana tak, aby ułatwić implementowanie długotrwałych interfejsów API asynchronicznych HTTP za pomocą rozszerzenia Durable Functions. Ten wzorzec jest czasami określany jako wzorzec odbiorcy sondowania. Przepływ klienta/serwera działa w następujący sposób:

Klient wysyła żądanie HTTP, aby uruchomić długotrwały proces, taki jak funkcja orkiestratora.
Docelowy wyzwalacz HTTP zwraca odpowiedź HTTP 202 z nagłówkiem Location o wartości "statusQueryGetUri".
Klient sonduje adres URL w nagłówku Lokalizacja. Klient nadal widzi odpowiedzi HTTP 202 z nagłówkiem Lokalizacja.
Gdy wystąpienie zakończy się niepowodzeniem lub zakończy się niepowodzeniem, punkt końcowy w nagłówku Lokalizacja zwraca błąd HTTP 200.

Ten protokół umożliwia koordynację długotrwałych procesów z klientami zewnętrznymi lub usługami, które mogą sondować punkt końcowy HTTP i postępować zgodnie z nagłówkiem Lokalizacja. Implementacje tego wzorca klienta i serwera są wbudowane w interfejsy API HTTP durable functions.

Uwaga

Domyślnie wszystkie akcje oparte na protokole HTTP udostępniane przez usługę Azure Logic Apps obsługują standardowy wzorzec operacji asynchronicznych. Ta funkcja umożliwia osadzanie długotrwałej funkcji trwałej w ramach przepływu pracy usługi Logic Apps. Więcej szczegółów na temat obsługi asynchronicznych wzorców HTTP usługi Logic Apps można znaleźć w dokumentacji akcji i wyzwalaczy przepływu pracy usługi Azure Logic Apps.

Uwaga

Interakcje z orkiestracjami można wykonywać z dowolnego typu funkcji, a nie tylko funkcji wyzwalanych przez protokół HTTP.

Aby uzyskać więcej informacji na temat zarządzania aranżacjami i jednostkami przy użyciu interfejsów API klienta, zobacz artykuł Zarządzanie wystąpieniami.

Korzystanie z interfejsów API HTTP

Zgodnie z opisem w ograniczeniach kodu funkcji orkiestratora funkcje orkiestratora nie mogą wykonywać bezpośrednio operacji we/wy. Zamiast tego zwykle wywołuje funkcje działań, które wykonują operacje we/wy.

Począwszy od rozszerzenia Durable Functions 2.0, orkiestracje mogą natywnie korzystać z interfejsów API HTTP przy użyciu powiązania wyzwalacza aranżacji.

Poniższy przykładowy kod przedstawia funkcję orkiestratora tworzącą wychodzące żądanie HTTP:

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

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)

Za pomocą akcji "Wywołaj http" możesz wykonać następujące akcje w funkcjach orkiestratora:

Wywołaj interfejsy API HTTP bezpośrednio z funkcji aranżacji, z pewnymi ograniczeniami, które zostały wymienione później.
Automatycznie obsługują wzorce sondowania stanu HTTP 202 po stronie klienta.
Użyj tożsamości zarządzanych platformy Azure, aby wykonywać autoryzowane wywołania HTTP do innych punktów końcowych platformy Azure.

Możliwość korzystania z interfejsów API HTTP bezpośrednio z funkcji orkiestratora jest przeznaczona dla określonego zestawu typowych scenariuszy. Wszystkie te funkcje można zaimplementować samodzielnie przy użyciu funkcji działań. W wielu przypadkach funkcje działań mogą zapewnić większą elastyczność.

Obsługa protokołu HTTP 202

Interfejs API "Wywoływanie protokołu HTTP" może automatycznie implementować stronę klienta wzorca sondowania użytkownika. Jeśli wywołany interfejs API zwraca odpowiedź HTTP 202 z nagłówkiem Lokalizacja, funkcja orkiestratora automatycznie sonduje zasób Lokalizacja do momentu otrzymania odpowiedzi innej niż 202. Ta odpowiedź będzie odpowiedzią zwróconą do kodu funkcji orkiestratora.

Uwaga

Funkcje programu Orchestrator obsługują również natywnie wzorzec sondowania po stronie serwera, zgodnie z opisem w temacie Async operation tracking (Śledzenie operacji asynchronicznych). Ta obsługa oznacza, że aranżacje w jednej aplikacji funkcji mogą łatwo koordynować funkcje orkiestratora w innych aplikacjach funkcji. Jest to podobne do koncepcji orkiestracji podrzędnej , ale z obsługą komunikacji między aplikacjami. Ta obsługa jest szczególnie przydatna w przypadku tworzenia aplikacji w stylu mikrousług.
Ze względu na tymczasowe ograniczenie wbudowany wzorzec sondowania HTTP nie jest obecnie dostępny w językach JavaScript/TypeScript i Python.

Tożsamości zarządzane

Rozszerzenie Durable Functions natywnie obsługuje wywołania interfejsów API, które akceptują tokeny entra firmy Microsoft na potrzeby autoryzacji. Ta obsługa używa tożsamości zarządzanych platformy Azure do uzyskiwania tych tokenów.

Poniższy kod jest przykładem funkcji orkiestratora. Funkcja wykonuje uwierzytelnione wywołania w celu ponownego uruchomienia maszyny wirtualnej przy użyciu interfejsu API REST maszyn wirtualnych usługi 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)

W poprzednim przykładzie tokenSource parametr jest skonfigurowany do uzyskiwania tokenów usługi Microsoft Entra dla usługi Azure Resource Manager. Tokeny są identyfikowane przez identyfikator URI https://management.core.windows.net/.defaultzasobu . W przykładzie założono, że bieżąca aplikacja funkcji działa lokalnie lub została wdrożona jako aplikacja funkcji z tożsamością zarządzaną. Przyjmuje się, że tożsamość lokalna lub tożsamość zarządzana ma uprawnienia do zarządzania maszynami wirtualnymi w określonej grupie myRGzasobów.

W czasie wykonywania skonfigurowane źródło tokenu automatycznie zwraca token dostępu OAuth 2.0. Następnie źródło dodaje token jako token elementu nośnego do nagłówka autoryzacji wychodzącego żądania. Ten model jest ulepszeniem ręcznego dodawania nagłówków autoryzacji do żądań HTTP z następujących powodów:

Odświeżanie tokenu jest obsługiwane automatycznie. Nie musisz martwić się o wygasłe tokeny.
Tokeny nigdy nie są przechowywane w stanie trwałej aranżacji.
Nie musisz pisać żadnego kodu, aby zarządzać pozyskiwaniem tokenów.

Bardziej kompletny przykład można znaleźć w przykładzie wstępnie skompilowanych maszyn wirtualnych RestartVM języka C#.

Tożsamości zarządzane nie są ograniczone do zarządzania zasobami platformy Azure. Tożsamości zarządzane umożliwiają dostęp do dowolnego interfejsu API, który akceptuje tokeny elementu nośnego firmy Microsoft, w tym usługi platformy Azure od firmy Microsoft i aplikacji internetowych od partnerów. Aplikacja internetowa partnera może być nawet inną aplikacją funkcji. Aby uzyskać listę usług platformy Azure firmy Microsoft, które obsługują uwierzytelnianie za pomocą identyfikatora Entra firmy Microsoft, zobacz Usługi platformy Azure, które obsługują uwierzytelnianie Firmy Microsoft Entra.

Ograniczenia

Wbudowana obsługa wywoływania interfejsów API HTTP jest funkcją wygody. Nie jest to odpowiednie dla wszystkich scenariuszy.

Żądania HTTP wysyłane przez funkcje orkiestratora i ich odpowiedzi są serializowane i utrwalane jako komunikaty u dostawcy magazynu Durable Functions. To trwałe zachowanie kolejkowania gwarantuje, że wywołania HTTP są niezawodne i bezpieczne w przypadku odtwarzania orkiestracji. Jednak trwałe zachowanie kolejkowania ma również ograniczenia:

Każde żądanie HTTP obejmuje dodatkowe opóźnienie w porównaniu z natywnym klientem HTTP.
W zależności od skonfigurowanego dostawcy magazynu duże komunikaty żądań lub odpowiedzi mogą znacznie obniżyć wydajność aranżacji. Na przykład w przypadku korzystania z usługi Azure Storage ładunki HTTP, które są zbyt duże, aby zmieścić się w komunikatach usługi Azure Queue, są kompresowane i przechowywane w usłudze Azure Blob Storage.
Przesyłanie strumieniowe, fragmenty i ładunki binarne nie są obsługiwane.
Możliwość dostosowywania zachowania klienta HTTP jest ograniczona.

Jeśli którekolwiek z tych ograniczeń może mieć wpływ na Twój przypadek użycia, rozważ użycie funkcji działania i bibliotek klienta HTTP specyficznych dla języka w celu wykonywania wychodzących wywołań HTTP.

Uwaga

Jeśli jesteś deweloperem platformy .NET, możesz się zastanawiać, dlaczego ta funkcja używa typów DurableHttpRequest i DurableHttpResponse zamiast wbudowanych typów HttpRequestMessage i HttpResponseMessage platformy .NET.

Ten wybór projektu jest zamierzony. Głównym powodem jest to, że typy niestandardowe pomagają zapewnić, że użytkownicy nie przyjmą nieprawidłowych założeń dotyczących obsługiwanych zachowań wewnętrznego klienta HTTP. Typy specyficzne dla rozszerzenia Durable Functions umożliwiają również uproszczenie projektowania interfejsu API. Mogą również łatwiej udostępniać specjalne funkcje, takie jak integracja tożsamości zarządzanej i wzorzec użytkownika sondowania.

Rozszerzalność (tylko platforma.NET)

Dostosowywanie zachowania wewnętrznego klienta HTTP orkiestracji jest możliwe przy użyciu wstrzykiwania zależności platformy .NET usługi Azure Functions. Ta możliwość może być przydatna do wprowadzania niewielkich zmian behawioralnych. Może być również przydatne podczas testowania jednostkowego klienta HTTP przez wstrzyknięcie obiektów pozornych.

W poniższym przykładzie pokazano użycie wstrzykiwania zależności w celu wyłączenia weryfikacji certyfikatu TLS/SSL dla funkcji orkiestratora wywołujących zewnętrzne punkty końcowe 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,
        };
    }
}

Następne kroki

Dowiedz się więcej o jednostkach trwałych

Funkcje HTTP

Uwidacznianie interfejsów API PROTOKOŁU HTTP

Wbudowane interfejsy API HTTP

Odnajdywanie adresów URL interfejsu API HTTP

Śledzenie operacji asynchronicznych

Korzystanie z interfejsów API HTTP

Obsługa protokołu HTTP 202

Tożsamości zarządzane

Ograniczenia

Rozszerzalność (tylko platforma.NET)

Następne kroki

Dodatkowe zasoby