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 usando 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 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 dell'agente di orchestrazione da pianificare.
• Input: dati serializzabili in JSON che devono essere passati come input alla funzione dell'agente di orchestrazione.
• InstanceId: (facoltativo) l'ID univoco dell'istanza. Se non si specifica questo parametro, il metodo usa un ID casuale.

Suggerimento

Usare un identificatore casuale per l'ID istanza quando 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 dell'agente di orchestrazione singleton.

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

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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

Se non diversamente specificato, gli esempi in questa pagina usano il trigger HTTP con il function.json seguente.

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
}

Nota

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

Python

Se non diversamente specificato, gli esempi in questa pagina usano il trigger HTTP con il function.json seguente.

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
}

Nota

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 function.json seguente.

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
}

Nota

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

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

Se si vuole attendere che l'agente di orchestrazione inizi prima di tornare dalla funzione, è anche possibile usare il waitForInstanceStart() metodo .

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

Azure Functions Core Tools

È 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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività durable functions da usare. Il valore predefinito è DurableFunctionsHub. È anche possibile impostare questo valore in host.json usando durableTask:HubName.

Nota

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 è possibile eseguire questi comandi senza un host dell'app per le funzioni in esecuzione, è possibile che non sia possibile osservare alcuni effetti a meno che l'host non sia in esecuzione. Ad esempio, il start-new comando 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'app per le funzioni in grado di elaborare il messaggio.

Nota

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-status nell'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:

• Name: il nome della funzione dell'agente di orchestrazione.
• InstanceId: l'ID istanza dell'orchestrazione (deve essere lo stesso dell'input instanceId).
• CreatedTime: l'ora in cui la funzione dell'agente di orchestrazione ha iniziato l'esecuzione.
• LastUpdatedTime: l'ora in cui l'orchestrazione ha eseguito l'ultimo checkpoint.
• Input: l'input della funzione come valore JSON. Questo campo non viene popolato se showInput è false.
• CustomStatus: stato personalizzato dell'orchestrazione in formato JSON.
• Output: l'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 dell'agente 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 iniziata l'esecuzione.
  • Running: l'istanza ha iniziato l'esecuzione.
  • Completed: l'istanza è stata completata normalmente.
  • ContinuedAsNew: l'istanza si è riavviata con una nuova cronologia. Questo stato è uno stato temporaneo.
  • Failed: l'esecuzione dell'istanza non è riuscita e ha generato un errore.
  • Terminata: l'istanza è stata terminata in modo anomalo.
  • Sospeso: l'istanza è stata sospesa e può essere ripresa in un secondo momento.
• History: cronologia di esecuzione dell'orchestrazione. Questo campo viene popolato solo se showHistory è impostato su true.

Nota

Un agente di orchestrazione non viene contrassegnato come Completed finché non vengono completate tutte le attività pianificate e l'agente di orchestrazione non viene 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 WhenAny viene usato; 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.
}

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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");

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

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

Java

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

Azure Functions Core Tools

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

Nota

I comandi di 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 get-runtime-status comando 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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub 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 func comando 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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività 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 linguaggio per eseguire query sullo stato di tutte le istanze di orchestrazione nell'hub 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.
}

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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");

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

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

Vedere Avviare le istanze per la configurazione di 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))

Vedere Avviare le istanze per la configurazione di function.json.

PowerShell

Nota

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

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

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

Nota

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 get-instances comando accetta i parametri seguenti:

• top (facoltativo) : Questo comando supporta il paging. Questo parametro corrisponde al numero di istanze recuperate per ogni richiesta. L'impostazione predefinita è 10.
• continuation-token (facoltativo): token per indicare la pagina o la sezione delle istanze da recuperare. Ogni esecuzione get-instances restituisce un token per il set successivo di istanze.
• connection-string-setting (facoltativo) : Nome dell'impostazione dell'applicazione che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività durable functions da usare. 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 il tempo di creazione dell'orchestrazione o lo stato del runtime di 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));
    }
}

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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");

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

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

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

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

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

PowerShell

Nota

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

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

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

Nota

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). Datetime in formato ISO 8601 accettati.
• runtime-status (facoltativo): recuperare le istanze con uno stato specifico(ad esempio, esecuzione o completamento). Può fornire più stati (separati da spazi).
• top (facoltativo) : Numero di istanze recuperate per ogni richiesta. L'impostazione predefinita è 10.
• continuation-token (facoltativo): token per indicare la pagina o la sezione delle istanze da recuperare. Ogni esecuzione get-instances restituisce un token per il set successivo di istanze.
• connection-string-setting (facoltativo) : Nome dell'impostazione dell'applicazione che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività 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 è sufficiente arrestarla prima che venga completata per qualsiasi motivo, è possibile 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);
}

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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");

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

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

Java

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

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.

Nota

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

Sospendere e riprendere le istanze

La sospensione di un'orchestrazione consente di arrestare 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)
{
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    DateTime dueTime = context.CurrentUtcDateTime.AddSeconds(30);
    await context.CreateTimer(dueTime, CancellationToken.None);
    
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

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

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

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

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

Python

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

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

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

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

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

Java

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

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

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

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.

Azure Functions Core Tools

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

Nota

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 terminate comando 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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub 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'agente di orchestrazione degli eventi esterni.

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

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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");

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

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

Java

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

Nota

Se non esiste 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.

Azure Functions Core Tools

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

Nota

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 raise-event comando accetta i parametri seguenti:

• id (obbligatorio): ID dell'istanza di orchestrazione.
• event-name: nome dell'evento da generare.
• event-data (facoltativo) : I 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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività 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 usata 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;
}

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

PowerShell

Nota

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

Java

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"

Nota

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, si verificano 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}"
}

Nota

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

Recuperare gli URL del webhook di gestione HTTP

È possibile usare un sistema esterno per monitorare o generare eventi a 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 usando 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: ID istanza dell'orchestrazione (deve 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 "suspend" 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 };
}

Nota

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

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

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

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

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

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

Java

Nota

Questa funzionalità non è attualmente supportata in Java.

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

Nota

Questa API non deve sostituire una corretta gestione degli errori e i criteri di ripetizione dei tentativi, ma deve essere usata solo nei casi in cui le istanze di orchestrazione hanno esito negativo per motivi non previsti. Le orchestrazioni in stati diversi Failed da (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 RewindAsync metodo (.NET) o rewind (JavaScript) dell'associazione client di orchestrazione per riportare l'orchestrazione nello stato In esecuzione . Questo metodo eseguirà anche 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 un database non valido stringa di connessione. Ne consegue un errore di orchestrazione 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.

Nota

La funzionalità di riavvolgimento non supporta la 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);
}

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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");

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

Nota

Questa funzionalità non è attualmente supportata in Python.

PowerShell

Nota

Questa funzionalità non è attualmente supportata in PowerShell.

Java

Nota

Questa funzionalità non è attualmente supportata in Java.

Azure Functions Core Tools

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

Nota

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 rewind comando 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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività durable functions da usare. Per impostazione predefinita, viene usato il nome dell'hub attività nel file host.json .

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

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

Vedere Avviare le istanze per la configurazione di function.json.

Python

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

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

    return await client.purge_instance_history(instance_id)

PowerShell

Nota

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

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

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

Nota

Il codice C# precedente è per Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare OrchestrationClient l'attributo 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

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
}

Nota

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

Nota

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

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

Nota

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.

Azure Functions Core Tools

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

Nota

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) : Ripulire le istanze create dopo questa data/ora (UTC). Datetime in formato ISO 8601 accettati.
• created-before (facoltativo) : Ripulire le istanze create prima di questa data/ora (UTC). Datetime in formato 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 spazi).
• connection-string-setting (facoltativo) : Nome dell'impostazione dell'applicazione che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività durable functions da usare. Per impostazione predefinita, viene usato il nome dell'hub 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à

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

Nota

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 che contiene la stringa di connessione di archiviazione da usare. Il valore predefinito è AzureWebJobsStorage.
• task-hub-name (facoltativo): nome dell'hub attività durable functions da usare. Per impostazione predefinita, viene usato il nome dell'hub attività nel file host.json .

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