Administración de instancias en Durable Functions en Azure

Las orquestaciones de Durable Functions son funciones con estado de ejecución prolongada que se pueden iniciar, consultar, suspender, reanudar y finalizar mediante las API de administración integradas. Otras API de administración de instancias también se exponen mediante el enlace de cliente de orquestación de Durable Functions, como el envío de eventos externos a instancias, la purga del historial de instancias, etc. En este artículo se describen los detalles de todas las operaciones de administración de instancias admitidas.

Inicio de instancias

El método start-new (o schedule-new) del enlace de cliente de orquestación inicia una nueva instancia de orquestación. Internamente, este método escribe un mensaje a través del proveedor de almacenamiento de Durable Functions y, a continuación, devuelve. Este mensaje desencadena de forma asincrónica el inicio de una función de orquestación con el nombre especificado.

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

• 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 cuando se escalan las funciones de orquestador en varias máquinas virtuales. El tiempo adecuado para usar identificadores de instancia no aleatorios es cuando el identificador debe proceder de un origen externo o al implementar el patrón de orquestador singleton .

El código siguiente es una función de ejemplo que inicia una nueva instancia de orquestación:

C#

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

Nota:

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

JavaScript

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 orchestrationClient en lugar de durableClient.

index.js

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

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

    const instanceId = await client.startNew("HelloWorld", undefined, input);
    context.log(`Started orchestration with ID = ${instanceId}.`);
};

Pitón

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 orchestrationClient en lugar de durableClient.

__init__.py

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

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

PowerShell

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 orchestrationClient en lugar de durableClient.

run.ps1

param($Request, $TriggerMetadata)

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

Java

@FunctionName("HelloWorldQueueTrigger")
public void helloWorldQueueTrigger(
        @QueueTrigger(name = "input", queueName = "start-queue", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    String instanceID = client.scheduleNewOrchestrationInstance("HelloWorld");
    context.getLogger().info("Scheduled orchestration with ID = " + instanceID);
}

Si desea esperar a que el orquestador se inicie antes de volver de la función, también puede usar el waitForInstanceStart() método .

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

Azure Functions Core Tools

También puede iniciar una instancia directamente mediante el func durable start-new comando de Core Tools, que toma los parámetros siguientes:

• function-name (obligatorio): nombre de la función que se va a iniciar.
• input (opcional): entrada para la función, ya sea en línea o a través de un archivo JSON. En el caso de los archivos, agregue un prefijo a la ruta de acceso al archivo con @, como @path/to/file.json.
• id (opcional): identificador de la instancia de orquestación. Si no especifica este parámetro, el comando usa un GUID aleatorio.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También puede establecerlo en host.json mediante durableTask:HubName.

Nota:

Los comandos de Core Tools suponen que los está ejecutando desde el directorio raíz de una aplicación de funciones. Si proporciona explícitamente los connection-string-setting parámetros y task-hub-name , puede ejecutar los comandos desde cualquier directorio. Aunque puede ejecutar estos comandos sin que se ejecute un host de aplicación de funciones, es posible que no pueda observar algunos efectos a menos que el host se esté ejecutando. Por ejemplo, el comando start-new pone en cola un mensaje de inicio en el centro de tareas de destino, pero la orquestación no se ejecuta realmente a menos que haya un proceso de host de la aplicación de función en ejecución que pueda procesar el mensaje.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El siguiente comando inicia la función denominada HelloWorld y pasa el contenido del archivo counter-data.json a ella:

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

Consulta de instancias

Después de iniciar nuevas instancias de orquestación, es probable que tenga que consultar su estado en tiempo de ejecución para saber si se están ejecutando, se han completado o se han producido errores.

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

Toma instanceId (obligatorio), showHistory (opcional), showHistoryOutput (opcional) y showInput (opcional) como parámetros.

• showHistory: si se establece en true, la respuesta contiene el historial de ejecución.
• showHistoryOutput: si se establece en true, el historial de ejecución contiene salidas de actividad.
• showInput: si se establece en false, la respuesta no contendrá la entrada de la función. El valor predeterminado es true.

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 instanceId entrada).
• CreatedTime: hora en la que se inició la ejecución de la función de orquestador.
• LastUpdatedTime: La hora en que la orquestación ha realizado un punto de control por última vez.
• Entrada: entrada de la función como un valor JSON. Este campo no se rellena si showInput es false.
• CustomStatus: estado de orquestación personalizada en formato JSON.
• Salida: la salida de la función como un valor JSON (si la función se ha completado). Si se produjo un error en la función de orquestador, esta propiedad incluye los detalles del error. Si la función de orquestador se suspendió o finalizó, esta propiedad incluye el motivo de la suspensión o finalización (si existe).
• RuntimeStatus: uno de los siguientes valores:
  • Pendiente: la instancia se ha programado pero aún no se ha iniciado la ejecución.
  • En ejecución: la instancia ha empezado a ejecutarse.
  • Completado: la instancia se ha completado 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 suspendió y se puede reanudar en un momento posterior.
• History: el historial de ejecución de la orquestación. Este campo solo se rellena si showHistory se establece en true.

Nota:

Los orquestadores no se marcan como Completed hasta que todas las tareas que tienen programadas han finalizado y el orquestador ha vuelto. En otras palabras, no basta con que un orquestador alcance su instrucción return para que se marque como Completed. Esto es especialmente importante en aquellos casos en los que se usa WhenAny; estos orquestadores a menudo usan return antes de que se hayan ejecutado todas las tareas programadas.

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

C#

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

Nota:

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

JavaScript

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

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

    const status = await client.getStatus(instanceId);
    // do something based on the current status.
    // example: if status.runtimeStatus === df.OrchestrationRuntimeStatus.Running: ...
}

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

Pitón

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

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

Java

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

Azure Functions Core Tools

También es posible obtener el estado de una instancia de orquestación directamente mediante el func durable get-runtime-status comando en Core Tools.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El comando durable get-runtime-status toma los parámetros siguientes:

• id (obligatorio): identificador de la instancia de orquestación.
• show-input (opcional): si se establece en true, la respuesta contiene la entrada de la función. El valor predeterminado es false.
• show-output (opcional): si se establece en true, la respuesta contiene la salida de la función. El valor predeterminado es false.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También se puede establecer en host.json, mediante durableTask:HubName.

El siguiente comando recupera el estado (incluida la entrada y la salida) de una instancia con un identificador de instancia de orquestación de 0ab8c55a66644d68a3a8b220b12d209c. Se supone que está ejecutando el func comando desde el directorio raíz de la aplicación de funciones:

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

Puede usar el durable get-history comando para recuperar el historial de una instancia de orquestación. Toma los parámetros siguientes:

• id (obligatorio): identificador de la instancia de orquestación.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También se puede establecer en host.json, mediante durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

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#

[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 el atributo OrchestrationClient en lugar del atributo DurableClient, y debe usar el tipo de parámetro DurableOrchestrationClient en lugar de IDurableOrchestrationClient. Para más información sobre las diferencias entre versiones, consulte el artículo Versiones de Durable Functions.

JavaScript

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

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

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

Consulte Iniciar instancias para la configuración de function.json.

Pitón

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

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

PowerShell

Nota:

Esta característica no se admite actualmente en PowerShell, pero se puede lograr mediante la API HTTP de Durable Functions.

Java

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

Azure Functions Core Tools

También es posible consultar instancias directamente mediante el func durable get-instances comando en Core Tools.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El comando durable get-instances toma los parámetros siguientes:

• top (opcional): este comando admite la paginación. Este parámetro corresponde al número de instancias recuperadas por solicitud. El valor predeterminado es 10.
• continuation-token (opcional): token para indicar qué página o sección de instancias se van a recuperar. Cada get-instances ejecución devuelve un token al siguiente conjunto de instancias.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También se puede establecer en host.json, mediante durableTask:HubName.

func durable get-instances

Consulta de instancias con filtros

¿Qué ocurre si realmente no necesita toda la información que puede proporcionar una consulta de instancia estándar? Por ejemplo, ¿qué sucede si solo desea obtener la hora de creación de la orquestación o el estado del entorno de ejecución de la orquestación? Puede restringir la consulta aplicando filtros.

C#

[FunctionName("QueryStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    // Get the first 100 running or pending instances that were created between 7 and 1 day(s) ago
    var queryFilter = new OrchestrationStatusQueryCondition
    {
        RuntimeStatus = new[]
        {
            OrchestrationRuntimeStatus.Pending,
            OrchestrationRuntimeStatus.Running,
        },
        CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
        CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
        PageSize = 100,
    };
    
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        queryFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
}

Nota:

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

JavaScript

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

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

    const runtimeStatus = [
        df.OrchestrationRuntimeStatus.Completed,
        df.OrchestrationRuntimeStatus.Running,
    ];
    const instances = await client.getStatusBy(
        new Date(2021, 3, 10, 10, 1, 0),
        new Date(2021, 3, 10, 10, 23, 59),
        runtimeStatus
    );
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

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

Pitón

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

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

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

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

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

PowerShell

Nota:

Esta característica no se admite actualmente en PowerShell, pero se puede lograr mediante la API HTTP de Durable Functions.

Java

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

Azure Functions Core Tools

En Azure Functions Core Tools, también puede usar el durable get-instances comando con filtros. Además de los parámetros mencionados anteriormente top, continuation-token, connection-string-setting, y task-hub-name , puede usar tres parámetros de filtro (created-after, created-beforey runtime-status).

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

A continuación se muestran los parámetros del durable get-instances comando .

• created-after (opcional): recupere las instancias creadas después de esta fecha y hora (UTC). Fechas y horas con formato ISO 8601 aceptados.
• created-before (opcional): recupere las instancias creadas antes de esta fecha y hora (UTC). Se aceptan valores de datetime con formato ISO 8601.
• runtime-status (opcional): recupere las instancias con un estado determinado (por ejemplo, en ejecución o completado). Puede proporcionar varios estados (separados por espacios).
• top (opcional): número de instancias recuperadas por solicitud. El valor predeterminado es 10.
• continuation-token (opcional): token para indicar qué página o sección de instancias se van a recuperar. Cada get-instances ejecución devuelve un token al siguiente conjunto de instancias.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También se puede establecer en host.json, mediante durableTask:HubName.

Si no proporciona ningún filtro (created-after, created-beforeo runtime-status), el comando simplemente recupera top instancias, sin tener en cuenta el estado de tiempo de ejecución ni el tiempo de creación.

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

Finalización de instancias

Si tiene una instancia de orquestación que está tardando demasiado en ejecutarse, o necesita interrumpirla antes de que termine por cualquier motivo, puede cancelarla.

Los dos parámetros de la API de finalizació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#

[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:

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

JavaScript

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

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

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

Consulte Iniciar instancias para la configuración de function.json.

Pitón

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

Una instancia terminada pasará finalmente al Terminated estado. Sin embargo, esta transición no se producirá inmediatamente. Más bien, la operación de finalización se pondrá en cola en el centro 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 Terminated 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 ha finalizado la instancia de orquestación que las llamó.

Suspensión y reanudación de instancias

La suspensión de una orquestación permite detener una orquestación en ejecución. A diferencia de la finalización, tiene la opción de reanudar un orquestador suspendido en un momento posterior.

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#

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

Pitón

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

Nota:

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

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

Una instancia suspendida pasará finalmente al Suspended estado. Sin embargo, esta transición no se producirá inmediatamente. Más bien, la operación de suspensión se pondrá en cola en el centro de tareas junto con otras operaciones para esa instancia. Puede usar las API de consulta de instancia para saber cuándo una instancia en ejecución ha alcanzado realmente el estado Suspendido.

Cuando se reanuda un orquestador suspendido, su estado volverá a cambiar a Running.

Azure Functions Core Tools

También puede finalizar una instancia de orquestación directamente mediante el func durable terminate comando en Core Tools.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El comando durable terminate toma los parámetros siguientes:

• id (obligatorio): identificador de la instancia de orquestación a terminar.
• reason (opcional): motivo de finalización.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También se puede establecer en host.json, mediante durableTask:HubName.

El siguiente comando finaliza una instancia de orquestación con un identificador de 0ab8c55a66644d68a3a8b220b12d209c:

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

Envío de eventos a instancias

En algunos escenarios, las funciones de orquestador deben esperar y escuchar eventos externos. Entre los escenarios de ejemplos en los que esto resulta ú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 los siguientes:

• 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#

[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:

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

JavaScript

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

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

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

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

Pitón

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

Java

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

Nota:

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 almacenará en el estado de instancia hasta que esté listo para recibirse y procesarse.

Azure Functions Core Tools

También puede generar un evento en una instancia de orquestación directamente a través del comando func durable raise-event en Core Tools.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El comando durable raise-event toma los parámetros siguientes:

• id (obligatorio): identificador de la instancia de orquestación.
• event-name: nombre del evento que se va a activar.
• event-data (opcional): datos que se van a enviar a la instancia de orquestación. Puede ser la ruta de acceso a un archivo JSON o puede proporcionar los datos directamente en la línea de comandos.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. El valor predeterminado es DurableFunctionsHub. También se puede establecer en host.json, mediante 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

Esperar a que finalice la orquestación

En las orquestaciones de larga ejecución, quizá prefiera esperar y obtener los resultados de una orquestación. En estos casos, también resulta útil poder definir un período de tiempo de espera en la orquestación. Si se agota el tiempo de espera, se debe devolver el estado de la orquestación en lugar de los resultados.

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

Esta es una función de desencadenador HTTP de ejemplo que muestra cómo usar esta 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;
}

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

Pitón

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

PowerShell

Nota:

PowerShell no tiene actualmente un comando integrado para este escenario.

Java

Java no tiene actualmente un único método para este escenario. Sin embargo, se puede implementar 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);
    }
}

Utilice la función con la siguiente línea. Use 2 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 E1_HelloSequence 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.

En función del tiempo necesario para obtener la respuesta de la instancia de orquestación, hay dos casos:

• Las instancias de orquestación se completan dentro del tiempo de espera definido (en este caso, 2 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 se pueden completar dentro del tiempo de espera definido, y la respuesta es la predeterminada que se describe en descubrimiento de URL de la 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 esté ejecutando. 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

Puede usar un sistema externo para supervisar o generar eventos en una orquestación. Los sistemas externos pueden comunicarse con Durable Functions a través de las URL del webhook que forman parte de la respuesta predeterminada descrita en el descubrimiento de URL de la API HTTP. También se puede acceder a las direcciones URL del webhook mediante programación mediante el enlace de cliente de orquestación. En concreto, la API de crear carga de administración HTTP se puede usar para obtener un objeto serializable que contenga 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 InstanceId 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 para suspensión de la instancia de orquestación.
• resumePostUri: la dirección URL "resume" de la instancia de orquestación.

Las funciones pueden enviar instancias de estos objetos a sistemas externos para supervisar o generar eventos en las orquestaciones correspondientes, como se muestra en los ejemplos siguientes:

C#

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

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

Nota:

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

JavaScript

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

modules.exports = async function(context, ctx) {
    const client = df.getClient(context);

    const payload = client.createHttpManagementPayload(ctx.instanceId);

    // send the payload to Azure Cosmos DB
    context.bindings.document = JSON.stringify({
        id: ctx.instanceId,
        payload,
    });
};

Consulte Iniciar instancias para la configuración de function.json.

Pitón

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

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

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

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

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

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

Java

Nota:

Esta característica no se admite actualmente en Java.

Rebobinado de instancias (versión preliminar)

Si tiene un error de la orquestación por un motivo inesperado, puede rebobinar la instancia a un estado correcto anterior mediante una API creada con ese propósito.

Nota:

Esta API no está pensada para ser un reemplazo para el control de errores adecuado y las directivas de reintento. En su lugar, está pensado para usarse solo en los casos en los que las instancias de orquestación produzcan un error por motivos inesperados. Las orquestaciones en estados distintos de Failed (por ejemplo, Running, Pending, Terminated, Completed) no se pueden "rebobinar". Para obtener más información sobre el control de errores y las directivas de reintento, consulte el artículo Control de errores.

Use los métodos RewindAsync (.NET) o rewind (JavaScript) del enlace del cliente de orquestación para volver a poner la orquestación en el estado En ejecución. Estos métodos volverán a ejecutar la actividad o los errores de ejecución de suborquestación que generaron el error en la orquestación.

Por ejemplo, supongamos que tiene un flujo de trabajo que implica una serie de aprobaciones humanas. Supongamos que hay una serie de funciones de actividad que notifican a alguien que su aprobación es necesaria y esperan la respuesta en tiempo real. Después de que todas las actividades de aprobación hayan recibido respuestas o agotado el tiempo de espera, suponga 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 RewindAsync API (.NET) o rewind (JavaScript), un administrador de aplicaciones puede corregir el error de configuración y rebobinar la orquestación fallida al estado inmediatamente anterior al 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#

[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:

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

JavaScript

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

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

    const reason = "Orchestrator failed and needs to be revived.";
    return client.rewind(instanceId, reason);
};

Consulte Iniciar instancias para la configuración de function.json.

Pitón

Nota:

Esta característica no se admite actualmente en Python.

PowerShell

Nota:

Esta característica no se admite actualmente en PowerShell.

Java

Nota:

Esta característica no se admite actualmente en Java.

Azure Functions Core Tools

También es posible rebobinar una instancia de orquestación directamente con el comando func durable rewind de Core Tools.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El comando durable rewind toma los parámetros siguientes:

• id (obligatorio): identificador de la instancia de orquestación.
• reason (opcional): motivo para reiniciar la instancia de orquestación.
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. De forma predeterminada, se usa el nombre del centro de tareas del archivo host.json .

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

Purga del historial de instancias

Para quitar todos los datos asociados a una orquestación, puede purgar el historial de instancias. Por ejemplo, es posible que quiera eliminar los recursos de almacenamiento asociados a una instancia completada. Para ello, use la API de instancia de purga definida por el cliente de orquestación.

En este primer ejemplo se muestra cómo purgar una sola instancia de orquestación.

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

Consulte Iniciar instancias para la configuración de function.json.

Pitón

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

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

    return await client.purge_instance_history(instance_id)

PowerShell

Nota:

Esta característica no se admite actualmente en PowerShell, pero se puede lograr mediante la API HTTP de 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();
    }
}

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#

[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 código de C# anterior es para Durable Functions 2.x. Para Durable Functions 1.x, debe usar el atributo OrchestrationClient en lugar del atributo DurableClient, y debe usar el tipo de parámetro DurableOrchestrationClient en lugar de IDurableOrchestrationClient. Para más información sobre las diferencias entre versiones, consulte el artículo Versiones de Durable Functions.

JavaScript

El purgeInstanceHistoryBy 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 orchestrationClient en lugar de durableClient.

index.js

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

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

PowerShell

Nota:

Esta característica no se admite actualmente en PowerShell, pero se puede lograr mediante la API HTTP de Durable Functions.

Pitón

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

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

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

Java

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

Nota:

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.

Azure Functions Core Tools

Puede purgar el historial de una instancia de orquestación mediante el func durable purge-history comando en Core Tools. De forma similar al segundo ejemplo de C# de la sección anterior, purga el historial de todas las instancias de orquestación creadas durante un intervalo de tiempo especificado. Puede filtrar aún más las instancias purgadas por estado en tiempo de ejecución.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El durable purge-history comando tiene varios parámetros:

• created-after (opcional): purga el historial de instancias creadas después de esta fecha y hora (UTC). Se aceptan valores de datetime con formato ISO 8601.
• created-before (opcional): purga el historial de instancias creadas antes de esta fecha y hora (UTC). Se aceptan valores de datetime con formato ISO 8601.
• runtime-status (opcional) : purga el historial de instancias con un estado determinado (por ejemplo, en ejecución o completado). Puede proporcionar varios estados (separados por espacios).
• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. De forma predeterminada, se usa el nombre del centro de tareas del archivo host.json .

El siguiente comando elimina el historial de todas las instancias con error creadas antes del 14 de noviembre de 2021 a las 7:35 p. m. (UTC).

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

Eliminación de un centro de tareas

Con el func durable delete-task-hub comando de Core Tools, puede eliminar todos los artefactos de almacenamiento asociados a un centro de tareas determinado, incluidas las tablas de Almacenamiento de Azure, las colas y los blobs.

Nota:

Actualmente, los comandos de Core Tools solo se admiten cuando se usa el proveedor predeterminado de Azure Storage para conservar el estado en tiempo de ejecución.

El durable delete-task-hub comando tiene dos parámetros:

• connection-string-setting (opcional): nombre de la configuración de la aplicación que contiene la cadena de conexión de almacenamiento que se va a usar. El valor predeterminado es AzureWebJobsStorage.
• task-hub-name (opcional): nombre del centro de tareas de Durable Functions que se va a usar. De forma predeterminada, se usa el nombre del centro de tareas del archivo host.json .

El comando siguiente elimina todos los datos de Azure Storage asociados al UserTest centro de tareas.

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

Pasos siguientes

Obtenga información sobre cómo controlar el control de versiones

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