Gerenciar instâncias no Durable Functions no Azure

As orquestrações no Durable Functions são funções de execução longa com estado que podem ser iniciadas, consultadas, suspensas, retomadas e encerradas usando APIs de gerenciamento integrado. Várias outras APIs de gerenciamento de instância também são expostas pela vinculação do cliente de orquestração do Durable Functions, como enviar eventos externos para instâncias, purgação do histórico da instância, etc. Este artigo detalha todas as operações suportadas de gerenciamento de instância.

Iniciar instâncias

O método start-new (ou schedule-new) na associação de cliente de orquestração inicia uma nova instância de orquestração. Internamente, esse método grava uma mensagem por meio do provedor de armazenamento durable functions e retorna. Essa mensagem dispara de forma assíncrona o início de uma função de orquestração com o nome especificado.

Os parâmetros para iniciar uma nova instância de orquestração são os seguintes:

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

Dica

Use um identificador aleatório para a ID da instância sempre que possível. As IDs de instância aleatória ajudam a garantir uma distribuição de carga igual quando você está dimensionando funções de orquestrador em várias VMs. O momento adequado para usar IDs de instância não aleatórias é quando a ID deve vir de uma origem externa ou quando você está implementando o padrão orquestrador singleton.

O código a seguir é uma função de exemplo que 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 é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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 function.jsona seguir.

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 destino o 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 function.jsona seguir.

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 destino o 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 function.jsona seguir.

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

Se você quiser aguardar o orquestrador iniciar antes de retornar da sua função, você também pode usar o método waitForInstanceStart().

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

Ferramentas principais do Azure Functions

Você também pode iniciar uma instância diretamente usando o func durable start-new comando em Ferramentas Principais, que usa os seguintes parâmetros:

• function-name (obrigatório): nome da função a ser iniciada.
• input (opcional): entrada para a função, embutida ou por meio de um arquivo JSON. Para arquivos, adicione um prefixo ao caminho para o arquivo com @, como @path/to/file.json.
• id (opcional): ID da instância de orquestração. Se você não especificar esse parâmetro, o comando usará um GUID aleatório.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Você também pode definir isso em host.json usando durableTask:HubName.

Observação

Os comandos das Ferramentas Principais pressupõem que você os esteja executando no diretório raiz de um aplicativo de funções. Se você fornecer explicitamente os parâmetros connection-string-setting e task-hub-name, poderá executar os comandos de qualquer diretório. Embora você possa executar esses comandos sem um host de aplicativo de funções em execução, talvez você não possa observar alguns efeitos, a menos que o host esteja em execução. Por exemplo, o comando start-new enfileira uma mensagem de início para o hub de tarefas de destino, mas a orquestração não é executada na verdade, a menos que haja um processo de host de aplicativo de funções em execução que pode processar a mensagem.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O comando a seguir inicia a função denominada HelloWorld e passa o conteúdo do arquivo counter-data.json para ele:

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

Consultar instâncias

Depois de iniciar novas instâncias de orquestração, provavelmente você precisará consultar seu status de runtime para saber se elas estão em execução, se foram concluídas ou falharam.

O método get-status na associação de cliente de orquestração consulta o status 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 como false, a resposta não conterá a entrada da função. O valor padrão é true.

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

• Nome: o nome da função de orquestrador.
• InstanceId: a ID da instância da orquestração (deve ser a mesma que a instanceId entrada).
• CreatedTime: a hora em que a função de orquestrador começou a ser executada.
• LastUpdatedTime: a hora em que a orquestração passou por uma verificação pontual pela última vez.
• Entrada: a entrada da função como um valor JSON. Esse campo não será preenchido se showInput estiver falso.
• CustomStatus: status de orquestração personalizado no formato JSON.
• Saída: a saída da função como um valor JSON (se a função tiver sido concluída). Se a função de orquestrador falhar, essa propriedade incluirá os detalhes da falha. Se a função de orquestrador tiver sido suspensa ou encerrada, essa propriedade incluirá o motivo da suspensão ou terminação (se houver).
• RuntimeStatus: um dos seguintes valores:
  • Pendente: A instância foi agendada, mas ainda não foi iniciado em execução.
  • Em execução: a instância começou a ser executada.
  • Concluído: a instância foi concluída normalmente.
  • ContinuedAsNew: a instância reiniciou a si mesma com um novo histórico. Esse estado é transitório.
  • Falha: a instância falhou com um erro.
  • Encerrado: a instância foi interrompida abruptamente.
  • Suspenso: a instância foi suspensa e pode ser retomada posteriormente.
• Histórico: O histórico de execução de orquestração. Esse 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 tenham sido concluídas e o orquestrador tenha retornado. Em outras palavras, não é suficiente para um orquestrador alcançar sua instrução return para que ele seja marcado como Completed. Isso é particularmente relevante para casos em que WhenAny é usado. Esses orquestradores geralmente return antes de todas as tarefas agendadas terem sido executadas.

Esse método retornará 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 é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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: ...
}

Confira Iniciar instâncias para a configuração do function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

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

Java

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

Ferramentas principais do Azure Functions

Também é possível obter o status de uma instância de orquestração diretamente usando o func durable get-runtime-status comando em Ferramentas Principais.

Observação

No momento, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O comando durable get-runtime-status usa os seguintes parâmetros:

• id (obrigatório): ID da instância de orquestração.
• show-input (opcional): se definido como true, a resposta contém a entrada da função. O valor padrão é false.
• show-output (opcional): se definido como true, a resposta contém a saída da função. O valor padrão é false.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Ele também pode ser definido em host.jsonusando durableTask:HubName.

O comando a seguir recupera o status (incluindo entrada e saída) de uma instância com uma ID de instância de orquestração de 0ab8c55a66644d68a3a8b220b12d209c. Ele pressupõe que você esteja executando o func comando do diretório raiz do aplicativo de funções:

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

Você pode usar o durable get-history comando para recuperar o histórico de uma instância de orquestração. Ele usa os seguintes parâmetros:

• id (obrigatório): ID da instância de orquestração.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Ele também pode ser definido em host.jsonusando durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

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 que correspondem 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 é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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));
    });
};

Confira Iniciar instâncias para a configuração do function.json.

Python

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


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

    instances = await client.get_status_all()

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

Confira Iniciar instâncias para a configuração do function.json.

PowerShell

Observação

Atualmente, não há suporte para esse recurso no PowerShell, mas pode ser obtido usando a API HTTP de Funções Duráveis.

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

Ferramentas principais do Azure Functions

Também é possível consultar instâncias diretamente usando o func durable get-instances comando em Ferramentas Principais.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O comando durable get-instances usa os seguintes parâmetros:

• top (opcional): esse comando dá suporte à paginação. Esse parâmetro corresponde ao número de instâncias recuperadas por solicitação. O padrão é 10.
• continuation-token (opcional): um token para indicar qual página ou seção de instâncias recuperar. Cada get-instances execução retorna um token para o próximo conjunto de instâncias.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Ele também pode ser definido em host.jsonusando durableTask:HubName.

func durable get-instances

Consultar instâncias com filtros

E se você realmente não precisar de todas as informações que uma consulta de instância padrão pode fornecer? Por exemplo, e se você estiver apenas procurando a hora de criação da orquestração ou o status do runtime da orquestração? Você pode restringir 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 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));
    }
}

Observação

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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));
    });
};

Confira Iniciar instâncias para a configuração do 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

Atualmente, não há suporte para esse recurso no PowerShell, mas pode ser obtido usando a API HTTP de Funções Duráveis.

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

Ferramentas principais do Azure Functions

Nas Ferramentas Principais do Azure Functions, você também pode usar o durable get-instances comando com filtros. Além dos parâmetros mencionados top, continuation-token, connection-string-setting e task-hub-name acima, você pode usar três parâmetros de filtro (created-after, created-before e runtime-status).

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

A seguir estão os parâmetros para o durable get-instances comando.

• created-after (opcional): recupere as instâncias criadas após essa data/hora (UTC). Datas e horas formatadas em ISO 8601 aceitas.
• created-before (opcional): recupere as instâncias criadas antes desta data/hora (UTC). Datas e horas no formato ISO 8601 aceitas.
• runtime-status (opcional): recupere as instâncias com um status específico (por exemplo, em execução ou concluída). Pode fornecer múltiplos status, separados por espaço.
• top (opcional): número de instâncias recuperadas por solicitação. O padrão é 10.
• continuation-token (opcional): um token para indicar qual página ou seção de instâncias recuperar. Cada get-instances execução retorna um token para o próximo conjunto de instâncias.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Ele também pode ser definido em host.jsonusando durableTask:HubName.

Se você não fornecer filtros (created-afterou created-beforeruntime-status), o comando simplesmente recuperará instânciastop, sem levar em conta o status do runtime ou o tempo de criação.

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

Encerrar instâncias

Se você tiver uma instância de orquestração que está demorando muito para ser executada ou só precisa pará-la antes que ela seja concluída por qualquer motivo, você pode encerrá-la.

Os dois parâmetros para a API terminada são uma ID de instância e uma cadeia de caracteres de motivo, que são gravados em logs no status 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 é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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);
};

Confira Iniciar instâncias para a configuração do 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);
}

Uma instância encerrada eventualmente fará a transição para o Terminated estado. No entanto, essa transição não acontecerá imediatamente. Em vez disso, a operação de encerramento será enfileirada no hub de tarefas junto com outras operações para essa 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

O encerramento da instância não propaga no momento. As funções de atividade e as suborquestrações são executadas por completo, independentemente de você ter terminado a instância de orquestração que as chamou.

Suspender e retomar instâncias

Suspender uma orquestração permite interromper uma orquestração que está em execução. Ao contrário do encerramento, você tem a opção de retomar um orquestrador suspenso em um momento posterior.

Os dois parâmetros para a API de suspensão são uma 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 Durable Functions PowerShell SDK autônomo. Veja a diferença entre o SDK autônomo e o SDK interno herdado, juntamente 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);
}

Uma instância suspensa eventualmente fará a transição para o Suspended estado. No entanto, essa transição não acontecerá imediatamente. Em vez disso, a operação de suspensão será enfileirada no hub de tarefas junto com outras operações para essa instância. Você pode usar as APIs de consulta de instância para saber quando uma instância em execução realmente atingiu o estado Suspenso.

Quando um orquestrador suspenso for retomado, o status dele será alterado de volta para Running.

Ferramentas principais do Azure Functions

Você também pode encerrar uma instância de orquestração diretamente usando o func durable terminate comando nas Ferramentas Principais.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O comando durable terminate usa os seguintes parâmetros:

• id (obrigatório): ID da instância de orquestração a ser encerrada.
• reason (opcional): motivo do encerramento.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Ele também pode ser definido em host.jsonusando durableTask:HubName.

O comando a seguir encerra uma instância de orquestração com uma ID de 0ab8c55a66644d68a3a8b220b12d209c:

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

Enviar eventos para instâncias

Em alguns cenários, as funções de orquestrador têm a capacidade de aguardar e escutar eventos externos. Exemplos de cenários em que isso é útil incluem os cenários de monitoramento e interação humana .

Você pode enviar notificações de eventos a instâncias em execução usando a API de gerar eventos do cliente de orquestração. As orquestrações podem escutar e responder a esses eventos usando a API do orquestrador de espera por evento externo.

Os parâmetros para evento de aumento são os seguintes:

• 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 serializável JSON a ser enviada para a 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 é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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);
};

Confira Iniciar instâncias para a configuração do 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);
}

Observação

Se não houver nenhuma instância de orquestração com a ID da instância especificada, a mensagem de evento será descartada. Se uma instância existir, mas ainda não estiver aguardando o evento, o evento será armazenado no estado da instância até que esteja pronto para ser recebido e processado.

Ferramentas principais do Azure Functions

Você também pode gerar um evento diretamente para uma instância de orquestração usando o func durable raise-event comando em Ferramentas Principais.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O comando durable raise-event usa os seguintes parâmetros:

• id (obrigatório): ID da instância de orquestração.
• event-name: nome do evento a ser gerado.
• event-data (opcional): dados a serem enviados para a instância de orquestração. Esse pode ser o caminho para um arquivo JSON ou você pode fornecer os dados diretamente na linha de comando.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. O padrão é DurableFunctionsHub. Ele também pode ser definido em host.jsonusando 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

Aguardar a conclusão da orquestração

Em orquestrações de longa execução, talvez você queira esperar e obter os resultados de uma orquestração. Nesses casos, também é útil poder definir um período de tempo limite na orquestração. Se o tempo limite for excedido, o estado da orquestração deverá ser retornado em vez dos resultados.

A API de "aguardar a conclusão ou criar resposta de status de verificação" pode ser usada para obter a saída real de uma instância de orquestração de forma síncrona. Por padrão, esse método tem um tempo limite padrão de 10 segundos e um intervalo de sondagem de 1 segundo.

Aqui está um exemplo de função de gatilho HTTP 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;
}

Confira Iniciar instâncias para a configuração do 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

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

Java

No momento, o Java não tem um único método para esse cenário. No entanto, ele pode ser implementado usando algumas linhas extras 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);
    }
}

Chame a função com a linha a seguir. Use 2 segundos para o tempo limite e 0,5 segundo para o intervalo de repetição:

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 de orquestrador nomeada E1_HelloSequence em seu projeto. Devido à forma como a função de gatilho HTTP é gravada, você pode substituí-la pelo nome de qualquer função de orquestrador em seu projeto.

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

• As instâncias de orquestração são concluídas dentro do tempo limite definido (nesse caso, 2 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 podem ser concluídas dentro do tempo limite 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 das URLs do webhook pode ser diferente, dependendo de qual versão do host do Azure Functions você está executando. O exemplo anterior é para o host do Azure Functions 3.0.

Recuperar URLs do webhook de gerenciamento de HTTP

Você pode usar um sistema externo para monitorar ou gerar eventos para uma orquestração. Os sistemas externos podem se comunicar com o Durable Functions por meio das URLs de webhook que fazem parte da resposta padrão descrita na descoberta da URL da API HTTP. Como alternativa, as URLs de webhook podem ser acessadas programaticamente usando a associação de cliente de orquestração. Especificamente, a API de payload de gerenciamento HTTP pode ser usada para obter um objeto serializável que contém essas URLs de webhook.

A interface de programação de aplicativos para criação do payload 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: a ID da instância da orquestração (deve ser a mesma que a InstanceId entrada).
• StatusQueryGetUri: a URL de status da instância de orquestração.
• SendEventPostUri: a URL "raise event" da instância de orquestração.
• TerminatePostUri: a URL "terminate" da instância de orquestração.
• PurgeHistoryDeleteUri: a URL "limpar histórico" da instância de orquestração.
• suspendPostUri: A URL "suspender" da instância de orquestração.
• resumePostUri: a URL "resume" da instância de orquestração.

As funções podem enviar instâncias desses objetos para sistemas externos com o objetivo de monitorar ou gerar eventos nas orquestrações relacionadas, conforme mostrado nos exemplos abaixo.

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 é para Durable Functions 2.x. Para durable functions 1.x, você deve usar DurableActivityContext em vez de IDurableActivityContext, você deve usar o OrchestrationClient atributo em vez do DurableClient atributo, e você deve usar o DurableOrchestrationClient tipo de parâmetro em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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,
    });
};

Confira Iniciar instâncias para a configuração do 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

Atualmente, não há suporte para esse recurso no Java.

Retroceder instâncias (versão prévia)

Se você tiver uma falha de orquestração por um motivo inesperado, poderá retroceder a instância para um estado saudável anterior usando uma API específica.

Observação

Essa API não se destina a ser uma substituição para políticas adequadas de tratamento de erros e repetição. Em vez disso, destina-se a ser usada apenas em casos em que as instâncias de orquestração falhem por motivos inesperados. Orquestrações em estados diferentes de Failed (por exemplo, Running, Pending, Terminated, Completed) não podem ser "rebobinadas". Para obter mais informações sobre tratamento de erros e políticas de repetição, consulte o artigo tratamento de erros .

Use o métodoRewindAsync (.NET) ou rewind (JavaScript) da associação de cliente de orquestração para devolver a orquestração ao estado Running. Esse método também executará novamente as falhas de execução da atividade ou da suborquestração que causaram a falha de orquestração.

Por exemplo, digamos que você tenha um fluxo de trabalho envolvendo uma série de aprovações humanas. Suponha que haja uma série de funções de atividade que notifiquem alguém de que sua aprovação é necessária e aguardem a resposta em tempo real. Depois que todas as atividades de aprovação tiverem recebido respostas ou tempo limite, suponha que outra atividade falhe devido a uma configuração incorreta do aplicativo, como uma cadeia de conexão de banco de dados inválida. O resultado é uma falha de orquestração profunda no fluxo de trabalho. Com a RewindAsync API (.NET) ou rewind (JavaScript), um administrador de aplicativos pode corrigir o erro de configuração e retroceder a orquestração com falha de volta ao estado imediatamente antes da falha. Nenhuma das etapas de interação humana precisa ser re-aprovada e a orquestração agora pode ser concluída com êxito.

Observação

O recurso de retroceder não dá suporte para retroceder instâncias de orquestração que usam 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 é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira 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);
};

Confira Iniciar instâncias para a configuração do function.json.

Python

Observação

Atualmente, não há suporte para esse recurso no Python.

PowerShell

Observação

Atualmente, não há suporte para esse recurso no PowerShell.

Java

Observação

Atualmente, não há suporte para esse recurso no Java.

Ferramentas principais do Azure Functions

Você também pode retroceder uma instância de orquestração diretamente usando o comando func durable rewind no Core Tools.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O comando durable rewind usa os seguintes parâmetros:

• id (obrigatório): ID da instância de orquestração.
• reason (opcional): motivo para reiniciar a instância de orquestração.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. Por padrão, o nome do hub de tarefas no arquivo host.json é usado.

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

Limpar o histórico da instância

Para remover todos os dados associados a uma orquestração, você pode limpar o histórico da instância. Por exemplo, talvez você queira excluir todos os recursos de armazenamento associados a uma instância concluída. Para fazer isso, use a API de instância de limpeza definida pelo cliente de orquestração.

Este primeiro exemplo mostra como limpar 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);
};

Confira Iniciar instâncias para a configuração do 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, não há suporte para esse recurso no PowerShell, mas pode ser obtido 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();
    }
}

O exemplo a seguir mostra uma função disparada pelo temporizador que limpa o histórico de todas as instâncias de orquestração que foram 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á agendada para ser executada uma vez por dia, às 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
        });
}

Observação

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar o atributo OrchestrationClient em vez do atributo DurableClient e deve usar o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, confira o artigo Versões do Durable Functions.

JavaScript

O método purgeInstanceHistoryBy pode ser usado para limpar 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 destino o 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, não há suporte para esse recurso no PowerShell, mas pode ser obtido 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()));
}

Observação

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

Ferramentas principais do Azure Functions

Você pode limpar o histórico de uma instância de orquestração usando o func durable purge-history comando no Core Tools. Semelhante ao segundo exemplo de C# na seção anterior, ele limpa o histórico de todas as instâncias de orquestração criadas durante um intervalo de tempo especificado. Você pode filtrar ainda mais instâncias limpas por status de runtime.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O durable purge-history comando tem vários parâmetros:

• created-after (opcional): limpe o histórico de instâncias criadas após essa data/hora (UTC). Datas e horas no formato ISO 8601 aceitas.
• created-before (opcional): limpe o histórico de instâncias criadas antes desta data/hora (UTC). Datas e horas no formato ISO 8601 aceitas.
• runtime-status (opcional): limpe o histórico de instâncias com um status específico (por exemplo, em execução ou concluído). Pode fornecer múltiplos status, separados por espaço.
• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. Por padrão, o nome do hub de tarefas no arquivo host.json é usado.

O comando a seguir exclui o histórico de todas as instâncias com falha criadas antes de 14 de novembro de 2021 às 19h35 (UTC).

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

Excluir um hub de tarefas

Usando o func durable delete-task-hub comando nas Ferramentas Principais, você pode excluir todos os artefatos de armazenamento associados a um hub de tarefas específico, incluindo tabelas de armazenamento do Azure, filas e blobs.

Observação

No momento, os comandos core tools só têm suporte ao usar o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

O durable delete-task-hub comando tem dois parâmetros:

• connection-string-setting (opcional): nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional): nome do hub de tarefas Durable Functions a ser usado. Por padrão, o nome do hub de tarefas no arquivo host.json é usado.

O comando a seguir exclui todos os dados de armazenamento do Azure associados ao UserTest hub de tarefas.

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

Próximas etapas

Saiba como lidar com o controle de versão

Referência de API HTTP interna para gerenciamento de instância