Verwalten von Instanzen in dauerhaften Funktionen in Azure

Orchestrierungen in langlebigen, zustandbehafteten Funktionen sind Funktionen, die mit integrierten Management-APIs gestartet, abgefragt, angehalten, fortgesetzt und beendet werden können. Mehrere andere Instanzverwaltungs-APIs werden auch durch die Orchestrierungs-Clientbindung der Durable Functions bereitgestellt, z. B. das Senden externer Ereignisse an Instanzen, das Löschen des Instanzverlaufs usw. In diesem Artikel werden die Details aller unterstützten Instanzverwaltungsoperationen erläutert.

Starten von Instanzen

Die Methode "start-new" (oder "schedule-new") auf der Orchestrierungs-Clientbindung startet eine neue Orchestrierungsinstanz. Intern schreibt diese Methode eine Nachricht über den Speicheranbieter für dauerhafte Funktionen und gibt dann zurück. Diese Meldung löst asynchron den Start einer Orchestrierungsfunktion mit dem angegebenen Namen aus.

Die Parameter für das Starten einer neuen Orchestrierungsinstanz sind wie folgt:

• Name: Der Name der Orchestratorfunktion, die zu planen ist.
• Eingabe: Alle JSON-serialisierbaren Daten, die als Eingabe an die Orchestratorfunktion übergeben werden sollen.
• InstanceId: (Optional) Die eindeutige ID der Instanz. Wenn Sie diesen Parameter nicht angeben, verwendet die Methode eine zufällige ID.

Tipp

Verwenden Sie nach Möglichkeit einen zufälligen Bezeichner für die Instanz-ID. Zufällige Instanzen-IDs sorgen dafür, dass eine gleichmäßige Lastverteilung gewährleistet wird, wenn Sie Orchestratorfunktionen auf mehrere VMs skalieren. Die richtige Zeit für die Verwendung nicht zufälliger Instanzen-IDs ist, wenn die ID von einer externen Quelle stammen muss oder wenn Sie das Singleton Orchestrator-Muster implementieren.

Der folgende Code ist eine Beispielfunktion, die eine neue Orchestrierungsinstanz startet:

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

JavaScript

Sofern nicht anders angegeben, verwenden die Beispiele auf dieser Seite den HTTP-Trigger mit dem folgenden 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
}

Hinweis

Dieses Beispiel ist auf Durable Functions Version 2.x ausgerichtet. Verwenden Sie orchestrationClient in Version 1.x anstelle von 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

Sofern nicht anders angegeben, verwenden die Beispiele auf dieser Seite den HTTP-Trigger mit dem folgenden 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
}

Hinweis

Dieses Beispiel zielt auf Durable Functions Version 2.x ab. Verwenden Sie orchestrationClient in Version 1.x anstelle von 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

Sofern nicht anders angegeben, verwenden die Beispiele auf dieser Seite den HTTP-Trigger mit dem folgenden 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
}

Hinweis

Dieses Beispiel gilt für Durable Functions Version 2.x. Verwenden Sie orchestrationClient in Version 1.x anstelle von 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);
}

Wenn Sie warten möchten, bis der Orchestrator gestartet wird, bevor Sie von Ihrer Funktion zurückkehren, können Sie auch die waitForInstanceStart() Methode verwenden.

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

Azure Funktionen Kernwerkzeuge

Sie können eine Instanz auch direkt starten, indem Sie den Befehl in Core func durable start-new Tools verwenden, der die folgenden Parameter verwendet:

• function-name (erforderlich): Name der zu startenden Funktion.
• input (optional): Eingabe an die Funktion, entweder inline oder über eine JSON-Datei. Fügen Sie für Dateien dem Pfad zur Datei ein Präfix hinzu @, z.B. @path/to/file.json.
• id (optional): ID der Orchestrierungsinstanz. Wenn Sie diesen Parameter nicht angeben, verwendet der Befehl eine zufällige GUID.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert ist AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions Aufgabenhubs. Der Standardwert ist DurableFunctionsHub. Sie können dies auch in host.json festlegen, indem Sie "durableTask:HubName" verwenden.

Hinweis

Kerntools-Befehle gehen davon aus, dass Sie sie aus dem Stammverzeichnis einer Funktions-App ausführen. Wenn Sie die connection-string-setting Befehle explizit angeben und task-hub-name Parameter angeben, können Sie die Befehle aus einem beliebigen Verzeichnis ausführen. Obwohl Sie diese Befehle ohne einen laufenden Funktions-App-Host ausführen können, könnten Sie feststellen, dass sich einige Effekte erst beobachten lassen, wenn der Host aktiv ist. Beispielsweise reiht der Befehl start-new eine Startmeldung in die Warteschlange für den Zielaufgabenhub ein, die Orchestrierung wird jedoch nicht ausgeführt, bis ein Funktions-App-Hostprozess ausgeführt wird, der die Nachricht verarbeiten kann.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Der folgende Befehl startet die Funktion "HelloWorld" und übergibt den Inhalt der Datei counter-data.json an sie.

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

Abfragen von Instanzen

Nach dem Start neuer Orchestrierungsinstanzen müssen Sie höchstwahrscheinlich deren Laufzeitstatus abfragen, um herauszufinden, ob sie ausgeführt werden, abgeschlossen sind oder fehlgeschlagen sind.

Die Get-Status-Methode für die Orchestrierungsclientbindung fragt den Status einer Orchestrierungsinstanz ab.

Es akzeptiert ein instanceId (erforderlich), showHistory (optional), showHistoryOutput (optional) und showInput (optional) als Parameter.

• showHistory: Wenn dieser Wert festgelegt ist true, enthält die Antwort den Ausführungsverlauf.
• showHistoryOutput: Wenn dieser Wert auf true festgelegt ist, enthält der Ausführungsverlauf Aktivitätsausgaben.
• showInput: Wenn diese Einstellung falsefestgelegt ist, enthält die Antwort nicht die Eingabe der Funktion. Der Standardwert ist true.

Die Methode gibt ein Objekt mit den folgenden Eigenschaften zurück:

• Name: Der Name der Orchestratorfunktion.
• InstanceId: Die Instanz-ID der Orchestrierung (sollte mit der instanceId Eingabe identisch sein).
• CreatedTime: Der Zeitpunkt, zu dem die Orchestratorfunktion gestartet wurde.
• LastUpdatedTime: der Zeitpunkt des letzten Prüfpunkts der Orchestrierung.
• Eingabe: Die Eingabe der Funktion als JSON-Wert. Dieses Feld wird nicht ausgefüllt, wenn showInput "false" ist.
• CustomStatus: Benutzerdefinierter Orchestrierungsstatus im JSON-Format.
• Ausgabe: Die Ausgabe der Funktion als JSON-Wert (wenn die Funktion abgeschlossen wurde). Wenn die Orchestratorfunktion fehlgeschlagen ist, enthält diese Eigenschaft die Fehlerdetails. Wenn die Orchestratorfunktion angehalten oder beendet wurde, enthält diese Eigenschaft den Grund für das Anhalten oder Beenden (falls vorhanden).
• RuntimeStatus: Einer der folgenden Werte:
  • Ausstehend: Die Instanz wurde geplant, aber noch nicht gestartet.
  • Ausführen: Die Instanz wurde ausgeführt.
  • Abgeschlossen: Die Instanz wurde normal abgeschlossen.
  • ContinuedAsNew: Die Instanz hat sich selbst mit einem neuen Verlauf neu gestartet. Dieser Zustand ist ein vorübergehender Zustand.
  • Fehler: Fehler bei der Instanz.
  • Beendet: Die Instanz wurde abrupt beendet.
  • Suspended: Die Instanz wurde suspendiert und kann zu einem späteren Zeitpunkt wieder aufgenommen werden.
• History: Der Ausführungsverlauf der Orchestrierung. Dieses Feld wird nur ausgefüllt, wenn showHistory auf true festgelegt ist.

Hinweis

Ein Orchestrator wird erst mit Completed gekennzeichnet, wenn alle seine geplanten Aufgaben abgeschlossen wurden und der Orchestrator die Anweisung zum Zurückgeben ausgeführt hat. Das bedeutet, es reicht nicht aus, dass ein Orchestrator seine return-Anweisung erreicht, damit er mit Completed gekennzeichnet wird. Dies ist besonders für Fälle relevant, in denen WhenAny verwendet wird; diese Orchestratoren führen häufig return aus, bevor alle geplanten Aufgaben abgeschlossen sind.

Diese Methode gibt null (.NET und Java), undefined (JavaScript) oder None (Python) zurück, wenn die Instanz nicht vorhanden ist.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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: ...
}

Siehe Startinstanzen für die function.json-Konfiguration.

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 Funktionen Kernwerkzeuge

Es ist auch möglich, den Status einer Orchestrierungsinstanz direkt mithilfe des Befehls in Core func durable get-runtime-status Tools abzurufen.

Hinweis

Core Tools-Befehle werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Für den Befehl durable get-runtime-status werden die folgenden Parameter verwendet:

• id (erforderlich): ID der Orchestrierungsinstanz.
• show-input (optional): Wenn dieser Wert festgelegt ist true, enthält die Antwort die Eingabe der Funktion. Der Standardwert ist false.
• show-output (optional): Wenn dieser Wert festgelegt ist true, enthält die Antwort die Ausgabe der Funktion. Der Standardwert ist false.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Aufgabenhubs für Durable Functions. Der Standardwert lautet DurableFunctionsHub. Sie kann auch in host.jsonfestgelegt werden, indem "durableTask:HubName" verwendet wird.

Der folgende Befehl ruft den Status (einschließlich Eingabe und Ausgabe) einer Instanz mit einer Orchestrierungsinstanz-ID von 0ab8c55a6644d68a3a8b220b12d209c ab. Es wird davon ausgegangen, dass Sie den func Befehl aus dem Stammverzeichnis der Funktions-App ausführen:

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

Mit dem durable get-history Befehl können Sie den Verlauf einer Orchestrierungsinstanz abrufen. Hierfür werden die folgenden Parameter verwendet:

• id (erforderlich): ID der Orchestrierungsinstanz.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions Aufgabenhubs. Der Standardwert lautet DurableFunctionsHub. Es kann auch in host.jsonfestgelegt werden, indem "durableTask:HubName" verwendet wird.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Abfragen aller Instanzen

Sie können APIs in Ihrem Sprach-SDK verwenden, um die Status aller Orchestrierungsinstanzen in Ihrem Aufgabenhub abzufragen. Diese API "list-instances" oder "get-status" gibt eine Liste von Objekten zurück, die die Orchestrierungsinstanzen darstellen, die den Abfrageparametern entsprechen.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Siehe Startinstanzen für die function.json-Konfiguration.

PowerShell

Hinweis

Dieses Feature wird derzeit in PowerShell nicht unterstützt, kann jedoch mithilfe der HTTP-API für dauerhafte Funktionen erreicht werden.

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 Funktionen Kernwerkzeuge

Es ist auch möglich, Instanzen direkt mithilfe des Befehls in Core func durable get-instances Tools abzufragen.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Für den Befehl durable get-instances werden die folgenden Parameter verwendet:

• top (optional): Dieser Befehl unterstützt paging. Dieser Parameter entspricht der Anzahl der Instanzen, die pro Anforderung abgerufen wurden. Der Standardwert ist 10.
• continuation-token (optional): Ein Token, das angibt, welche Seite oder welcher Abschnitt von Instanzen abgerufen werden soll. Jede get-instances Ausführung gibt ein Token an den nächsten Satz von Instanzen zurück.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions Aufgabenhubs. Der Standardwert lautet DurableFunctionsHub. Sie kann auch in host.jsonfestgelegt werden, indem "durableTask:HubName" verwendet wird.

func durable get-instances

Abfrageinstanzen mit Filtern

Was geschieht, wenn Sie nicht wirklich alle Informationen benötigen, die eine Standardinstanzabfrage bereitstellen kann? Wie wäre es beispielsweise, wenn Sie nur nach der Zeit für die Orchestrierungserstellung oder nach dem Orchestrierungslaufzeitstatus suchen? Sie können Ihre Abfrage einschränken, indem Sie Filter anwenden.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Hinweis

Dieses Feature wird derzeit in PowerShell nicht unterstützt, kann jedoch mithilfe der HTTP-API für dauerhafte Funktionen erreicht werden.

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 Funktionen Kernwerkzeuge

In den Azure Functions Core Tools können Sie auch den durable get-instances Befehl mit Filtern verwenden. Zusätzlich zu den oben genannten top, , continuation-token, connection-string-settingund task-hub-name Parametern können Sie drei Filterparameter (created-after, created-beforeund runtime-status) verwenden.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Im Folgenden sind die Parameter für den durable get-instances Befehl aufgeführt.

• created-after (optional): Rufen Sie die Instanzen ab, die nach diesem Datum/dieser Uhrzeit (UTC) erstellt wurden. ISO-8601 formatierte Datums- und Zeitangaben werden akzeptiert.
• created-before (optional): Rufen Sie die Instanzen ab, die vor diesem Datum/dieser Uhrzeit (UTC) erstellt wurden. ISO 8601-formatierte Datum-Uhrzeiten werden akzeptiert.
• runtime-status (optional): Abrufen der Instanzen mit einem bestimmten Status (z. B. Ausführen oder Abgeschlossen). Kann mehrere Status (durch Leerzeichen getrennt) bereitstellen.
• top (optional): Anzahl der Instanzen, die pro Anforderung abgerufen wurden. Der Standardwert ist 10.
• continuation-token (optional): Ein Token, das angibt, welche Seite oder welcher Abschnitt von Instanzen abgerufen werden soll. Jede get-instances Ausführung gibt ein Token an den nächsten Satz von Instanzen zurück.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions Aufgabenhubs. Der Standardwert lautet DurableFunctionsHub. Sie kann auch in host.jsonfestgelegt werden, indem "durableTask:HubName" verwendet wird.

Wenn Sie keine Filter (created-after, created-beforeoder runtime-status) bereitstellen, ruft der Befehl einfach Instanzen ab top , ohne dass der Laufzeitstatus oder die Erstellungszeit berücksichtigt wird.

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

Beenden von Instanzen

Wenn die Ausführung einer Orchestrierungsinstanz zu lange dauert oder Sie sie aus beliebigem Grund vor dem Abschluss unterbrechen müssen, können Sie sie beenden.

Die beiden Parameter für die Beendigungs-API sind eine Instanz-ID und eine Grundzeichenfolge , die in Protokolle und in den Instanzstatus geschrieben werden.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Eine beendete Instanz wechselt schließlich in den Terminated Zustand. Dieser Übergang wird jedoch nicht sofort passieren. Stattdessen wird der Beendigungsvorgang im Aufgabenhub zusammen mit anderen Vorgängen für diese Instanz in eine Warteschlange eingereiht. Sie können die Instanzabfrage-APIs verwenden, um zu wissen, wann eine beendete Instanz tatsächlich den Terminated Status erreicht hat.

Hinweis

Die Instanzbeendigung wird momentan nicht weitergegeben. Aktivitätsfunktionen und Suborchestrierungen werden bis zum Abschluss ausgeführt, unabhängig davon, ob Sie die Orchestrierungsinstanz beendet haben, die sie aufgerufen hat.

Anhalten und Fortsetzen von Instanzen

Durch das Anhalten einer Orchestrierung können Sie eine laufende Orchestrierung beenden. Im Gegensatz zur Beendigung haben Sie die Möglichkeit, einen angehaltenen Orchestrator zu einem späteren Zeitpunkt fortzusetzen.

Die beiden Parameter für die Suspend-API sind eine Instanz-ID und ein Begründungstext, die in die Protokolle und den Instanzstatus geschrieben werden.

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // To resume an orchestration
    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);

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

    // To resume an orchestration
    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)

    # To suspend an orchestration
    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # To resume an orchestration
    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

# To suspend an orchestration
$SuspendReason = 'Need to pause workflow'
Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# To resume an orchestration
$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

Hinweis

Dieses Feature ist nur im eigenständigen PowerShell-SDK für dauerhafte Funktionen verfügbar. Sehen Sie sich den Unterschied zwischen dem eigenständigen SDK und dem integrierten Legacy-SDK zusammen mit dem Migrationshandbuch an.

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

    // To suspend an orchestration
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // To resume an orchestration
    String resumeReason = "Continue workflow";
    client.resumeInstance(instanceID, resumeReason);
}

Eine angehaltene Instanz wird schließlich in den Zustand Suspended wechseln. Dieser Übergang wird jedoch nicht sofort passieren. Stattdessen wird der Anhaltevorgang im Aufgabenhub zusammen mit anderen Vorgängen für diese Instanz in eine Warteschlange eingereiht. Sie können die Instanzabfrage-APIs verwenden, um zu wissen, wann eine ausgeführte Instanz tatsächlich den Zustand "Angehalten" erreicht hat.

Wenn ein angehaltener Orchestrator fortgesetzt wird, ändert sich sein Status erneut in Running.

Azure Funktionen Kernwerkzeuge

Sie können eine Orchestrierungsinstanz auch direkt beenden, indem Sie den func durable terminate-Befehl in Core Tools verwenden.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Für den Befehl durable terminate werden die folgenden Parameter verwendet:

• id (erforderlich): ID der zu beendenden Orchestrierungsinstanz.
• reason (optional): Grund für kündigung.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des Task-Hubs für Dauerhafte Funktionen, der verwendet werden soll. Der Standardwert lautet DurableFunctionsHub. Sie kann auch in host.jsonfestgelegt werden, indem "durableTask:HubName" verwendet wird.

Der folgende Befehl beendet eine Orchestrierungsinstanz mit einer ID von 0ab8c55a6644d68a3a8b220b12d209c:

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

Senden von Ereignissen an Instanzen

In einigen Szenarien müssen Orchestratorfunktionen warten und auf externe Ereignisse lauschen. Beispiele für Szenarien, in denen dies hilfreich ist, sind überwachungs - und menschliche Interaktionsszenarien .

Sie können Ereignisbenachrichtigungen an ausgeführte Instanzen senden, indem Sie die Auslösen-Ereignis-API des Orchestrierungsclients verwenden. Orchestrierungen können diese Ereignisse überwachen und darauf reagieren, indem sie die Warten auf externes Ereignis Orchestrator-API verwenden.

Die Parameter für das Auslösen-Ereignis sind wie folgt:

• Instanz-ID: Die eindeutige ID der Instanz.
• Ereignisname: Der Name des zu sendenden Ereignisses.
• Ereignisdaten: Eine JSON-serialisierbare Nutzlast, die an die Instanz gesendet werden soll.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Hinweis

Wenn keine Orchestrierungsinstanz mit der angegebenen Instanz-ID vorhanden ist, wird die Ereignismeldung verworfen. Wenn eine Instanz vorhanden ist, aber noch nicht auf das Ereignis wartet, wird das Ereignis im Instanzzustand gespeichert, bis es bereit ist, empfangen und verarbeitet zu werden.

Azure Funktionen Kernwerkzeuge

Sie können ein Ereignis für eine Orchestrierungsinstanz auch direkt mit dem func durable raise-event-Befehl der Azure Core Tools auslösen.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Für den Befehl durable raise-event werden die folgenden Parameter verwendet:

• id (erforderlich): ID der Orchestrierungsinstanz.
• event-name: Name des auszulösenden Ereignisses.
• event-data (optional): Daten, die an die Orchestrierungsinstanz gesendet werden sollen. Dies kann der Pfad zu einer JSON-Datei sein, oder Sie können die Daten direkt in der Befehlszeile bereitstellen.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions-Aufgabenhubs. Der Standardwert lautet DurableFunctionsHub. Sie kann auch in host.jsonfestgelegt werden, indem "durableTask:HubName" verwendet wird.

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

Warten auf den Abschluss der Orchestrierung

Bei lange andauernden Orchestrierungen möchten Sie vielleicht warten und die Ergebnisse einer Orchestrierung erhalten. In diesen Fällen ist es auch nützlich, einen Timeoutzeitraum für die Orchestrierung zu definieren. Wenn das Timeout überschritten wird, sollte der Status der Orchestrierung anstelle der Ergebnisse zurückgegeben werden.

Die API zum Warten auf den Abschluss oder die Erstellung einer Antwort zur Statusüberprüfung kann verwendet werden, um die tatsächliche Ausgabe einer Orchestrierungsinstanz synchron abzurufen. Standardmäßig verfügt diese Methode über ein standardmäßiges Timeout von 10 Sekunden und ein Abfrageintervall von 1 Sekunde.

Nachfolgend sehen Sie eine Beispielfunktion für HTTP-Trigger, die die Verwendung dieser API veranschaulicht:

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Hinweis

PowerShell verfügt derzeit nicht über einen integrierten Befehl für dieses Szenario.

Java

Java verfügt derzeit nicht über eine einzige Methode für dieses Szenario. Sie kann jedoch mit einigen zusätzlichen Codezeilen implementiert werden.

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

Rufen Sie die Funktion mit der folgenden Zeile auf. Verwenden Sie 2 Sekunden für das Timeout und 0,5 Sekunden für das Wiederholungsintervall:

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

Hinweis

Der obige cURL-Befehl geht davon aus, dass Sie über eine Orchestratorfunktion verfügen, die in Ihrem Projekt benannt ist E1_HelloSequence . Aufgrund der Art und Weise, wie die HTTP-Triggerfunktion geschrieben wird, können Sie sie durch den Namen jeder Orchestratorfunktion in Ihrem Projekt ersetzen.

Je nachdem, wie lange es dauert, eine Antwort von der Orchestrierungsinstanz zu erhalten, gibt es zwei Szenarien:

• Die Orchestrierungsinstanzen werden innerhalb des definierten Zeitraums (hier: 2 Sekunden) abgeschlossen, und die Antwort ist die tatsächliche Orchestrierungsinstanzausgabe, die synchron bereitgestellt wird:

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

• Die Orchestrierungsinstanzen können nicht innerhalb des definierten Timeouts abgeschlossen werden, und die Antwort ist die Standardinstanz, die in der HTTP-API-URL-Ermittlung beschrieben wird:

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

Hinweis

Das Format der Webhook-URLs kann variieren, je nachdem, welche Version des Azure Functions-Hosts Sie ausführen. Das vorherige Beispiel ist für den Azure Functions 3.0-Host vorgesehen.

Abrufen der HTTP-Verwaltungswebhook-URLs

Sie können ein externes System zum Überwachen oder zum Auslösen von Ereignissen bei einer Orchestrierung verwenden. Externe Systeme können mit dauerhaften Funktionen über die Webhook-URLs kommunizieren, die Teil der in der HTTP-API-URL-Ermittlung beschriebenen Standardantwort sind. Der Zugriff auf die Webhook-URLs kann auch programmgesteuert mithilfe der Orchestrierungsclientbindung erfolgen. Insbesondere kann die create HTTP management payload-API verwendet werden, um ein serialisierbares Objekt zu erhalten, das diese Webhook-URLs enthält.

Die API zur Erstellung einer HTTP-Verwaltungsnutzlast hat einen Parameter:

• Instanz-ID: Die eindeutige ID der Instanz.

Die Methoden geben ein Objekt mit den folgenden Zeichenfolgeneigenschaften zurück:

• ID: Die Instanz-ID der Orchestrierung (sollte mit der InstanceId Eingabe identisch sein).
• StatusQueryGetUri: Die Status-URL der Orchestrierungsinstanz.
• SendEventPostUri: Die URL der Orchestrierungsinstanz zum Auslösen eines Ereignisses.
• TerminatePostUri: URL der Orchestrierungsinstanz für das „Beenden“.
• PurgeHistoryDeleteUri: Die URL „Verlauf löschen“ der Orchestrierungsinstanz.
• suspendPostUri: Die "suspend"-URL der Orchestrierungsinstanz.
• resumePostUri: Die „resume“-URL der Orchestrierungsinstanz.

Funktionen können Instanzen dieser Objekte zu externe Systeme senden, um Ereignisse bei den entsprechenden Orchestrierungen zu überwachen oder auszulösen, wie in den folgenden Beispielen gezeigt.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für dauerhafte Funktionen 1.x müssen Sie DurableActivityContext anstelle von IDurableActivityContext verwenden, das OrchestrationClient Attribut anstelle des DurableClient Attributs verwenden, und Sie müssen den DurableOrchestrationClient Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Hinweis

Dieses Feature wird derzeit in Java nicht unterstützt.

Zurückspulen von Instanzen (Vorschau)

Wenn aus unerwartetem Grund ein Orchestrierungsfehler auftritt, können Sie die Instanz mithilfe einer api, die zu diesem Zweck erstellt wurde, in einen zuvor fehlerfreien Zustand zurückspulen .

Hinweis

Diese API ist nicht als Ersatz für ordnungsgemäße Fehlerbehandlungs- und Wiederholungsrichtlinien gedacht. Stattdessen soll sie nur in Fällen verwendet werden, in denen Orchestrierungsinstanzen aus unerwarteten Gründen fehlschlagen. Orchestrierungen in anderen Zuständen als Failed (z. B. Running, Pending, Terminated, Completed) können nicht „zurückgespult“ werden. Weitere Informationen zur Fehlerbehandlungs- und Wiederholungsrichtlinien finden Sie im Artikel zur Fehlerbehandlung .

Verwenden Sie die RewindAsync (.NET) oder rewind (JavaScript)-Methode der Orchestrierungsclientbindung , um die Orchestrierung wieder in den Zustand "Running " zu setzen. Diese Methode führt auch die Aktivität oder die Ausführungsfehler der untergeordneten Orchestrierung, die den Orchestrierungsfehler verursacht hat, erneut aus.

Angenommen, Sie haben einen Workflow mit einer Reihe von menschlichen Genehmigungen. Angenommen, es gibt eine Reihe von Aktivitätsfunktionen, die jemanden benachrichtigen, dass seine Genehmigung erforderlich ist, und auf die Antwort in Echtzeit warten. Nachdem alle Genehmigungsaktivitäten Antworten oder Timeouts erhalten haben, gehen Sie davon aus, dass eine andere Aktivität aufgrund einer fehlkonfigurierten Anwendung fehlschlägt, z. B. eine ungültige Datenbankverbindungszeichenfolge. Das Ergebnis ist ein Orchestrierungsfehler tief im Workflow. Mit der RewindAsync (.NET)- oder rewind (JavaScript)-API kann ein Anwendungsadministrator den Konfigurationsfehler beheben und die fehlgeschlagene Orchestrierung unmittelbar vor dem Fehler wieder in den Zustand zurückspulen. Keiner der Schritte für die menschliche Interaktion muss erneut genehmigt werden, und die Orchestrierung kann jetzt erfolgreich abgeschlossen werden.

Hinweis

Das Rewind-Feature unterstützt keine Zurückspulen von Orchestrierungsinstanzen, die dauerhafte Zeitgeber verwenden.

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

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

Siehe Startinstanzen für die function.json-Konfiguration.

Python

Hinweis

Dieses Feature wird derzeit in Python nicht unterstützt.

PowerShell

Hinweis

Dieses Feature wird derzeit in PowerShell nicht unterstützt.

Java

Hinweis

Dieses Feature wird derzeit in Java nicht unterstützt.

Azure Funktionen Kernwerkzeuge

Sie können eine Orchestrierungsinstanz auch direkt mit dem func durable rewind-Befehl der Core Tools zurückspulen.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Für den Befehl durable rewind werden die folgenden Parameter verwendet:

• id (erforderlich): ID der Orchestrierungsinstanz.
• reason (optional): Grund für das Zurückspulen der Orchestrierungsinstanz.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions-Aufgabenhubs. Standardmäßig wird der Task Hub Name in der Datei host.json verwendet.

func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."

Instanzverlauf löschen

Um alle Daten im Zusammenhang mit einer Orchestrierung zu entfernen, können Sie den Instanzverlauf löschen. Sie können beispielsweise alle Speicherressourcen löschen, die einer abgeschlossenen Instanz zugeordnet sind. Verwenden Sie dazu die vom Orchestrierungsclient definierte Bereinigungsinstanz-API.

In diesem ersten Beispiel wird gezeigt, wie eine einzelne Orchestrierungsinstanz gelöscht wird.

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

Siehe Startinstanzen für die function.json-Konfiguration.

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

Hinweis

Dieses Feature wird derzeit in PowerShell nicht unterstützt, kann jedoch mithilfe der HTTP-API für dauerhafte Funktionen erreicht werden.

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

Das nächste Beispiel zeigt eine von einem Timer ausgelöste Funktion, die den Verlauf für alle Orchestrierungsinstanzen löscht, die nach Ablauf der angegebenen Zeitspanne abgeschlossen wurden. In diesem Fall werden Daten für alle Vorgänge entfernt, die vor 30 oder mehr Tagen abgeschlossen wurden. Diese Beispielfunktion soll einmal pro Tag und um 12:00 Uhr UTC ausgeführt werden:

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

Hinweis

Der vorherige C#-Code gilt für dauerhafte Funktionen 2.x. Für Durable Functions 1.x müssen Sie das OrchestrationClient-Attribut anstelle des DurableClient-Attributs verwenden, und Sie müssen den DurableOrchestrationClient-Parametertyp anstelle von IDurableOrchestrationClient verwenden. Weitere Informationen zu den Unterschieden zwischen den Versionen finden Sie im Artikel Durable Functions-Versionen.

JavaScript

Die purgeInstanceHistoryBy Methode kann zum bedingten Löschen des Instanzverlaufs für mehrere Instanzen verwendet werden.

function.json

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

Hinweis

Dieses Beispiel gilt für Durable Functions Version 2.x. Verwenden Sie orchestrationClient in Version 1.x anstelle von 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

Hinweis

Dieses Feature wird derzeit in PowerShell nicht unterstützt, kann jedoch mithilfe der HTTP-API für dauerhafte Funktionen erreicht werden.

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

Hinweis

Damit der Löschverlaufsvorgang erfolgreich ausgeführt werden kann, muss der Laufzeitstatus der Zielinstanz abgeschlossen, beendet oder fehlgeschlagen sein.

Azure Funktionen Kernwerkzeuge

Sie können den Verlauf einer Orchestrierungsinstanz löschen, indem Sie den func durable purge-history Befehl in Core Tools verwenden. Ähnlich wie im zweiten C#-Beispiel im vorherigen Abschnitt, löscht es die Historie aller Orchestrierungsinstanzen, die während eines bestimmten Zeitintervalls erstellt wurden. Sie können gelöschte Instanzen weiter nach Laufzeitstatus filtern.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Der durable purge-history Befehl hat mehrere Parameter:

• created-after (optional): Löschen des Verlaufs von Instanzen, die nach diesem Datum/dieser Uhrzeit (UTC) erstellt wurden. ISO 8601-formatierte Datum-Uhrzeiten werden akzeptiert.
• created-before (optional): Löschen des Verlaufs von Instanzen, die vor diesem Datum/dieser Uhrzeit (UTC) erstellt wurden. ISO 8601-formatierte Datum-Uhrzeiten werden akzeptiert.
• runtime-status (optional): Löschen des Verlaufs von Instanzen mit einem bestimmten Status (z. B. in Ausführung oder abgeschlossen). Kann mehrere Status (durch Leerzeichen getrennt) bereitstellen.
• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions-Aufgabenhubs. Standardmäßig wird der Name des Aufgaben-Hubs in der Datei host.json verwendet.

Der folgende Befehl löscht den Verlauf aller fehlerhaften Instanzen, die vor dem 14. November 2021 um 19:35 Uhr UTC erstellt wurden.

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

Löschen eines Aufgaben-Hubs

Mit dem func durable delete-task-hub Befehl in Core Tools können Sie alle Speicherartefakte löschen, die einem bestimmten Task Hub zugeordnet sind, einschließlich Azure-Speichertabellen, Warteschlangen und Blobs.

Hinweis

Die Befehle "Core Tools" werden derzeit nur unterstützt, wenn sie den Standardmäßigen Azure Storage-Anbieter für den dauerhaften Laufzeitstatus verwenden.

Der durable delete-task-hub Befehl hat zwei Parameter:

• connection-string-setting (optional): Name der Anwendungseinstellung, die die zu verwendende Speicherverbindungszeichenfolge enthält. Der Standardwert lautet AzureWebJobsStorage.
• task-hub-name (optional): Name des zu verwendenden Durable Functions-Aufgabenhubs. Standardmäßig wird der Task Hub Name in der Datei host.json verwendet.

Mit dem folgenden Befehl werden alle Azure-Speicherdaten gelöscht, die dem UserTest Aufgabenhub zugeordnet sind.

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

Nächste Schritte

Erfahren Sie, wie Sie die Versionsverwaltung behandeln.

Integrierte HTTP-API-Referenz für die Instanzverwaltung