Gestire le istanze in Durable Functions in Azure

Le orchestrazioni in Durable Functions sono funzioni con stato a esecuzione prolungata che possono essere avviate, sottoposte a query, sospese, riprese e terminate utilizzando le API di gestione predefinite. Diverse altre API di gestione delle istanze sono esposte anche dall'associazione client di orchestrazione di Durable Functions, ad esempio l'invio di eventi esterni alle istanze, l'eliminazione della cronologia delle istanze e così via. Questo articolo illustra in dettaglio tutte le operazioni di gestione delle istanze supportate.

Avviare le istanze

Il metodo start-new (o schedule-new) nell'associazione client di orchestrazione avvia una nuova istanza di orchestrazione. Internamente, questo metodo scrive un messaggio tramite il provider di archiviazione di Durable Functions e quindi restituisce. Questo messaggio attiva in modo asincrono l'inizio di una funzione di orchestrazione con il nome specificato.

I parametri per l'avvio di una nuova istanza di orchestrazione sono i seguenti:

• Nome: il nome della funzione di orchestrazione che deve essere pianificata.
• Input: tutti i dati serializzabili JSON che devono essere passati come input alla funzione dell'agente di orchestrazione.
• InstanceId: (facoltativo) ID univoco dell'istanza. Se non si specifica questo parametro, il metodo usa un ID casuale.

Suggerimento

Utilizzare un identificatore casuale per l'ID dell'istanza ogni volta possibile. Gli ID istanza casuale consentono di garantire una distribuzione del carico uguale quando si ridimensionano le funzioni dell'agente di orchestrazione tra più macchine virtuali. Il momento appropriato per usare gli ID di istanza non casuali è quando l'ID deve provenire da un'origine esterna o quando si implementa il modello singleton orchestrator.

Il codice seguente è una funzione di esempio che avvia una nuova istanza di orchestrazione:

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di Durable Functions .

JavaScript

Se non diversamente specificato, gli esempi in questa pagina usano il trigger HTTP con il seguente 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
}

Annotazioni

Questo esempio è destinato a Durable Functions versione 2.x. Nella versione 1.x usare orchestrationClient anziché 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}.`);
};

Pitone

Se non diversamente specificato, gli esempi in questa pagina usano il trigger HTTP con il seguente 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
}

Annotazioni

Questo esempio è destinato a Durable Functions versione 2.x. Nella versione 1.x usare orchestrationClient anziché durableClient.

__init__.py

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

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    
    instance_id = await client.start_new('HelloWorld', None, None)
    logging.log(f"Started orchestration with ID = ${instance_id}.")

PowerShell

Se non diversamente specificato, gli esempi in questa pagina usano il trigger HTTP con il seguente 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
}

Annotazioni

Questo esempio è destinato a Durable Functions versione 2.x. Nella versione 1.x usare orchestrationClient anziché durableClient.

run.ps1

param($Request, $TriggerMetadata)

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

Giava

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

Se vuoi attendere che l'orchestratore inizi prima di tornare dalla tua funzione, puoi anche usare il metodo waitForInstanceStart().

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

Strumenti Core di Azure Functions

È anche possibile avviare un'istanza direttamente usando il func durable start-new comando in Core Tools, che accetta i parametri seguenti:

• function-name (obbligatorio): nome della funzione da avviare.
• input (facoltativo): input per la funzione, inline o tramite un file JSON. Per i file, aggiungere un prefisso al percorso del file con @, ad esempio @path/to/file.json.
• id (facoltativo): ID dell'istanza di orchestrazione. Se non si specifica questo parametro, il comando usa un GUID casuale.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività di Durable Functions da utilizzare. Il valore predefinito è DurableFunctionsHub. È anche possibile impostare questo valore in host.json usando durableTask:HubName.

Annotazioni

I comandi di Core Tools presuppongono che vengano eseguiti dalla directory radice di un'app per le funzioni. Se si specificano in modo esplicito i connection-string-setting parametri e task-hub-name , è possibile eseguire i comandi da qualsiasi directory. Anche se puoi eseguire questi comandi senza che un host dell'app per le funzioni sia in esecuzione, potresti non riuscire a osservare alcuni effetti a meno che l'host non sia attivo. Ad esempio, il comando start-new accoda un messaggio di avvio nell'hub attività di destinazione, ma l'orchestrazione non viene effettivamente eseguita a meno che non sia in esecuzione un processo host dell'applicazione per le funzioni in grado di elaborare il messaggio.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il comando seguente avvia la funzione denominata HelloWorld e passa il contenuto del file counter-data.json :

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

Istanze di query

Dopo aver avviato nuove istanze di orchestrazione, è molto probabile che sia necessario eseguire una query sullo stato di runtime per sapere se sono in esecuzione, sono state completate o non riuscite.

Il metodo get-statusnell'associazione client di orchestrazione esegue una query sullo stato di un'istanza di orchestrazione.

Accetta ( instanceId obbligatorio), showHistory (facoltativo), showHistoryOutput (facoltativo) e showInput (facoltativo) come parametri.

• showHistory: se impostato su true, la risposta contiene la cronologia di esecuzione.
• showHistoryOutput: se impostato su true, la cronologia di esecuzione contiene output di attività.
• showInput: se impostato su false, la risposta non conterrà l'input della funzione. Il valore predefinito è true.

Il metodo restituisce un oggetto con le proprietà seguenti:

• Nome: nome della funzione di orchestratore.
• InstanceId: l'ID istanza dell'orchestrazione (deve essere lo stesso dell'input instanceId).
• CreatedTime: L'ora in cui è stata avviata l'esecuzione della funzione di orchestrazione.
• LastUpdatedTime: l'ora in cui l'orchestrazione ha eseguito l'ultimo checkpoint.
• Input: input della funzione come valore JSON. Questo campo non viene popolato se showInput è false.
• CustomStatus: stato di orchestrazione personalizzato in formato JSON.
• Output: output della funzione come valore JSON (se la funzione è stata completata). Se la funzione dell'agente di orchestrazione non è riuscita, questa proprietà include i dettagli dell'errore. Se la funzione di orchestrazione è stata sospesa o terminata, questa proprietà include il motivo della sospensione o della terminazione (se presente).
• RuntimeStatus: uno dei valori seguenti:
  • In sospeso: l'istanza è stata pianificata ma non è ancora stata eseguita.
  • In esecuzione: l'istanza è stata avviata.
  • Completato: l'istanza è stata completata normalmente.
  • ContinueAsNew: l'istanza è stata riavviata con una nuova cronologia. Questo stato è uno stato temporaneo.
  • Non riuscito: l'istanza non è riuscita con un errore.
  • Terminata: l'istanza è stata terminata in modo anomalo.
  • Sospeso: l'istanza è stata sospesa e può essere ripresa in un secondo momento.
• Cronologia: cronologia di esecuzione dell'orchestrazione. Questo campo viene popolato solo se showHistory è impostato su true.

Annotazioni

Un agente di orchestrazione non viene contrassegnato come Completed finché non vengono completate tutte le attività pianificate e l'agente di orchestrazione è stato restituito. In altre parole, non è sufficiente che un agente di orchestrazione raggiunga l'istruzione return affinché venga contrassegnata come Completed. Ciò è particolarmente rilevante per i casi in cui viene utilizzato WhenAny; tali agenti di orchestrazione spesso return prima dell'esecuzione di tutte le attività pianificate.

Questo metodo restituisce null (.NET e Java), undefined (JavaScript) o None (Python) se l'istanza non esiste.

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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: ...
}

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

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

Giava

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

Strumenti Core di Azure Functions

È anche possibile ottenere lo stato di un'istanza di orchestrazione direttamente usando il func durable get-runtime-status comando in Core Tools.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il comando durable get-runtime-status accetta i parametri seguenti:

• id (obbligatorio): ID dell'istanza di orchestrazione.
• show-input (facoltativo): se impostato su true, la risposta contiene l'input della funzione. Il valore predefinito è false.
• show-output (facoltativo): se impostato su true, la risposta contiene l'output della funzione. Il valore predefinito è false.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub di attività Durable Functions da usare. Il valore predefinito è DurableFunctionsHub. Può anche essere impostato in host.json, usando durableTask:HubName.

Il comando seguente recupera lo stato (incluso l'input e l'output) di un'istanza con un ID istanza di orchestrazione pari a 0ab8c55a66644d68a3a8b220b12d209c. Si presuppone che si esegua il comando func dalla directory radice dell'app per le funzioni:

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

È possibile usare il durable get-history comando per recuperare la cronologia di un'istanza di orchestrazione. È necessario specificare i seguenti parametri:

• id (obbligatorio): ID dell'istanza di orchestrazione.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub di attività delle Durable Functions da usare. Il valore predefinito è DurableFunctionsHub. Può anche essere impostato in host.json, usando durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Eseguire query su tutte le istanze

È possibile usare le API nell'SDK del proprio linguaggio per eseguire query sullo stato di tutte le istanze di orchestrazione nell'hub delle attività. Questa API "list-instances" o "get-status" restituisce un elenco di oggetti che rappresentano le istanze di orchestrazione corrispondenti ai parametri di query.

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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));
    });
};

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

Per la configurazione di function.json, vedere Istanze di avvio .

PowerShell

Annotazioni

Questa funzionalità non è attualmente supportata in PowerShell, ma può essere ottenuta usando l'API HTTP di Funzioni permanenti.

Giava

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

Strumenti Core di Azure Functions

È anche possibile eseguire query direttamente sulle istanze usando il func durable get-instances comando in Core Tools.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il comando durable get-instances accetta i parametri seguenti:

• top (facoltativo): questo comando supporta il paging. Questo parametro corrisponde al numero di istanze recuperate per richiesta. Il valore predefinito è 10.
• continuation-token (facoltativo): token per indicare la pagina o la sezione delle istanze da recuperare. Ogni get-instances esecuzione restituisce un token al set di istanze successivo.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub di attività di Durable Functions da utilizzare. Il valore predefinito è DurableFunctionsHub. Può anche essere impostato in host.json, usando durableTask:HubName.

func durable get-instances

Eseguire query su istanze con filtri

Cosa accade se non sono effettivamente necessarie tutte le informazioni che una query di istanza standard può fornire? Ad esempio, cosa accade se si sta semplicemente cercando l'ora di creazione dell'orchestrazione o lo stato del runtime dell'orchestrazione? È possibile restringere la query applicando filtri.

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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));
    });
};

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

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

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

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

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

PowerShell

Annotazioni

Questa funzionalità non è attualmente supportata in PowerShell, ma può essere ottenuta usando l'API HTTP di Funzioni permanenti.

Giava

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

Strumenti Core di Azure Functions

In Azure Functions Core Tools è anche possibile usare il durable get-instances comando con i filtri. Oltre ai parametri top, continuation-token, connection-string-setting e task-hub-name indicati in precedenza, è possibile usare tre parametri di filtro (created-after, created-before e runtime-status).

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Di seguito sono riportati i parametri per il durable get-instances comando .

• created-after (facoltativo): recuperare le istanze create dopo questa data/ora (UTC). Datetime in formato ISO 8601 accettati.
• created-before (facoltativo): recuperare le istanze create prima di questa data/ora (UTC). Formati di datetime ISO 8601 accettati.
• runtime-status (facoltativo): recuperare le istanze con uno stato specifico(ad esempio, esecuzione o completamento). Può fornire più stati (separati da spazio).
• top (facoltativo): numero di istanze recuperate per richiesta. Il valore predefinito è 10.
• continuation-token (facoltativo): token per indicare la pagina o la sezione delle istanze da recuperare. Ogni get-instances esecuzione restituisce un token al set di istanze successivo.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): Nome dell'hub delle attività di Durable Functions da usare. Il valore predefinito è DurableFunctionsHub. Può anche essere impostato in host.json, usando durableTask:HubName.

Se non si forniscono filtri (created-after, created-beforeo runtime-status), il comando recupera top semplicemente le istanze, senza considerare lo stato di runtime o il tempo di creazione.

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

Terminare le istanze

Se si dispone di un'istanza di orchestrazione che richiede troppo tempo per l'esecuzione, oppure se hai bisogno di fermarla prima che venga completata per qualsiasi motivo, puoi terminarla.

I due parametri per l'API terminate sono un ID istanza e una stringa motivo , che vengono scritti nei log e nello stato dell'istanza.

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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);
};

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

Giava

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

Un'istanza terminata passerà infine allo Terminated stato . Tuttavia, questa transizione non verrà eseguita immediatamente. L'operazione di chiusura verrà invece accodata nell'hub attività insieme ad altre operazioni per tale istanza. È possibile usare le API di query dell'istanza per sapere quando un'istanza terminata ha effettivamente raggiunto lo Terminated stato.

Annotazioni

La terminazione dell'istanza non viene attualmente propagata. Le funzioni delle attività e delle orchestrazioni secondarie vengono eseguite fino al completamento, indipendentemente dal fatto che sia terminata o meno l'istanza di orchestrazione che le ha chiamate.

Sospendere e riprendere le istanze

Sospendere un'orchestrazione consente di interrompere un'orchestrazione in esecuzione. A differenza della terminazione, è possibile riprendere un agente di orchestrazione sospeso in un secondo momento.

I due parametri per l'API di sospensione sono un ID istanza e una stringa motivo, che vengono scritti nei log e nello stato dell'istanza.

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // To resume an orchestration
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

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

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

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

Pitone

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

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

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

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

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

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

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

Annotazioni

Questa funzionalità è disponibile solo nel Durable Functions PowerShell SDK autonomo. Vedere la differenza tra l'SDK autonomo e l'SDK predefinito legacy insieme alla guida alla migrazione.

Giava

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

Un'istanza sospesa passerà infine allo Suspended stato . Tuttavia, questa transizione non verrà eseguita immediatamente. L'operazione di sospensione verrà invece accodata nell'hub attività insieme ad altre operazioni per tale istanza. È possibile usare le API di query dell'istanza per sapere quando un'istanza in esecuzione ha effettivamente raggiunto lo stato Suspended.

Quando un agente di orchestrazione sospeso viene ripreso, il relativo stato torna a Running.

Strumenti Core di Azure Functions

È anche possibile terminare direttamente un'istanza di orchestrazione usando il func durable terminate comando in Core Tools.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il comando durable terminate accetta i parametri seguenti:

• id (obbligatorio): ID dell'istanza di orchestrazione da terminare.
• reason (facoltativo): motivo della terminazione.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub delle attività Durable Functions da usare. Il valore predefinito è DurableFunctionsHub. Può anche essere impostato in host.json, usando durableTask:HubName.

Il comando seguente termina un'istanza di orchestrazione con ID 0ab8c55a66644d68a3a8b220b12d209c:

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

Inviare eventi alle istanze

In alcuni scenari, le funzioni dell'agente di orchestrazione devono attendere e ascoltare gli eventi esterni. Gli scenari in cui è utile includono gli scenari di monitoraggio e interazione umana .

È possibile inviare notifiche di eventi alle istanze in esecuzione usando l'API di generazione di eventi del client di orchestrazione. Le orchestrazioni possono ascoltare e rispondere a questi eventi usando l'API dell'orchestratore 'wait for external event'.

I parametri per l'evento di generazione sono i seguenti:

• ID istanza: ID univoco dell'istanza.
• Nome evento: nome dell'evento da inviare.
• Dati dell'evento: payload serializzabile JSON da inviare all'istanza.

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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);
};

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

Giava

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

Annotazioni

Se non è presente alcuna istanza di orchestrazione con l'ID istanza specificato, il messaggio di evento viene rimosso. Se esiste un'istanza ma non è ancora in attesa dell'evento, l'evento verrà archiviato nello stato dell'istanza finché non sarà pronto per essere ricevuto ed elaborato.

Strumenti Core di Azure Functions

È anche possibile generare un evento a un'istanza di orchestrazione direttamente usando il func durable raise-event comando in Core Tools.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il comando durable raise-event accetta i parametri seguenti:

• id (obbligatorio): ID dell'istanza di orchestrazione.
• event-name: nome dell'evento da generare.
• event-data (facoltativo): dati da inviare all'istanza di orchestrazione. Può trattarsi del percorso di un file JSON oppure di fornire i dati direttamente nella riga di comando.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub delle attività di Durable Functions da usare. Il valore predefinito è DurableFunctionsHub. Può anche essere impostato in host.json, usando 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

Attendere il completamento dell'orchestrazione

Nelle orchestrazioni a esecuzione prolungata, è possibile attendere e ottenere i risultati di un'orchestrazione. In questi casi, è utile anche essere in grado di definire un periodo di timeout per l'orchestrazione. Se il timeout viene superato, lo stato dell'orchestrazione deve essere restituito anziché i risultati.

L'API "wait for completion or create check status response" può essere utilizzata per ottenere l'output effettivo da un'istanza di orchestrazione in modo sincrono. Per impostazione predefinita, questo metodo ha un timeout predefinito di 10 secondi e un intervallo di polling di 1 secondo.

Di seguito è riportato un esempio di funzione trigger HTTP che illustra come usare questa 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;
}

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

PowerShell

Annotazioni

PowerShell non dispone attualmente di un comando predefinito per questo scenario.

Giava

Java attualmente non ha un singolo metodo per questo scenario. Tuttavia, può essere implementato usando alcune righe di codice aggiuntive.

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

Chiamare la funzione con la riga seguente. Usare 2 secondi per il timeout e 0,5 secondi per l'intervallo di ripetizione dei tentativi:

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

Annotazioni

Il comando cURL precedente presuppone che nel progetto sia presente una funzione dell'agente di orchestrazione denominata E1_HelloSequence . A causa del modo in cui viene scritta la funzione trigger HTTP, è possibile sostituirla con il nome di qualsiasi funzione dell'agente di orchestrazione nel progetto.

A seconda del tempo necessario per ottenere la risposta dall'istanza di orchestrazione, esistono due casi:

• Le istanze di orchestrazione vengono completate entro il timeout definito (in questo caso 2 secondi) e la risposta è l'output effettivo dell'istanza di orchestrazione, recapitato in modo sincrono:

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

• Le istanze di orchestrazione non possono essere completate entro il timeout definito e la risposta è quella predefinita descritta in Individuazione 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}"
}

Annotazioni

Il formato degli URL del webhook può variare a seconda della versione dell'host di Funzioni di Azure in esecuzione. L'esempio precedente riguarda l'host Azure Functions 3.0.

Recupera gli URL del webhook HTTP di gestione

È possibile utilizzare un sistema esterno per monitorare o generare eventi per un'orchestrazione. I sistemi esterni possono comunicare con Durable Functions tramite gli URL del webhook che fanno parte della risposta predefinita descritta in Individuazione URL API HTTP. È possibile accedere agli URL del webhook a livello di codice utilizzando l'associazione client di orchestrazione. In particolare, l'API di creazione del payload di gestione HTTP può essere usata per ottenere un oggetto serializzabile che contiene questi URL webhook.

L'API crea payload di gestione HTTP ha un parametro:

• ID istanza: ID univoco dell'istanza.

I metodi restituiscono un oggetto con le proprietà stringa seguenti:

• ID: L'ID dell'istanza dell'orchestrazione (dovrebbe essere lo stesso dell'input InstanceId).
• StatusQueryGetUri: URL di stato dell'istanza di orchestrazione.
• SendEventPostUri: URL di generazione di eventi dell'istanza di orchestrazione.
• TerminatePostUri: URL di terminazione dell'istanza di orchestrazione.
• PurgeHistoryDeleteUri: URL di "ripulitura della cronologia" dell'istanza di orchestrazione.
• suspendPostUri: URL di "sospensione" dell'istanza di orchestrazione.
• resumePostUri: URL "resume" dell'istanza di orchestrazione.

Le funzioni possono inviare istanze di questi oggetti a sistemi esterni per monitorare o generare eventi nelle orchestrazioni corrispondenti, come illustrato negli esempi seguenti:

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare DurableActivityContext invece di IDurableActivityContext, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient ed è necessario usare il DurableOrchestrationClient tipo di IDurableOrchestrationClientparametro anziché . Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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,
    });
};

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

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

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

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

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

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

Giava

Annotazioni

Questa funzionalità non è attualmente supportata in Java.

Riavvolgere le istanze (anteprima)

Se si verifica un errore di orchestrazione per un motivo imprevisto, è possibile riavvolgere l'istanza a uno stato precedentemente integro usando un'API compilata a tale scopo.

Annotazioni

Questa API non deve essere una sostituzione per la corretta gestione degli errori e i criteri di ripetizione dei tentativi. È invece progettato per essere usato solo nei casi in cui le istanze di orchestrazione hanno esito negativo per motivi imprevisti. Le orchestrazioni in stati diversi da Failed (ad esempio, Running, Pending, Terminated, Completed) non possono essere "riavvolte". Per altre informazioni sulla gestione degli errori e sui criteri di ripetizione dei tentativi, vedere l'articolo Gestione degli errori .

Usare il metodo RewindAsync (.NET) o rewind (JavaScript) dell'associazione client di orchestrazione per riportare l'orchestrazione nello stato In esecuzione. Anche questo metodo eseguirà di nuovo l'attività o gli errori di esecuzione dell'orchestrazione secondaria che hanno causato l'errore di orchestrazione.

Si supponga, ad esempio, di avere un flusso di lavoro che coinvolge una serie di approvazioni umane. Si supponga che siano presenti una serie di funzioni di attività che comunicano a un utente che è necessaria l'approvazione e che attendano la risposta in tempo reale. Dopo che tutte le attività di approvazione hanno ricevuto risposte o timeout, si supponga che un'altra attività non riesca a causa di una configurazione errata dell'applicazione, ad esempio una stringa di connessione di database non valida. Il risultato è un errore di orchestrazione profondo nel flusso di lavoro. Con l'API RewindAsync (.NET) o rewind (JavaScript), un amministratore dell'applicazione può correggere l'errore di configurazione e riavvolgere l'orchestrazione non riuscita allo stato immediatamente prima dell'errore. Nessuno dei passaggi di interazione umana deve essere nuovamente approvato e l'orchestrazione può ora essere completata correttamente.

Annotazioni

La funzionalità rewind non supporta il riavvolgimento delle istanze di orchestrazione che usano timer durevoli.

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di 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);
};

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

Annotazioni

Questa funzionalità non è attualmente supportata in Python.

PowerShell

Annotazioni

Questa funzionalità non è attualmente supportata in PowerShell.

Giava

Annotazioni

Questa funzionalità non è attualmente supportata in Java.

Strumenti Core di Azure Functions

È anche possibile riavvolgere un'istanza di orchestrazione direttamente usando il func durable rewind comando in Core Tools.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il comando durable rewind accetta i parametri seguenti:

• id (obbligatorio): ID dell'istanza di orchestrazione.
• reason (facoltativo): motivo della riavvolgimento dell'istanza di orchestrazione.
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività di Durable Functions da utilizzare. Per impostazione predefinita, viene utilizzato il nome dell'hub delle attività nel file host.json.

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

Eliminare la cronologia delle istanze

Per rimuovere tutti i dati associati a un'orchestrazione, è possibile eliminare la cronologia delle istanze. Ad esempio, è possibile eliminare tutte le risorse di archiviazione associate a un'istanza completata. A tale scopo, usare l'API dell'istanza di ripulitura definita dal client di orchestrazione.

Questo primo esempio illustra come eliminare una singola istanza di orchestrazione.

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

Per la configurazione di function.json, vedere Istanze di avvio .

Pitone

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

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

    return await client.purge_instance_history(instance_id)

PowerShell

Annotazioni

Questa funzionalità non è attualmente supportata in PowerShell, ma può essere ottenuta usando l'API HTTP di Funzioni permanenti.

Giava

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

Nell'esempio seguente viene illustrata una funzione attivata dal timer che elimina la cronologia per tutte le istanze di orchestrazione completate dopo l'intervallo di tempo specificato. In questo caso, rimuove i dati per tutte le istanze completate 30 o più giorni fa. Questa funzione di esempio è pianificata per l'esecuzione una volta al giorno, alle 12:00 UTC:

C#

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

Annotazioni

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare l'attributo OrchestrationClient anziché l'attributo DurableClient, ed è necessario usare il tipo di parametro DurableOrchestrationClient anziché IDurableOrchestrationClient. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di Durable Functions .

JavaScript

Il purgeInstanceHistoryBy metodo può essere usato per eliminare in modo condizionale la cronologia delle istanze per più istanze.

function.json

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

Annotazioni

Questo esempio è destinato a Durable Functions versione 2.x. Nella versione 1.x usare orchestrationClient anziché durableClient.

index.js

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

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

PowerShell

Annotazioni

Questa funzionalità non è attualmente supportata in PowerShell, ma può essere ottenuta usando l'API HTTP di Funzioni permanenti.

Pitone

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)

Giava

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

Annotazioni

Affinché l'operazione di eliminazione della cronologia abbia esito positivo, lo stato di runtime dell'istanza di destinazione deve essere Completato, Terminato o Non riuscito.

Strumenti Core di Azure Functions

È possibile eliminare la cronologia di un'istanza di orchestrazione usando il func durable purge-history comando in Core Tools. Analogamente al secondo esempio C# nella sezione precedente, elimina la cronologia per tutte le istanze di orchestrazione create durante un intervallo di tempo specificato. È possibile filtrare ulteriormente le istanze eliminate in base allo stato di runtime.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il durable purge-history comando ha diversi parametri:

• created-after (facoltativo): elimina la cronologia delle istanze create dopo questa data/ora (UTC). Formati di datetime ISO 8601 accettati.
• created-before (facoltativo): elimina la cronologia delle istanze create prima di questa data/ora (UTC). Formati di datetime ISO 8601 accettati.
• runtime-status (facoltativo): eliminare la cronologia delle istanze con uno stato specifico(ad esempio, esecuzione o completamento). Può fornire più stati (separati da spazio).
• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività di Durable Functions da utilizzare. Per impostazione predefinita, viene utilizzato il nome dell'hub delle attività nel file host.json.

Il comando seguente elimina la cronologia di tutte le istanze non riuscite create prima del 14 novembre 2021 alle 17:35 (UTC).

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

Eliminare un hub attività

Utilizzando il func durable delete-task-hub comando in Core Tools, è possibile eliminare tutti gli artefatti di archiviazione associati a un particolare hub attività, tra cui tabelle di archiviazione di Azure, code e BLOB.

Annotazioni

I comandi core tools sono attualmente supportati solo quando si usa il provider di archiviazione di Azure predefinito per rendere persistente lo stato di runtime.

Il durable delete-task-hub comando ha due parametri:

• connection-string-setting (facoltativo): nome dell'impostazione dell'applicazione contenente la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività di Durable Functions da utilizzare. Per impostazione predefinita, nel file host.json viene usato il nome dell'hub attività.

Il comando seguente elimina tutti i dati di archiviazione di Azure associati all'hub UserTest attività.

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

Passaggi successivi

Informazioni su come gestire il controllo delle versioni

Informazioni di riferimento sulle API HTTP predefinite per la gestione delle istanze