Funkce HTTP

Durable Functions má několik funkcí, které usnadňují začlenění trvalých orchestrací a entit do pracovních postupů HTTP. Tento článek podrobně popisuje některé z těchto funkcí.

Zveřejnění rozhraní HTTP API

Orchestrace a entity je možné vyvolat a spravovat pomocí požadavků HTTP. Rozšíření Durable Functions zveřejňuje integrovaná rozhraní HTTP API. Poskytuje také rozhraní API pro interakci s orchestracemi a entitami z funkcí aktivovaných protokolem HTTP.

Integrovaná rozhraní HTTP API

Rozšíření Durable Functions automaticky přidá sadu rozhraní HTTP API do hostitele Azure Functions. S těmito rozhraními API můžete pracovat a spravovat orchestrace a entity bez psaní kódu.

Podporují se následující integrovaná rozhraní API HTTP.

Úplný popis všech integrovaných rozhraní HTTP API vystavených rozšířením Durable Functions najdete v článku rozhraní HTTP API.

Zjišťování adres URL rozhraní HTTP API

Vazba klienta orchestrace zveřejňuje rozhraní API, která můžou generovat pohodlné datové části odpovědi HTTP. Může například vytvořit odpověď obsahující odkazy na rozhraní API pro správu pro konkrétní instanci orchestrace. Následující příklady ukazují funkci triggeru HTTP, která ukazuje použití tohoto rozhraní API pro novou instanci orchestrace:

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

Spuštění funkce orchestrátoru pomocí funkcí triggeru HTTP zobrazených dříve lze provést pomocí libovolného klienta HTTP. Následující příkaz cURL spustí funkci orchestratoru s názvem DoWork:

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

Dále je příklad odpovědi pro orchestraci, která má abc123 jako ID. Některé podrobnosti byly odstraněny, aby bylo jasné.

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

V předchozím příkladu každý z polí končících Uri odpovídá integrovanému rozhraní HTTP API. Tato rozhraní API můžete použít ke správě cílové instance orchestrace.

Poznámka

Formát adres URL webhooku závisí na tom, jakou verzi hostitele Azure Functions používáte. Předchozí příklad je pro hostitele Azure Functions 2.0.

Popis všech integrovaných rozhraní HTTP API najdete v referenčních informacích k rozhraní HTTP API.

Sledování asynchronních operací

Výše uvedená odpověď HTTP je navržena tak, aby pomohla implementovat dlouhotrvající asynchronní rozhraní API HTTP s Durable Functions. Tento model se někdy označuje jako model uživatele dotazování. Tok klienta/serveru funguje takto:

  1. Klient vydá požadavek HTTP na spuštění dlouhotrvajícího procesu, jako je funkce orchestrátoru.
  2. Cílový trigger HTTP vrátí odpověď HTTP 202 s hlavičkou Umístění, která má hodnotu statusQueryGetUri.
  3. Klient se dotazuje na adresu URL v hlavičce Umístění. Klient bude dál zobrazovat odpovědi HTTP 202 s hlavičkou Umístění.
  4. Po dokončení nebo selhání instance vrátí koncový bod v hlavičce Umístění http 200.

Tento protokol umožňuje koordinaci dlouhotrvajících procesů s externími klienty nebo službami, které můžou dotazovat koncový bod HTTP a sledovat hlavičku Umístění. Implementace tohoto vzoru klienta i serveru jsou integrované do rozhraní API HTTP Durable Functions.

Poznámka

Ve výchozím nastavení podporují všechny akce založené na protokolu HTTP poskytované Azure Logic Apps standardní asynchronní operace. Tato funkce umožňuje vložit dlouho běžící odolnou funkci jako součást pracovního postupu Logic Apps. Další podrobnosti o podpoře logic Apps pro asynchronní vzory HTTP najdete v dokumentaci k akcím pracovního postupu Azure Logic Apps a triggerům.

Poznámka

Interakce s orchestracemi je možné provést z libovolného typu funkce, nejen z funkcí aktivovaných protokolem HTTP.

Další informace o správě orchestrací a entit pomocí klientských rozhraní API najdete v článku Správa instancí.

Využívání rozhraní HTTP API

Jak je popsáno v omezeních kódu funkce orchestrátoru, funkce orchestrátoru nemůžou přímo provádět vstupně-výstupní operace. Místo toho obvykle volají funkce aktivit , které dělají vstupně-výstupní operace.

Počínaje verzí Durable Functions 2.0 můžou orchestrace nativně využívat rozhraní HTTP API pomocí vazby triggeru orchestrace.

Následující příklad kódu ukazuje funkci orchestratoru, která provádí odchozí požadavek 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
    }
}

Pomocí akce "call HTTP" můžete ve funkcích orchestrátoru provést následující akce:

  • Volání rozhraní HTTP API přímo z orchestračních funkcí s některými omezeními, která jsou zmíněna později.
  • Automaticky podporují vzory dotazování stavu na straně klienta HTTP 202.
  • Pomocí spravovaných identit Azure můžete provádět autorizovaná volání HTTP na jiné koncové body Azure.

Možnost využívat rozhraní HTTP API přímo z funkcí orchestrátoru je určena jako pohodlí pro určitou sadu běžných scénářů. Všechny tyto funkce můžete implementovat sami pomocí funkcí aktivit. V mnoha případech vám funkce aktivit můžou poskytnout větší flexibilitu.

Zpracování HTTP 202

Rozhraní API "volání HTTP" může automaticky implementovat stranu klienta modelu příjemce dotazování. Pokud volání rozhraní API vrátí odpověď HTTP 202 s hlavičkou Umístění, orchestrátor automaticky dotazuje prostředek umístění, dokud neobdrží jinou odpověď než 202. Tato odpověď bude odpověď vrácená kódu funkce orchestrátoru.

Poznámka

  1. Funkce orchestratoru také nativně podporují model dotazování na straně serveru, jak je popsáno ve sledování asynchronních operací. Tato podpora znamená, že orchestrace v jedné aplikaci funkcí můžou snadno koordinovat funkce orchestrátoru v jiných aplikacích funkcí. To se podobá konceptu dílčí orchestrace , ale s podporou komunikace mezi aplikacemi. Tato podpora je užitečná zejména pro vývoj aplikací ve stylu mikroslužeb.
  2. Vzhledem k dočasnému omezení není integrovaný vzor dotazování HTTP aktuálně k dispozici v JavaScriptu nebo TypeScriptu a Pythonu.

Spravované identity

Durable Functions nativně podporuje volání rozhraní API, která přijímají tokeny Azure Active Directory (Azure AD) pro autorizaci. Tato podpora používá spravované identity Azure k získání těchto tokenů.

Následující kód je příkladem funkce orchestratoru. Funkce provádí ověřená volání pro restartování virtuálního počítače pomocí rozhraní REST API služby 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}");
    }
}

V předchozím příkladu tokenSource je parametr nakonfigurovaný tak, aby získal tokeny Azure AD pro Azure Resource Manager. Tokeny jsou identifikovány identifikátorem URI https://management.core.windows.net/.defaultprostředku . Příklad předpokládá, že aktuální aplikace funkcí běží místně nebo byla nasazena jako aplikace funkcí se spravovanou identitou. Místní identita nebo spravovaná identita se předpokládá, že má oprávnění ke správě virtuálních počítačů v zadané skupině myRGprostředků .

Za běhu vrátí nakonfigurovaný zdroj tokenu automaticky přístupový token OAuth 2.0. Zdroj pak přidá token jako nosný token do hlavičky Autorizace odchozího požadavku. Tento model je vylepšením ručního přidávání autorizačních hlaviček do požadavků HTTP z následujících důvodů:

  • Aktualizace tokenu se zpracovává automaticky. Nemusíte se starat o vypršení platnosti tokenů.
  • Tokeny se nikdy neukládají ve stavu trvalé orchestrace.
  • Ke správě získávání tokenů nemusíte psát žádný kód.

Podrobnější příklad najdete v ukázce předkompilovaných počítačů RestartVM v jazyce C#.

Spravované identity nejsou omezené na správu prostředků Azure. Spravované identity můžete použít pro přístup k libovolnému rozhraní API, které přijímá Azure AD nosné tokeny, včetně služeb Azure od Microsoftu a webových aplikací od partnerů. Webová aplikace partnera může být dokonce jinou aplikací funkcí. Seznam služeb Azure od Microsoftu, které podporují ověřování pomocí Azure AD, najdete ve službách Azure, které podporují ověřování Azure AD.

Omezení

Integrovaná podpora volání rozhraní HTTP API je funkce usnadnění. Není vhodné pro všechny scénáře.

Požadavky HTTP odeslané funkcemi orchestrátoru a jejich odpovědi se serializují a uchovávají jako zprávy v poskytovateli úložiště Durable Functions. Toto trvalé chování při řízení front zajišťuje, že volání HTTP jsou spolehlivá a bezpečná pro přehrání orchestrace. Trvalé chování ve frontě ale má také omezení:

  • Každý požadavek HTTP zahrnuje další latenci ve srovnání s nativním klientem HTTP.
  • V závislosti na nakonfigurovaného poskytovatele úložiště můžou velké zprávy požadavků nebo odpovědí výrazně snížit výkon orchestrace. Například při použití Azure Storage se datové části HTTP, které jsou příliš velké, aby se vešly do zpráv ve frontě Azure, se komprimují a ukládají ve službě Azure Blob Storage.
  • Streamování, blokované datové části a binární datové části se nepodporují.
  • Schopnost přizpůsobit chování klienta HTTP je omezená.

Pokud některá z těchto omezení může mít vliv na váš případ použití, zvažte raději použití funkcí aktivit a klientských knihoven HTTP specifických pro jazyk k provádění odchozích volání HTTP.

Poznámka

Pokud jste vývojář .NET, možná vás zajímá, proč tato funkce používá typy DurableHttpRequest a DurableHttpResponse místo předdefinovaných typů .NET HttpRequestMessage a HttpResponseMessage .

Tato volba návrhu je úmyslná. Primárním důvodem je, že vlastní typy pomáhají zajistit, aby uživatelé neudělali nesprávné předpoklady o podporovaném chování interního klienta HTTP. Typy specifické pro Durable Functions také umožňují zjednodušit návrh rozhraní API. Můžou také snadněji zpřístupnit speciální funkce, jako je integrace spravované identity a model uživatele dotazování.

Rozšiřitelnost (jenom .NET)

Přizpůsobení chování interního klienta HTTP orchestrace je možné použít Azure Functions injektáž závislostí .NET. Tato schopnost může být užitečná pro provádění malých změn chování. Může být také užitečné pro testování jednotek klienta HTTP vložením napodobených objektů.

Následující příklad ukazuje použití injektáže závislostí k zakázání ověřování certifikátů TLS/SSL pro funkce orchestrátoru, které volají externí koncové body 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,
        };
    }
}

Další kroky