Správa instancí v Durable Functions v Azure

Orchestrace v Durable Functions jsou dlouhotrvající stavové funkce, které je možné spustit, dotazovat, pozastavit, obnovit a ukončit pomocí integrovaných rozhraní API pro správu. Několik dalších rozhraní API pro správu instancí jsou také vystavena vazbou klienta pro orchestraci Durable Functions, jako je odesílání externích událostí do instancí, vymazání historie instancí atd. Tento článek popisuje podrobnosti o všech podporovaných operacích správy instancí.

Spuštění instancí

Metoda start-new (nebo schedule-new) u vazby klienta orchestrace spustí novou instanci orchestrace. Interně tato metoda zapíše zprávu prostřednictvím poskytovatele úložiště Durable Functions a poté vrátí zprávu. Tato zpráva asynchronně aktivuje začátek funkce orchestrace se zadaným názvem.

Parametry pro spuštění nové instance orchestrace jsou následující:

  • Název: Název funkce orchestrátoru pro naplánování.
  • Vstup: Všechna serializovatelná data JSON, která by se měla předat jako vstup funkci orchestrátoru.
  • InstanceId: (Volitelné) Jedinečné ID instance. Pokud tento parametr nezadáte, metoda použije náhodné ID.

Tip

Pokud je to možné, použijte pro ID instance náhodný identifikátor. ID náhodných instancí pomáhají zajistit rovnoměrnou distribuci zatížení, když škálujete funkce orchestratoru napříč několika virtuálními počítači. Správný čas použití id nenáhodných instancí spočívá v tom, že ID musí pocházet z externího zdroje nebo při implementaci vzoru orchestrátoru s jednímtonem .

Následující kód je ukázková funkce, která spustí novou instanci orchestrace:

[FunctionName("HelloWorldQueueTrigger")]
public static async Task Run(
    [QueueTrigger("start-queue")] string input,
    [DurableClient] IDurableOrchestrationClient starter,
    ILogger log)
{
    string instanceId = await starter.StartNewAsync("HelloWorld", input);
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo DurableClient atributu a místo parametru použít typ parametru DurableOrchestrationClientIDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Azure Functions Core Tools

Instanci můžete také spustit přímo pomocí func durable start-new příkazu v nástrojích Core Tools, který přebírá následující parametry:

  • function-name (povinné): Název funkce, která se má spustit.
  • input (volitelné): Vstup do funkce, buď vložený, nebo prostřednictvím souboru JSON. U souborů přidejte předponu k cestě k souboru, @například @path/to/file.json.
  • id (volitelné): ID instance orchestrace. Pokud tento parametr nezadáte, příkaz použije náhodný identifikátor GUID.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí hodnota je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Můžete to také nastavit v souboru host.json pomocí durableTask:HubName.

Poznámka

Příkazy Nástroje Core Tools předpokládají, že je spouštíte z kořenového adresáře aplikace funkcí. Pokud explicitně zadáte connection-string-setting a task-hub-name parametry, můžete příkazy spustit z libovolného adresáře. I když můžete tyto příkazy spustit bez spuštěného hostitele aplikace funkcí, můžete zjistit, že nemůžete sledovat některé efekty, pokud hostitel není spuštěný. Příkaz například start-new vytvoří zprávu start do cílového centra úloh, ale orchestrace se ve skutečnosti nespustí, pokud není spuštěný hostitelský proces aplikace funkcí, který může zprávu zpracovat.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Následující příkaz spustí funkci s názvem HelloWorld a předá mu obsah souboru counter-data.json :

func durable start-new --function-name HelloWorld --input @counter-data.json --task-hub-name TestTaskHub

Instance dotazů

Po spuštění nových instancí orchestrace budete pravděpodobně muset dotazovat stav modulu runtime, abyste se dozvěděli, jestli jsou spuštěné, dokončené nebo neúspěšné.

Metoda get-status u vazby klienta orchestrace dotazuje stav instance orchestrace.

Jako parametry přebírá instanceId (povinné), showHistoryshowHistoryOutput (volitelné), (volitelné) a showInput (volitelné).

  • showHistory: Pokud je nastavená hodnota true, odpověď obsahuje historii spuštění.
  • showHistoryOutput: Pokud je nastavená hodnota true, historie provádění obsahuje výstupy aktivit.
  • showInput: Pokud je nastavená hodnota false, odpověď nebude obsahovat vstup funkce. Výchozí hodnota je true.

Metoda vrátí objekt s následujícími vlastnostmi:

  • Název: Název funkce orchestrátoru.
  • InstanceId: ID instance orchestrace (musí být stejné jako instanceId vstup).
  • CreatedTime: Čas, kdy se spustila funkce orchestrátoru.
  • LastUpdatedTime: Čas posledního kontrolního bodu orchestrace
  • Vstup: Vstup funkce jako hodnota JSON. Toto pole není vyplněno, pokud showInput je false.
  • CustomStatus: Vlastní stav orchestrace ve formátu JSON
  • Výstup: Výstup funkce jako hodnoty JSON (pokud je funkce dokončená). Pokud se funkce orchestratoru nezdařila, tato vlastnost obsahuje podrobnosti o selhání. Pokud byla funkce orchestrátoru pozastavena nebo ukončena, tato vlastnost obsahuje důvod pozastavení nebo ukončení (pokud existuje).
  • RuntimeStatus: Jedna z následujících hodnot:
    • Čeká se: Instance byla naplánována, ale ještě nebyla spuštěna.
    • Spuštěno: Instance se spustila.
    • Dokončeno: Instance se normálně dokončila.
    • PokračovatAsNew: Instance se restartovala s novou historií. Tento stav je přechodný stav.
    • Selhání: Instance selhala s chybou.
    • Ukončeno: Instance byla náhle zastavena.
    • Pozastaveno: Instance byla pozastavena a může být obnovena později v čase.
  • Historie: Historie provádění orchestrace. Toto pole je vyplněno pouze v případě, že showHistory je nastaveno na true.

Poznámka

Orchestrátor není označený jako Completed až do dokončení všech plánovaných úkolů a orchestrátor se vrátí. Jinými slovy, není dostačující, aby orchestrátor dosáhl svého return prohlášení, aby byl označen jako Completed. To je obzvláště důležité pro případy, kdy WhenAny se používají; orchestrátory často return před provedením všech plánovaných úloh.

Tato metoda vrátí null (.NET a Java), undefined (JavaScript) nebo None (Python), pokud instance neexistuje.

[FunctionName("GetStatus")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("check-status-queue")] string instanceId)
{
    DurableOrchestrationStatus status = await client.GetStatusAsync(instanceId);
    // do something based on the current status.
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo DurableClient atributu a místo parametru použít typ parametru DurableOrchestrationClientIDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Azure Functions Core Tools

Stav instance orchestrace je také možné získat přímo pomocí func durable get-runtime-status příkazu v Nástrojích Core Tools.

Poznámka

Příkazy Core Tools se v současné době podporují jenom v případě, že pro zachování stavu modulu runtime používáte výchozího poskytovatele služby Azure Storage .

Příkaz durable get-runtime-status přebírá následující parametry:

  • id (povinné): ID instance orchestrace.
  • show-input (volitelné): Pokud je nastavená hodnota true, odpověď obsahuje vstup funkce. Výchozí hodnota je false.
  • show-output (volitelné): Pokud je nastavená hodnota true, odpověď obsahuje výstup funkce. Výchozí hodnota je false.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí formát je DurableFunctionsHub. Dá se také nastavit v souboru host.json pomocí durableTask:HubName.

Následující příkaz načte stav instance (včetně vstupu a výstupu) s ID instance orchestrace 0ab8c55a6664d68a3a8b220b12d209c. Předpokládá se, že spouštíte func příkaz z kořenového adresáře aplikace funkcí:

func durable get-runtime-status --id 0ab8c55a66644d68a3a8b220b12d209c --show-input true --show-output true

Pomocí durable get-history příkazu můžete načíst historii instance orchestrace. Přebírá následující parametry:

  • id (povinné): ID instance orchestrace.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí formát je DurableFunctionsHub. Dá se také nastavit v souboru host.json pomocí durableTask:HubName.
func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Dotazování na všechny instance

Pomocí rozhraní API ve vaší jazykové sadě SDK můžete dotazovat stav všech instancí orchestrace v centru úloh. Toto rozhraní API typu list-instance nebo get-status vrátí seznam objektů, které představují instance orchestrace odpovídající parametrům dotazu.

[FunctionName("GetAllStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    var noFilter = new OrchestrationStatusQueryCondition();
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        noFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
    
    // Note: ListInstancesAsync only returns the first page of results.
    // To request additional pages provide the result.ContinuationToken
    // to the OrchestrationStatusQueryCondition's ContinuationToken property.
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo DurableClient atributu a místo parametru použít typ parametru DurableOrchestrationClientIDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Azure Functions Core Tools

Instance je také možné dotazovat přímo pomocí func durable get-instances příkazu v Nástrojích Core Tools.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Příkaz durable get-instances přebírá následující parametry:

  • top (volitelné): Tento příkaz podporuje stránkování. Tento parametr odpovídá počtu načtených instancí na požadavek. Výchozí hodnota je 10.
  • continuation-token (volitelné): Token označující stránku nebo oddíl instancí, které se mají načíst. Každé get-instances spuštění vrátí token k další sadě instancí.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí formát je DurableFunctionsHub. Dá se také nastavit v souboru host.json pomocí durableTask:HubName.
func durable get-instances

Dotazy na instance s filtry

Co když opravdu nepotřebujete všechny informace, které může poskytnout standardní dotaz instance? Co když například hledáte čas vytvoření orchestrace nebo stav modulu runtime orchestrace? Dotaz můžete zúžit použitím filtrů.

[FunctionName("QueryStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    // Get the first 100 running or pending instances that were created between 7 and 1 day(s) ago
    var queryFilter = new OrchestrationStatusQueryCondition
    {
        RuntimeStatus = new[]
        {
            OrchestrationRuntimeStatus.Pending,
            OrchestrationRuntimeStatus.Running,
        },
        CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
        CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
        PageSize = 100,
    };
    
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        queryFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo DurableClient atributu a místo parametru použít typ parametru DurableOrchestrationClientIDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Azure Functions Core Tools

V nástrojích Azure Functions Core Tools můžete také použít durable get-instances příkaz s filtry. Kromě výše uvedených topparametrů , , continuation-tokenconnection-string-settinga task-hub-name parametrů můžete použít tři parametry filtru (created-after, created-beforea runtime-status).

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Níže jsou uvedené parametry durable get-instances příkazu.

  • created-after (volitelné): Načtěte instance vytvořené po tomto datu a čase (UTC). Přijalo se formátované datum a časy ISO 8601.
  • created-before (volitelné): Načtěte instance vytvořené před tímto datem a časem (UTC). Přijalo se formátované datum a časy ISO 8601.
  • runtime-status (volitelné): Načtěte instance s konkrétním stavem (například spuštěné nebo dokončené). Může poskytovat více stavů (oddělených mezerami).
  • top (volitelné): Počet načtených instancí na požadavek Výchozí hodnota je 10.
  • continuation-token (volitelné): Token označující stránku nebo oddíl instancí, které se mají načíst. Každé get-instances spuštění vrátí token k další sadě instancí.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí formát je DurableFunctionsHub. Dá se také nastavit v souboru host.json pomocí durableTask:HubName.

Pokud nezadáte žádné filtry (created-afternebo created-before), runtime-statuspříkaz jednoduše načte top instance bez ohledu na stav modulu runtime nebo čas vytvoření.

func durable get-instances --created-after 2021-03-10T13:57:31Z --created-before  2021-03-10T23:59Z --top 15

Ukončení instancí

Pokud máte instanci orchestrace, která trvá příliš dlouho, nebo ji stačí zastavit, než se z nějakého důvodu dokončí, můžete ji ukončit.

Dva parametry rozhraní API pro ukončení jsou ID instance a řetězec důvodu , který se zapisuje do protokolů a stavu instance.

[FunctionName("TerminateInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("terminate-queue")] string instanceId)
{
    string reason = "Found a bug";
    return client.TerminateAsync(instanceId, reason);
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo DurableClient atributu a místo parametru použít typ parametru DurableOrchestrationClientIDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Ukončená instance se nakonec převede do Terminated stavu. Tento přechod se ale nestane okamžitě. Místo toho bude operace ukončení zařazena do fronty v centru úloh spolu s dalšími operacemi pro danou instanci. Rozhraní API dotazů instance můžete použít k tomu, abyste věděli, kdy ukončená instance skutečně dosáhla Terminated stavu.

Poznámka

Ukončení instance se v současné době nešíruje. Funkce aktivit a dílčí orchestrace se spouští k dokončení bez ohledu na to, jestli jste ukončili instanci orchestrace, která je volala.

Pozastavení a obnovení instancí (Preview)

Pozastavení orchestrace umožňuje zastavit spuštěnou orchestraci. Na rozdíl od ukončení máte možnost obnovit pozastavený orchestrátor v pozdějším bodě v čase.

Dva parametry pro rozhraní API pro pozastavení jsou ID instance a řetězec důvodu, který se zapisuje do protokolů a do stavu instance.

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // ... wait for some period of time since suspending is an async operation...
    
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

Pozastavená instance nakonec přejde do Suspended stavu. Tento přechod se ale nestane okamžitě. Místo toho bude operace pozastavení zařazena do fronty v centru úloh spolu s dalšími operacemi pro danou instanci. Rozhraní API dotazů instance můžete použít k tomu, abyste věděli, kdy spuštěná instance skutečně dosáhla pozastaveného stavu.

Po obnovení pozastaveného orchestrátoru se jeho stav změní zpět na Running.

Azure Functions Core Tools

Instanci orchestrace můžete také ukončit přímo pomocí func durable terminate příkazu v nástrojích Core Tools.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Příkaz durable terminate přebírá následující parametry:

  • id (povinné): ID instance orchestrace, která se má ukončit.
  • reason (volitelné): Důvod ukončení.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí formát je DurableFunctionsHub. Dá se také nastavit v souboru host.json pomocí durableTask:HubName.

Následující příkaz ukončí instanci orchestrace s ID 0ab8c55a6664d68a3a8b220b12d209c:

func durable terminate --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Found a bug"

Odesílání událostí do instancí

V některých scénářích musí funkce orchestrátoru čekat a naslouchat externím událostem. Příklady scénářů, ve kterých je to užitečné, patří scénáře monitorování a lidské interakce .

Oznámení událostí můžete odesílat spuštěným instancím pomocí rozhraní API pro vyvolání událostíklienta orchestrace. Orchestrace můžou naslouchat těmto událostem a reagovat na ně pomocí rozhraní API pro orchestrator externích událostí .

Parametry pro vyvolání událostí jsou následující:

  • ID instance: Jedinečné ID instance
  • Název události: Název události, která se má odeslat.
  • Data událostí: Datová část json serializable pro odeslání do instance.
[FunctionName("RaiseEvent")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("event-queue")] string instanceId)
{
    int[] eventData = new int[] { 1, 2, 3 };
    return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo DurableClient atributu a místo parametru použít typ parametru DurableOrchestrationClientIDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku Durable Functions verze.

Poznámka

Pokud neexistuje žádná instance orchestrace se zadaným ID instance, zpráva události se zahodí. Pokud instance existuje, ale ještě nečeká na událost, bude událost uložena ve stavu instance, dokud nebude připravena k přijetí a zpracování.

Azure Functions Core Tools

Událost můžete také vyvolat přímo do instance orchestrace pomocí func durable raise-event příkazu v Nástrojích Core Tools.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Příkaz durable raise-event přebírá následující parametry:

  • id (povinné): ID instance orchestrace.
  • event-name: Název události, která se má vyvolat.
  • event-data (volitelné): Data, která se mají odeslat do instance orchestrace. Může to být cesta k souboru JSON nebo můžete data zadat přímo na příkazovém řádku.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí formát je DurableFunctionsHub. Dá se také nastavit v souboru host.json pomocí durableTask:HubName.
func durable raise-event --id 0ab8c55a66644d68a3a8b220b12d209c --event-name MyEvent --event-data @eventdata.json
func durable raise-event --id 1234567 --event-name MyOtherEvent --event-data 3

Čekání na dokončení orchestrace

V dlouhotrvajících orchestracích můžete chtít počkat a získat výsledky orchestrace. V těchto případech je také užitečné definovat časové období orchestrace. Pokud dojde k překročení časového limitu, měl by se místo výsledků vrátit stav orchestrace.

K synchronnímu získání skutečného výstupu z instance orchestrace se dá použít rozhraní API pro čekání na dokončení nebo vytvoření odpovědi na stav . Ve výchozím nastavení má tato metoda výchozí časový limit 10 sekund a interval dotazování 1 sekund.

Tady je příklad funkce triggeru HTTP, která ukazuje, jak používat toto rozhraní API:

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

using System;
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 HttpSyncStart
    {
        private const string Timeout = "timeout";
        private const string RetryInterval = "retryInterval";

        [FunctionName("HttpSyncStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}/wait")]
            HttpRequestMessage req,
            [DurableClient] IDurableOrchestrationClient 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}'.");

            TimeSpan timeout = GetTimeSpan(req, Timeout) ?? TimeSpan.FromSeconds(30);
            TimeSpan retryInterval = GetTimeSpan(req, RetryInterval) ?? TimeSpan.FromSeconds(1);
            
            return await starter.WaitForCompletionOrCreateCheckStatusResponseAsync(
                req,
                instanceId,
                timeout,
                retryInterval);
        }

        private static TimeSpan? GetTimeSpan(HttpRequestMessage request, string queryParameterName)
        {
            string queryParameterStringValue = request.RequestUri.ParseQueryString()[queryParameterName];
            if (string.IsNullOrEmpty(queryParameterStringValue))
            {
                return null;
            }

            return TimeSpan.FromSeconds(double.Parse(queryParameterStringValue));
        }
    }
}

Volejte funkci pomocí následujícího řádku. Pro časový limit použijte 2 sekundy a interval opakování 0,5 sekundy:

curl -X POST "http://localhost:7071/orchestrators/E1_HelloSequence/wait?timeout=2&retryInterval=0.5"

Poznámka

Výše uvedený příkaz cURL předpokládá, že máte v projektu funkci orchestrátoru.E1_HelloSequence Vzhledem k tomu, jak je funkce triggeru HTTP napsaná, můžete ji nahradit názvem libovolné funkce orchestrátoru ve vašem projektu.

V závislosti na čase potřebném k získání odpovědi z instance orchestrace existují dva případy:

  • Instance orchestrace se dokončí v rámci definovaného časového limitu (v tomto případě 2 sekundy) a odpověď je skutečný výstup instance orchestrace, který se dodává synchronně:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:14:29 GMT
Transfer-Encoding: chunked

[
    "Hello Tokyo!",
    "Hello Seattle!",
    "Hello London!"
]
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:13:51 GMT
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
Retry-After: 10
Transfer-Encoding: chunked

{
    "id": "d3b72dddefce4e758d92f4d411567177",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/suspend?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/resume?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
}

Poznámka

Formát adres URL webhooku se může lišit v závislosti na tom, jakou verzi hostitele Azure Functions používáte. Předchozí příklad je pro hostitele Azure Functions 3.0.

Načtení adres URL webhooku pro správu HTTP

Externí systém můžete použít k monitorování nebo vyvolání událostí k orchestraci. Externí systémy můžou komunikovat s Durable Functions prostřednictvím adres URL webhooku, které jsou součástí výchozí odpovědi popsané ve zjišťování adres URL rozhraní HTTP API. K adresám URL webhooku je možné přistupovat programově pomocí vazby klienta orchestrace. Konkrétně je možné použít rozhraní API pro vytvoření datové části správy HTTP k získání serializovatelného objektu, který obsahuje tyto adresy URL webhooku.

Rozhraní API pro vytvoření datové části správy HTTP má jeden parametr:

  • ID instance: Jedinečné ID instance.

Metody vrátí objekt s následujícími vlastnostmi řetězce:

  • ID: ID instance orchestrace (musí být stejné jako InstanceId vstup).
  • StatusQueryGetUri: Adresa URL stavu instance orchestrace.
  • SendEventPostUri: Adresa URL vyvolání události instance orchestrace.
  • TerminatePostUri: Adresa URL "terminate" instance orchestrace.
  • PurgeHistoryDeleteUri: Adresa URL "historie vymazání" instance orchestrace.
  • suspendPostUri: Adresa URL "suspend" instance orchestrace.
  • resumePostUri: Adresa URL "resume" instance orchestrace.

Funkce můžou odesílat instance těchto objektů externím systémům za účelem monitorování nebo vyvolání událostí v odpovídajících orchestracích, jak je znázorněno v následujících příkladech:

[FunctionName("SendInstanceInfo")]
public static void SendInstanceInfo(
    [ActivityTrigger] IDurableActivityContext ctx,
    [DurableClient] IDurableOrchestrationClient client,
    [DocumentDB(
        databaseName: "MonitorDB",
        collectionName: "HttpManagementPayloads",
        ConnectionStringSetting = "CosmosDBConnection")]out dynamic document)
{
    HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);

    // send the payload to Cosmos DB
    document = new { Payload = payload, id = ctx.InstanceId };
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít místo , musíte použít DurableActivityContextOrchestrationClient atribut místo atributu DurableClient a musíte použít typ parametru DurableOrchestrationClient místo IDurableOrchestrationClient.IDurableActivityContext Další informace o rozdílech mezi verzemi najdete v článku o Durable Functions verzích.

Převinutí instancí zpět (Preview)

Pokud dojde k selhání orchestrace z neočekávaného důvodu, můžete instanci převinout do stavu, který je dříve v pořádku, pomocí rozhraní API vytvořeného pro tento účel.

Poznámka

Toto rozhraní API nemá být náhradou za správné zpracování chyb a zásady opakování. Spíše je určena k použití pouze v případech, kdy instance orchestrace selžou z neočekávaných důvodů. Další informace o zpracování chyb a zásadách opakování najdete v článku o zpracování chyb .

RewindAsync Pomocí metody (.NET) nebo rewind (JavaScript) vazby klienta orchestrace umístěte orchestraci zpět do stavu Spuštěno. Tato metoda také znovu spustí selhání provádění aktivity nebo dílčí orchestrace, které způsobily selhání orchestrace.

Řekněme například, že máte pracovní postup zahrnující řadu lidských schválení. Předpokládejme, že existuje řada funkcí aktivit, které uživatele upozorní, že je potřeba schválení, a počkejte na odezvu v reálném čase. Jakmile všechny aktivity schválení obdržely odpovědi nebo vypršel časový limit, předpokládejme, že jiná aktivita selže kvůli chybné konfiguraci aplikace, například kvůli neplatnému připojovacímu řetězci databáze. Výsledkem je selhání orchestrace hluboko do pracovního postupu. RewindAsync Pomocí rozhraní API (.NET) nebo rewind (JavaScript) může správce aplikace chybu konfigurace opravit a znovu převinout orchestraci, která selhala, zpět do stavu před selháním. Žádný z kroků pro lidskou interakci není potřeba znovu schválit a orchestrace se teď může úspěšně dokončit.

Poznámka

Funkce převinutí zpět nepodporuje převinutí instancí orchestrace, které používají trvalé časovače.

[FunctionName("RewindInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("rewind-queue")] string instanceId)
{
    string reason = "Orchestrator failed and needs to be revived.";
    return client.RewindAsync(instanceId, reason);
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo atributu DurableClient a musíte použít typ parametru DurableOrchestrationClient místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o Durable Functions verzích.

Azure Functions Core Tools

Instanci orchestrace můžete také převinout přímo pomocí func durable rewind příkazu v nástrojích Core Tools.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Příkaz durable rewind přijímá následující parametry:

  • id (povinné): ID instance orchestrace.
  • reason (volitelné): Důvod opětovného převinutí instance orchestrace.
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Ve výchozím nastavení se používá název centra úloh v souboru host.json .
func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."

Vyprázdnění historie instancí

Pokud chcete odebrat všechna data přidružená k orchestraci, můžete historii instancí vyprázdnit. Můžete například chtít odstranit všechny prostředky úložiště přidružené k dokončené instanci. K tomu použijte rozhraní API instance mazání definované klientem orchestrace.

Tento první příklad ukazuje, jak vyprázdnit jednu instanci orchestrace.

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("purge-queue")] string instanceId)
{
    return client.PurgeInstanceHistoryAsync(instanceId);
}

Další příklad ukazuje funkci aktivovanou časovačem, která vymaže historii pro všechny instance orchestrace, které se dokončily po zadaném časovém intervalu. V tomto případě odebere data pro všechny instance dokončené před 30 nebo více dny. Tato ukázková funkce je naplánovaná tak, aby běžela jednou denně v 12:00 UTC:

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [TimerTrigger("0 0 12 * * *")] TimerInfo myTimer)
{
    return client.PurgeInstanceHistoryAsync(
        DateTime.MinValue,
        DateTime.UtcNow.AddDays(-30),  
        new List<OrchestrationStatus>
        {
            OrchestrationStatus.Completed
        });
}

Poznámka

Předchozí kód jazyka C# je pro Durable Functions 2.x. Pro Durable Functions 1.x musíte použít OrchestrationClient atribut místo atributu DurableClient a musíte použít typ parametru DurableOrchestrationClient místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o Durable Functions verzích.

Poznámka

Aby operace historie vymazání proběhla úspěšně, stav modulu runtime cílové instance musí být Dokončeno, Ukončeno nebo Neúspěšné.

Azure Functions Core Tools

Historii instance orchestrace můžete vymazat pomocí func durable purge-history příkazu v nástrojích Core Tools. Podobně jako druhý příklad jazyka C# v předchozí části vymaže historii pro všechny instance orchestrace vytvořené během zadaného časového intervalu. Vyprázdněné instance můžete dále filtrovat podle stavu modulu runtime.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Příkaz durable purge-history má několik parametrů:

  • created-after (volitelné): Vyprázdnění historie instancí vytvořených po tomto datu a čase (UTC). Přijatá data a časy ve formátu ISO 8601.
  • created-before (volitelné): Vyprázdnění historie instancí vytvořených před tímto datem a časem (UTC). Přijatá data a časy ve formátu ISO 8601.
  • runtime-status (volitelné): Vyprázdnění historie instancí s konkrétním stavem (například spuštění nebo dokončení). Může poskytovat více stavů (oddělených mezerami).
  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Ve výchozím nastavení se používá název centra úloh v souboru host.json .

Následující příkaz odstraní historii všech neúspěšných instancí vytvořených před 14. listopadem 2021 v 7:35 (UTC).

func durable purge-history --created-before 2021-11-14T19:35:00.0000000Z --runtime-status failed

Odstranění centra úloh

func durable delete-task-hub Pomocí příkazu v nástrojích Core Tools můžete odstranit všechny artefakty úložiště přidružené ke konkrétnímu centru úloh, včetně tabulek úložiště Azure, front a objektů blob.

Poznámka

Příkazy Core Tools se v současné době podporují pouze při použití výchozího poskytovatele služby Azure Storage pro zachování stavu modulu runtime.

Příkaz durable delete-task-hub má dva parametry:

  • connection-string-setting (volitelné): Název nastavení aplikace obsahující připojovací řetězec úložiště, který se má použít. Výchozí formát je AzureWebJobsStorage.
  • task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Ve výchozím nastavení se používá název centra úloh v souboru host.json .

Následující příkaz odstraní všechna data úložiště Azure přidružená k UserTest centru úloh.

func durable delete-task-hub --task-hub-name UserTest

Další kroky