Gerir instâncias de orquestração

As orquestrações são fluxos de trabalho com estado de longa duração que pode iniciar, consultar, suspender, retomar e terminar usando APIs de gestão integradas. Em Durable Functions, a ligação do cliente orchestration expõe estas APIs. Nos SDKs de Tarefas Duráveis, estas operações estão disponíveis através da DurableTaskClient classe. Este artigo cobre todas as operações de gestão de instâncias suportadas para ambas as plataformas.

Sugestão

O Azure Durable Task Scheduler é o backend recomendado tanto para Durable Functions como para os Durable Task SDKs, proporcionando uma experiência totalmente gerida e serverless para executar fluxos de trabalho duráveis em escala.

Iniciar instâncias

O método start-new (ou schedule-new) no cliente de orquestração inicia uma nova instância de orquestração. Internamente, este método escreve uma mensagem no backend configurado (como o Durable Task Scheduler ou o Azure Storage) e depois devolve. Esta mensagem desencadeia assíncronamente o início de uma orquestração com o nome especificado.

Aqui estão os parâmetros para iniciar uma nova instância de orquestração:

• Nome: O nome da função orquestradora a ser agendada.
• Entrada: Qualquer dado serializável em JSON que deve ser passado como entrada para a função orchestrator.
• InstanceId: (Opcional) A ID exclusiva da instância. Se você não especificar esse parâmetro, o método usará uma ID aleatória.

Sugestão

Use um identificador aleatório para o ID da instância sempre que possível. IDs de instância aleatórios ajudam a garantir uma distribuição de carga igual quando escalas funções do orquestrador em várias VMs. O momento correto para usar IDs de instância não aleatórios é quando o ID vem de uma fonte externa ou quando está a implementar o padrão singleton orchestrator .

• Nome: O nome da orquestração a agendar.
• Entrada: Quaisquer dados serializáveis em JSON que devam ser passados como entrada para a orquestração.
• InstanceId: (Opcional) A ID exclusiva da instância. Se você não especificar esse parâmetro, o método usará uma ID aleatória.

Sugestão

Use um identificador aleatório para o ID da instância sempre que possível. IDs de instância aleatórios ajudam a garantir uma distribuição de carga igual quando escalas orquestrações em várias VMs. O momento correto para usar IDs de instância não aleatórios é quando o ID vem de uma fonte externa ou quando está a implementar o padrão singleton orchestrator .

A seguinte função de exemplo inicia uma nova instância de orquestração:

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do Durable Functions.

Javascript

A menos que especificado de outra forma, os exemplos nesta página usam o gatilho HTTP com o seguinte 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
}

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez 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}.`);
};

Python

A menos que especificado de outra forma, os exemplos nesta página usam o gatilho HTTP com o seguinte 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
}

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez 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 especificado de outra forma, os exemplos nesta página usam o gatilho HTTP com o seguinte 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
}

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez 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);
}

Para esperar que o orquestrador comece antes de regressar da sua função, use o waitForInstanceStart() método.

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

Importante

Atualmente, o PowerShell Durable Task SDK não está disponível.

O código seguinte mostra como iniciar uma nova instância de orquestração usando os Durable Task SDKs:

C#

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

Python

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)

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Instâncias de consulta

Depois de iniciar novas instâncias de orquestração, provavelmente terá de consultar o estado de execução delas para saber se estão em execução, concluídas ou com falha.

O método get-status no cliente de orquestração devolve o estado de uma instância de orquestração.

Ele usa um instanceId (obrigatório), showHistory (opcional), showHistoryOutput (opcional) e showInput (opcional) como parâmetros.

• showHistory: Se definido como true, a resposta contém o histórico de execução.
• showHistoryOutput: Se definido como true, o histórico de execução contém saídas de atividade.
• showInput: Se definido para false, a resposta não contém a entrada da função. O valor predefinido é true.

O método retorna um objeto com as seguintes propriedades:

• Nome: O nome da função orquestradora.
• InstanceId: O ID da instância da orquestração (deve ser o mesmo que a instanceId entrada).
• CreatedTime: O momento em que a função do orquestrador começa a funcionar.
• LastUpdatedTime: O momento em que a orquestração termina nos pontos de controlo.
• Entrada: A entrada da função como um valor JSON. Este campo não é preenchido se showInput for false.
• CustomStatus: Status de orquestração personalizado no formato JSON.
• Saída: A saída da função como valor JSON (se a função estiver completa). Se a função do orquestrador falhar, esta propriedade inclui os detalhes da falha. Se a função orquestradora for suspensa ou terminada, esta propriedade inclui a razão da suspensão ou terminação (se existir).
• RuntimeStatus: Um dos seguintes valores:
  • Pendente: A instância está programada, mas ainda não começou a estar em execução.
  • Em execução: A instância está em execução.
  • Concluído: A instância foi concluída normalmente.
  • ContinuedAsNew: A instância reiniciou-se com uma nova história. Este estado é um estado transitório.
  • Falha: A instância falhou com um erro.
  • Terminado: A instância foi interrompida abruptamente.
  • Suspenso: A instância está suspensa e pode ser retomada posteriormente.
• História: O histórico de execução da orquestração. Este campo só será preenchido se showHistory estiver definido como true.

• showHistory: Se definido como true, a resposta contém o histórico de execução.
• showHistoryOutput: Se definido como true, o histórico de execução contém saídas de atividade.
• showInput: Se definido para false, a resposta não contém a entrada da orquestração. O valor predefinido é true.

O método retorna um objeto com as seguintes propriedades:

• Nome: O nome da orquestração.
• InstanceId: O ID da instância da orquestração (deve ser o mesmo que a instanceId entrada).
• CreatedTime: O momento em que a orquestração começa a ser executada.
• LastUpdatedTime: O momento em que a orquestração termina nos pontos de controlo.
• Entrada: A entrada da orquestração como um valor no formato JSON. Este campo não é preenchido se showInput for false.
• CustomStatus: Status de orquestração personalizado no formato JSON.
• Saída: A saída da orquestração como valor JSON (se a orquestração estiver concluída). Se a orquestração falhar, esta propriedade inclui os detalhes da falha. Se a orquestração for suspensa ou terminada, esta característica inclui a razão da suspensão ou rescisão (se existir).
• RuntimeStatus: Um dos seguintes valores:
  • Pendente: A instância está programada, mas ainda não começou a estar em execução.
  • Em execução: A instância está em execução.
  • Concluído: A instância foi concluída normalmente.
  • ContinuedAsNew: A instância reiniciou-se com uma nova história. Este estado é um estado transitório.
  • Falha: A instância falhou com um erro.
  • Terminado: A instância foi interrompida abruptamente.
  • Suspenso: A instância está suspensa e pode ser retomada posteriormente.
• História: O histórico de execução da orquestração. Este campo só será preenchido se showHistory estiver definido como true.

Observação

Um orquestrador não é marcado como Completed até que todas as suas tarefas agendadas terminem e o orquestrador tenha regressado. Por outras palavras, não basta que um orquestrador alcance a sua return afirmação para que esta seja marcada como Completed. Isto é particularmente relevante para casos em que WhenAny é utilizado; esses orquestradores frequentemente return antes de todas as tarefas agendadas serem executadas.

Esse método retorna null (.NET e Java), undefined (JavaScript) ou None (Python) se a instância não existir.

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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: ...
}

Para a configuração function.json, Veja Instâncias de Início.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

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

Java

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

C#

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
}

Python

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

Java

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
}

Javascript

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
}

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Consultar todas as instâncias

Você pode usar APIs em seu SDK de idioma para consultar os status de todas as instâncias de orquestração em seu hub de tarefas. Essa API "list-instances" ou "get-status" retorna uma lista de objetos que representam as instâncias de orquestração correspondentes aos 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.
}

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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));
    });
};

Para a configuração do function.json, consulte Instâncias de Início.

Python

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


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

    instances = await client.get_status_all()

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

Para a configuração do function.json, consulte Instâncias de Início.

PowerShell

Observação

O PowerShell não suporta atualmente esta funcionalidade, mas pode fazê-lo usando a API HTTP Durable Functions.

Java

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

C#

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

Python

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

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

for instance in instances:
    print(instance.instance_id)

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Consultar instâncias com filtros

E se não precisar de toda a informação que uma consulta de instância padrão fornece? Por exemplo, e se estiver apenas à procura da hora de criação da orquestração ou do estado de execução da orquestração? Restringir a sua 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 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));
    }
}

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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 Iniciar instâncias para a configuração function.json.

Python

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

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

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

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

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

PowerShell

Observação

Esta funcionalidade não é atualmente suportada no PowerShell, mas pode fazê-la usando a API HTTP Durable Functions.

Java

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

C#

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

Python

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

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Encerrar instâncias

Se tiver uma instância de orquestração que demora demasiado a ser executada, ou precisar de a parar antes de terminar por qualquer motivo, pode finalizá-la.

Os dois parâmetros para a API de terminação são um ID de instância e uma cadeia de caracteres de razão, que escrevem nos logs e no estado da instância.

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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 instâncias para a configuração function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

Java

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

C#

using Microsoft.DurableTask.Client;

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

Python

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

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

Java

import com.microsoft.durabletask.DurableTaskClient;

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

Javascript

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

const client = createAzureManagedClient(connectionString);

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Uma instância terminada acaba por transitar para o Terminated estado. Mas esta transição não acontece imediatamente. Em vez disso, a operação de terminação é colocada na fila no centro de tarefas juntamente com outras operações nessa instância. Você pode usar as APIs de consulta de instância para saber quando uma instância encerrada realmente atingiu o Terminated estado.

Observação

Atualmente, o encerramento da instância não se propaga. As funções de atividade e suborquestrações correm até ao fim, independentemente de terminares ou não a instância de orquestração que as chamou.

Suspender ou retomar instâncias

Suspender uma orquestração permite-te parar uma orquestração em curso. Ao contrário de terminar uma orquestração, podes retomar um orquestrador suspenso mais tarde.

Os dois parâmetros para a API de suspensão são um ID de instância e uma cadeia de caracteres de motivo, que são gravados em logs e no status da instância.

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);

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

Javascript

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

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

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

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

Python

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

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

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

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

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

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

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

Observação

Esse recurso está disponível apenas no SDK independente PowerShell de Funções Duráveis. Veja a diferença entre o SDK autônomo e o SDK interno herdado junto com o guia de migração.

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

C#

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

Python

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)

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Uma instância suspensa acaba por transitar para o Suspended estado. No entanto, esta transição não acontece imediatamente. Em vez disso, a operação de suspensão é colocada na fila no hub de tarefas juntamente com outras operações nessa situação. Use as APIs de consulta de instâncias para saber quando uma instância em execução atingiu realmente o Suspended estado.

Quando um orquestrador suspenso é retomado, o seu estado retorna para Running.

Enviar eventos para instâncias

Em alguns cenários, as funções do orquestrador precisam esperar e ouvir eventos externos. Exemplos em que esta abordagem é útil incluem os cenários de monitorização e interação humana .

Em alguns cenários, as orquestrações precisam de esperar e ouvir eventos externos. Exemplos em que esta abordagem é útil incluem os cenários de monitorização e interação humana .

Pode enviar notificações de eventos para instâncias em execução usando a API de raise event do cliente de orquestração. As orquestrações podem ouvir e responder a esses eventos usando a API do orquestrador de espera de evento externo.

Os parâmetros para o evento de elevação são:

• ID da instância: a ID exclusiva da instância.
• Nome do evento: o nome do evento a ser enviado.
• Dados do evento: uma carga útil serializável em JSON para enviar à instância.

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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 Iniciar instâncias para a configuração function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

Java

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

C#

using Microsoft.DurableTask.Client;

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

Python

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

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

Java

import com.microsoft.durabletask.DurableTaskClient;

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

Javascript

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

const client = createAzureManagedClient(connectionString);

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Observação

Se não houver uma instância de orquestração com o ID de instância especificado, a mensagem do evento é descartada. Se existir uma instância mas ainda não estiver à espera do evento, o evento é armazenado no estado da instância até estar pronto para ser recebido e processado.

Aguarde a conclusão da orquestração

Em orquestrações de longa duração, talvez queira aguardar e obter os resultados de uma orquestração. Nestes casos, também é útil definir um tempo limite na orquestração. Se o tempo limite for ultrapassado, o estado da orquestração é retornado em vez dos resultados.

Use a API "esperar pela conclusão ou criar resposta de estado de verificação" para obter a saída real de uma instância de orquestração de forma síncrona. Por defeito, este método tem um tempo de espera de dez segundos e um intervalo de sondagem de um segundo.

Aqui está um exemplo de função HTTP trigger que demonstra como 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 Iniciar instâncias para a configuração function.json.

Python

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

PowerShell

Observação

Atualmente, o PowerShell não tem um comando interno para esse cenário.

Java

O Java atualmente não tem um único método para este cenário, mas podes implementá-lo com algumas linhas extra de código.

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

Os SDKs de Tarefas Duráveis fornecem um método para esperar que uma orquestração termine de forma síncrona.

C#

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

Python

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

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Chame a função com a seguinte linha. Utilize dois segundos para o tempo de espera e 0,5 segundos para o intervalo de reintentar.

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

Observação

O comando cURL acima pressupõe que você tenha uma função orchestrator nomeada E1_HelloSequence em seu projeto. Devido a como a função de gatilho HTTP é escrita, você pode substituí-la pelo nome de qualquer função orquestradora em seu projeto.

Dependendo do tempo necessário para obter a resposta da instância de orquestração, existem dois casos:

• As instâncias de orquestração terminam dentro do timeout definido (neste caso, dois segundos), e a resposta é a saída real da instância de orquestração, entregue de forma síncrona:

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

• As instâncias de orquestração não conseguem terminar dentro do timeout definido, e a resposta é a padrão descrita na descoberta da URL da 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}"
}

Observação

O formato dos URLs do webhook pode variar, dependendo da versão do host do Azure Functions que utiliza. O exemplo anterior é para o host do Azure Functions 3.0.

Recuperar URLs de webhook de gerenciamento HTTP

Use um sistema externo para monitorizar ou elevar eventos para uma orquestração. Sistemas externos comunicam com Durable Functions através das URLs de webhook que fazem parte da resposta padrão descrita na descoberta de URLs da API HTTP. Os URLs dos webhooks são alternativamente acessíveis programaticamente usando a ligação do cliente de orquestração. Especificamente, a API create HTTP management payload recebe um objeto serializável que contém estes URLs de webhook.

A API de criação de carga útil de gerenciamento HTTP possui um parâmetro:

• ID da instância: a ID exclusiva da instância.

Os métodos retornam um objeto com as seguintes propriedades de cadeia de caracteres:

• Id: O ID da instância da orquestração (deve ser o mesmo que a InstanceId entrada).
• StatusQueryGetUri: A URL de status da instância de orquestração.
• SendEventPostUri: O URL de "gerar evento" da instância de orquestração.
• TerminatePostUri: URL "terminate" da instância de orquestração.
• PurgeHistoryDeleteUri: A URL do histórico de purga da instância de orquestração.
• SuspendPostUri: O URL "suspend" da instância de orquestração.
• ResumePostUri: A URL "resume" da instância de orquestração.

As funções enviam instâncias destes objetos para sistemas externos para monitorizar ou gerar eventos nas orquestrações correspondentes, como mostrado nos exemplos seguintes.

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient e IDurableActivityContext, que são marcados como obsoletos nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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 instâncias para a configuração function.json.

Python

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

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

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

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

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

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

Java

Observação

O Java atualmente não suporta esta funcionalidade.

Reverter instâncias

Se tiver uma falha de orquestração por uma razão inesperada, rebobine a instância para um estado previamente saudável usando uma API criada para tal fim.

Observação

Esta API não pretende substituir políticas adequadas de manipulação de erros e de novas tentativas. Em vez disso, é destinado a ser utilizado apenas em casos em que as instâncias de orquestração falham por razões inesperadas. Orquestrações em estados diferentes de Failed (por exemplo, Running, Pending, Terminated, ou Completed) não podem ser "revertidas". Para mais informações sobre tratamento de erros e políticas de repetição, consulte o artigo Tratamento de Erros.

Use o método (.NET) ou (JavaScript) da vinculação do cliente de orquestração para retornar a orquestração ao estado Running. Este método também repete as falhas de atividade ou execução de suborquestração que causaram a falha de orquestração.

Por exemplo, suponha que tem um fluxo de trabalho envolvendo uma série de aprovações humanas. Suponha que uma série de funções de atividade notificam alguém de que a sua aprovação é necessária e esperam pela resposta em tempo real. Depois de todas as atividades de aprovação receberem respostas ou atingirem o tempo limite, imagine que uma outra atividade falha devido a uma configuração incorreta da aplicação, como uma cadeia de conexão inválida à base de dados. O resultado é uma falha de orquestração profunda no fluxo de trabalho. Com a API RewindAsync (.NET) ou rewind (JavaScript), um administrador de aplicação pode corrigir o erro de configuração e rebobinar a orquestração falhada para o estado imediatamente anterior à falha. Nenhuma das etapas de interação humana precisa ser reaprovada, e a orquestração agora pode ser concluída com sucesso.

Observação

O recurso de rebobinar não oferece suporte a instâncias de orquestração que utilizam temporizadores duráveis.

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do 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 instâncias para a configuração function.json.

Python

Observação

O Python atualmente não suporta esta funcionalidade.

PowerShell

Observação

O PowerShell atualmente não suporta esta funcionalidade.

Java

Observação

O Java atualmente não suporta esta funcionalidade.

C#

using Microsoft.DurableTask.Client;

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

Javascript

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

Python

Este exemplo é mostrado apenas para .NET e JavaScript.

PowerShell

Este exemplo é mostrado apenas para .NET e JavaScript.

Java

Este exemplo é mostrado apenas para .NET e JavaScript.

Recomeçar instâncias

Reiniciar uma orquestração cria uma nova instância utilizando o histórico de uma instância previamente executada. Esta funcionalidade é útil quando se quer reexecutar uma orquestração com o mesmo padrão de entrada e ID de instância, criando uma execução nova baseada no original.

C#

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

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do Durable Functions.

Javascript

Observação

O JavaScript atualmente não suporta esta funcionalidade.

Python

Observação

O Python atualmente não suporta esta funcionalidade.

PowerShell

Observação

O PowerShell atualmente não suporta esta funcionalidade.

Java

Observação

Esta funcionalidade atualmente não é suportada em Java.

C#

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

Javascript

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

Python

Este exemplo é mostrado apenas para .NET e JavaScript.

PowerShell

Este exemplo é mostrado apenas para .NET e JavaScript.

Java

Este exemplo é mostrado apenas para .NET e JavaScript.

Limpar histórico de instâncias

Para remover todos os dados associados a uma orquestração, purgue o histórico da instância. Por exemplo, eliminar quaisquer recursos de armazenamento associados a uma instância concluída. Use a API de eliminação de instância definida pelo cliente de orquestração.

O exemplo seguinte mostra como purgar uma única instância de orquestração.

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 instâncias para a configuração function.json.

Python

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

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

    return await client.purge_instance_history(instance_id)

PowerShell

Observação

Atualmente, esse recurso não é suportado no PowerShell, mas pode ser alcançado usando a API HTTP de Funções Duráveis.

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

C#

using Microsoft.DurableTask.Client;

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

Python

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

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

O exemplo seguinte mostra uma função ativada por temporizador que purga o histórico de todas as instâncias de orquestração concluídas após o intervalo de tempo especificado. Nesse caso, ele remove dados de todas as instâncias concluídas há 30 ou mais dias. Esta função de exemplo está programada para ser executada uma vez por dia, às 12:00 PM 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
        });
}

Observação

O código C# anterior utiliza o modelo em processo com IDurableOrchestrationClient, que é marcado como obsoleto nas versões mais recentes da extensão Durable Functions. Para novos projetos .NET, considere usar o modelo de trabalhador isolado .NET com DurableTaskClient. Para mais informações, consulte o artigo Versões do Durable Functions.

Javascript

O método purgeInstanceHistoryBy pode ser usado para purgar condicionalmente o histórico de várias instâncias.

function.json

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

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez 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

Observação

Atualmente, esse recurso não é suportado no PowerShell, mas pode ser alcançado usando a API HTTP de Funções Duráveis.

Python

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

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

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

Java

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

C#

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

Python

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

Java

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

Javascript

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

PowerShell

O Durable Task SDK não está disponível para PowerShell. Use Durable Functions em vez disso.

Observação

Para que a operação do histórico de limpeza seja bem-sucedida, o status do tempo de execução da instância de destino deve ser Concluído, Encerrado ou Falhado.

Passos seguintes

Gerenciar versionamento

Referência de API HTTP integrada para gerenciamento de instâncias

Comece com SDKs de Tarefas Duráveis

Saiba mais sobre o Agendador de Tarefas Durável