Gerenciar instâncias em 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 associação de cliente de orquestração do Durable Functions, como o envio de eventos externos para instâncias, a limpeza do histórico de instâncias etc. Este artigo mostra os detalhes de todas as operações de gerenciamento de instância compatíveis.

Iniciar instâncias

O método start-new (ou schedule-new) na e 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 do Durable Functions e retorna. Essa mensagem dispara de maneira 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 de instância sempre que possível. As IDs de instância aleatórias ajudam a garantir uma distribuição de carga igual ao dimensionar funções de orquestrador entre várias VMs. O momento adequado para usar IDs de instância não aleatórias é quando a ID precisar ser proveniente de uma fonte externa ou ao implementar o padrão de 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 o 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 os seguintes 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 se destina ao 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 os seguintes 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 se destina ao 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 os seguintes 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 se destina ao 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 começar antes de retornar de sua função, também poderá 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));

Azure Functions Core Tools

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

• function-name (obrigatório) : nome da função para iniciar.
• input (opcional) : entrada para a função, seja embutida ou por meio de um arquivo JSON. Para arquivos, adicione um prefixo para o caminho para o arquivo com @, como @path/to/file.json.
• id (optional) : a ID da instância de orquestração. Se você não especificar esse parâmetro, o método usará um GUID aleatório.
• connection-string-setting (opcional) : nome da configuração do aplicativo que contém a cadeia de caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do 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 do Core Tools supõem que elas estão sendo executadas do 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 seja possível executar esses comandos sem um host de aplicativo de funções em execução, você pode achar que não é possível 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

Atualmente, só há suporte para os comandos do Core Tools se você está usando o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

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

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, você provavelmente precisará consultar seu status de runtime para saber se elas estão em execução, se foram concluídas ou se 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) e showHistoryOutput (opcional) e showInput (opcional) como parâmetros.

• showHistory : se definido para 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 da atividade.
• showInput : se definido para false, a resposta contém a entrada da função. O valor padrão é true.

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

• Name: o nome da função de orquestrador.
• InstanceId: a ID da instância de orquestração (deve ser o mesmo que a entrada instanceId).
• 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.
• Input: a entrada da função como um valor JSON. Esse campo não será preenchido se showInput for false.
• CustomStatus: status de orquestração personalizado no formato JSON.
• Output: a saída da função como um valor JSON (se a função tiver sido concluída). Se a função de orquestrador tiver falhado, essa propriedade incluirá os detalhes da falha. Se a função do orquestrador tiver sido suspensa ou terminada, essa propriedade incluirá o motivo da suspensão ou do encerramento (se houver).
• RuntimeStatus: um dos seguintes valores:
  • Pendente: A instância foi agendada, mas ainda não foi iniciado em execução.
  • Running: a instância começou a ser executada.
  • Completed: a instância foi concluída normalmente.
  • ContinuedAsNew: a instância reiniciou a si mesma com um novo histórico. Este é um estado transiente.
  • Failed: a instância falhou com um erro.
  • Terminated: a instância foi interrompida abruptamente.
  • Suspended: a instância foi suspensa e poderá ser retomada posteriormente.
• Histórico: O histórico de execução de orquestração. Este campo é preenchido somente se showHistory é 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 o 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
        }
    }
}

Azure Functions Core Tools

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

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando 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) : a ID da instância de orquestração.
• show-input (opcional) : se definido como true, a resposta conterá a entrada da função. O valor padrão é false.
• show-output (opcional) : se definido como true, a resposta conterá 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 caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do Durable Functions a ser usado. O padrão é DurableFunctionsHub. Também pode ser definido no host.json usando durableTask:HubName.

O comando a seguir recupera o status (incluindo entrada e saída) de uma instância com uma ID da instância de orquestração de 0ab8c55a66644d68a3a8b220b12d209c. Ele pressupõe que você está executando o comando func 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 comando durable get-history para recuperar o histórico de uma instância de orquestração. Ele usa os seguintes parâmetros:

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

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

Consultar todas as instâncias

Você pode usar as 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 é para Durable Functions 2.x. Para o 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 do Durable Functions.

Java

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

Azure Functions Core Tools

Também é possível consultar as instâncias diretamente usando o comando func durable get-instances no Core Tools.

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando 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) : este 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 a serem recuperados. 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 caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do Durable Functions a ser usado. O padrão é DurableFunctionsHub. Também pode ser definido no host.json usando durableTask:HubName.

func durable get-instances

Consultar instâncias com filtros

E se você não precisar realmente 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 o 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 do Durable Functions.

Java

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

Azure Functions Core Tools

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

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

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

• created-after (opcional) : recuperar as instâncias criadas após essa data/hora (UTC). Datetimes formato ISO 8601 aceito.
• created-before (opcional) : recuperar as instâncias criadas antes dessa hora/data (UTC). Datetimes formato ISO 8601 aceito.
• runtime-status (opcional) : recuperar as instâncias com um status específico (por exemplo, running ou completed). Pode fornecer o status de vários (separado 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 a serem recuperados. 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 caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do Durable Functions a ser usado. O padrão é DurableFunctionsHub. Também pode ser definido no host.json usando durableTask:HubName.

Se você não fornece filtros (created-after, created-before ou runtime-status), o comando simplesmente recupera instâncias top, sem considerar 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 demorando muito para ser executada ou apenas precisar interrompê-la antes de ser concluída por qualquer motivo, você poderá 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 o 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 estado Terminated. No entanto, essa transição não ocorrerá 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 estado Terminated.

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 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 suspensa são uma ID de instância e uma cadeia de caracteres de motivo, que são gravadas em logs no status da instância.

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    DateTime dueTime = context.CurrentUtcDateTime.AddSeconds(30);
    await context.CreateTimer(dueTime, CancellationToken.None);
    
    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);

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

    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.  
    const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime, {zone: 'utc'}).plus({ seconds: 30 });
    yield context.df.createTimer(deadline.toJSDate());

    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)

    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    due_time = context.current_utc_datetime + timedelta(seconds=30)
    yield context.create_timer(due_time)

    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$SuspendReason = 'Need to pause workflow'

Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# Wait for 30 seconds to ensure that the orchestrator state is updated to suspended.
$duration = New-TimeSpan -Seconds 30
Start-DurableTimer -Duration $duration

$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

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();  
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // Wait for 30 seconds to ensure that the orchestrator state is updated to suspended. 
    ctx.createTimer(Duration.ofSeconds(30)).await();

    String resumeReason = "Continue workflow";
    client.getClient().resumeInstance(instanceID, resumeReason);
}

Uma instância suspensa acabará fazendo a transição para o estado Suspended. No entanto, essa transição não ocorrerá 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.

Azure Functions Core Tools

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

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando 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) : a ID da instância de orquestração para encerrar.
• reason (opcional) : motivo do término.
• connection-string-setting (opcional) : nome da configuração do aplicativo que contém a cadeia de caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do Durable Functions a ser usado. O padrão é DurableFunctionsHub. Também pode ser definido no host.json usando durableTask:HubName.

O seguinte comando 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. Os cenários de exemplo em que isso é útil incluem os cenários de monitoramento e de 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 gerar eventos são os seguintes:

• ID de instância: a ID exclusiva da instância.
• Nome do evento: o nome do evento a ser enviado.
• Dados do evento: um payload serializável em JSON para enviar 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 o 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 é 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.

Azure Functions Core Tools

Você também pode acionar um evento para uma instância de orquestração diretamente usando o comando func durable raise-event no Core Tools.

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando 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) : a 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. Isso 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 caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do Durable Functions a ser usado. O padrão é DurableFunctionsHub. Também pode ser definido no host.json usando 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 ser capaz de 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.

Veja um exemplo de função de gatilho HTTP que demonstra como usar essa 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), a resposta é a saída de instância de orquestração real entregue sincronicamente:

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 é o padrão descrito na Descoberta de URL na 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 de webhook pode variar dependendo de qual versão do host do Azure Functions você está executando. O exemplo acima refere-se ao 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 do webhook que fazem parte da resposta padrão descrita na Descoberta de URL na 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 API de payload de gerenciamento HTTP de criação tem um parâmetro:

• ID de 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 da entrada InstanceId).
• 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 "retomar" da instância de orquestração.

O Functions pode enviar instâncias desses objetos a sistemas externos para monitorar ou gerar eventos nas orquestrações correspondentes, conforme mostrado nos exemplos a seguir:

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 o Durable Functions 1.x, você deve usar DurableActivityContext em vez de IDurableActivityContext, usar o atributo OrchestrationClient em vez de o DurableClient e usar o tipo de parâmetro DurableOrchestrationClient em vez de o 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

No momento, 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 de integridade anterior usando uma API criada para essa finalidade.

Observação

Essa API não pretende ser uma substituição para as políticas de repetição e de tratamento de erros apropriadas. 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 políticas de repetição e tratamento de erro, confira o artigo Tratamento de erro.

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 que envolva uma série de aprovações humanas. Suponha que haja uma série de funções de atividade que notifique alguém sobre a necessidade de aprovação e aguarde a resposta em tempo real. Depois de todas as atividades de aprovação terem recebido respostas ou atingido o tempo limite, suponha que outra atividade falha devido a um erro de configuração do aplicativo, como uma cadeia de conexão de banco de dados inválida. O resultado é uma falha de orquestração profundamente no fluxo de trabalho. Com a API RewindAsync (.NET) ou rewind (JavaScript), um administrador do aplicativo pode corrigir o erro de configuração e retrocede a orquestração com falha de volta para o estado imediatamente anterior à falha. Nenhuma das etapas com interação humana precisa ser aprovada novamente e a orquestração pode agora 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 o 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

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

PowerShell

Observação

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

Java

Observação

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

Azure Functions Core Tools

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

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando 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) : a ID da instância de orquestração.
• reason (opcional) : o motivo para retroceder a instância de orquestração.
• connection-string-setting (opcional) : nome da configuração do aplicativo que contém a cadeia de caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do 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 quaisquer 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 do Durable Functions.

Java

@FunctionName("PurgeInstance")
public HttpResponseMessage purgeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}, route = "purge/{instanceID}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("instanceID") String instanceID) {
    PurgeResult result = durableContext.getClient().purgeInstance(instanceID);
    if (result.getDeletedInstanceCount() == 0) {
        return req.createResponseBuilder(HttpStatus.NOT_FOUND)
                .body("No completed instance with ID '" + instanceID + "' was found!")
                .build();
    } else {
        return req.createResponseBuilder(HttpStatus.OK)
                .body("Successfully purged data for " + instanceID)
                .build();
    }
}

O próximo exemplo mostra uma função disparada por temporizador que limpa o histórico de todas as instâncias de orquestração concluída após o intervalo de tempo especificado. Nesse caso, ela removerá os dados para 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 o 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 da instância para 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 se destina ao 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 do Durable Functions.

Python

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

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

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

Java

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

Observação

Para que a operação limpar histórico seja concluída com êxito, o status do runtime da instância de destino deve ser Completed, Terminated ou Failed.

Azure Functions Core Tools

Você pode limpar o histórico de uma instância de orquestração usando o comando func durable purge-history no Core Tools. Semelhante ao segundo exemplo 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 as instâncias limpas por status do runtime.

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

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

• created-after (opcional) : limpar as instâncias criadas após essa data/hora (UTC). Datetimes formato ISO 8601 aceito.
• created-before (opcional) : limpar as instâncias criadas depois dessa data/hora (UTC). Datetimes formato ISO 8601 aceito.
• runtime-status (opcional) : limpar o histórico de instâncias com um status específico (por exemplo, running ou completed). Pode fornecer o status de vários (separado por espaço).
• connection-string-setting (opcional) : nome da configuração do aplicativo que contém a cadeia de caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do 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 no Core Tools, você pode excluir todos os artefatos de armazenamento associados a um hub de tarefas específico, incluindo tabelas, filas e blobs de armazenamento do Azure.

Observação

Atualmente, só há suporte para os comandos do Core Tools se você está usando o provedor de Armazenamento do Azure padrão para manter o estado de runtime.

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

• connection-string-setting (opcional) : nome da configuração do aplicativo que contém a cadeia de caracteres de conexão de armazenamento para usar. O padrão é AzureWebJobsStorage.
• task-hub-name (opcional) : nome do hub de tarefas do 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 hub de tarefas UserTest.

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