Gestionar instancias de orquestación

Las orquestaciones son flujos de trabajo con estado de ejecución prolongada que se pueden iniciar, consultar, suspender, reanudar y finalizar mediante las API de administración integradas. En Durable Functions, el enlace de cliente de orchestration expone estas API. En los SDK de Durable Task, estas operaciones están disponibles a través de la clase . En este artículo se tratan todas las operaciones de administración de instancias admitidas para ambas plataformas.

Sugerencia

La Azure Durable Task Scheduler es el back-end recomendado para Durable Functions y los SDK de Durable Task, lo que proporciona una experiencia totalmente administrada y sin servidor para ejecutar flujos de trabajo duraderos a escala.

Inicio de instancias

El método start-new (o schedule-new) en el cliente de orquestación inicia una nueva instancia de orquestación. Internamente, este método escribe un mensaje en el backend configurado (como el Durable Task Scheduler o Azure Storage) y luego devuelve. Este mensaje desencadena de forma asincrónica el inicio de una orquestación con el nombre especificado.

Estos son los parámetros para iniciar una nueva instancia de orquestación:

Name: el nombre de la función de orquestador que programar.
Entrada: cualquier dato serializable json que se debe pasar como entrada a la función de orquestador.
InstanceId: (Opcional) El identificador único de la instancia. Si no especifica este parámetro, el método usa un identificador aleatorio.

Sugerencia

Use un identificador aleatorio para el identificador de instancia siempre que sea posible. Los identificadores de instancia aleatorios ayudan a garantizar una distribución de carga igual al escalar las funciones de orquestador en varias máquinas virtuales. El momento adecuado para usar identificadores de instancia no aleatorios es cuando el identificador procede de un origen externo o cuando se implementa el patrón de orquestador singleton.

Nombre: El nombre de la orquestación que se va a programar.
Entrada: cualquier dato serializable por JSON que se debe pasar como entrada a la orquestación.
InstanceId: (Opcional) El identificador único de la instancia. Si no especifica este parámetro, el método usa un identificador aleatorio.

Sugerencia

Use un identificador aleatorio para el identificador de instancia siempre que sea posible. Los identificadores de instancia aleatorios ayudan a garantizar una distribución de carga igual al escalar orquestaciones entre varias máquinas virtuales. El momento adecuado para usar identificadores de instancia no aleatorios es cuando el identificador procede de un origen externo o cuando se implementa el patrón de orquestador singleton.

La siguiente función de ejemplo inicia una nueva instancia de orquestación:

C#
JavaScript
Python
PowerShell
Java

[FunctionName("HelloWorldQueueTrigger")]
public static async Task Run(
    [QueueTrigger("start-queue")] string input,
    [DurableClient] IDurableOrchestrationClient starter,
    ILogger log)
{
    string instanceId = await starter.StartNewAsync("HelloWorld", input);
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
}

Nota:

El código de C# anterior es para Durable Functions 2.x. Para Durable Functions 1.x, use el atributo en lugar del atributo /> en lugar de . Para obtener más información sobre las diferencias entre versiones, vea Durable Functions versiones.

A menos que se especifique lo contrario, los ejemplos de esta página usan el desencadenador HTTP con el siguiente function.json.

function.json

{
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Nota:

Este ejemplo tiene como destino Durable Functions versión 2.x. En la versión 1.x, use en lugar de .

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

A menos que se especifique lo contrario, los ejemplos de esta página usan el desencadenador HTTP con el siguiente function.json.

function.json

{
  "scriptFile": "__init__.py",
  "bindings": [    
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Nota:

Este ejemplo tiene como destino Durable Functions versión 2.x. En la versión 1.x, use en lugar de .

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

A menos que se especifique lo contrario, los ejemplos de esta página usan el desencadenador HTTP con el siguiente function.json.

function.json

{
  "bindings": [    
    {
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "Response",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

Nota:

Este ejemplo tiene como destino Durable Functions versión 2.x. En la versión 1.x, use en lugar de .

run.ps1

param($Request, $TriggerMetadata)

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

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

Para esperar a que el orquestador se inicie antes de regresar desde su función, use el método.

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

Importante

Actualmente, el SDK de Durable Task de PowerShell no está disponible.

En el código siguiente se muestra cómo iniciar una nueva instancia de orquestación mediante los SDK de Durable Task:

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Schedule a new orchestration instance
string instanceId = await client.ScheduleNewOrchestrationInstanceAsync("HelloWorld", input);
Console.WriteLine($"Started orchestration with ID = '{instanceId}'.");

// Optionally, wait for the orchestration to start
OrchestrationMetadata metadata = await client.WaitForInstanceStartAsync(instanceId, timeout: TimeSpan.FromSeconds(30));

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Schedule a new orchestration instance
instance_id = client.schedule_new_orchestration(hello_world, input=input_data)
print(f"Started orchestration with ID = '{instance_id}'.")

# Optionally, wait for the orchestration to start
state = client.wait_for_orchestration_start(instance_id, timeout=30)

import com.microsoft.durabletask.DurableTaskClient;

// Schedule a new orchestration instance
String instanceId = client.scheduleNewOrchestrationInstance("HelloWorld", input);
System.out.println("Started orchestration with ID = '" + instanceId + "'.");

// Optionally, wait for the orchestration to start
OrchestrationMetadata metadata = client.waitForInstanceStart(instanceId, Duration.ofSeconds(30), false);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Schedule a new orchestration instance
const instanceId = await client.scheduleNewOrchestration("HelloWorld", input);
console.log(`Started orchestration with ID = '${instanceId}'.`);

// Optionally, wait for the orchestration to start
const state = await client.waitForOrchestrationStart(instanceId, false, 30);

Consulta de instancias

Después de iniciar nuevas instancias de orquestación, lo más probable es que tenga que consultar sus estados en tiempo de ejecución para saber si se están ejecutando, han completado o han fallado.

El método get-status del cliente de orquestación devuelve el estado de una instancia de orquestación.

Toma (obligatorio), (opcional), (opcional) y (opcional) como parámetros.

: si se establece en , la respuesta contiene el historial de ejecución.
: si se establece en , el historial de ejecución contiene salidas de actividad.
: si se establece en , la respuesta no contiene la entrada de la función. El valor predeterminado es .

El método devuelve un objeto con las siguientes propiedades:

Nombre: el nombre de la función de orquestación.
InstanceId: el identificador de instancia de la orquestación (debe ser el mismo que la entrada).
CreatedTime: hora en la que se inicia la ejecución de la función de orquestador.
LastUpdatedTime: La hora en que la orquestación realizó el último registro de los puntos de control.
Entrada: entrada de la función como un valor JSON. Este campo no se rellena si es .
CustomStatus: estado de orquestación personalizada en formato JSON.
Salida: la salida de la función como un valor JSON (si se completa la función). Si se produce un error en la función de orquestador, esta propiedad incluye los detalles del error. Si la función de orquestador está suspendida o terminada, esta propiedad incluye el motivo de la suspensión o finalización (si existe).
RuntimeStatus: uno de los siguientes valores:
- Pendiente: la instancia está programada, pero aún no se ha iniciado la ejecución.
- En ejecución: la instancia se está ejecutando.
- Completado: la instancia se completó normalmente.
- ContinuedAsNew: la instancia se ha reiniciado con un nuevo historial. Este estado es un estado transitorio.
- Fallido: La instancia falló con un error.
- Finalizado: la instancia se detuvo abruptamente.
- Suspendido: la instancia se suspende y se puede reanudar en un momento posterior.
History: el historial de ejecución de la orquestación. Este campo solo se rellena si se establece en .

: si se establece en , la respuesta contiene el historial de ejecución.
: si se establece en , el historial de ejecución contiene salidas de actividad.
: si se establece en , la respuesta no contiene la entrada de la orquestación. El valor predeterminado es .

El método devuelve un objeto con las siguientes propiedades:

Nombre: nombre de la orquestación.
InstanceId: el identificador de instancia de la orquestación (debe ser el mismo que la entrada).
CreatedTime: hora en la que se inicia la ejecución de la orquestación.
LastUpdatedTime: La hora en que la orquestación realizó el último registro de los puntos de control.
Entrada: entrada de la orquestación como un valor JSON. Este campo no se rellena si es .
CustomStatus: estado de orquestación personalizada en formato JSON.
Salida: la salida de la orquestación como un valor JSON (si se completa la orquestación). Si se produce un error en la orquestación, esta propiedad incluye los detalles del error. Si la orquestación se suspende o finaliza, esta propiedad incluye el motivo de la suspensión o finalización (si existe).
RuntimeStatus: uno de los siguientes valores:
- Pendiente: la instancia está programada, pero aún no se ha iniciado la ejecución.
- En ejecución: la instancia se está ejecutando.
- Completado: la instancia se completó normalmente.
- ContinuedAsNew: la instancia se ha reiniciado con un nuevo historial. Este estado es un estado transitorio.
- Fallido: La instancia falló con un error.
- Finalizado: la instancia se detuvo abruptamente.
- Suspendido: la instancia se suspende y se puede reanudar en un momento posterior.
History: el historial de ejecución de la orquestación. Este campo solo se rellena si se establece en .

Nota:

Un orquestador no está marcado como hasta que finalicen todas sus tareas programadas y el orquestador vuelva. En otras palabras, no es suficiente que un orquestador llegue a su instrucción para que se marque como . Esto es especialmente relevante para los casos en los que se usa; esos orquestadores a menudo antes de que se ejecuten todas las tareas programadas.

Este método devuelve null (.NET y Java), undefined (JavaScript) o None (Python) si la instancia no existe.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("GetStatus")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("check-status-queue")] string instanceId)
{
    DurableOrchestrationStatus status = await client.GetStatusAsync(instanceId);
    // do something based on the current status.
}

Nota:

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

Para la configuración de function.json, consulte Iniciar instancias.

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

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

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Get the status of an orchestration instance
OrchestrationMetadata? metadata = await client.GetInstanceAsync(instanceId, getInputsAndOutputs: true);
if (metadata != null)
{
    OrchestrationRuntimeStatus status = metadata.RuntimeStatus;
    // do something based on the current status
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Get the status of an orchestration instance
state = client.get_orchestration_state(instance_id, fetch_payloads=True)
if state is not None:
    status = state.runtime_status
    # do something based on the current status

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationMetadata;

// Get the status of an orchestration instance
OrchestrationMetadata metadata = client.getInstanceMetadata(instanceId, true);
if (metadata != null) {
    OrchestrationRuntimeStatus status = metadata.getRuntimeStatus();
    // do something based on the current status
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Get the status of an orchestration instance
const state = await client.getOrchestrationState(instanceId, true);
if (state) {
    const status = state.runtimeStatus;
    // do something based on the current status
}

Consultar todas las instancias

Puede usar las API en el SDK de lenguaje para consultar los estados de todas las instancias de orquestación en el centro de tareas. Esta API "list-instances" o "get-status" devuelve una lista de objetos que representan las instancias de orquestación que coinciden con los parámetros de consulta.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("GetAllStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    var noFilter = new OrchestrationStatusQueryCondition();
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        noFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }

    // Note: ListInstancesAsync only returns the first page of results.
    // To request additional pages provide the result.ContinuationToken
    // to the OrchestrationStatusQueryCondition's ContinuationToken property.
}

Nota:

El código de C# anterior es para Durable Functions 2.x. Para Durable Functions 1.x, debe usar OrchestrationClient atributo en lugar del atributo DurableClient y debe usar el tipo de parámetro DurableOrchestrationClient en lugar de IDurableOrchestrationClient. Para obtener más información sobre las diferencias entre versiones, consulte el artículo Durable Functions versiones.

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

Para la configuración de function.json, véase Start instances.

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

Para obtener la configuración de function.json, consulte Start instances.

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Query all orchestration instances
AsyncPageable<OrchestrationMetadata> instances = client.GetAllInstancesAsync(new OrchestrationQuery());

await foreach (OrchestrationMetadata instance in instances)
{
    Console.WriteLine(instance.InstanceId);
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Query all orchestration instances
instances = client.list_orchestrations()

for instance in instances:
    print(instance.instance_id)

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationStatusQuery;
import com.microsoft.durabletask.OrchestrationStatusQueryResult;

// Query all orchestration instances
OrchestrationStatusQuery query = new OrchestrationStatusQuery();
OrchestrationStatusQueryResult result = client.queryInstances(query);

for (OrchestrationMetadata instance : result.getOrchestrationState()) {
    System.out.println(instance.getInstanceId());
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Query all orchestration instances
const instances = client.getAllInstances();

for await (const instance of instances) {
    console.log(instance.instanceId);
}

Consulta de instancias con filtros

¿Qué ocurre si no necesita toda la información que proporciona una consulta de instancia estándar? Por ejemplo, ¿qué ocurre si solo busca la hora de creación de la orquestación o el estado del tiempo de ejecución de la orquestación? Restrinja la consulta aplicando filtros.

C#
JavaScript
Python
PowerShell
Java

[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 days ago
    var queryFilter = new OrchestrationStatusQueryCondition
    {
        RuntimeStatus = new[]
        {
            OrchestrationRuntimeStatus.Pending,
            OrchestrationRuntimeStatus.Running,
        },
        CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
        CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
        PageSize = 100,
    };

    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        queryFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
}

Nota:

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

Consulte Instancias de inicio para la configuración del archivo function.json.

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

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Get running or pending instances created in the last 7 days
var query = new OrchestrationQuery
{
    Statuses = new[] { OrchestrationRuntimeStatus.Running, OrchestrationRuntimeStatus.Pending },
    CreatedFrom = DateTime.UtcNow.AddDays(-7),
    CreatedTo = DateTime.UtcNow.AddDays(-1),
    PageSize = 100
};

AsyncPageable<OrchestrationMetadata> instances = client.GetAllInstancesAsync(query);

await foreach (OrchestrationMetadata instance in instances)
{
    Console.WriteLine($"{instance.InstanceId}: {instance.RuntimeStatus}");
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from datetime import datetime, timedelta

# Get running or pending instances created in the last 7 days
instances = client.list_orchestrations(
    created_time_from=datetime.utcnow() - timedelta(days=7),
    created_time_to=datetime.utcnow() - timedelta(days=1),
    runtime_status=['RUNNING', 'PENDING']
)

for instance in instances:
    print(f"{instance.instance_id}: {instance.runtime_status}")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationStatusQuery;
import com.microsoft.durabletask.OrchestrationRuntimeStatus;
import java.time.Duration;
import java.time.Instant;
import java.util.List;

// Get running or pending instances created in the last 7 days
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);

for (OrchestrationMetadata instance : result.getOrchestrationState()) {
    System.out.println(instance.getInstanceId() + ": " + instance.getRuntimeStatus());
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

// Get running or pending instances created in the last 7 days
const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);

const instances = client.getAllInstances({
    statuses: [OrchestrationStatus.RUNNING, OrchestrationStatus.PENDING],
    createdFrom: sevenDaysAgo,
    createdTo: oneDayAgo,
});

for await (const instance of instances) {
    console.log(`${instance.instanceId}: ${instance.runtimeStatus}`);
}

Finalización de instancias

Si tiene una instancia de orquestación que tarda demasiado tiempo en ejecutarse o necesita detenerla antes de que se complete por cualquier motivo, puede finalizarla.

Los dos parámetros de la API de terminación son un identificador de instancia y una cadena de razones, que escriben en los registros y en el estado de la instancia.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("TerminateInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("terminate-queue")] string instanceId)
{
    string reason = "Found a bug";
    return client.TerminateAsync(instanceId, reason);
}

Nota:

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

Consulte Instancias de inicio para la configuración del archivo function.json.

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)

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

string reason = "Found a bug";
await client.TerminateInstanceAsync(instanceId, reason);

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

reason = "Found a bug"
client.terminate_orchestration(instance_id, reason=reason)

import com.microsoft.durabletask.DurableTaskClient;

String reason = "Found a bug";
client.terminate(instanceId, reason);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

const reason = "Found a bug";
await client.terminateOrchestration(instanceId, reason);

Una instancia terminada finalmente pasa al estado. Pero esta transición no se produce inmediatamente. En su lugar, la operación de finalización se pone en cola en el hub de tareas junto con otras operaciones para esa instancia. Puede usar las API de consulta de instancia para saber cuándo una instancia terminada ha alcanzado realmente el estado .

Nota:

La finalización de la instancia no se propaga actualmente. Las funciones de actividad y las suborquestaciones se ejecutan hasta completarse, independientemente de si finaliza la instancia de orquestación que las llamó.

Suspender y reanudar instancias

Suspender una orquestación le permite detener una orquestación en ejecución. A diferencia de finalizar una orquestación, puede reanudar una orquestación suspendida más adelante.

Los dos parámetros de la API de suspensión son un identificador de instancia y una cadena de motivo, que se escriben en los registros y en el estado de la instancia.

C#
JavaScript
Python
PowerShell
Java

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

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

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)

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

Nota:

Esta característica solo está disponible en el SDK de PowerShell independiente Durable Functions. Consulte la diferencia entre el SDK independiente y el SDK integrado heredado junto con la guía de migración.

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

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

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

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

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

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

import com.microsoft.durabletask.DurableTaskClient;

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

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// To suspend an orchestration
await client.suspendOrchestration(instanceId);

// To resume an orchestration
await client.resumeOrchestration(instanceId);

Una instancia suspendida finalmente realiza la transición al estado. Sin embargo, esta transición no se produce inmediatamente. En su lugar, la operación de suspensión se pone en cola en el hub de tareas junto con otras operaciones para esa instancia. Use las API de consulta de instancia para saber cuándo una instancia en ejecución ha alcanzado realmente el estado .

Cuando se reanuda un orquestador suspendido, su estado cambia de nuevo a su estado anterior.

Envío de eventos a instancias

En algunos escenarios, las funciones de orquestador deben esperar y escuchar eventos externos. Entre los ejemplos en los que este enfoque es útil se incluyen los escenarios de supervisión e interacción humana .

En algunos escenarios, las orquestaciones deben esperar y escuchar eventos externos. Entre los ejemplos en los que este enfoque es útil se incluyen los escenarios de supervisión e interacción humana .

Puede enviar notificaciones de eventos a instancias en ejecución mediante la API de generar eventos del cliente de orquestación. Las orquestaciones pueden escuchar y responder a estos eventos mediante la API de orquestador de esperar a evento externo.

Los parámetros para el evento 'raise' son:

Id. de instancia: identificador único de la instancia.
Nombre del evento: nombre del evento que se va a enviar.
Datos de eventos: una carga serializable en JSON para enviar a la instancia.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("RaiseEvent")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("event-queue")] string instanceId)
{
    int[] eventData = new int[] { 1, 2, 3 };
    return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}

Nota:

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

Consulte Instancias de inicio para la configuración del archivo function.json.

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)

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

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

int[] eventData = new int[] { 1, 2, 3 };
await client.RaiseEventAsync(instanceId, "MyEvent", eventData);

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

event_data = [1, 2, 3]
client.raise_orchestration_event(instance_id, "MyEvent", event_data)

import com.microsoft.durabletask.DurableTaskClient;

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

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

const eventData = [1, 2, 3];
await client.raiseOrchestrationEvent(instanceId, "MyEvent", eventData);

Nota:

Si no hay ninguna instancia de orquestación con el identificador de instancia especificado, se descarta el mensaje de evento. Si existe una instancia, pero aún no está esperando el evento, el evento se almacena en el estado de la instancia hasta que esté listo para recibirse y procesarse.

Esperar a que finalice la orquestación

En orquestaciones de larga duración, es posible que desees esperar para obtener los resultados de una orquestación específica. En estos casos, también es útil definir un período de tiempo de espera en la orquestación. Si se supera el tiempo de espera, se devuelve el estado de la orquestación en lugar de los resultados.

Utilice el API "esperar a la finalización o crear respuesta de estado de comprobación" para obtener de forma sincrónica la salida real de una instancia de orquestación. De forma predeterminada, este método tiene un tiempo de espera de diez segundos y un intervalo de sondeo de un segundo.

Esta es una función de desencadenador HTTP de ejemplo que muestra cómo usar esta API:

C#
JavaScript
Python
PowerShell
Java

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

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

Consulte Instancias de inicio para la configuración del archivo function.json.

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

Java no tiene actualmente un único método para este escenario, pero puede implementarlo con algunas líneas de código adicionales.

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

Los SDK de Durable Task proporcionan un método para esperar a que una orquestación finalice sincrónicamente.

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Wait for orchestration to complete with a timeout
OrchestrationMetadata metadata = await client.WaitForInstanceCompletionAsync(
    instanceId,
    timeout: TimeSpan.FromSeconds(30),
    getInputsAndOutputs: true);

if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Completed)
{
    Console.WriteLine($"Output: {metadata.SerializedOutput}");
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Wait for orchestration to complete with a timeout
state = client.wait_for_orchestration_completion(
    instance_id,
    timeout=30,
    fetch_payloads=True)

if state.runtime_status == 'COMPLETED':
    print(f"Output: {state.serialized_output}")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationMetadata;
import java.time.Duration;
import java.util.concurrent.TimeoutException;

// Wait for orchestration to complete with a timeout
try {
    OrchestrationMetadata metadata = client.waitForInstanceCompletion(
            instanceId,
            Duration.ofSeconds(30),
            true /* getInputsAndOutputs */);
    System.out.println("Output: " + metadata.getSerializedOutput());
} catch (TimeoutException e) {
    System.out.println("Orchestration did not complete within timeout");
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

// Wait for orchestration to complete with a timeout
const state = await client.waitForOrchestrationCompletion(instanceId, true, 30);

if (state?.runtimeStatus === OrchestrationStatus.COMPLETED) {
    console.log(`Output: ${state.serializedOutput}`);
}

Utilice la función con la siguiente línea. Use dos segundos para el tiempo de espera y 0,5 segundos para el intervalo de reintento:

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

Nota:

El comando cURL anterior supone que tiene una función de orquestador denominada en el proyecto. Debido a cómo se escribe la función de desencadenador HTTP, puede reemplazarla por el nombre de cualquier función de orquestador del proyecto.

Dependiendo del tiempo necesario para obtener la respuesta de la instancia de orquestación, existen dos casos:

Las instancias de orquestación finalizan dentro del tiempo de espera definido (en este caso, dos segundos) y la respuesta es la salida de la instancia de orquestación real, entregada de forma sincrónica:

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

Las instancias de orquestación no pueden finalizar dentro del tiempo de espera definido y la respuesta es la que está predeterminada como se describe en descubrimiento de URL de API HTTP.

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:13:51 GMT
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
Retry-After: 10
Transfer-Encoding: chunked

{
    "id": "d3b72dddefce4e758d92f4d411567177",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/suspend?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/resume?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
}

Nota:

El formato de las direcciones URL del webhook puede diferir, en función de la versión del host de Azure Functions que ejecute. El ejemplo anterior es para el host de Azure Functions 3.0.

Recuperación de las direcciones URL del webhook de administración de HTTP

Utilice un sistema externo para monitorizar o generar eventos en una orquestación. Los sistemas externos se comunican con Durable Functions a través de las direcciones URL de webhook que forman parte de la respuesta predeterminada descrita en detección de direcciones URL de APIHTTP. Las direcciones URL del webhook son accesibles programáticamente mediante la vinculación del cliente de orquestación. En concreto, la API de carga de administración HTTP crea un objeto serializable que contiene estas direcciones URL de webhook.

La API create HTTP management payload tiene un parámetro:

Id. de instancia: identificador único de la instancia.

Los métodos devuelven un objeto con las siguientes propiedades de cadena:

Id. : el identificador de instancia de la orquestación (debe ser el mismo que la entrada).
StatusQueryGetUri: la dirección URL de estado de la instancia de orquestación.
SendEventPostUri: La dirección URL para generar evento de la instancia de orquestación.
TerminatePostUri: la dirección URL de generación del evento de la instancia de orquestación.
PurgeHistoryDeleteUri: la dirección URL del "historial de purga" de la instancia de orquestación.
SuspendPostUri: la URL de suspensión de la instancia de orquestación.
ResumePostUri: la dirección URL "resume" de la instancia de orquestación.

Las funciones envían instancias de estos objetos a sistemas externos para supervisar o generar eventos en las orquestaciones correspondientes, como se muestra en los ejemplos siguientes.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("SendInstanceInfo")]
public static void SendInstanceInfo(
    [ActivityTrigger] IDurableActivityContext ctx,
    [DurableClient] IDurableOrchestrationClient client,
    [CosmosDB(
        databaseName: "MonitorDB",
        containerName: "HttpManagementPayloads",
        Connection = "CosmosDBConnectionSetting")]out dynamic document)
{
    HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);

    // send the payload to Azure Cosmos DB
    document = new { Payload = payload, id = ctx.InstanceId };
}

Nota:

El código de C# anterior es para Durable Functions 2.x. Para Durable Functions 1.x, use DurableActivityContext en lugar de IDurableActivityContext, use el atributo OrchestrationClient en lugar del atributo DurableClient y use el tipo de parámetro DurableOrchestrationClient en lugar de IDurableOrchestrationClient. Para obtener más información sobre las diferencias entre versiones, consulte el artículo Durable Functions versiones.

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

Consulte Instancias de inicio para la configuración del archivo function.json.

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

using namespace System.Net

param($Request, $TriggerMetadata)

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

Retroceso de instancias

Si tiene un error de orquestación por un motivo inesperado, restaure la instancia a un estado correcto anteriormente mediante una API diseñada para ese propósito.

Nota:

Esta API no está pensada para reemplazar las directivas de control de errores y reintento adecuadas. En su lugar, está pensado para usarse solo en los casos en los que las instancias de orquestación fallen por razones inesperadas. Las orquestaciones en estados diferentes a (por ejemplo, , , u ) no pueden ser «rebobinadas». Para obtener más información sobre el control de errores y las directivas de reintento, consulte el artículo Control de errores.

Use el método RewindAsync (.NET) o rewind (JavaScript) del enlace de cliente orchestration para volver a colocar la orquestación en el estado Running. Este método también vuelve a ejecutar los errores de ejecución de la actividad o suborchestración que provocaron el error de orquestación.

Por ejemplo, supongamos que tiene un flujo de trabajo que implica una serie de aprobaciones humanas. Supongamos que una serie de funciones de actividad notifican a alguien que necesita su aprobación y espera una respuesta en tiempo real. Después de que todas las actividades de aprobación reciban respuestas o agotan el tiempo de espera, supongamos que se produce un error en otra actividad debido a una configuración incorrecta de la aplicación, como una cadena de conexión de base de datos no válida. El resultado es un error de orquestación en profundidad en el flujo de trabajo. Con la API de RewindAsync (.NET) o rewind (JavaScript), un administrador de aplicaciones puede corregir el error de configuración y rebobinar la orquestación que falló al estado inmediatamente antes del fallo. Ninguno de los pasos de interacción humana debe volver a aprobarse y la orquestación ahora puede completarse correctamente.

Nota:

La característica para rebobinar no admite el rebobinado de instancias de orquestación que utilizan temporizadores durables.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("RewindInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("rewind-queue")] string instanceId)
{
    string reason = "Orchestrator failed and needs to be revived.";
    return client.RewindAsync(instanceId, reason);
}

Nota:

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

Consulte Instancias de inicio para la configuración del archivo function.json.

C#
JavaScript
Python
PowerShell
Java

using Microsoft.DurableTask.Client;

string reason = "Orchestrator failed and needs to be revived.";
await client.RewindInstanceAsync(instanceId, reason);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

const reason = "Orchestrator failed and needs to be revived.";
await client.rewindInstance(instanceId, reason);

Reinicio de instancias

Al reiniciar una orquestación se crea una nueva instancia mediante el historial de una instancia de ejecución anterior. Esta característica es útil cuando desea volver a ejecutar una orquestación con el mismo patrón de identificador de instancia e entrada, creando una nueva ejecución basada en el original.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("RestartInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("restart-queue")] string instanceId)
{
    return client.RestartAsync(instanceId, restartWithNewInstanceId: true);
}

Nota:

C#
JavaScript
Python
PowerShell
Java

using Microsoft.DurableTask.Client;

// Restart an orchestration with a new instance ID
string newInstanceId = await client.RestartInstanceAsync(instanceId, restartWithNewInstanceId: true);
Console.WriteLine($"Restarted as new instance: {newInstanceId}");

// Restart an orchestration keeping the same instance ID
await client.RestartInstanceAsync(instanceId, restartWithNewInstanceId: false);

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Restart an orchestration with a new instance ID
const newInstanceId = await client.restartOrchestration(instanceId, true);
console.log(`Restarted as new instance: ${newInstanceId}`);

// Restart an orchestration keeping the same instance ID
await client.restartOrchestration(instanceId, false);

Purga del historial de instancias

Para quitar todos los datos asociados a una orquestación, purgue el historial de instancias. Por ejemplo, elimine los recursos de almacenamiento asociados a una instancia completada. Use la API de instancia de purga definida por el cliente de orquestación.

En el ejemplo siguiente se muestra cómo purgar una única instancia de orquestación.

C#
JavaScript
Python
PowerShell
Java

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("purge-queue")] string instanceId)
{
    return client.PurgeInstanceHistoryAsync(instanceId);
}

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

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

Consulte Instancias de inicio para la configuración del archivo function.json.

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)

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Purge a single orchestration instance
PurgeResult result = await client.PurgeInstanceAsync(instanceId);
Console.WriteLine($"Purged {result.PurgedInstanceCount} instance(s).");

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

# Purge a single orchestration instance
result = client.purge_orchestration(instance_id)
print(f"Purged {result.deleted_instance_count} instance(s).")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.PurgeResult;

// Purge a single orchestration instance
PurgeResult result = client.purgeInstance(instanceId);
System.out.println("Purged " + result.getDeletedInstanceCount() + " instance(s).");

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";

const client = createAzureManagedClient(connectionString);

// Purge a single orchestration instance
const result = await client.purgeOrchestration(instanceId);
console.log(`Purged ${result?.deletedInstanceCount ?? 0} instance(s).`);

En el ejemplo siguiente se muestra una función desencadenada por el temporizador que purga el historial de todas las instancias de orquestación que se completaron después del intervalo de tiempo especificado. En este caso, quita los datos de todas las instancias completadas hace 30 o más días. Esta función de ejemplo está programada para ejecutarse una vez al día, a las 12:00 UTC:

C#
JavaScript
PowerShell
Python
Java

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

Nota:

El método se puede usar para purgar condicionalmente el historial de instancias de varias instancias.

function.json

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

Nota:

Este ejemplo tiene como destino Durable Functions versión 2.x. En la versión 1.x, use en lugar de .

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

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)

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

C#
Python
Java
JavaScript
PowerShell

using Microsoft.DurableTask.Client;

// Purge completed instances older than 30 days
var filter = new PurgeInstancesFilter(
    CreatedFrom: DateTime.MinValue,
    CreatedTo: DateTime.UtcNow.AddDays(-30),
    Statuses: new[] { OrchestrationRuntimeStatus.Completed });

PurgeResult result = await client.PurgeAllInstancesAsync(filter);
Console.WriteLine($"Purged {result.PurgedInstanceCount} instance(s).");

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from datetime import datetime, timedelta

# Purge completed instances older than 30 days
result = client.purge_orchestrations(
    created_time_from=datetime.min,
    created_time_to=datetime.utcnow() - timedelta(days=30),
    runtime_status=['COMPLETED']
)
print(f"Purged {result.deleted_instance_count} instance(s).")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.PurgeInstanceCriteria;
import com.microsoft.durabletask.PurgeResult;
import com.microsoft.durabletask.OrchestrationRuntimeStatus;
import java.time.Duration;
import java.time.Instant;
import java.util.List;

// Purge completed instances older than 30 days
PurgeInstanceCriteria criteria = new PurgeInstanceCriteria()
    .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(30)))
    .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.COMPLETED));

PurgeResult result = client.purgeInstances(criteria);
System.out.println("Purged " + result.getDeletedInstanceCount() + " instance(s).");

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus, PurgeInstanceCriteria } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

// Purge completed instances older than 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

const criteria = new PurgeInstanceCriteria();
criteria.setCreatedTimeTo(thirtyDaysAgo);
criteria.setRuntimeStatusList([OrchestrationStatus.COMPLETED]);

const result = await client.purgeOrchestration(criteria);
console.log(`Purged ${result?.deletedInstanceCount ?? 0} instance(s).`);

Nota:

Para que la operación del historial de purga se realice correctamente, el estado en tiempo de ejecución de la instancia de destino debe ser Completado, Finalizado o Erróneo.

Pasos siguientes

Control de versiones

Referencia de API HTTP integrada para la administración de instancias

Introducción a los SDK de Durable Task

Más información sobre el programador de tareas duraderas

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-03-06

Compartir a través de

Gestionar instancias de orquestación

Inicio de instancias

Consulta de instancias

Consultar todas las instancias

Consulta de instancias con filtros

Finalización de instancias

Suspender y reanudar instancias

Envío de eventos a instancias

Esperar a que finalice la orquestación

Recuperación de las direcciones URL del webhook de administración de HTTP

Retroceso de instancias

Reinicio de instancias

Purga del historial de instancias

Pasos siguientes

Comentarios

Recursos adicionales