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ż uwidacznianych przez powiązanie klienta orkiestracji durable functions, takie jak wysyłanie zdarzeń zewnętrznych do wystąpień, przeczyszczanie historii wystąpienia 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 aranżacji uruchamia nowe wystąpienie aranżacji. 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 zaplanowana.
• 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.

Napiwek

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. Odpowiedni czas używania identyfikatorów wystąpień innych niż losowe jest wtedy, gdy identyfikator musi pochodzić ze źródła zewnętrznego lub podczas implementowania wzorca orkiestratora pojedynczego wystąpienia.

Poniższy kod to przykładowa funkcja, która uruchamia nowe wystąpienie orkiestracji:

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

Ten przykład dotyczy rozszerzenia 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}.`);
};

Python

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

Ten przykład dotyczy rozszerzenia 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}.")

Program PowerShell

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

Ten przykład dotyczy rozszerzenia 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'"

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

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

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

Azure Functions Core Tools

Możesz również uruchomić wystąpienie bezpośrednio przy użyciu func durable start-new polecenia w narzędziach Core Tools, które przyjmuje 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 aranżacji. 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

Polecenia narzędzi Core Tools zakładają, że uruchamiasz je z katalogu głównego aplikacji funkcji. Jeśli jawnie podasz connection-string-setting parametry 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 start-new polecenie umieszcza komunikat początkowy w docelowym centrum zadań, ale aranżacja nie jest uruchamiana, chyba że istnieje proces hosta aplikacji funkcji, który może przetworzyć komunikat.

Uwaga

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

Wystąpienia zapytań

Po uruchomieniu nowych wystąpień orkiestracji najprawdopodobniej będzie konieczne wykonanie zapytania o stan środowiska uruchomieniowego, aby dowiedzieć się, czy są uruchomione, czy zakończyły się niepowodzeniem.

Metoda get-status w powiązaniu klienta aranżacji wysyła zapytanie o stan wystąpienia aranżacji.

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. Domyślna wartość to true.

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

• Nazwa: nazwa funkcji orkiestratora.
• InstanceId: identyfikator wystąpienia aranżacji (powinien być taki sam jak instanceId dane wejściowe).
• CreatedTime: czas uruchomienia funkcji orkiestratora.
• LastUpdatedTime: godzina ostatniego punktu kontrolnego aranżacji.
• 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: wystąpienie zostało zaplanowane, ale nie zostało jeszcze uruchomione.
  • 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: historia wykonywania orkiestracji. To pole jest wypełniane tylko wtedy, gdy showHistory jest ustawione na truewartość .

Uwaga

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 instrukcji, return aby został oznaczony jako Completed. Jest to szczególnie istotne w przypadkach, w których WhenAny jest używana; te orkiestratory często return przed wykonaniem wszystkich zaplanowanych zadań.

Ta metoda zwraca null wartość (.NET i Java), undefined (JavaScript) lub None (Python), jeśli wystąpienie nie istnieje.

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

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

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

Program PowerShell

param($Request, $TriggerMetadata)

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

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

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

Java

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

Azure Functions Core Tools

Stan wystąpienia orkiestracji można również uzyskać bezpośrednio przy użyciu func durable get-runtime-status polecenia w narzędziach Core Tools.

Uwaga

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 aranżacji.
• show-input (opcjonalnie): Jeśli ustawiono wartość true, odpowiedź zawiera dane wejściowe funkcji. Domyślna wartość to false.
• show-output (opcjonalnie): Jeśli ustawiono wartość true, odpowiedź zawiera dane wyjściowe funkcji. Domyślna wartość to false.
• 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.json za pomocą rozszerzenia durableTask:HubName.

Następujące polecenie pobiera stan (w tym dane wejściowe i wyjściowe) wystąpienia z identyfikatorem wystąpienia aranżacji 0ab8c5a66644d68a3a8b220b12d209c. Przyjęto założenie, że uruchamiasz func polecenie z katalogu głównego aplikacji funkcji:

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

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

• id (wymagane): identyfikator wystąpienia aranżacji.
• 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.json za pomocą rozszerzenia durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Wykonywanie zapytań względem wszystkich wystąpień

Interfejsy API w zestawie SDK języka umożliwiają wykonywanie zapytań o stany wszystkich wystąpień aranżacji w centrum zadań. Ten interfejs API "list-instances" lub "get-status" zwraca listę obiektów reprezentujących wystąpienia aranżacji zgodne z parametrami zapytania.

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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


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

    instances = await client.get_status_all()

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Program PowerShell

Uwaga

Ta funkcja nie jest obecnie obsługiwana w programie PowerShell, ale można osiągnąć przy użyciu interfejsu API HTTP rozszerzenia Durable Functions.

Java

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

Azure Functions Core Tools

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

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 wskazujący, która strona lub sekcja wystąpień do pobrania. 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.json za pomocą rozszerzenia durableTask:HubName.

func durable get-instances

Wykonywanie zapytań względem wystąpień z filtrami

Co zrobić, jeśli naprawdę nie potrzebujesz wszystkich informacji, które może dostarczyć standardowe zapytanie wystąpienia? Na przykład co zrobić, jeśli szukasz czasu utworzenia orkiestracji lub stanu środowiska uruchomieniowego orkiestracji? Zapytanie można zawęzić, stosując filtry.

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

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

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

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

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

Program PowerShell

Uwaga

Ta funkcja nie jest obecnie obsługiwana w programie PowerShell, ale można osiągnąć przy użyciu interfejsu API HTTP rozszerzenia Durable Functions.

Java

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

Azure Functions Core Tools

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

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): pobierz wystąpienia utworzone przed tą datą/godziną (UTC). Zaakceptowano formatowane daty/godziny ISO 8601.
• runtime-status (opcjonalnie): pobieranie wystąpień o określonym stanie (na przykład uruchomienie lub ukończenie). Może zapewnić wiele stanów (rozdzielonych spacjami).
• top (opcjonalnie): liczba wystąpień pobranych na żądanie. Wartość domyślna to 10.
• continuation-token (opcjonalnie): token wskazujący, która strona lub sekcja wystąpień do pobrania. 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.json za 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

Koń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 interfejsu API zakończenia są identyfikatorem wystąpienia i ciągiem przyczyny, który jest zapisywany w dziennikach i w stanie wystąpienia.

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

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

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

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

Zakończone wystąpienie zostanie ostatecznie przekształcone w Terminated stan . Jednak to przejście nie nastąpi natychmiast. Zamiast tego operacja zakończenia zostanie w kolejce w centrum zadań wraz z innymi operacjami dla tego wystąpienia. Możesz użyć interfejsów API zapytań wystąpienia, aby dowiedzieć się, kiedy wystąpienie zakończone faktycznie osiągnęło Terminated stan.

Uwaga

Zakończenie wystąpienia nie jest obecnie propagowane. Funkcje działań i podarancje są uruchamiane w celu ukończenia, niezależnie od tego, czy wystąpienie orkiestracji zostało zakończone, które je nazwało.

Wstrzymywanie i wznawianie wystąpień

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

Dwa parametry interfejsu API wstrzymania to identyfikator wystąpienia i ciąg przyczyny, który jest zapisywany w dziennikach i w stanie wystąpienia.

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    DateTime dueTime = context.CurrentUtcDateTime.AddSeconds(30);
    await context.CreateTimer(dueTime, CancellationToken.None);
    
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

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

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

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

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

Python

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

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

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

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

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

Program PowerShell

param($Request, $TriggerMetadata)

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

Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

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

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

Java

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

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

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

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

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

Azure Functions Core Tools

Wystąpienie orkiestracji można również zakończyć bezpośrednio za pomocą func durable terminate polecenia w narzędziach Core Tools.

Uwaga

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 wystąpienia 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.
• 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.json za pomocą rozszerzenia durableTask:HubName.

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

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

Wysyłanie zdarzeń 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 zewnętrzne orkiestratora zdarzeń .

Parametry zdarzenia zgłaszania 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.

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

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

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

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

Uwaga

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.

Azure Functions Core Tools

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

Uwaga

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 aranżacji.
• event-name: nazwa zdarzenia do wywołania.
• event-data (opcjonalnie): dane do wysłania do wystąpienia aranżacji. 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 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.json za 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 aranżacjach możesz poczekać i uzyskać wyniki aranżacji. W takich przypadkach warto również zdefiniować limit czasu aranżacji. Jeśli przekroczono limit czasu, należy zwrócić stan aranżacji zamiast wyników.

Interfejs API "wait for completion or create check status response" (Oczekiwanie na ukończenie lub tworzenie odpowiedzi na stan sprawdzania stanu) może służyć do synchronicznego pobierania rzeczywistych danych wyjściowych z wystąpienia 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:

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

Program PowerShell

Uwaga

Program PowerShell nie ma obecnie wbudowanego polecenia dla tego scenariusza.

Java

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

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 są kompletne w zdefiniowanym limicie czasu (w tym przypadku 2 sekundy), a odpowiedź jest rzeczywistym wynikiem wystąpienia orkiestracji, dostarczanym synchronicznie:

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 artykule Odnajdywanie adresów URL interfejsu 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

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.

Pobieranie adresów URL elementów webhook zarządzania http

Możesz użyć systemu zewnętrznego do monitorowania lub zgłaszania zdarzeń do aranżacji. Systemy zewnętrzne mogą komunikować się z usługą Durable Functions za pośrednictwem adresów URL elementów webhook, które są częścią domyślnej odpowiedzi opisanej w artykule Odnajdywanie adresów URL interfejsu API PROTOKOŁU HTTP. Adresy URL elementów webhook mogą być również uzyskiwane programowo przy użyciu powiązania klienta aranżacji. 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 aranżacji (powinien być taki sam jak InstanceId dane wejściowe).
• StatusQueryGetUri: adres URL stanu wystąpienia orkiestracji.
• SendEventPostUri: adres URL "zgłoś zdarzenie" wystąpienia orkiestracji.
• TerminatePostUri: adres URL "terminate" wystąpienia orkiestracji.
• PurgeHistoryDeleteUri: adres URL "historii przeczyszczania" wystąpienia aranżacji.
• suspendPostUri: adres URL "suspend" wystąpienia 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 aranżacjach, jak pokazano w poniższych przykładach:

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions w wersji 1.x należy DurableActivityContext użyć atrybutu IDurableActivityContextOrchestrationClient zamiast atrybutu , a nie atrybutuDurableClient, a zamiast atrybutu należy użyć DurableOrchestrationClient typu parametru IDurableOrchestrationClient. Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

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

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

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

Program 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

Uwaga

Ta funkcja nie jest obecnie obsługiwana w języku Java.

Ponowne przewijanie wystąpień (wersja zapoznawcza)

Jeśli wystąpi błąd orkiestracji z nieoczekiwanego powodu, możesz przywrócić wystąpienie do wcześniej w dobrej kondycji przy użyciu interfejsu API utworzonego w tym celu.

Uwaga

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, ) Completednie mogą być "zachwiane". Aby uzyskać więcej informacji na temat obsługi błędów i zasad ponawiania prób, zobacz artykuł Obsługa błędów.

Użyj metody (.NET) lub rewind (JavaScript) powiązania klienta aranżacji, aby przywrócić aranżację do stanu Uruchomiono.RewindAsync 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 przepływ pracy obejmujący serię zatwierdzeń człowieka. 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, takiej jak nieprawidłowa parametry 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 cofnąć aranżację, która zakończyła się niepowodzeniem, bezpośrednio 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

Funkcja przewijania nie obsługuje ponownego przewijania wystąpień aranżacji korzystających z trwałych czasomierzy.

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

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

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

Uwaga

Ta funkcja nie jest obecnie obsługiwana w języku Python.

Program PowerShell

Uwaga

Ta funkcja nie jest obecnie obsługiwana w programie PowerShell.

Java

Uwaga

Ta funkcja nie jest obecnie obsługiwana w języku Java.

Azure Functions Core Tools

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

Uwaga

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 aranżacji.
• reason (opcjonalnie): Przyczyna ponownego przewijania wystąpienia aranżacji.
• 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. 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."

Przeczyszczanie historii wystąpień

Aby usunąć wszystkie dane skojarzone z aranżacją, możesz przeczyś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 przeczyścić pojedyncze wystąpienie orkiestracji.

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

Zobacz Uruchamianie wystąpień konfiguracji function.json.

Python

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

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

    return await client.purge_instance_history(instance_id)

Program PowerShell

Uwaga

Ta funkcja nie jest obecnie obsługiwana w programie PowerShell, ale można osiągnąć przy użyciu interfejsu API HTTP rozszerzenia Durable Functions.

Java

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

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:

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

Uwaga

Poprzedni kod języka C# jest przeznaczony dla rozszerzenia Durable Functions 2.x. W przypadku rozszerzenia Durable Functions 1.x należy użyć OrchestrationClient atrybutu zamiast atrybutu DurableClient i należy użyć typu parametru DurableOrchestrationClientIDurableOrchestrationClientzamiast . Aby uzyskać więcej informacji na temat różnic między wersjami, zobacz artykuł Wersje rozszerzenia Durable Functions.

JavaScript

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

Ten przykład dotyczy rozszerzenia 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);
};

Program PowerShell

Uwaga

Ta funkcja nie jest obecnie obsługiwana w programie PowerShell, ale można osiągnąć przy użyciu interfejsu API HTTP rozszerzenia Durable Functions.

Python

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

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

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

Java

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

Uwaga

Aby operacja historii przeczyszczania powiodła się, stan środowiska uruchomieniowego wystąpienia docelowego musi być ukończony, zakończony lub niepowodzenie.

Azure Functions Core Tools

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 języka C# w poprzedniej sekcji, przeczyszcza historię wszystkich wystąpień aranżacji utworzonych w określonym przedziale czasu. Możesz dalej filtrować przeczyszczane wystąpienia według stanu środowiska uruchomieniowego.

Uwaga

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 stanów (rozdzielonych spacjami).
• 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. 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

Usuwanie centrum zadań

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

Uwaga

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

Następne kroki

Dowiedz się, jak obsługiwać przechowywanie wersji

Wbudowana dokumentacja interfejsu API PROTOKOŁU HTTP na potrzeby zarządzania wystąpieniami