Správa instancí v Durable Functions v Azure

Orchestrace v Durable Functions jsou dlouhotrvající stavové funkce, které se dají spustit, dotazovat, pozastavit, obnovit a ukončit pomocí integrovaných rozhraní API pro správu. Klientská vazba orchestrace Durable Functions také vystavuje několik dalších rozhraní API pro správu instancí, jako je odesílání externích událostí do instancí, vymazání historie instancí atd. Tento článek obsahuje podrobnosti o všech podporovaných operacích správy instancí.

Spuštění instancí

Metoda start-new (nebo schedule-new) na vazbě klienta orchestrace spustí novou instanci orchestrace. Interně tato metoda zapíše zprávu prostřednictvím zprostředkovatele úložiště Durable Functions a poté vrátí. 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, který se má naplánovat.
• Vstup: Jakákoli serializovatelná data JSON, která by měla být předána jako vstup do funkce orchestrátoru.
• InstanceId: (Volitelné) Jedinečné ID instance. Pokud tento parametr nezadáte, použije metoda náhodné ID.

Tip

Kdykoli 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í při škálování funkcí orchestrátoru napříč několika virtuálními počítači. Správný čas pro použití nenáhodných ID instancí je, když ID musí pocházet z externího zdroje nebo při implementaci vzoru jednoúčelového orchestrátoru.

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

C#

[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 musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

Pokud není uvedeno jinak, příklady na této stránce používají trigger HTTP s následujícími function.json.

function.json

{
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Poznámka:

Tento příklad cílí na Durable Functions verze 2.x. Ve verzi 1.x použijte orchestrationClient místo durableClient.

index.js

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

module.exports = async function(context, input) {
    const client = df.getClient(context);

    const instanceId = await client.startNew("HelloWorld", undefined, input);
    context.log(`Started orchestration with ID = ${instanceId}.`);
};

Python

Pokud není uvedeno jinak, příklady na této stránce používají trigger HTTP s následujícími function.json.

function.json

{
  "scriptFile": "__init__.py",
  "bindings": [    
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Poznámka:

Tento příklad cílí na Durable Functions verze 2.x. Ve verzi 1.x použijte orchestrationClient místo durableClient.

__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)
    
    instance_id = await client.start_new('HelloWorld', None, None)
    logging.log(f"Started orchestration with ID = ${instance_id}.")

PowerShell

Pokud není uvedeno jinak, příklady na této stránce používají trigger HTTP s následujícími function.json.

function.json

{
  "bindings": [    
    {
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "Response",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Poznámka:

Tento příklad cílí na Durable Functions verze 2.x. Ve verzi 1.x použijte orchestrationClient místo durableClient.

run.ps1

param($Request, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld'
Write-Host "Started orchestration with ID = '$InstanceId'"

Java

@FunctionName("HelloWorldQueueTrigger")
public void helloWorldQueueTrigger(
        @QueueTrigger(name = "input", queueName = "start-queue", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    String instanceID = client.scheduleNewOrchestrationInstance("HelloWorld");
    context.getLogger().info("Scheduled orchestration with ID = " + instanceID);
}

Pokud chcete před návratem z funkce počkat, než se orchestrátor spustí, můžete také použít metodu waitForInstanceStart() .

// wait up to 30 seconds for the scheduled orchestration to enter the "Running" state
client.waitForInstanceStart(instanceID, Duration.ofSeconds(30));

Azure Functions Core Tools

Instanci můžete spustit také 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. Pro soubory přidejte předponu k cestě k souboru, @například @path/to/file.json.
• id (volitelné): ID instance orchestrace. Pokud tento parametr nezadáte, použije příkaz 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 host.json pomocí durableTask:HubName.

Poznámka:

Příkazy 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 parametry a task-hub-name parametry, můžete příkazy spustit z libovolného adresáře. I když tyto příkazy můžete spouštět bez spuštěného hostitele aplikace funkcí, můžete zjistit, že pokud není hostitel spuštěný, některé efekty nemůžete sledovat. start-new Například příkaz založí zprávu startu 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í jenom v případě, že pro zachování stavu modulu runtime používáte výchozího poskytovatele služby Azure Storage.

Následující příkaz spustí funkci s názvem HelloWorld a předá do ní 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 na vazbě klienta orchestrace dotazuje stav instance orchestrace.

Jako parametry přebírá instanceId (povinné), showHistory (volitelné showHistoryOutput ), (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 byla spuštěna funkce orchestrátoru.
• LastUpdatedTime: Čas posledního kontrolního bodu orchestrace.
• Vstup: Vstup funkce jako hodnota JSON. Pokud je toto pole nepravdivé, toto pole se nenaplní showInput .
• CustomStatus: Vlastní stav orchestrace ve formátu JSON
• Výstup: Výstup funkce jako hodnota JSON (pokud se funkce dokončila). Pokud funkce orchestrátoru selhala, tato vlastnost obsahuje podrobnosti o selhání. Pokud byla funkce orchestrátoru pozastavena nebo ukončena, zahrnuje tato vlastnost důvod pozastavení nebo ukončení (pokud existuje).
• RuntimeStatus: Jedna z následujících hodnot:
  • Čeká se: Instance byla naplánovaná, ale ještě nebyla spuštěna.
  • Spuštěno: Instance se spustila.
  • Dokončeno: Instance se dokončila normálně.
  • ContinuedAsNew: Instance se znovu spustila s novou historií. Tento stav je přechodný.
  • Nezdařilo se: 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 truehodnotu .

Poznámka:

Orchestrátor není označený jako Completed dokud nedokončí všechny naplánované úkoly 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 zvlášť důležité pro případy, kdy WhenAny se používají; tyto orchestrátory často return před provedením všech naplánovaných úloh.

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

C#

[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 musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const status = await client.getStatus(instanceId);
    // do something based on the current status.
    // example: if status.runtimeStatus === df.OrchestrationRuntimeStatus.Running: ...
}

Viz instance Start pro konfiguraci function.json.

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    status = await client.get_status(instance_id)
    # do something based on the current status
    # example: if (existing_instance.runtime_status is df.OrchestrationRuntimeStatus.Running) { ...

PowerShell

param($Request, $TriggerMetadata)

# Get instanceid from body
$InstanceId = $Request.Body.InstanceId

$Status = Get-DurableStatus -InstanceId $InstanceId -ShowHistory -ShowHistoryOutput -ShowInput
Write-Host "Status: $($Status | ConvertTo-Json)"

# Do something based on status
# example: if ($Status.runtimeStatus -eq 'Running') { ... }

Java

@FunctionName("GetStatus")
public void getStatus(
        @QueueTrigger(name = "instanceID", queueName = "check-status-queue", connection = "Storage") String instanceID,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    OrchestrationMetadata metadata = client.getInstanceMetadata(instanceID, false);
    if (metadata != null) {
        OrchestrationRuntimeStatus status = metadata.getRuntimeStatus();
        switch (status) {
            // do something based on the current status
        }
    }
}

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řijímá 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 nastavena 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í hodnota je AzureWebJobsStorage.
• task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Dá se také nastavit v 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í hodnota je AzureWebJobsStorage.
• task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Dá se také nastavit v host.json pomocí durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Dotazování na všechny instance

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

C#

[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 musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const instances = await client.getStatusAll();
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

Viz instance Start pro konfiguraci function.json.

Python

import logging
import json
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)

    instances = await client.get_status_all()

    for instance in instances:
        logging.log(json.dumps(instance))

Viz instance Start pro konfiguraci function.json.

PowerShell

Poznámka:

Tato funkce se v současné době nepodporuje v PowerShellu , ale dá se dosáhnout pomocí rozhraní HTTP API Durable Functions.

Java

@FunctionName("GetAllStatus")
public String getAllStatus(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery noFilter = new OrchestrationStatusQuery();
    OrchestrationStatusQueryResult result = client.queryInstances(noFilter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

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í 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-instances přijímá následující parametry:

• top (volitelné): Tento příkaz podporuje stránkování. Tento parametr odpovídá počtu instancí načtených 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 do další sady 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í hodnota je AzureWebJobsStorage.
• task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Dá se také nastavit v host.json pomocí durableTask:HubName.

func durable get-instances

Dotazování instancí pomocí filtrů

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

C#

[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 musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const runtimeStatus = [
        df.OrchestrationRuntimeStatus.Completed,
        df.OrchestrationRuntimeStatus.Running,
    ];
    const instances = await client.getStatusBy(
        new Date(2021, 3, 10, 10, 1, 0),
        new Date(2021, 3, 10, 10, 23, 59),
        runtimeStatus
    );
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

Viz instance Start pro konfiguraci function.json.

Python

import logging
from datetime import datetime
import json
import azure.functions as func
import azure.durable_functions as df
from azure.durable_functions.models.OrchestrationRuntimeStatus import OrchestrationRuntimeStatus

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

    instances = await client.get_status_by(
        datetime(2021, 3, 10, 10, 1, 0),
        datetime(2021, 3, 10, 10, 23, 59),
        runtime_status
    )

    for instance in instances:
        logging.log(json.dumps(instance))

PowerShell

Poznámka:

Tato funkce se v současné době nepodporuje v PowerShellu , ale dá se dosáhnout pomocí rozhraní HTTP API Durable Functions.

Java

@FunctionName("GetRunningInstances")
public String getRunningInstances(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery filter = new OrchestrationStatusQuery()
        .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.PENDING, OrchestrationRuntimeStatus.RUNNING))
        .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(7)))
        .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(1)));
    OrchestrationStatusQueryResult result = client.queryInstances(filter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

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í jenom v případě, že pro zachování stavu modulu runtime používáte výchozího poskytovatele služby Azure Storage.

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

• created-after (volitelné): Načtěte instance vytvořené po tomto datu a čase (UTC). Datum a časy formátu ISO 8601 byly přijaty.
• created-before (volitelné): Načtěte instance vytvořené před tímto datem a časem (UTC). Datum a časy formátu ISO 8601 byly přijaty.
• runtime-status (volitelné): Načtěte instance s určitým stavem (například spuštěno nebo dokončeno). 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 do další sady 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í hodnota je AzureWebJobsStorage.
• task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Dá se také nastavit v host.json pomocí durableTask:HubName.

Pokud nezadáte žádné filtry (created-afternebo created-beforeruntime-status), pří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 potřebujete zastavit, než se z nějakého důvodu dokončí, můžete ji ukončit.

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

C#

[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 musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Found a bug";
    return client.terminate(instanceId, reason);
};

Viz instance Start pro konfiguraci function.json.

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    reason = "Found a bug"
    return await client.terminate(instance_id, reason)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$Reason = 'Found a bug'

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

Java

@FunctionName("TerminateInstance")
public void terminateInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String reason = "Found a bug";
    durableContext.getClient().terminate(instanceID, reason);
}

Ukončená instance se nakonec převedou do Terminated stavu. K tomuto přechodu však nedojde okamžitě. Místo toho bude operace ukončení zařazena do fronty v centru úloh spolu s dalšími operacemi pro danou instanci. Pomocí rozhraní API pro dotazy instance můžete zjistit, 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ějí na dokončení bez ohledu na to, jestli jste ukončili instanci orchestrace, která je volala.

Pozastavení a obnovení instancí

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 okamžiku.

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

C#

[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 30 seconds to ensure that the orchestrator state is updated to suspended. 
    DateTime dueTime = context.CurrentUtcDateTime.AddSeconds(30);
    await context.CreateTimer(dueTime, CancellationToken.None);
    
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const suspendReason = "Need to pause workflow";
    await client.suspend(instanceId, suspendReason);

    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.  
    const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime, {zone: 'utc'}).plus({ seconds: 30 });
    yield context.df.createTimer(deadline.toJSDate());

    const resumeReason = "Continue workflow";
    await client.resume(instanceId, resumeReason);
};

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str):
    client = df.DurableOrchestrationClient(starter)

    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    due_time = context.current_utc_datetime + timedelta(seconds=30)
    yield context.create_timer(due_time)

    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$SuspendReason = 'Need to pause workflow'

Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.
$duration = New-TimeSpan -Seconds 30
Start-DurableTimer -Duration $duration

$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

Java

@FunctionName("SuspendResumeInstance")
public void suspendResumeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    DurableTaskClient client = durableContext.getClient();  
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    ctx.createTimer(Duration.ofSeconds(30)).await();

    String resumeReason = "Continue workflow";
    client.getClient().resumeInstance(instanceID, resumeReason);
}

Pozastavená instance nakonec přejde do Suspended stavu. K tomuto přechodu však nedojde okamžitě. Místo toho se operace pozastavení zařadí do fronty v centru úloh spolu s dalšími operacemi pro danou instanci. Pomocí rozhraní API pro dotazy instance můžete zjistit, 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í 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 terminate přijímá 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í hodnota je AzureWebJobsStorage.
• task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Dá se také nastavit v host.json pomocí durableTask:HubName.

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

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. Mezi 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 do spuštěných instancí pomocí rozhraní API pro vyvolání událostí klienta orchestrace. Orchestrace můžou naslouchat těmto událostem a reagovat na ně pomocí čekání na rozhraní API orchestrátoru externích událostí .

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

• ID instance: Jedinečné ID instance.
• Název události: Název události, která se má odeslat.
• Data události: Datová část json serializovatelná, která se má odeslat do instance.

C#

[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 musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const eventData = [ 1, 2, 3 ];
    return client.raiseEvent(instanceId, "MyEvent", eventData);
};

Viz instance Start pro konfiguraci function.json.

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    event_data = [1, 2 ,3]
    return await client.raise_event(instance_id, 'MyEvent', event_data)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$EventName = 'MyEvent'
$EventData = @(1,2,3)

Send-DurableExternalEvent -InstanceId $InstanceId -EventName $EventName -EventData $EventData

Java

@FunctionName("RaiseEvent")
public void raiseEvent(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String eventName = "MyEvent";
    int[] eventData = { 1, 2, 3 };
    durableContext.getClient().raiseEvent(instanceID, eventName, eventData);
}

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, událost bude 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í 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 raise-event přijímá 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í hodnota je AzureWebJobsStorage.
• task-hub-name (volitelné): Název centra úloh Durable Functions, které se má použít. Výchozí hodnota je DurableFunctionsHub. Dá se také nastavit v 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ý limit 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 je možné 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 sekundu.

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

C#

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

JavaScript

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

const timeout = "timeout";
const retryInterval = "retryInterval";

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}'.`);

    const timeoutInMilliseconds = getTimeInSeconds(req, timeout) || 30000;
    const retryIntervalInMilliseconds = getTimeInSeconds(req, retryInterval) || 1000;

    const response = client.waitForCompletionOrCreateCheckStatusResponse(
        context.bindingData.req,
        instanceId,
        timeoutInMilliseconds,
        retryIntervalInMilliseconds
    );
    return response;
};

function getTimeInSeconds(req, queryParameterName) {
    const queryValue = req.query[queryParameterName];
    return queryValue
        ? queryValue * 1000 // expected to be in seconds
        : undefined;
}

Viz instance Start pro konfiguraci function.json.

Python

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

timeout = "timeout"
retry_interval = "retryInterval"

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    instance_id = await client.start_new(req.route_params['functionName'], None, req.get_body())
    logging.log(f"Started orchestration with ID = '${instance_id}'.")

    timeout_in_milliseconds = get_time_in_seconds(req, timeout)
    timeout_in_milliseconds = timeout_in_milliseconds if timeout_in_milliseconds != None else 30000
    retry_interval_in_milliseconds = get_time_in_seconds(req, retry_interval)
    retry_interval_in_milliseconds = retry_interval_in_milliseconds if retry_interval_in_milliseconds != None else 1000

    return await client.wait_for_completion_or_create_check_status_response(
        req,
        instance_id,
        timeout_in_milliseconds,
        retry_interval_in_milliseconds
    )

def get_time_in_seconds(req: func.HttpRequest, query_parameter_name: str):
    query_value = req.params.get(query_parameter_name)
    return query_value if query_value != None else 1000

PowerShell

Poznámka:

PowerShell v současné době nemá integrovaný příkaz pro tento scénář.

Java

Java v současné době nemá pro tento scénář jedinou metodu. Dá se ale implementovat pomocí několika dalších řádků kódu.

@FunctionName("HttpStartAndWait")
public HttpResponseMessage httpStartAndWait(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}/wait", methods = {HttpMethod.POST}) 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);
    try {
        String timeoutString = req.getQueryParameters().get("timeout");
        Integer timeoutInSeconds = Integer.parseInt(timeoutString);
        OrchestrationMetadata orchestration = client.waitForInstanceCompletion(
                instanceId,
                Duration.ofSeconds(timeoutInSeconds),
                true /* getInputsAndOutputs */);
        return req.createResponseBuilder(HttpStatus.OK)
                .body(orchestration.getSerializedOutput())
                .header("Content-Type", "application/json")
                .build();
    } catch (TimeoutException timeoutEx) {
        // timeout expired - return a 202 response
        return durableContext.createCheckStatusResponse(req, instanceId);
    }
}

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 zapisována funkce triggeru HTTP, můžete ji nahradit názvem libovolné funkce orchestrátoru ve vašem projektu.

V závislosti na době potřebné 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 doručuje 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!"
]

• Instance orchestrace se v rámci definovaného časového limitu nedokončí a odpověď je výchozí, která je popsaná ve zjišťování adres URL rozhraní HTTP API:

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 určený pro hostitele Azure Functions 3.0.

Načtení adres URL webhooků pro správu HTTP

Externí systém můžete použít k monitorování nebo vyvolání událostí pro 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. Adresy URL webhooku lze alternativně přistupovat prostřednictvím kódu programu pomocí vazby klienta orchestrace. Konkrétně lze k získání serializovatelného objektu , který obsahuje tyto adresy URL webhooků, použít rozhraní API pro vytvoření datové části správy HTTP.

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 "raise event" instance orchestrace.
• TerminatePostUri: Adresa URL "terminate" instance orchestrace.
• PurgeHistoryDeleteUri: Adresa URL "vyprázdnění historie" instance orchestrace.
• suspendPostUri: Adresa URL "suspend" instance orchestrace.
• resumePostUri: Adresa URL "resume" instance orchestrace.

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

C#

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

    // send the payload to Azure 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 DurableActivityContext místo IDurableActivityContext, musíte použít OrchestrationClient atribut místo DurableClient atributu, a musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

modules.exports = async function(context, ctx) {
    const client = df.getClient(context);

    const payload = client.createHttpManagementPayload(ctx.instanceId);

    // send the payload to Azure Cosmos DB
    context.bindings.document = JSON.stringify({
        id: ctx.instanceId,
        payload,
    });
};

Viz instance Start pro konfiguraci function.json.

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.cosmosdb.cdb.Document:
    client = df.DurableOrchestrationClient(starter)

    payload = client.create_check_status_response(req, instance_id).get_body().decode()

    return func.cosmosdb.CosmosDBConverter.encode({
        id: instance_id,
        payload: payload
    })

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId
$Response = New-DurableOrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
Push-OutputBinding -Name Response -Value $Response

Java

Poznámka:

Tato funkce se v současné době nepodporuje v Javě.

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ů. Orchestrace v jiných stavech než Failed (např Running. , Pending, Terminated, ) Completednesmí být "znovu". Další informace o zpracování chyb a zásadách opakování najdete v článku Zpracování chyb.

Pomocí metody (.NET) nebo rewind (JavaScript) vazby klienta orchestrace přepněte orchestraci zpět do stavu Spuštěno.RewindAsync 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 odpověď v reálném čase. Jakmile všechny aktivity schválení obdržely odpovědi nebo vypršel časový limit, předpokládejme, že kvůli chybné konfiguraci aplikace selže jiná aktivita, například kvůli neplatné databázi připojovací řetězec. Výsledkem je selhání orchestrace hluboko do pracovního postupu. RewindAsync Pomocí rozhraní API (.NET) nebo rewind (JavaScript) může správce aplikace opravit chybu konfigurace a převinout orchestraci, která selhala, zpět do stavu bezprostředně 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.

C#

[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 DurableClient atributu a musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Orchestrator failed and needs to be revived.";
    return client.rewind(instanceId, reason);
};

Viz instance Start pro konfiguraci function.json.

Python

Poznámka:

Tato funkce se v Pythonu v současné době nepodporuje.

PowerShell

Poznámka:

Tato funkce se v PowerShellu v současné době nepodporuje.

Java

Poznámka:

Tato funkce se v současné době nepodporuje v Javě.

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í 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 rewind přijímá následující parametry:

• id (povinné): ID instance orchestrace.
• reason (volitelné): Důvod převinutí instance orchestrace zpět.
• 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. 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."

Vymazání historie instancí

Pokud chcete odebrat všechna data přidružená k orchestraci, můžete historii instancí vymazat. 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 vyprázdnění definované klientem orchestrace.

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

C#

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

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);
    return client.purgeInstanceHistory(instanceId);
};

Viz instance Start pro konfiguraci function.json.

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    return await client.purge_instance_history(instance_id)

PowerShell

Poznámka:

Tato funkce se v současné době nepodporuje v PowerShellu , ale dá se dosáhnout pomocí rozhraní HTTP API Durable Functions.

Java

@FunctionName("PurgeInstance")
public HttpResponseMessage purgeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}, route = "purge/{instanceID}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("instanceID") String instanceID) {
    PurgeResult result = durableContext.getClient().purgeInstance(instanceID);
    if (result.getDeletedInstanceCount() == 0) {
        return req.createResponseBuilder(HttpStatus.NOT_FOUND)
                .body("No completed instance with ID '" + instanceID + "' was found!")
                .build();
    } else {
        return req.createResponseBuilder(HttpStatus.OK)
                .body("Successfully purged data for " + instanceID)
                .build();
    }
}

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:

C#

[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 DurableClient atributu a musíte použít DurableOrchestrationClient typ parametru místo IDurableOrchestrationClient. Další informace o rozdílech mezi verzemi najdete v článku o verzích Durable Functions.

JavaScript

Metodu purgeInstanceHistoryBy lze použít k podmíněnému vymazání historie instancí pro více instancí.

function.json

{
  "bindings": [
    {
      "schedule": "0 0 12 * * *",
      "name": "myTimer",
      "type": "timerTrigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Poznámka:

Tento příklad cílí na Durable Functions verze 2.x. Ve verzi 1.x použijte orchestrationClient místo durableClient.

index.js

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

module.exports = async function (context, myTimer) {
    const client = df.getClient(context);
    const createdTimeFrom = new Date(0);
    const createdTimeTo = new Date().setDate(today.getDate() - 30);
    const runtimeStatuses = [ df.OrchestrationRuntimeStatus.Completed ];
    return client.purgeInstanceHistoryBy(createdTimeFrom, createdTimeTo, runtimeStatuses);
};

PowerShell

Poznámka:

Tato funkce se v současné době nepodporuje v PowerShellu , ale dá se dosáhnout pomocí rozhraní HTTP API Durable Functions.

Python

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    created_time_from = datetime.min
    created_time_to = datetime.today() + timedelta(days = -30)
    runtime_statuses = [OrchestrationRuntimeStatus.Completed]

    return await client.purge_instance_history_by(created_time_from, created_time_to, runtime_statuses)

Java

@FunctionName("PurgeInstances")
public void purgeInstances(
        @TimerTrigger(name = "purgeTimer", schedule = "0 0 12 * * *") String timerInfo,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        ExecutionContext context) throws TimeoutException {
    PurgeInstanceCriteria criteria = new PurgeInstanceCriteria()
            .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(60)))
            .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(30)))
            .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.COMPLETED));
    PurgeResult result = durableContext.getClient().purgeInstances(criteria);
    context.getLogger().info(String.format("Purged %d instance(s)", result.getDeletedInstanceCount()));
}

Poznámka:

Aby operace historie vyprázdně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 vyprázdnit pomocí func durable purge-history příkazu v nástrojích Core Tools. Podobně jako v druhém příkladu 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í 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 purge-history má několik parametrů:

• created-after (volitelné): Vymažte historii instancí vytvořených po tomto datu a čase (UTC). Datum a časy formátu ISO 8601 byly přijaty.
• created-before (volitelné): Vymažte historii instancí vytvořených před tímto datem a časem (UTC). Datum a časy formátu ISO 8601 byly přijaty.
• runtime-status (volitelné): Vymažte historii instancí s určitý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í hodnota 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. listopadu 2021 v 17: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é k určité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í 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 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í hodnota 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

Naučte se zpracovávat správu verzí.

Předdefinované referenční informace k rozhraní HTTP API pro správu instancí