Zarządzanie wystąpieniami w usłudze Durable Functions na platformie Azure

Orkiestracje w usłudze Durable Functions to długotrwałe funkcje stanowe, które mogą być uruchamiane, odpytywane, zawieszone, wznawiane i przerywane przy użyciu wbudowanych interfejsów API zarządzania. Kilka innych interfejsów API zarządzania wystąpieniami jest również udostępnianych przez powiązanie klienta orkiestracji Durable Functions, takie jak wysyłanie zdarzeń zewnętrznych do wystąpień, czyszczenie historii wystąpień itp. Ten artykuł zawiera szczegółowe informacje o wszystkich obsługiwanych operacjach zarządzania wystąpieniami.

Uruchamianie wystąpień

Metoda start-new (lub schedule-new) w powiązaniu klienta orkiestracji uruchamia nowe wystąpienie orkiestracji. Ta metoda wewnętrznie zapisuje komunikat za pośrednictwem dostawcy magazynu Durable Functions , a następnie zwraca. Ten komunikat asynchronicznie wyzwala początek funkcji orkiestracji o określonej nazwie.

Parametry uruchamiania nowego wystąpienia orkiestracji są następujące:

Nazwa: nazwa funkcji orkiestratora do zaplanowania.
Dane wejściowe: wszelkie dane serializowalne w formacie JSON, które powinny być przekazywane jako dane wejściowe do funkcji orkiestratora.
InstanceId: (Opcjonalnie) Unikatowy identyfikator wystąpienia. Jeśli nie określisz tego parametru, metoda używa losowego identyfikatora.

Wskazówka

Użyj identyfikatora losowego dla identyfikatora wystąpienia, jeśli jest to możliwe. Identyfikatory wystąpień losowych pomagają zapewnić równomierną dystrybucję obciążenia podczas skalowania funkcji orkiestratora na wielu maszynach wirtualnych. Odpowiednim momentem na użycie identyfikatorów wystąpień innych niż losowe jest wtedy, gdy identyfikator musi pochodzić ze źródła zewnętrznego lub podczas implementowania wzorca singleton orchestratora.

Poniższy kod to przykładowa funkcja, która uruchamia nową instancję orkiestracji.

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

Uwaga / Notatka

Poprzedni kod C# dotyczy funkcji Durable Functions w wersji 2.x. W przypadku Durable Functions 1.x, należy użyć atrybutu OrchestrationClient zamiast atrybutu DurableClient, a także należy użyć typu parametru DurableOrchestrationClient zamiast IDurableOrchestrationClient. Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje Durable Functions.

Jeśli nie określono inaczej, przykłady na tej stronie używają wyzwalacza HTTP z następującymi 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
}

Uwaga / Notatka

Ten przykład dotyczy Durable Functions w wersji 2.x. W wersji 1.x użyj polecenia orchestrationClient zamiast 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}.`);
};

Jeśli nie określono inaczej, przykłady na tej stronie używają wyzwalacza HTTP z następującymi 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
}

Uwaga / Notatka

Ten przykład dotyczy Durable Functions w wersji 2.x. W wersji 1.x użyj polecenia orchestrationClient zamiast 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}.")

Jeśli nie określono inaczej, przykłady na tej stronie używają wyzwalacza HTTP z następującymi 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
}

Uwaga / Notatka

Ten przykład dotyczy Durable Functions w wersji 2.x. W wersji 1.x użyj polecenia orchestrationClient zamiast durableClient.

run.ps1

param($Request, $TriggerMetadata)

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

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

Jeśli chcesz poczekać na uruchomienie orkiestratora przed powrotem z funkcji, możesz również użyć metody waitForInstanceStart().

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

Podstawowe narzędzia usługi Azure Functions

Możesz również uruchomić wystąpienie bezpośrednio przy użyciu polecenia func durable start-new w ramach narzędzi Core Tools, które obsługuje następujące parametry:

function-name (wymagane): nazwa funkcji do uruchomienia.
input (opcjonalnie): Dane wejściowe funkcji w tekście lub za pośrednictwem pliku JSON. W przypadku plików dodaj prefiks do ścieżki do pliku z elementem @, takim jak @path/to/file.json.
id (opcjonalnie): identyfikator wystąpienia orkiestracji. Jeśli nie określisz tego parametru, polecenie używa losowego identyfikatora GUID.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającego parametry połączenia magazynu do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): Nazwa centrum zadań Durable Functions do użycia. Wartość domyślna to DurableFunctionsHub. Można to również ustawić w host.json za pomocą rozszerzenia durableTask:HubName.

Uwaga / Notatka

Polecenia narzędzi Core Tools zakładają, że uruchamiasz je z katalogu głównego aplikacji funkcyjnej. Jeśli jawnie podasz parametry connection-string-setting i task-hub-name, możesz uruchomić polecenia z dowolnego katalogu. Chociaż można uruchamiać te polecenia bez uruchomionego hosta aplikacji funkcji, może się okazać, że nie można obserwować niektórych efektów, chyba że host jest uruchomiony. Na przykład polecenie start-new umieszcza komunikat początkowy w docelowym centrum zadań, ale orkiestracja nie jest faktycznie uruchamiana, chyba że istnieje proces hosta aplikacji funkcji, który może przetworzyć komunikat.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Następujące polecenie uruchamia funkcję o nazwie HelloWorld i przekazuje do niego zawartość pliku counter-data.json :

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

Instancje zapytań

Po uruchomieniu nowych wystąpień orchestrowania najprawdopodobniej będzie konieczne wykonanie zapytania o ich stan w czasie działania, aby dowiedzieć się, czy są uruchomione, zakończone, czy zakończyły się niepowodzeniem.

Metoda get-status w powiązaniu klienta orchestracji zapytuje o stan instancji orchestracji.

Przyjmuje ( instanceId wymagane), showHistory (opcjonalne), showHistoryOutput (opcjonalne) i showInput (opcjonalnie) jako parametry.

showHistory: Jeśli ustawiono wartość true, odpowiedź zawiera historię wykonywania.
showHistoryOutput: Jeśli ustawiono wartość true, historia wykonywania zawiera dane wyjściowe działań.
showInput: Jeśli ustawiono wartość false, odpowiedź nie będzie zawierać danych wejściowych funkcji. Wartość domyślna to true.

Metoda zwraca obiekt o następujących właściwościach:

Nazwa: nazwa funkcji orkiestratora.
InstanceId: identyfikator wystąpienia orkiestracji (powinien być taki sam jak instanceId).
CreatedTime: czas uruchomienia funkcji orkiestratora.
LastUpdatedTime: czas, w którym orchestracja ostatnio zaktualizowała punkt kontrolny.
Dane wejściowe: dane wejściowe funkcji jako wartość JSON. To pole nie jest wypełniane, jeśli showInput ma wartość false.
CustomStatus: niestandardowy stan orkiestracji w formacie JSON.
Dane wyjściowe: dane wyjściowe funkcji jako wartość JSON (jeśli funkcja została ukończona). Jeśli funkcja orkiestratora nie powiodła się, ta właściwość zawiera szczegóły błędu. Jeśli funkcja orkiestratora została zawieszona lub zakończona, ta właściwość zawiera przyczynę zawieszenia lub zakończenia (jeśli istnieje).
RuntimeStatus: Jedna z następujących wartości:
- Oczekujące: Instancja została zaplanowana, ale jeszcze nie została uruchomiona.
- Uruchomione: uruchomiono wystąpienie.
- Ukończono: Wystąpienie zostało ukończone normalnie.
- ContinuedAsNew: Wystąpienie zostało ponownie uruchomione z nową historią. Ten stan jest stanem przejściowym.
- Niepowodzenie: wystąpienie nie powiodło się z powodu błędu.
- Zakończone: wystąpienie zostało nagle zatrzymane.
- Zawieszone: wystąpienie zostało zawieszone i może zostać wznowione w późniejszym momencie.
Historia: przebieg orkiestracji. To pole jest wypełniane tylko wtedy, gdy showHistory jest ustawione na true.

Uwaga / Notatka

Orkiestrator nie jest oznaczony jako Completed do momentu zakończenia wszystkich zaplanowanych zadań i zwrócenia orkiestratora. Innymi słowy, nie wystarczy, aby orkiestrator dotarł do swojej instrukcji return, aby został oznaczony jako Completed. Jest to szczególnie istotne w przypadkach, w których WhenAny jest używany; te orkiestratory często return zanim wykonane zostaną wszystkie zaplanowane zadania.

Ta metoda zwraca null (.NET i Java), undefined (JavaScript) lub None (Python), jeśli instancja nie istnieje.

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

Uwaga / Notatka

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

Zobacz Uruchom instancje dla konfiguracji function.json.

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

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

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

Podstawowe narzędzia usługi Azure Functions

Można również bezpośrednio uzyskać status wystąpienia orkiestracji, korzystając z polecenia func durable get-runtime-status w narzędziach Core Tools.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable get-runtime-status przyjmuje następujące parametry:

id (wymagane): identyfikator wystąpienia orkiestracji.
show-input (opcjonalnie): Jeśli ustawiono wartość true, odpowiedź zawiera dane wejściowe funkcji. Wartość domyślna to false.
show-output (opcjonalnie): Jeśli ustawiono wartość true, odpowiedź zawiera dane wyjściowe funkcji. Wartość domyślna to false.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającej ciąg połączenia z magazynem do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): nazwa centrum zadań Durable Functions do użycia. Wartość domyślna to DurableFunctionsHub. Można go również ustawić w host.jsonza pomocą rozszerzenia durableTask:HubName.

Następujące polecenie pobiera stan (w tym dane wejściowe i wyjściowe) wystąpienia z identyfikatorem wystąpienia orkiestracji 0ab8c55a66644d68a3a8b220b12d209c. Zakłada się, że uruchamiasz polecenie func z katalogu głównego aplikacji funkcji.

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

Możesz użyć polecenia durable get-history, aby pobrać historię wystąpienia orkiestracji. Przyjmuje następujące parametry:

id (wymagane): identyfikator wystąpienia orkiestracji.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającego parametry połączenia magazynu do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): Nazwa centrum zadań Durable Functions do użycia. Wartość domyślna to DurableFunctionsHub. Można również ustawić to w host.json, używając parametru durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Zapytaj wszystkie instancje

Możesz używać interfejsów API w SDK w danym języku, aby wykonywać zapytania dotyczące statusów wszystkich instancji orkiestracji w centrum zadań. Interfejs API "list-instances" lub "get-status" zwraca listę obiektów reprezentujących instancje orkiestracji zgodne z parametrami zapytania.

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

Uwaga / Notatka

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

Zobacz Uruchom wystąpienia dla konfiguracji function.json.

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

Zobacz Uruchom wystąpienia dla konfiguracji function.json.

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

Podstawowe narzędzia usługi Azure Functions

Istnieje również możliwość bezpośredniego wykonywania zapytań dotyczących wystąpień za pomocą func durable get-instances polecenia w narzędziach Core Tools.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable get-instances przyjmuje następujące parametry:

top (opcjonalnie): To polecenie obsługuje stronicowanie. Ten parametr odpowiada liczbie wystąpień pobranych na żądanie. Wartość domyślna to 10.
continuation-token (opcjonalnie): token określający, którą stronę lub sekcję wystąpień należy pobrać. Każde get-instances wykonanie zwraca token do następnego zestawu wystąpień.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającego parametry połączenia magazynu do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): Nazwa centrum zadań Durable Functions do użycia. Wartość domyślna to DurableFunctionsHub. Można go również ustawić w host.jsonza pomocą rozszerzenia durableTask:HubName.

func durable get-instances

Zapytaj instancje za pomocą filtrów

Co zrobić, jeśli nie potrzebujesz naprawdę wszystkich informacji, które może dostarczyć standardowe zapytanie instancji? Na przykład, co jeśli chcesz poznać czas tworzenia orkiestracji lub stan działania orkiestracji? Zapytanie można zawęzić, stosując filtry.

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

Uwaga / Notatka

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

Zobacz Uruchom wystąpienia dla konfiguracji function.json.

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

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

Podstawowe narzędzia usługi Azure Functions

W narzędziach Azure Functions Core Tools można również użyć durable get-instances polecenia z filtrami. Oprócz wyżej wymienionych topparametrów , , continuation-tokenconnection-string-settingi task-hub-name można użyć trzech parametrów filtru (created-after, created-before, i runtime-status).

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Poniżej przedstawiono parametry polecenia durable get-instances .

created-after (opcjonalnie): pobierz wystąpienia utworzone po tej dacie/godzinie (UTC). Zaakceptowano formatowane daty/godziny ISO 8601.
created-before (opcjonalnie): Zwrot instancji utworzonych przed tą datą/godziną (UTC). Zaakceptowano formatowane daty/godziny ISO 8601.
runtime-status (opcjonalnie): Pobierz instancje o określonym stanie (na przykład działające lub ukończone). Może zapewnić wiele statusów (oddzielonych spacjami).
top (opcjonalnie): liczba wystąpień pobranych na żądanie. Wartość domyślna to 10.
continuation-token (opcjonalnie): token sygnalizujący, którą stronę lub sekcję instancji należy pobrać. Każde get-instances wykonanie zwraca token do następnego zestawu wystąpień.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającego parametry połączenia magazynu do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): Nazwa centrum zadań Durable Functions do użycia. Wartość domyślna to DurableFunctionsHub. Można go również ustawić w host.jsonza pomocą rozszerzenia durableTask:HubName.

Jeśli nie podasz żadnych filtrów (created-after, created-beforelub runtime-status), polecenie po prostu pobiera top wystąpienia bez względu na stan środowiska uruchomieniowego ani czas tworzenia.

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

Zakończenie wystąpień

Jeśli masz wystąpienie orkiestracji, które trwa zbyt długo lub po prostu musisz zatrzymać je przed ukończeniem z jakiegokolwiek powodu, możesz go zakończyć.

Dwa parametry API zakończenia to identyfikator wystąpienia i ciąg przyczyny, które są zapisywane w dziennikach i w stanie wystąpienia.

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

Uwaga / Notatka

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

Zobacz Uruchom wystąpienia dla konfiguracji function.json.

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)

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

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

Zakończona instancja ostatecznie przejdzie do stanu Terminated. Jednak to przejście nie nastąpi natychmiast. Zamiast tego operacja zakończenia zostanie dołączona do kolejki w centrum przetwarzania zadań wraz z innymi operacjami dla tego wystąpienia. Możesz użyć interfejsów API zapytania instancji, aby dowiedzieć się, kiedy zakończona instancja faktycznie osiągnęła Terminated stan.

Uwaga / Notatka

Zakończenie wystąpienia nie jest obecnie propagowane. Funkcje działań i suborkiestracje działają do momentu ukończenia, niezależnie od tego, czy zakończono wystąpienie orkiestracji, które je wywołało.

Wstrzymywanie i wznawianie instancji

Wstrzymanie orkiestracji pozwala na zatrzymanie działającej orkiestracji. W przeciwieństwie do zakończenia, istnieje możliwość wznowienia zawieszonego orkiestratora w późniejszym momencie.

Dwa parametry API zawieszenia to identyfikator wystąpienia i ciąg przyczyny, które są zapisywane w dziennikach i w stanie wystąpienia.

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

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

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)

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

Uwaga / Notatka

Ta funkcja jest dostępna tylko w samodzielnym zestawie SDK Durable Functions dla programu PowerShell. Zapoznaj się z różnicą między autonomicznym zestawem SDK i starszym wbudowanym zestawem SDK wraz z przewodnikiem migracji.

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

Wstrzymane wystąpienie zostanie przeniesione do stanu Suspended ostatecznie. Jednak to przejście nie nastąpi natychmiast. Operacja wstrzymania zostanie umieszczona w kolejce w centrum zadań wraz z innymi operacjami dla tego wystąpienia. Możesz użyć interfejsów API do zapytań wystąpień, aby wiedzieć, kiedy uruchomione wystąpienie rzeczywiście osiągnęło stan wstrzymania.

Po wznowieniu zawieszonego orchestratora jego stan zmieni się z powrotem na Running.

Podstawowe narzędzia usługi Azure Functions

Możesz również bezpośrednio zakończyć instancję orkiestracji za pomocą polecenia func durable terminate w narzędziach Core Tools.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable terminate przyjmuje następujące parametry:

id (wymagane): identyfikator instancji orkiestracji do zakończenia.
reason (opcjonalnie): przyczyna zakończenia.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającego parametry połączenia magazynu do użycia. Wartość domyślna to AzureWebJobsStorage.
pl-PL: task-hub-name (opcjonalnie): nazwa hubu zadań Durable Functions, którego chcesz użyć. Wartość domyślna to DurableFunctionsHub. Można go również ustawić w host.jsonza pomocą rozszerzenia durableTask:HubName.

Następujące polecenie kończy instancję orkiestracji o identyfikatorze 0ab8c55a66644d68a3a8b220b12d209c:

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

Wyślij zdarzenia do wystąpień

W niektórych scenariuszach funkcje orkiestratora muszą czekać i nasłuchiwać zdarzeń zewnętrznych. Przykładowe scenariusze, w których jest to przydatne, obejmują scenariusze monitorowania i interakcji człowieka .

Powiadomienia o zdarzeniach można wysyłać do uruchomionych wystąpień przy użyciu interfejsu API zgłaszania zdarzeńklienta aranżacji. Orkiestracje mogą nasłuchiwać tych zdarzeń i reagować na nie przy użyciu interfejsu API oczekiwania na zdarzenie zewnętrzne orkiestratora.

Parametry wywołania zdarzenia są następujące:

Identyfikator wystąpienia: unikatowy identyfikator wystąpienia.
Nazwa zdarzenia: nazwa zdarzenia do wysłania.
Dane zdarzenia: ładunek z możliwością serializacji JSON do wysłania do wystąpienia.

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

Uwaga / Notatka

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

Zobacz rozdział Uruchamianie wystąpień dotyczącą konfiguracji function.json.

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)

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

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

Uwaga / Notatka

Jeśli nie ma wystąpienia orkiestracji z określonym identyfikatorem wystąpienia, komunikat zdarzenia zostanie odrzucony. Jeśli wystąpienie istnieje, ale nie oczekuje jeszcze na zdarzenie, zdarzenie będzie przechowywane w stanie wystąpienia, dopóki nie będzie gotowe do odebrania i przetworzenia.

Podstawowe narzędzia usługi Azure Functions

Zdarzenie można również zgłosić bezpośrednio do wystąpienia orchestracji przy użyciu polecenia func durable raise-event w narzędziach Core Tools.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable raise-event przyjmuje następujące parametry:

id (wymagane): identyfikator wystąpienia orkiestracji.
event-name: nazwa zdarzenia do wywołania.
event-data (opcjonalnie): dane do wysłania do wystąpienia orkiestracji. Może to być ścieżka do pliku JSON lub możesz podać dane bezpośrednio w wierszu polecenia.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji, które zawiera ciąg połączenia magazynu do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): Nazwa centrum zadań Durable Functions do użycia. Wartość domyślna to DurableFunctionsHub. Można go również ustawić w host.jsonza pomocą rozszerzenia 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

Poczekaj na ukończenie aranżacji

W długotrwałych orkiestracjach możesz chcieć poczekać i uzyskać wyniki orkiestracji. W takich przypadkach warto również zdefiniować limit czasu aranżacji. Jeśli przekroczono limit czasu, zamiast wyników należy zwrócić stan orkiestracji.

Interfejs API "wait for completion or create check status response" (Oczekiwanie na zakończenie lub tworzenie odpowiedzi kontroli statusu) może być używany do synchronicznego uzyskiwania rzeczywistych rezultatów z instancji orkiestracji. Domyślnie ta metoda ma domyślny limit czasu wynoszący 10 sekund i interwał sondowania wynoszący 1 sekundę.

Oto przykładowa funkcja wyzwalacza HTTP, która pokazuje, jak używać tego interfejsu API:

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

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace VSSample
{
    public static class HttpSyncStart
    {
        private const string Timeout = "timeout";
        private const string RetryInterval = "retryInterval";

        [FunctionName("HttpSyncStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}/wait")]
            HttpRequestMessage req,
            [DurableClient] IDurableOrchestrationClient starter,
            string functionName,
            ILogger log)
        {
            // Function input comes from the request content.
            object eventData = await req.Content.ReadAsAsync<object>();
            string instanceId = await starter.StartNewAsync(functionName, eventData);

            log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

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

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

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

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

Zobacz Uruchom wystąpienia dla konfiguracji function.json.

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

Język Java nie ma obecnie jednej metody dla tego scenariusza. Można go jednak zaimplementować przy użyciu kilku dodatkowych wierszy kodu.

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

Wywołaj funkcję za pomocą następującego wiersza. Użyj 2 sekund dla limitu czasu i 0,5 sekundy dla interwału ponawiania prób:

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

Uwaga / Notatka

Powyższe polecenie cURL zakłada, że masz funkcję orkiestratora o nazwie E1_HelloSequence w projekcie. Ze względu na sposób zapisywania funkcji wyzwalacza HTTP można zastąpić ją nazwą dowolnej funkcji orkiestratora w projekcie.

W zależności od czasu wymaganego do uzyskania odpowiedzi z wystąpienia orkiestracji istnieją dwa przypadki:

Wystąpienia orkiestracji zakończają się w zdefiniowanym limicie czasu (w tym przypadku 2 sekundy), a odpowiedź to rzeczywisty wynik wystąpienia orkiestracji, synchronizowany.

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

Wystąpienia orkiestracji nie mogą zakończyć się w ramach zdefiniowanego limitu czasu, a odpowiedź jest domyślną określoną w Odnajdywanie adresu URL API HTTP:

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

Uwaga / Notatka

Format adresów URL elementu webhook może się różnić w zależności od używanej wersji hosta usługi Azure Functions. Powyższy przykład dotyczy hosta usługi Azure Functions 3.0.

Pobierz adresy URL webhook zarządzania HTTP

Możesz użyć systemu zewnętrznego do monitorowania lub zgłaszania zdarzeń do orkiestracji. Systemy zewnętrzne mogą komunikować się z Durable Functions za pośrednictwem adresów URL webhook, które są częścią domyślnej odpowiedzi opisanej w HTTP API URL discovery. Adresy URL webhooków mogą być również uzyskiwane programowo przy użyciu powiązania klienta orkiestracji. W szczególności interfejs API tworzenia ładunku zarządzania protokołem HTTP może służyć do uzyskiwania obiektu z możliwością serializacji zawierającego te adresy URL elementu webhook.

Interfejs API tworzenia ładunku zarządzania http ma jeden parametr:

Identyfikator wystąpienia: unikatowy identyfikator wystąpienia.

Metody zwracają obiekt z następującymi właściwościami ciągu:

Identyfikator: identyfikator wystąpienia orkiestracji (powinien być taki sam jak InstanceId wejście).
StatusQueryGetUri: URL stanu wystąpienia orkiestracji.
SendEventPostUri: adres URL "zgłoś zdarzenie" wystąpienia orkiestracji.
TerminatePostUri: adres URL "terminate" wystąpienia orkiestracji.
PurgeHistoryDeleteUri: adres URL "czyszczenia historii" wystąpienia orkiestracji.
suspendPostUri: URL „suspend” dla instancji orkiestracji.
resumePostUri: adres URL "resume" wystąpienia orkiestracji.

Funkcje mogą wysyłać wystąpienia tych obiektów do systemów zewnętrznych w celu monitorowania lub zgłaszania zdarzeń w odpowiednich orkiestracjach, jak pokazano w poniższych przykładach.

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

Uwaga / Notatka

Poprzedni kod C# dotyczy funkcji Durable Functions w wersji 2.x. W przypadku rozszerzenia Durable Functions w wersji 1.x należy użyć DurableActivityContext zamiast IDurableActivityContext, należy użyć atrybutu OrchestrationClient zamiast atrybutu DurableClient, a zamiast typu parametru IDurableOrchestrationClient należy użyć typu DurableOrchestrationClient. Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje Durable Functions.

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

Zobacz Uruchom instancje dla konfiguracji function.json.

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

using namespace System.Net

param($Request, $TriggerMetadata)

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

Ponowne przewijanie wystąpień (wersja zapoznawcza)

Jeśli wystąpi błąd orkiestracji z nieoczekiwanego powodu, możesz przywrócić wystąpienie do poprzedniego zdrowego stanu przy użyciu interfejsu API przeznaczonego do tego celu.

Uwaga / Notatka

Ten interfejs API nie jest przeznaczony do zastąpienia odpowiednich zasad obsługi błędów i ponawiania prób. Zamiast tego ma być używany tylko w przypadkach, gdy wystąpienia orkiestracji kończą się niepowodzeniem z nieoczekiwanych powodów. Orkiestracje w stanach innych niż Failed (np. Running, Pending, Terminated, Completed) nie mogą być "przewinięte". Aby uzyskać więcej informacji na temat obsługi błędów i zasad ponawiania prób, zobacz artykuł Obsługa błędów .

RewindAsync Użyj metody (.NET) lub rewind (JavaScript) powiązania klienta orkiestracji, aby przywrócić orkiestrację do stanu Uruchomiony. Ta metoda spowoduje również ponowne uruchomienie niepowodzeń wykonywania działań lub podaranżacji, które spowodowały niepowodzenie aranżacji.

Załóżmy na przykład, że masz workflow obejmujący serię zatwierdzeń ludzkich. Załóżmy, że istnieje szereg funkcji działań, które powiadamiają kogoś o potrzebie zatwierdzenia i oczekują na odpowiedź w czasie rzeczywistym. Po otrzymaniu odpowiedzi lub przekroczeniu limitu czasu wszystkich działań zatwierdzania załóżmy, że inne działanie kończy się niepowodzeniem z powodu błędnej konfiguracji aplikacji, na przykład nieprawidłowych parametrów połączenia bazy danych. Wynikiem jest niepowodzenie aranżacji głęboko w przepływie pracy. Za pomocą interfejsu RewindAsync API (.NET) lub rewind (JavaScript) administrator aplikacji może naprawić błąd konfiguracji i przywrócić niepowodzoną orkiestrację do stanu tuż przed awarią. Żaden z kroków interakcji z człowiekiem nie musi zostać ponownie zatwierdzony, a aranżacja może zakończyć się pomyślnie.

Uwaga / Notatka

Funkcja przewijania nie obsługuje instancji orkiestracji korzystających z trwałych czasomierzy.

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

Uwaga / Notatka

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

Zobacz Uruchom instancje dla konfiguracji function.json.

Podstawowe narzędzia usługi Azure Functions

Możesz również przewinąć wystąpienie orkiestracji bezpośrednio przy użyciu func durable rewind polecenia za pomocą narzędzia Core Tools.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable rewind przyjmuje następujące parametry:

id (wymagane): identyfikator wystąpienia orkiestracji.
reason (opcjonalnie): Przyczyna ponownego uruchomienia instancji orkiestracji.
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającej ciąg połączenia z magazynem do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): nazwa centrum zadań Durable Functions do użycia. Domyślnie używana jest nazwa centrum zadań w pliku host.json .

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

Usunięcie historii wystąpień

Aby usunąć wszystkie dane skojarzone z orkiestracją, możesz wyczyścić historię wystąpienia. Możesz na przykład usunąć wszystkie zasoby magazynu skojarzone z ukończonym wystąpieniem. W tym celu należy użyć interfejsu API przeczyszczania wystąpienia zdefiniowanego przez klienta aranżacji.

W tym pierwszym przykładzie pokazano, jak usunąć pojedyncze wystąpienie orkiestracji.

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

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

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

Zobacz Uruchom instancje dla konfiguracji function.json.

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)

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

W następnym przykładzie pokazano funkcję wyzwalaną przez czasomierz, która czyści historię wszystkich wystąpień aranżacji zakończonych po określonym interwale czasu. W takim przypadku usuwa dane dla wszystkich wystąpień ukończonych 30 lub więcej dni temu. Ta przykładowa funkcja jest zaplanowana raz dziennie, o 12:00 CZASU UTC:

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

Uwaga / Notatka

Metoda purgeInstanceHistoryBy może służyć do warunkowego przeczyszczania historii wystąpień dla wielu wystąpień.

function.json

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

Uwaga / Notatka

Ten przykład dotyczy Durable Functions w wersji 2.x. W wersji 1.x użyj polecenia orchestrationClient zamiast 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);
};

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)

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

Uwaga / Notatka

Aby operacja historii przeczyszczania powiodła się, status uruchomieniowy wystąpienia docelowego musi być Zakończony, Przerwany lub Niepowodzenie zakończone.

Podstawowe narzędzia usługi Azure Functions

Historię wystąpienia orkiestracji można przeczyścić przy użyciu func durable purge-history polecenia w narzędziach Core Tools. Podobnie jak w drugim przykładzie w języku C# w poprzedniej sekcji, czyści historię wszystkich wystąpień orkiestracji utworzonych w określonym przedziale czasu. Możesz dalej filtrować przeczyszczane wystąpienia według stanu środowiska uruchomieniowego.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable purge-history ma kilka parametrów:

created-after (opcjonalnie): Przeczyść historię wystąpień utworzonych po tej dacie/godzinie (UTC). Zaakceptowano formatowane daty/godziny ISO 8601.
created-before (opcjonalnie): Przeczyść historię wystąpień utworzonych przed tą datą/godziną (UTC). Zaakceptowano formatowane daty/godziny ISO 8601.
runtime-status (opcjonalnie): Przeczyść historię wystąpień o określonym stanie (na przykład uruchomione lub ukończone). Może zapewnić wiele statusów (oddzielonych spacjami).
connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającej ciąg połączenia z magazynem do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): nazwa centrum zadań Durable Functions do użycia. Domyślnie używana jest nazwa centrum zadań w pliku host.json .

Następujące polecenie usuwa historię wszystkich nieudanych wystąpień utworzonych przed 14 listopada 2021 r. o 17:35 (UTC).

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

Usuń centrum zadań

Za pomocą polecenia func durable delete-task-hub w Core Tools można usunąć wszystkie artefakty magazynowe skojarzone z określonym centrum zadań, w tym tabele Azure Storage, kolejki i obiekty blob.

Uwaga / Notatka

Polecenia narzędzi Core Tools są obecnie obsługiwane tylko w przypadku używania domyślnego dostawcy usługi Azure Storage do utrwalania stanu środowiska uruchomieniowego.

Polecenie durable delete-task-hub ma dwa parametry:

connection-string-setting (opcjonalnie): nazwa ustawienia aplikacji zawierającej ciąg połączenia z magazynem do użycia. Wartość domyślna to AzureWebJobsStorage.
task-hub-name (opcjonalnie): nazwa centrum zadań Durable Functions do użycia. Domyślnie używana jest nazwa centrum zadań w pliku host.json .

Następujące polecenie usuwa wszystkie dane usługi Azure Storage skojarzone z UserTest centrum zadań.

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

Dalsze kroki

Dowiedz się, jak obsługiwać przechowywanie wersji

Wbudowana dokumentacja API HTTP do zarządzania instancjami

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-06-28

Udostępnij za pomocą

Zarządzanie wystąpieniami w usłudze Durable Functions na platformie Azure

Uruchamianie wystąpień

Podstawowe narzędzia usługi Azure Functions

Instancje zapytań

Podstawowe narzędzia usługi Azure Functions

Zapytaj wszystkie instancje

Podstawowe narzędzia usługi Azure Functions

Zapytaj instancje za pomocą filtrów

Podstawowe narzędzia usługi Azure Functions

Zakończenie wystąpień

Wstrzymywanie i wznawianie instancji

Podstawowe narzędzia usługi Azure Functions

Wyślij zdarzenia do wystąpień

Podstawowe narzędzia usługi Azure Functions

Poczekaj na ukończenie aranżacji

Pobierz adresy URL webhook zarządzania HTTP

Ponowne przewijanie wystąpień (wersja zapoznawcza)

Podstawowe narzędzia usługi Azure Functions

Usunięcie historii wystąpień

Podstawowe narzędzia usługi Azure Functions

Usuń centrum zadań

Dalsze kroki

Sprzężenie zwrotne

Dodatkowe zasoby