Gerenciar instâncias em funções duráveis no Azure

As orquestrações em funções duráveis são funções com estado de longa duração que podem ser iniciadas, consultadas, suspensas, retomadas e encerradas usando APIs de gerenciamento incorporadas. Várias outras APIs de gestão de instâncias são também disponibilizadas pela associação do cliente de orquestração das Funções Duráveis, como o envio de eventos externos para instâncias, a purgação do histórico de instâncias, etc. Este artigo aborda em detalhe todas as operações de gestão de instâncias suportadas.

Iniciar instâncias

O método start-new (ou schedule-new) na ligação do 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, em seguida, retorna. Esta 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:

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

Sugestão

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

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, 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, consulte o artigo Durable Functions versions .

Javascript

A menos que especificado de outra forma, os exemplos nesta página usam o gatilho HTTP com o seguinte function.json.

function.json

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

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez de durableClient.

index.js

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

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

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

Píton

A menos que especificado de outra forma, os exemplos nesta página usam o gatilho HTTP com o seguinte function.json.

function.json

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

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez de durableClient.

__init__.py

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

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

PowerShell

A menos que especificado de outra forma, os exemplos nesta página usam o gatilho HTTP com o seguinte function.json.

function.json

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

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez de durableClient.

run.ps1

param($Request, $TriggerMetadata)

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

Java

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

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

// 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 Core Tools, que usa os seguintes parâmetros:

• function-name (obrigatório): Nome da função a iniciar.
• input (opcional): Entrada para a função, em linha ou através 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 Funções Duráveis 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 a partir do diretório raiz de um aplicativo de função. Se você fornecer explicitamente os connection-string-setting parâmetros 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ção em execução, você pode achar que não pode observar alguns efeitos, a menos que o host esteja em execução. Por exemplo, o comando start-new enfileira uma mensagem de início no hub de tarefas de destino, mas a orquestração não é efetivamente executada a menos que haja um processo host de aplicação de funções ativo que possa processar a mensagem.

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

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

Instâncias de consulta

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

O método get-status na vinculação do 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 predefinido é true.

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

• Nome: O nome da função orquestradora.
• InstanceId: O ID da instância da orquestração (deve ser o mesmo que a instanceId entrada).
• CreatedTime: A hora em que a função orquestradora começou a ser executada.
• LastUpdatedTime: A hora em que a orquestração foi verificada pela última vez.
• Entrada: A entrada da função como um valor JSON. Este campo não é preenchido se showInput for 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 orchestrator falhou, esta propriedade inclui os detalhes do erro. Se a função de orquestrador foi suspensa ou encerrada, esta propriedade inclui o motivo da suspensão ou rescisão (se houver).
• RuntimeStatus: Um dos seguintes valores:
  • Pendente: A instância foi agendada, mas ainda não começou a ser executada.
  • 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-se com um novo histórico. Este estado é um 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ória: O histórico de execução da orquestração. Este campo só será preenchido se showHistory estiver definido como true.

Observação

Um orquestrador não é marcado como Completed até que todas as suas tarefas programadas tenham terminado e o orquestrador tenha retornado. Por outras palavras, não basta que um orquestrador chegue à sua return declaração para que seja marcado como Completed. Isto é particularmente relevante para os casos em que WhenAny é usado, esses orquestradores muitas vezes return antes de todas as tarefas programadas terem sido executadas.

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

C#

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

Observação

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, 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, consulte o artigo Durable Functions versions .

Javascript

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

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

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

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

Píton

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 Core Tools.

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

O durable get-runtime-status comando 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 predefinido é false.
• show-output (opcional): Se definido como true, a resposta contém a saída da função. O valor predefinido é false.
• connection-string-setting (opcional): Nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis a ser usado. A predefinição é DurableFunctionsHub. Ele também pode ser definido em host.json, usando durableTask:HubName.

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

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. Aceita 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. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis a ser usado. A predefinição é DurableFunctionsHub. Ele também pode ser definido em host.json, usando 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 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 Durable Functions 1.x, 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, consulte o artigo Durable Functions versions .

Javascript

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

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

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

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

Píton

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


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

    instances = await client.get_status_all()

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

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

PowerShell

Observação

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

Java

@FunctionName("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 Core Tools.

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

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

• top (opcional): Este comando suporta 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 deve ser recuperada. 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. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis a ser usado. A predefinição é DurableFunctionsHub. Ele também pode ser definido em host.json, usando 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 o tempo de criação da orquestração ou o status do tempo de execução 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, 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, consulte o artigo Durable Functions versions .

Javascript

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

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

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

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

Píton

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, esse recurso não é suportado no PowerShell, mas pode ser alcançado 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 top, continuation-token, connection-string-setting e task-hub-name acima mencionados, você pode usar três parâmetros de filtro (created-after, created-before e runtime-status).

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

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

• created-after (opcional): Recupere as instâncias criadas após esta data/hora (UTC). Datas aceitas formatadas segundo a norma ISO 8601.
• created-before (opcional): Recupere as instâncias criadas antes desta data/hora (UTC). Datas e horas formatadas de acordo com a norma ISO 8601 são aceites.
• runtime-status (opcional): recupere as instâncias com um status específico (por exemplo, em execução ou concluídas). Pode fornecer múltiplos estados separados por espaços.
• 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 deve ser recuperada. 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. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis a ser usado. A predefinição é DurableFunctionsHub. Ele também pode ser definido em host.json, usando durableTask:HubName.

Se não fornecer quaisquer filtros (created-after, created-before ou runtime-status), o comando simplesmente recuperará instâncias top, sem considerar o status de execução 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 se você só precisa pará-la antes que ela seja concluída por qualquer motivo, você pode encerrá-la.

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

C#

[FunctionName("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, 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, consulte o artigo Durable Functions versions .

Javascript

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

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

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

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

Píton

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 acabará por transitar para o Terminated estado. No entanto, essa transição não acontecerá imediatamente. Em vez disso, a operação de encerramento será colocada na fila do hub de tarefas juntamente 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

Atualmente, o encerramento da instância não se propaga. As funções de atividade e as suborquestrações continuam a ser executadas até à sua conclusão, independentemente de ter encerrado a instância de orquestração que as chamou.

Suspender e retomar instâncias

Suspender uma orquestração permite que você interrompa uma orquestração em execução. Ao contrário da rescisão, 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 um ID de instância e uma cadeia de caracteres de motivo, que são gravados em logs e no status da instância.

C#

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

Javascript

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

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

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

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

Píton

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

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

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

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

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

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

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

Observação

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

Java

@FunctionName("SuspendResumeInstance")
public void suspendResumeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    DurableTaskClient client = durableContext.getClient();  

    // To suspend an orchestration
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // To resume an orchestration
    String resumeReason = "Continue workflow";
    client.resumeInstance(instanceID, resumeReason);
}

Uma instância suspensa acabará por transitar para o Suspended estado. No entanto, essa transição não acontecerá imediatamente. Em vez disso, a operação de suspensão será colocada na fila 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 é retomado, o seu estado será alterado novamente 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 em Core Tools.

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

O durable terminate comando usa os seguintes parâmetros:

• id (obrigatório): ID da instância de orquestração a ser encerrada.
• reason (opcional): Motivo da rescisão.
• connection-string-setting (opcional): Nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis a ser usado. A predefinição é DurableFunctionsHub. Ele também pode ser definido em host.json, usando 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 do orquestrador precisam esperar e ouvir 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 para instâncias em execução através da API de raise event do cliente de orquestração. As orquestrações podem ouvir e responder a esses eventos usando a API do orquestrador de espera de evento externo.

Os parâmetros para gerar evento 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 útil serializável em JSON para enviar à instância.

C#

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

Observação

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, 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, consulte o artigo Durable Functions versions .

Javascript

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

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

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

Consulte a seção Iniciar instâncias para a configuração function.json.

Píton

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 o ID de instância especificado, 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 elevar um evento para uma instância de orquestração diretamente, usando o func durable raise-event comando em Core Tools.

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

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

• id (obrigatório): ID da instância de orquestração.
• event-name: Nome do evento a angariar.
• 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. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis a ser usado. A predefinição é DurableFunctionsHub. Ele também pode ser definido em 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

Aguarde a conclusão da orquestração

Em orquestrações de longa duração, você pode querer 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, deve ser retornado o estado da orquestração em vez dos resultados.

"A API “esperar pela conclusão ou criar resposta de verificação de estado” 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 HTTP-trigger 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;
}

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

Píton

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

timeout = "timeout"
retry_interval = "retryInterval"

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

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

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

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

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

PowerShell

Observação

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

Java

Atualmente, 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 seguinte linha. 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 orchestrator nomeada E1_HelloSequence em seu projeto. Devido a como a função de gatilho HTTP é escrita, você pode substituí-la pelo nome de qualquer função orquestradora em seu projeto.

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

• As instâncias de orquestração são concluídas dentro do tempo limite definido (neste 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 de URL de API HTTP:

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

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

Observação

O formato das URLs do webhook pode ser diferente, dependendo da versão do host do Azure Functions que você está executando. O exemplo anterior é para o host do Azure Functions 3.0.

Recuperar URLs de webhook de gerenciamento HTTP

Você pode usar um sistema externo para monitorar ou elevar eventos a uma orquestração. Os sistemas externos podem comunicar-se com as Funções Duráveis através das URLs de webhook que são parte da resposta padrão descrita na descoberta de URL de API HTTP. Como alternativa, as URLs do webhook podem ser acedidas programaticamente usando a vinculação do cliente de orquestração. Especificamente, a API de criação de carga útil de gestão HTTP pode ser usada para obter um objeto serializável que contenha os URLs de webhook.

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

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

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

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

As funções podem enviar instâncias desses objetos para 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 Durable Functions 1.x, deve usar DurableActivityContext em vez de IDurableActivityContext, o atributo OrchestrationClient em vez do atributo DurableClient, e o tipo de parâmetro DurableOrchestrationClient em vez de IDurableOrchestrationClient. Para obter mais informações sobre as diferenças entre versões, consulte o artigo Durable Functions versions .

Javascript

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

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

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

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

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

Píton

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

Este recurso não é suportado atualmente em Java.

Retroceder instâncias (visualização)

Se tiveres uma falha de orquestração por um motivo imprevisto, poderás retroceder essa instância para um estado previamente saudável usando uma API destinada a esse fim.

Observação

Esta API não se destina a ser um substituto para o tratamento adequado de erros e políticas de novas tentativas. Em vez disso, destina-se a ser usado apenas nos casos em que as instâncias de orquestração falham por razões inesperadas. Orquestrações em estados diferentes de Failed (por exemplo, Running, Pending, Terminated, Completed) não podem ser "rebobinadas". Para obter mais informações sobre políticas de tratamento de erros e novas tentativas, consulte o artigo Tratamento de erros .

Use o método RewindAsync (.NET) ou rewind (JavaScript) da ligação do cliente de orquestração para colocar a orquestração de volta no estado Running. Esse método também executará novamente as falhas de execução de atividade ou 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 há uma série de funções de atividade que notificam alguém de que sua aprovação é necessária e aguardam a resposta em tempo real. Depois que todas as atividades de aprovação tiverem recebido respostas ou expirado, 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 aplicativo 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 reaprovada, e a orquestração agora pode ser concluída com sucesso.

Observação

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

C#

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

Observação

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, 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, consulte o artigo Durable Functions versions .

Javascript

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

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

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

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

Píton

Observação

Este recurso não é suportado atualmente em Python.

PowerShell

Observação

No momento, esse recurso não é suportado no PowerShell.

Java

Observação

Este recurso não é suportado atualmente em Java.

Ferramentas principais do Azure Functions

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

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

O durable rewind comando 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. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis 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 histórico de instâncias

Para remover todos os dados associados a uma orquestração, você pode limpar o histórico de instâncias. 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);
};

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

Píton

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

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

    return await client.purge_instance_history(instance_id)

PowerShell

Observação

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

Java

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

O próximo exemplo mostra uma função acionada por temporizador que limpa o histórico de todas as instâncias de orquestração concluídas após o intervalo de tempo especificado. Nesse caso, ele remove dados de todas as instâncias concluídas há 30 ou mais dias. Esta função de exemplo está programada para ser executada uma vez por dia, às 12:00 PM UTC:

C#

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

Observação

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, 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, consulte o artigo Durable Functions versions .

Javascript

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

function.json

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

Observação

Este exemplo tem como alvo Durable Functions versão 2.x. Na versão 1.x, use orchestrationClient em vez de durableClient.

index.js

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

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

PowerShell

Observação

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

Píton

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 do histórico de limpeza seja bem-sucedida, o status do tempo de execução da instância de destino deve ser Concluído, Encerrado ou Falhado.

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 em Ferramentas principais. 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 purgadas por estado de execução.

Observação

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

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 formatadas de acordo com a norma ISO 8601 são aceites.
• created-before (opcional): Limpe o histórico de instâncias criadas antes dessa data/hora (UTC). Datas e horas formatadas de acordo com a norma ISO 8601 são aceites.
• runtime-status (opcional): limpe o histórico de instâncias com um status específico (por exemplo, em execução ou concluída). Pode fornecer múltiplos estados separados por espaços.
• connection-string-setting (opcional): Nome da configuração do aplicativo que contém a cadeia de conexão de armazenamento a ser usada. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis 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 em 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

Atualmente, os comandos das Ferramentas Principais só têm suporte ao usar o provedor de Armazenamento do Azure padrão para o estado de tempo de execução persistente.

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. A predefinição é AzureWebJobsStorage.
• task-hub-name (opcional): Nome do hub de tarefas Funções Duráveis 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 UserTest tarefas.

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

Próximos passos

Saiba como lidar com o controle de versão

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