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í API HTTP. Poskytuje také rozhraní API pro interakci s orchestracemi a entitami z funkcí aktivovaných protokolem HTTP.

Integrovaná rozhraní API HTTP

Rozšíření Durable Functions automaticky přidá sadu rozhraní HTTP API do hostitele Azure Functions. Pomocí těchto rozhraní API můžete interagovat s orchestracemi a entitami a spravovat je bez psaní kódu.

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

• Zahájení nové orchestrace
• Instance orchestrace dotazů
• Ukončení instance orchestrace
• Odeslání externí události do orchestrace
• Historie orchestrace vyprázdnění
• Odeslání události operace do entity
• Získání stavu entity
• Dotazování na seznam entit

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

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

Klientská vazba 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:

C#

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

JavaScript

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
  }

Python

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

PowerShell

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

Java

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

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

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

Další je příklad odpovědi pro orchestraci, která má abc123 jako ID. Kvůli přehlednosti byly odebrány některé podrobnosti.

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 odpovídá každé z polí Uri končících na předdefinované 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 určený pro hostitele Azure Functions 2.0.

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

Sledování asynchronních operací

Výše uvedená odpověď HTTP je navržená tak, aby pomohla implementovat dlouhotrvající asynchronní rozhraní API HTTP s Durable Functions. Tento vzor se někdy označuje jako model příjemce dotazování. Tok klienta nebo 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á aktivační událost HTTP vrátí odpověď HTTP 202 s hlavičkou Location s hodnotou statusQueryGetUri.
3. Klient se dotazuje na adresu URL v hlavičce Umístění. Klient bude dál zobrazovat odpovědi HTTP 202 hlavičkou Umístění.
4. Po dokončení nebo selhání instance koncový bod v hlavičce umístění vrátí 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 postupovat podle hlavičky Umístění. Implementace tohoto modelu klienta i serveru jsou integrované do rozhraní HTTP API Durable Functions.

Poznámka:

Ve výchozím nastavení podporují všechny akce založené na PROTOKOLU HTTP poskytované službou Azure Logic Apps standardní vzor asynchronních operací. 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 a triggerům Azure Logic Apps.

Poznámka:

Interakce s orchestracemi je možné provádět z libovolného typu funkce, ne jenom 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 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 orchestrátoru, která vytváří odchozí požadavek HTTP:

C#

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

JavaScript

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

Python

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)

PowerShell

Tato funkce není dostupná v PowerShellu.

Java

Tato funkce není dostupná v Javě.

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

• Volejte rozhraní API HTTP přímo z funkcí orchestrace s určitými omezeními, která jsou zmíněna později.
• Automaticky podporuje vzory dotazování na stav HTTP 202 na straně klienta.
• Pomocí spravovaných identit Azure můžete provádět autorizovaná volání HTTP do jiných koncových bodů Azure.

Možnost využívat rozhraní HTTP API přímo z funkcí orchestrátoru je určená 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 vzoru příjemce dotazování. Pokud volaná rozhraní API vrátí odpověď HTTP 202 s hlavičkou Umístění, funkce orchestrátoru 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 cyklického 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í. Podobá se 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 v současné době k dispozici v JavaScriptu nebo TypeScriptu a Pythonu.

Spravované identity

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

Následující kód je příkladem funkce orchestrátoru. Funkce provádí ověřená volání k restartování virtuálního počítače pomocí rozhraní REST API virtuálních počítačů Azure Resource Manageru.

C#

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

JavaScript

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

Python

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)

PowerShell

Tato funkce není dostupná v PowerShellu.

Java

Tato funkce není dostupná v Javě.

V předchozím příkladu tokenSource je parametr nakonfigurovaný tak, aby získal tokeny Microsoft Entra 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. Předpokládá se, že místní identita nebo spravovaná identita mají oprávnění ke správě virtuálních počítačů v zadané skupině myRGprostředků.

Za běhu nakonfigurovaný zdroj tokenu automaticky vrátí přístupový token OAuth 2.0. Zdroj pak token přidá jako nosný token do autorizační hlavičky 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 tokeny s vypršenou platností.
• Tokeny se nikdy neukládají ve stavu trvalé orchestrace.
• Ke správě získávání tokenů nemusíte psát žádný kód.

Kompletní 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á nosné tokeny Microsoft Entra, 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í ID Microsoft Entra, najdete ve službách Azure, které podporují ověřování Microsoft Entra.

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í při řízení front však má také omezení:

• Každý požadavek HTTP zahrnuje další latenci ve srovnání s nativním klientem HTTP.
• V závislosti na nakonfigurovaných poskytovatelích ú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í služby Azure Storage se datové části HTTP, které jsou příliš velké, aby se vešly do zpráv fronty Azure, se komprimují a ukládají v Úložišti objektů blob v Azure.
• Streamování, blokované 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 místo toho použití funkce aktivit a klientské knihovny HTTP specifické pro jazyk k odchozím voláním HTTP.

Poznámka:

Pokud jste vývojář rozhraní .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á. Hlavním důvodem je, že vlastní typy pomáhají zajistit, aby uživatelé nepředpokládá 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 příjemce dotazování.

Rozšiřitelnost (pouze .NET)

Přizpůsobení chování interního klienta HTTP orchestrace je možné pomocí injektáže závislostí azure Functions .NET. Tato schopnost může být užitečná při 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

Informace o trvalých entitách