Gérer des instances dans Durable Functions dans Azure

Les orchestrations dans Durable Functions sont des fonctions avec état à exécution longue qui peuvent être démarrées, interrogées, suspendues, reprises et arrêtées à l’aide d’API de gestion intégrées. Plusieurs autres API de gestion d’instance sont également exposées par la liaison du client d’orchestration Durable Functions, par exemple l’envoi d’événements externes à des instances, la purge de l’historique des instances, etc. Cet article présente les détails de toutes les opérations de gestion des instances prises en charge.

Démarrer des instances

La méthode start-new (ou schedule-new) sur la liaison du client d’orchestration démarre une nouvelle instance d’orchestration. En interne, cette méthode écrit un message par le biais du fournisseur de stockage Durable Functions, puis retourne. Ce message déclenche de manière asynchrone le démarrage d’une fonction d’orchestration avec le nom spécifié.

Les paramètres de démarrage d’une nouvelle instance d’orchestration sont les suivants :

• Name : Nom de la fonction orchestrator à planifier.
• Entrée: Toutes les données JSON sérialisables devant être passées comme entrée à la fonction orchestrator.
• InstanceId : (Facultatif) ID unique de l’instance. Si vous ne spécifiez pas ce paramètre, la méthode utilise un ID aléatoire.

Conseil

Utilisez un identificateur aléatoire pour l’ID d’instance quand cela est possible. Les ID d’instance aléatoires permettent de garantir une distribution égale de la charge lors de la mise à l’échelle des fonctions orchestrator sur plusieurs machines virtuelles. Le moment qui convient pour l’utilisation des ID d’instance non aléatoires correspond au moment où l’ID provient d’une source externe ou lors de l’implémentation du modèle orchestrateur singleton.

Le code suivant est un exemple de fonction qui démarre une nouvelle instance d’orchestration :

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de Durable Functions.

JavaScript

Sauf indication contraire, les exemples de cette page utilisent le déclencheur HTTP avec le function  JSON suivant.

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
}

Notes

Cet exemple cible la version 2  x de Durable Functions. Dans la version 1. x, utilisez orchestrationClientau lieu dedurableClient.

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

Sauf indication contraire, les exemples de cette page utilisent le déclencheur HTTP avec le function  JSON suivant.

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
}

Notes

Cet exemple cible la version 2  x de Durable Functions. Dans la version 1. x, utilisez orchestrationClientau lieu dedurableClient.

__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

Sauf indication contraire, les exemples de cette page utilisent le déclencheur HTTP avec le function  JSON suivant.

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
}

Notes

Cet exemple cible la version 2  x de Durable Functions. Dans la version 1. x, utilisez orchestrationClientau lieu dedurableClient.

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

Si vous souhaitez attendre que l’orchestrateur démarre avant de retourner à partir de votre fonction, vous pouvez également utiliser la méthode waitForInstanceStart().

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

Azure Functions Core Tools

Vous pouvez également démarrer une instance directement avec la commande func durable start-new dans les Core Tools, qui utilise les paramètres suivants :

• function-name (obligatoire) : Nom de la fonction à démarrer.
• input (facultatif) : Entrée de la fonction, en ligne ou par le biais d’un fichier JSON. Pour les fichiers, ajoutez un préfixe au chemin du fichier avec @, par exemple, @path/to/file.json.
• id (facultatif) : ID de l’instance d’orchestration. Si vous ne spécifiez pas ce paramètre, la commande utilise un GUID aléatoire.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. La valeur par défaut est AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. La valeur par défaut est DurableFunctionsHub. Vous pouvez également le définir dans host.json à l’aide de durableTask:HubName.

Notes

Les commandes Core Tools supposent que vous les exécutiez à partir du répertoire racine d’une application de fonction. Si vous fournissez explicitement les paramètres connection-string-setting et task-hub-name, vous pouvez exécuter les commandes à partir de n’importe quel répertoire. Même si vous pouvez exécuter ces commandes sans exécuter d’hôte d’application de fonction, vous constaterez peut-être que vous ne pouvez pas observer certains effets si l’hôte n’est pas exécuté. Par exemple, la commande start-new met en file d’attente un message de démarrage dans le hub de tâches cible, mais l’orchestration ne peut pas réellement s’exécuter à moins d’avoir un processus hôte d’application de fonction en cours d’exécution pouvant traiter le message.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande suivante démarre la fonction nommée HelloWorld et lui passe le contenu du fichier counter-data.json :

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

Interroger des instances

Après le démarrage de nouvelles instances d’orchestration, vous devrez probablement interroger leur état d’exécution pour savoir si elles sont en cours d’exécution, si elles ont terminé ou si elles ont échoué.

La méthode get-status sur la liaison du client d’orchestration demande l’état d’une instance d’orchestration.

Elle prend instanceId (obligatoire), showHistory (facultatif), showHistoryOutput (facultatif) et showInput (facultatif) comme paramètres.

• showHistory : Si la valeur est définie sur true, la réponse contient l’historique d’exécution.
• showHistoryOutput : Si la valeur est définie sur true, l’historique d’exécution contient les sorties de l’activité.
• showInput : Si la valeur est définie sur false, la réponse ne contient pas l’entrée de la fonction. La valeur par défaut est true.

La méthode renvoie un objet avec les propriétés suivantes :

• Name : Nom de la fonction orchestrator.
• InstanceId : ID d’instance de l’orchestration (doit être identique à l’entrée instanceId).
• CreatedTime : Heure à laquelle la fonction orchestrator a commencé à s’exécuter.
• LastUpdatedTime : Heure du dernier point de contrôle d’orchestration.
• Entrée: Entrée de la fonction sous forme de valeur JSON. Ce champ n’est pas rempli si showInput est false.
• CustomStatus : État personnalisé de l’orchestration au format JSON.
• Sortie: Sortie de la fonction sous forme de valeur JSON (si cette fonction est terminée). En cas d’échec de la fonction d’orchestrateur, cette propriété inclut les détails de l’échec. En cas de suspension ou d’arrêt de la fonction de l’orchestrateur, cette propriété en indique la raison (s’il y en a une).
• RuntimeStatus : une des valeurs suivantes :
  • Pending : L’instance a été planifiée mais n’est pas encore en cours d’exécution.
  • En cours d’exécution : L’instance a commencé à s’exécuter.
  • Completed : L’instance s’est terminée normalement.
  • ContinuedAsNew : L’instance a redémarré automatiquement avec un nouvel historique. Cet état est temporaire.
  • Échec : Échec de l’instance avec une erreur.
  • Terminé : L’instance a été brusquement arrêtée.
  • Suspended : l’instance a été suspendue et pourra être reprise ultérieurement.
• History : L’historique d’exécution de l’orchestration. Ce champ est renseigné uniquement si showHistory est défini sur true.

Notes

Un orchestrateur n’est pas marqué comme Completed avant que toutes ses tâches planifiées soient terminées et que l’orchestrateur ait renvoyé son résultat. En d’autres termes, il n’est pas suffisant qu’un orchestrateur atteigne son instruction return pour qu’il soit marqué comme Completed. Cela s’avère particulièrement pertinent dans les cas où WhenAny est utilisé : ces orchestrateurs sont souvent return avant l’exécution de toutes les tâches planifiées.

Cette méthode renvoie null (.NET et Java), undefined (JavaScript) ou None (Python) si l’instance n’existe pas.

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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: ...
}

Consultez les Instances de démarrage pour la configuration de la 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

Il est également possible d’obtenir l’état d’une instance d’orchestration à l’aide de la commande func durable get-runtime-status dans Core Tools.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable get-runtime-status utilise les paramètres suivants :

• id (obligatoire) : ID de l’instance d’orchestration.
• show-input (facultatif) : Si la valeur est définie sur true, la réponse contient l’entrée de la fonction. La valeur par défaut est false.
• show-output (facultatif) : Si la valeur est définie sur true, la réponse contient la sortie de la fonction. La valeur par défaut est false.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, il s’agit de DurableFunctionsHub. Vous pouvez également le définir dans host.json, à l’aide de durableTask:HubName.

La commande suivante récupère l’état (y compris l’entrée et la sortie) d’une instance avec l’ID d’instance d’orchestration 0ab8c55a66644d68a3a8b220b12d209c. Cela suppose que la commande func est exécutée à partir du répertoire racine de l’application de fonction :

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

Vous pouvez utiliser la commande durable get-history pour récupérer l’historique d’une instance d’orchestration. Les paramètres suivants sont pris en compte :

• id (obligatoire) : ID de l’instance d’orchestration.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, il s’agit de DurableFunctionsHub. Vous pouvez également le définir dans host.json à l’aide de durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Interroger toutes les instances

Vous pouvez utiliser des API dans votre Kit de développement logiciel (SDK) de langage pour interroger les états de toutes les instances d’orchestration dans votre hub de tâches. Cette API « list-instances » ou « get-status » retourne une liste d’objets qui représentent les instances de l’orchestration correspondant aux paramètres de la requête.

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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));
    });
};

Consultez les Instances de démarrage pour la configuration de la 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))

Consultez les Instances de démarrage pour la configuration de la function  JSON.

PowerShell

Notes

Actuellement, cette fonctionnalité n’est pas prise en charge dans PowerShell, mais elle peut être obtenue à l’aide de l’API HTTP Durable Functions.

Java

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

Azure Functions Core Tools

Vous pouvez aussi interroger des instances directement à l’aide de la commande func durable get-instances dans Core Tools.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable get-instances utilise les paramètres suivants :

• top (facultatif) : Cette commande prend en charge la pagination. Ce paramètre correspond au nombre d’instances récupérées par demande. La valeur par défaut est de 10.
• continuation-token (facultatif) : Jeton qui indique la page ou la section des instances à récupérer. Chaque exécution de get-instances retourne un jeton à l’ensemble suivant d’instances.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, il s’agit de DurableFunctionsHub. Vous pouvez également le définir dans host.json, à l’aide de durableTask:HubName.

func durable get-instances

Interroger les instances en appliquant des filtres

Il est possible que vous n’ayez pas vraiment besoin de toutes les informations fournies par une requête d’instance standard. Peut-être avez-vous seulement besoin de connaître l’heure de création de l’orchestration ou de l’état de son exécution ? Vous pouvez affiner votre requête en appliquant des filtres.

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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));
    });
};

Consultez les Instances de démarrage pour la configuration de la 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

Notes

Actuellement, cette fonctionnalité n’est pas prise en charge dans PowerShell, mais elle peut être obtenue à l’aide de l’API HTTP Durable Functions.

Java

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

Azure Functions Core Tools

Dans Azure Functions Core Tools, vous pouvez également utiliser la commande durable get-instances avec des filtres. Outre les paramètres top, continuation-token, connection-string-setting et task-hub-name mentionnés ci-dessus, vous pouvez utiliser trois paramètres de filtre (created-after, created-before et runtime-status).

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

Voici les paramètres de la commande durable get-instances.

• created-after (facultatif) : Récupère les instances créées après cette date/heure (UTC). Les dates et heures au format ISO 8601 sont acceptées.
• created-before (facultatif) : Récupère les instances créées avant cette date/heure (UTC). Les dates et heures au format ISO 8601 sont acceptées.
• runtime-status (facultatif) : Récupérez les instances avec un état particulier (par exemple, En cours d’exécution ou Terminé). Peut fournir plusieurs états (séparés par des espaces).
• top (facultatif) : Nombre d’instances récupérées par requête. La valeur par défaut est de 10.
• continuation-token (facultatif) : Jeton qui indique la page ou la section des instances à récupérer. Chaque exécution de get-instances retourne un jeton à l’ensemble suivant d’instances.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, il s’agit de DurableFunctionsHub. Vous pouvez également le définir dans host.json, à l’aide de durableTask:HubName.

Si vous n’appliquez pas de filtres (created-after, created-before ou runtime-status), la commande récupère simplement les instances top, sans se soucier de l’état de l’exécution ou de l’heure de création.

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

Arrêter les instances

Si vous disposez d’une instance d’orchestration dont l’exécution est trop longue, ou si vous devez simplement l’arrêter avant la fin pour une raison quelconque, vous avez la possibilité de l’arrêter.

Les deux paramètres de l'API de résiliation sont un ID d'instance et une chaîne de raison, qui sont écrits dans les journaux et dans l'état de l'instance.

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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);
};

Consultez les Instances de démarrage pour la configuration de la 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);
}

Une fois terminées, les instances passent à l’état Terminated. Toutefois, ce passage ne se produit pas immédiatement. En effet, l’opération de terminaison est mise en file d’attente dans le hub de tâches avec les autres opérations concernant cette instance. Vous pouvez utiliser les API d’interrogation d’instance pour savoir à quel moment une instance terminée est passée à l’état Terminated.

Notes

Il n’est pas possible de propager l’arrêt des instances. Les fonctions et sous-orchestrations de l’activité s’exécutent jusqu’à la fin, même si l’instance d’orchestration qui les a appelées a été arrêtée.

Suspendre et reprendre des instances

La suspension d’une orchestration vous permet d’interrompre une orchestration en cours d’exécution. Contrairement à l’arrêt, la suspension vous permet de reprendre un orchestrateur suspendu ultérieurement.

Les deux paramètres de l’API de suspension sont un ID d’instance et une chaîne de raison, qui sont écrits dans les journaux et dans l’état de l’instance.

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

Une instance suspendue passera finalement à l’état Suspended. Toutefois, ce passage ne se produit pas immédiatement. En effet, l’opération de suspension est mise en file d’attente dans le hub de tâches avec les autres opérations concernant cette instance. Vous pouvez utiliser les API d’interrogation d’instance pour savoir à quel moment une instance exécutée passe effectivement à l’état Suspended.

Quand un orchestrateur suspendu est repris, son état revient à Running.

Azure Functions Core Tools

Vous pouvez aussi directement arrêter une instance d’orchestration, à l’aide de la commande func durable terminate dans Core Tools.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable terminate utilise les paramètres suivants :

• id (obligatoire) : ID de l’instance d’orchestration à arrêter.
• reason (facultatif) : Raison de l’arrêt.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, il s’agit de DurableFunctionsHub. Vous pouvez également le définir dans host.json, à l’aide de durableTask:HubName.

La commande suivante arrête une instance d’orchestration avec l’ID 0ab8c55a66644d68a3a8b220b12d209c :

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

Envoyer des événements à des instances

Dans certains scénarios, les fonctions d’orchestrateur doivent attendre et écouter les événements externes. Les scénarios de surveillance et d’interaction humaine sont des exemples de scénarios où cela est utile.

Vous pouvez envoyer des notifications d'événements aux instances en cours d'exécution en utilisant l'API raise event de l’orchestration client. Les orchestrations peuvent écouter et répondre à ces événements à l’aide de l’API d’orchestrateur wait for external event.

Les paramètres de raise event sont les suivants :

• ID d’instance : ID unique de l’instance.
• Nom de l’événement : nom de l’événement à envoyer.
• Données de l’événement : charge utile JSON sérialisable à envoyer à l’instance.

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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);
};

Consultez les Instances de démarrage pour la configuration de la 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);
}

Notes

S’il n’existe aucune instance d’orchestration avec l’ID d’instance spécifié, le message d’événement est ignoré. Si une instance existe, mais qu’elle n’attend pas encore l’événement, ce dernier est stocké dans l’état de l’instance jusqu’à ce qu’il soit prêt à être reçu et traité.

Azure Functions Core Tools

Vous pouvez aussi déclencher un événement dans une instance d’orchestration, à l’aide de la commande func durable raise-event dans Core Tools.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable raise-event utilise les paramètres suivants :

• id (obligatoire) : ID de l’instance d’orchestration.
• event-name : Nom de l’événement à déclencher.
• event-data (facultatif) : Données à envoyer à l’instance d’orchestration. Il peut s’agir d’un chemin de fichier JSON. Vous pouvez également fournir les données directement sur la ligne de commande.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, il s’agit de DurableFunctionsHub. Vous pouvez également le définir dans host.json, à l’aide de 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

Attendre la fin de l’orchestration

Dans les orchestrations à exécution longue, vous pouvez souhaiter attendre les résultats de l’orchestration. Dans ce cas, il est également utile de définir un délai d’attente pour l’orchestration. Si le délai d’attente est dépassé, l’état de l’orchestration doit être retourné à la place des résultats.

L’API « wait for completion or create check status response » peut être utilisée pour obtenir la sortie réelle d’une instance d’orchestration de manière synchrone. Par défaut, cette méthode a un délai d’expiration par défaut de 10 secondes et un intervalle d’interrogation de 1 seconde.

Voici un exemple de fonction de déclencheur HTTP qui montre comment utiliser cette 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;
}

Consultez les Instances de démarrage pour la configuration de la 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

Notes

Actuellement, PowerShell n’a pas de commande intégrée pour ce scénario.

Java

Java n’a actuellement pas de méthode unique pour ce scénario. Toutefois, il peut être implémenté à l’aide de quelques lignes de code supplémentaires.

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

Appelez la fonction avec la ligne suivante. Utilisez une valeur de 2 secondes pour le délai d’attente et de 0,5 seconde pour l’intervalle avant nouvelle tentative :

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

Notes

La commande cURL ci-dessus suppose que vous disposez d’une fonction d’orchestrateur nommée E1_HelloSequence dans votre projet. En raison de la façon dont la fonction de déclencheur HTTP est écrite, vous pouvez la remplacer par le nom de n’importe quelle fonction d’orchestrateur dans votre projet.

Selon le temps nécessaire pour obtenir la réponse de l’instance d’orchestration, il existe deux cas de figure :

• Les instances d’orchestration sont terminées dans le délai imparti (dans ce cas, 2 secondes). La réponse est la sortie d’instance d’orchestration qui est remise de manière synchrone :

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

• Les instances d’orchestration ne peuvent pas être terminées dans le délai imparti. La réponse est celle par défaut qui est décrite dans Découverte de l’URL de l’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}"
}

Notes

Le format des URL webhook peut varier selon la version de l’hôte Azure Functions que vous exécutez. L’exemple précédent utilise l’hôte Azure Functions 3.0.

Récupérer les URL webhook de gestion HTTP

Vous pouvez utiliser un système externe pour superviser ou déclencher des événements au sein d’une orchestration. Les systèmes externes peuvent communiquer avec Durable Functions via les URL webhook qui font partie de la réponse par défaut décrite dans Découverte de l’URL de l’API HTTP. Vous pouvez également accéder par programme aux URL du webhook à l’aide de la liaison du client d’orchestration. Plus précisément, l’API create HTTP management payload peut être utilisée pour obtenir un objet sérialisable qui contient ces URL de webhook.

L’API create HTTP management payload crée un paramètre :

• ID d’instance : ID unique de l’instance.

Les méthodes renvoient un objet avec les propriétés de chaîne suivantes :

• Id : ID d’instance de l’orchestration (doit être identique à l’entrée InstanceId).
• StatusQueryGetUri : L’URL de l’état de l’instance d’orchestration.
• SendEventPostUri : L’URL « Raise event » de l’instance d’orchestration.
• TerminatePostUri : L’URL « d’arrêt » de l’instance d’orchestration.
• PurgeHistoryDeleteUri : URL de « purge de l’historique » de l’instance d’orchestration.
• suspendPostUri : URL de « suspension » de l’instance de l’orchestration.
• resumePostUri : URL de « reprise » de l’instance de l’orchestration.

Les fonctions peuvent envoyer des instances de ces objets à des systèmes externes pour surveiller ou déclencher des événements sur les orchestrations correspondantes, comme indiqué dans les exemples suivants :

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut DurableActivityContext au lieu de l’attribut IDurableActivityContext, et vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et devez utiliser le type de paramètre DurableOrchestrationClient et non IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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,
    });
};

Consultez les Instances de démarrage pour la configuration de la 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

Notes

Cette fonctionnalité n’est pas prise en charge en Java.

Rembobiner des instances (préversion)

Si une orchestration échoue pour une raison quelconque, vous pouvez rembobiner l’instance vers un état sain précédent à l’aide d’une API intégrée à cet effet.

Notes

Cette API n’est pas destinée à se substituer à des stratégies appropriées de nouvelles tentatives et de gestion des erreurs. Son utilisation est plutôt uniquement réservée dans les cas où les instances d’orchestration échouent pour des raisons inattendues. Les orchestrations dans des états autres que Failed (par exemple, Running, Pending, Terminated et Completed) ne peuvent pas être « rembobinées ». Pour en savoir plus sur les stratégies de gestion des nouvelles tentatives et des erreurs, consultez l’article Gestion des erreurs.

Utilisez la méthode RewindAsync (.NET) ou rewind (JavaScript) de la liaison du client d’orchestration pour replacer l’orchestration à l’état Exécution en cours. Cette méthode réexécute également l’activité ou la sous-orchestration qui a échoué et provoqué l’échec de l’orchestration.

Par exemple, supposons que vous ayez un workflow impliquant une suite d’approbations humaines. Supposons que vous ayez une suite de fonctions d’activité qui informe une personne que son approbation est nécessaire, et qui attend la réponse en temps réel. Une fois que toutes les activités d’approbation ont reçu des réponses ou ont expiré, supposons qu’une autre activité échoue en raison d’un problème de configuration d’application (par exemple, une chaîne de connexion de base de données non valide). Il en résulte un échec de l’orchestration, survenu en profondeur dans le workflow. Avec l’API RewindAsync (.NET) ou rewind (JavaScript), un administrateur d’application peut corriger l’erreur de configuration et rembobiner (rewind) l’orchestration ayant échoué jusqu’à l’état situé immédiatement avant l’échec. Aucune des étapes nécessitant une interaction humaine ne doit être approuvée de nouveau ; l’orchestration peut désormais s’effectuer correctement.

Notes

La fonctionnalité de rembobinage ne prend pas en charge le rembobinage des instances d’orchestration qui utilisent des minuteurs durables.

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

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de 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);
};

Consultez les Instances de démarrage pour la configuration de la function  JSON.

Python

Notes

Cette fonctionnalité n’est pas prise en charge en Python.

PowerShell

Notes

Actuellement, cette fonctionnalité n’est pas prise en charge dans PowerShell.

Java

Notes

Cette fonctionnalité n’est pas prise en charge en Java.

Azure Functions Core Tools

Vous pouvez aussi rembobiner une instance d’orchestration, à l’aide de la commande func durable rewind dans Core Tools.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable rewind utilise les paramètres suivants :

• id (obligatoire) : ID de l’instance d’orchestration.
• reason (facultatif) : Motif de rembobinage de l’instance d’orchestration.
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, le nom du hub de tâches dans le fichier host.json est utilisé.

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

Vider l’historique des instances

Pour supprimer toutes les données associées à une orchestration, vous pouvez vider l’historique des instances. Par exemple, vous pouvez vouloir supprimer toutes les ressources de stockage associées à une instance terminée. Pour ce faire, utilisez l’API purge instance définie par le client d’orchestration.

Ce premier exemple montre comment vider une instance d’orchestration unique.

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

Consultez les Instances de démarrage pour la configuration de la 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

Notes

Actuellement, cette fonctionnalité n’est pas prise en charge dans PowerShell, mais elle peut être obtenue à l’aide de l’API HTTP Durable Functions.

Java

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

L’exemple suivant affiche une fonction déclenchée, par un minuteur, qui purge l’historique de toutes les instances d’orchestration terminées après l’intervalle de temps spécifié. Dans ce cas, elle supprime les données de toutes les instances terminées depuis 30 jours ou plus. Cet exemple de fonction est programmé pour s’exécuter une fois par jour, à midi 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
        });
}

Notes

Le code C# précédent correspond à Durable Functions 2.x. Pour Durable Functions 1.x, vous devez utiliser l’attribut OrchestrationClient au lieu de l’attribut DurableClient, et vous devez utiliser le type de paramètre DurableOrchestrationClient au lieu de IDurableOrchestrationClient. Pour en savoir plus sur les différences entre les versions, consultez l’article Versions de Durable Functions.

JavaScript

La méthode purgeInstanceHistoryBy peut être utilisée pour vider l’historique des instances de plusieurs instances de manière conditionnelle.

function.json

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

Notes

Cet exemple cible la version 2  x de Durable Functions. Dans la version 1. x, utilisez orchestrationClientau lieu dedurableClient.

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

Notes

Actuellement, cette fonctionnalité n’est pas prise en charge dans PowerShell, mais elle peut être obtenue à l’aide de l’API HTTP Durable Functions.

Python

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

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

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

Java

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

Notes

Pour que cette opération aboutisse, l’état d’exécution de l’instance cible doit être Terminé, Terminé ou Échec.

Azure Functions Core Tools

Vous pouvez aussi supprimer définitivement l’historique d’une instance d’orchestration, à l’aide de la commande func durable purge-history dans Core Tools. Tout comme dans le deuxième exemple C# de la section précédente, elle vide l’historique de toutes les instances d’orchestration créées dans un intervalle de temps spécifié. Vous pouvez filtrer encore davantage les instances vidées, selon leur état d’exécution.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable purge-history a plusieurs paramètres :

• created-after (facultatif) : Purge l’historique des instances créées après cette date/heure (UTC). Les dates et heures au format ISO 8601 sont acceptées.
• created-before (facultatif) : Purge l’historique des instances créées avant cette date/heure (UTC). Les dates et heures au format ISO 8601 sont acceptées.
• runtime-status (facultatif) : Videz l’historique des instances avec un état particulier (par exemple, Running ou Completed). Peut fournir plusieurs états (séparés par des espaces).
• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, le nom du hub de tâches dans le fichier host.json est utilisé.

La commande suivante supprime l’historique de toutes les instances qui ont été créées avant le 14 novembre 2021 à 19:35 (UTC) et qui ont échoué.

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

Supprimer un hub de tâches

À l’aide de la commande func durable delete-task-hub dans Core Tools, vous pouvez supprimer tous les artefacts de stockage associés à un concentrateur de tâches particulier, notamment les tables de stockage, les files d’attente et les objets blob Azure.

Notes

Les commandes Core Tools ne sont actuellement prises en charge que lors de l’utilisation du fournisseur Stockage Azure par défaut pour rendre l’état d’exécution persistant.

La commande durable delete-task-hub a deux paramètres :

• connection-string-setting (facultatif) : Nom du paramètre d’application contenant la chaîne de connexion de stockage à utiliser. Par défaut, il s’agit de AzureWebJobsStorage.
• task-hub-name (facultatif) : Nom du hub de tâches Durable Functions à utiliser. Par défaut, le nom du hub de tâches dans le fichier host.json est utilisé.

La commande suivante supprime toutes les données de stockage Azure associées au hub de tâches UserTest.

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

Étapes suivantes

Découvrez comment gérer les versions

Référence sur l'API HTTP intégrée pour la gestion des instances