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’instances sont également exposées par la liaison client d’orchestration Durable Functions, telles que l’envoi d’événements externes aux instances, la purge de l’historique des instances, etc. Cet article détaille toutes les opérations de gestion des instances prises en charge.

Démarrer les 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 via le fournisseur de stockage Durable Functions , puis retourne. Ce message déclenche de façon asynchrone le début 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 :

• Nom : nom de la fonction d’orchestrateur à planifier.
• Entrée : toutes les données JSON sérialisables qui doivent être transmises en tant qu’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 / Astuce

Utilisez un identificateur aléatoire pour l’ID d’instance dans la mesure du possible. Les ID d’instance aléatoire permettent de garantir une distribution de charge égale lorsque vous mettant à l’échelle les fonctions d’orchestrateur sur plusieurs machines virtuelles. Le temps approprié d’utiliser des ID d’instance non aléatoires est le moment où l’ID doit provenir d’une source externe ou lorsque vous implémentez le modèle d’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}'.");
}

Remarque

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

JavaScript

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

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
}

Remarque

Cet exemple cible Durable Functions version 2.x. Dans la version 1.x, utilisez orchestrationClient plutôt durableClientque .

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 la function.jsonsuivante.

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
}

Remarque

Cet exemple cible Durable Functions version 2.x. Dans la version 1.x, utilisez orchestrationClient plutôt durableClientque .

__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 la function.jsonsuivante.

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
}

Remarque

Cet exemple cible Durable Functions version 2.x. Dans la version 1.x, utilisez orchestrationClient plutôt durableClientque .

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 Outils Principaux

Vous pouvez également démarrer une instance directement à l’aide de la func durable start-new commande dans Core Tools, qui prend les paramètres suivants :

• function-name (obligatoire) : nom de la fonction à démarrer.
• input (facultatif) : Entrée dans la fonction, inline ou via un fichier JSON. Pour les fichiers, ajoutez un préfixe au chemin d’accès au 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 définir cette valeur dans host.json à l’aide de durableTask :HubName.

Remarque

Les commandes Core Tools supposent que vous les exécutez à 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. Bien que vous puissiez exécuter ces commandes sans hôte d’application de fonction en cours d’exécution, vous pouvez constater que vous ne pouvez pas observer certains effets, sauf si l’hôte est en cours d’exécution. Par exemple, la start-new commande met en file d’attente un message de démarrage dans le hub de tâches cible, mais l’orchestration ne s’exécute pas réellement, sauf s’il existe un processus hôte d’application de fonction en cours d’exécution qui peut traiter le message.

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

La commande suivante démarre la fonction nommée HelloWorld et transmet le contenu du fichier counter-data.json à celui-ci :

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

Interroger des instances

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

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

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

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

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

• Nom : nom de la fonction d’orchestrateur.
• 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 à laquelle l’orchestration a effectué le dernier point de contrôle.
• Entrée : entrée de la fonction sous forme de valeur JSON. Ce champ n’est pas renseigné s’il showInput a la valeur false.
• CustomStatus : état d’orchestration personnalisé au format JSON.
• Sortie : sortie de la fonction sous forme de valeur JSON (si la fonction est terminée). Si la fonction d’orchestrateur a échoué, cette propriété inclut les détails de l’échec. Si la fonction d’orchestrateur a été suspendue ou arrêtée, cette propriété inclut la raison de la suspension ou de l’arrêt (le cas échéant).
• RuntimeStatus : une des valeurs suivantes :
  • En attente : l’instance a été planifiée mais n’a pas encore démarré.
  • En cours d’exécution : l’instance a commencé à s’exécuter.
  • Terminé : l’instance s’est terminée normalement.
  • ContinuedAsNew : l’instance a redémarré avec un nouvel historique. Cet état est un état temporaire.
  • Échec : l’instance a échoué avec une erreur.
  • Terminé : l’instance a été arrêtée brusquement.
  • Suspendu : l’instance a été suspendue et peut être reprise ultérieurement.
• L’historique : l’historique d’exécution de l’orchestration. Ce champ est renseigné uniquement si showHistory est défini sur true.

Remarque

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

Remarque

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

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 de la configuration 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 Outils Principaux

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

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

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 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 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. 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. Il peut également être défini 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 un ID d’instance d’orchestration 0ab8c55a6644d68a3a8b220b12d209c. Il part du principe que vous exécutez la func commande à 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 durable get-history commande 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. 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. Il peut également être défini 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 d’orchestration correspondant aux paramètres de 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.
}

Remarque

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

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 de la configuration 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 de la configuration function.json.

PowerShell

Remarque

Cette fonctionnalité n’est actuellement pas prise en charge dans PowerShell, mais 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 Outils Principaux

Il est également possible d’interroger des instances directement à l’aide de la func durable get-instances commande dans Core Tools.

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

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 requête. La valeur par défaut est de 10.
• continuation-token (facultatif) : jeton pour indiquer la page ou la section des instances à récupérer. Chaque get-instances exécution retourne un jeton au jeu d’instances suivant.
• 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. Il peut également être défini dans host.json, à l’aide de durableTask :HubName.

func durable get-instances

Interroger des instances avec des filtres

Que se passe-t-il si vous n’avez pas vraiment besoin de toutes les informations qu’une requête d’instance standard peut fournir ? Par exemple, que se passe-t-il si vous recherchez simplement le temps de création de l’orchestration ou l’état du runtime d’orchestration ? 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));
    }
}

Remarque

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

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 de la configuration 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

Remarque

Cette fonctionnalité n’est actuellement pas prise en charge dans PowerShell, mais 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 Outils Principaux

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

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

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

• created-after (facultatif) : Récupérez les instances créées après cette date/heure (UTC). Les datetimes au format ISO 8601 sont acceptées.
• created-before (facultatif) : Récupérez les instances créées avant cette date/heure (UTC). Les datetimes 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ée). Peut fournir plusieurs états (séparés par l’espace).
• top (facultatif) : nombre d’instances récupérées par requête. La valeur par défaut est de 10.
• continuation-token (facultatif) : jeton pour indiquer la page ou la section des instances à récupérer. Chaque get-instances exécution retourne un jeton au jeu d’instances suivant.
• 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. Il peut également être défini dans host.json, à l’aide de durableTask :HubName.

Si vous ne fournissez aucun filtre (created-after, created-beforeou runtime-status), la commande récupère simplement les top instances, sans tenir compte de l’état du runtime 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

Terminer les instances

Si vous disposez d’une instance d’orchestration qui prend trop de temps pour s’exécuter, ou si vous devez simplement l’arrêter pour une raison quelconque, vous pouvez l’arrêter.

Les deux paramètres de l’API de fin 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);
}

Remarque

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

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 de la configuration 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 instance terminée va finir par passer à l’état Terminated . Toutefois, cette transition 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 de requête d’instance pour savoir quand une instance terminée a atteint l’état Terminated .

Remarque

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

Suspendre une orchestration vous permet de mettre en pause 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)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // To resume an orchestration
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

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

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

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

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)

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

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

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

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

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

Remarque

Cette fonctionnalité est disponible uniquement dans le Kit de développement logiciel (SDK) PowerShell Durable Functions autonome. Découvrez la différence entre le KIT de développement logiciel (SDK) autonome et le SDK intégré hérité, ainsi que le guide de migration.

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

    // To suspend an orchestration
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // To resume an orchestration
    String resumeReason = "Continue workflow";
    client.resumeInstance(instanceID, resumeReason);
}

Une instance suspendue finira par passer à l’état Suspended . Toutefois, cette transition 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 de requête d’instance pour savoir quand une instance en cours d’exécution a atteint l’état suspendu.

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

Azure Functions Outils Principaux

Vous pouvez également mettre fin directement à une instance d’orchestration à l’aide de la func durable terminate commande dans Core Tools.

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

La commande durable terminate utilise les paramètres suivants :

• id (obligatoire) : ID de l’instance d’orchestration à terminer.
• reason (facultatif) : Motif de l’arrêt.
• 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. Il peut également être défini dans host.json, à l’aide de durableTask :HubName.

La commande suivante met fin à une instance d’orchestration avec un ID de 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. Exemples de scénarios où cela est utile incluent les scénarios de surveillance et d’interaction humaine .

Vous pouvez envoyer des notifications d’événements à des instances en cours d’exécution à l’aide de l’API déclencher l’événement du client d’orchestration. 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 l’événement de levée sont les suivants :

• ID d’instance : ID unique de l’instance.
• Nom de l’événement : nom de l’événement à envoyer.
• Données d’événement : charge utile sérialisable JSON à 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);
}

Remarque

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

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 de la configuration 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);
}

Remarque

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, l’événement est stocké dans l’état de l’instance jusqu’à ce qu’il soit prêt à être reçu et traité.

Azure Functions Outils Principaux

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

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

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 du chemin d’accès à un fichier JSON, ou vous pouvez 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. 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. Il peut également être défini 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 « attendre l’achèvement ou créer une réponse d’état de vérification » 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 de la configuration 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

Remarque

PowerShell n’a actuellement 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 2 secondes pour le délai d’expiration et 0,5 seconde pour l’intervalle de nouvelle tentative :

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

Remarque

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 :

• Les instances d’orchestration se terminent dans le délai d’expiration défini (dans ce cas 2 secondes) et la réponse est la sortie réelle de l’instance d’orchestration, 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 se terminer dans le délai d’expiration défini et la réponse est celle par défaut décrite dans la découverte d’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}"
}

Remarque

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

Récupérer les URL de gestion de webhook 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 de webhook qui font partie de la réponse par défaut décrite dans la découverte d’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 de création de charge utile de gestion HTTP peut être utilisée pour récupérer un objet sérialisable contenant ces URL de webhook.

L’API créer une charge utile de gestion HTTP a un paramètre :

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

Les méthodes retournent 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 : URL d’état de l’instance d’orchestration.
• SendEventPostUri : URL « déclencher un événement » de l’instance de l’orchestration.
• TerminatePostUri : URL « terminate » de l’instance d’orchestration.
• PurgeHistoryDeleteUri : URL « historique de purge » de l’instance d’orchestration.
• suspendPostUri : URL « suspend » de l’instance d’orchestration.
• resumePostUri : URL « resume » de l’instance d’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 };
}

Remarque

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

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 de la configuration 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

Remarque

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

Rembobiner des instances (préversion)

Si vous avez une panne d’orchestration pour une raison inattendue, vous pouvez réinitialiser l’instance à un état antérieur sain en utilisant une API conçue à cet effet.

Remarque

Cette API n’est pas destinée à remplacer la gestion des erreurs et les stratégies de nouvelle tentative appropriées. Il est plutôt destiné à être utilisé uniquement 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 plus d’informations sur la gestion des erreurs et les stratégies de nouvelle tentative, consultez l’article de gestion des erreurs .

Utilisez la méthode RewindAsync (.NET) ou rewind (JavaScript) de la liaison du client d’orchestration pour remettre l’orchestration dans l’état d'exécution. 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 disposez d’un flux de travail impliquant une série d’approbations humaines. Supposons qu’il existe une série de fonctions d’activité qui informent quelqu’un que leur approbation est nécessaire et attendent 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'une configuration incorrecte de l'application, comme une chaîne de connexion à une base de données invalide. Le résultat est une défaillance d’orchestration approfondie dans le flux de travail. Avec l’API RewindAsync (.NET) ou rewind (JavaScript), un administrateur d’application peut corriger l’erreur de configuration et rembobiner l’orchestration ayant échoué vers l’état immédiatement avant l’échec. Aucune des étapes d’interaction humaine n’a besoin d’être révalidée, et l’orchestration peut maintenant se terminer avec succès.

Remarque

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

Remarque

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

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 de la configuration function.json.

Python

Remarque

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

PowerShell

Remarque

Cette fonctionnalité n’est actuellement pas prise en charge dans PowerShell.

Java

Remarque

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

Azure Functions Outils Principaux

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

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

La commande durable rewind utilise les paramètres suivants :

• id (obligatoire) : ID de l’instance d’orchestration.
• reason (facultatif) : Raison de la réinitialisation de l’instance d’orchestration.
• 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. 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."

Purger 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 supprimer toutes les ressources de stockage associées à une instance terminée. Pour ce faire, utilisez l’API d’instance de vidage 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 de la configuration 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

Remarque

Cette fonctionnalité n’est actuellement pas prise en charge dans PowerShell, mais 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 montre une fonction déclenchée par un minuteur qui purge l’historique de toutes les instances d’orchestration qui se sont terminées après l’intervalle de temps spécifié. Dans ce cas, il supprime les données de toutes les instances terminées il y a 30 jours ou plus. Cet exemple de fonction est planifié pour s’exécuter une fois par jour, à 12 h 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
        });
}

Remarque

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

JavaScript

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

function.json

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

Remarque

Cet exemple cible Durable Functions version 2.x. Dans la version 1.x, utilisez orchestrationClient plutôt durableClientque .

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

Remarque

Cette fonctionnalité n’est actuellement pas prise en charge dans PowerShell, mais 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()));
}

Remarque

Pour que l’opération d’historique de vidage réussisse, l’état d’exécution de l’instance cible doit être terminé, terminé ou échoué.

Azure Functions Outils Principaux

Vous pouvez vider l’historique d’une instance d’orchestration à l’aide de la func durable purge-history commande dans Core Tools. Comme pour le deuxième exemple C# de la section précédente, il purge l’historique de toutes les instances d’orchestration créées pendant un intervalle de temps spécifié. Vous pouvez filtrer d’autres instances vidées en fonction de l’état du runtime.

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

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

• created-after (facultatif) : videz l’historique des instances créées après cette date/heure (UTC). Les datetimes au format ISO 8601 sont acceptées.
• created-before (facultatif) : videz l’historique des instances créées avant cette date/heure (UTC). Les datetimes au format ISO 8601 sont acceptées.
• runtime-status (facultatif) : videz l’historique des instances avec un état particulier (par exemple, en cours d’exécution ou terminé). Peut fournir plusieurs états (séparés par l’espace).
• 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. 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 ayant échoué créées avant le 14 novembre 2021 à 17h35 (UTC).

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 func durable delete-task-hub commande dans Core Tools, vous pouvez supprimer tous les artefacts de stockage associés à un hub de tâches particulier, notamment les tables de stockage Azure, les files d’attente et les objets blob.

Remarque

Les commandes Core Tools sont actuellement uniquement prises en charge lors de l’utilisation du fournisseur de stockage Azure par défaut pour conserver l’état d’exécution.

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

• 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. 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 UserTest hub de tâches.

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

Étapes suivantes

Découvrez comment gérer le contrôle de version

Informations de référence sur l’API HTTP intégrées pour la gestion des instances