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

As orquestrações em funções duráveis são funções com monitoração de estado de longa duração que podem ser iniciadas, consultadas, suspensas, retomadas e encerradas usando APIs de gerenciamento internas. Várias outras APIs de gerenciamento de instâncias também são expostas pela vinculação do cliente de orquestração de funções duráveis, como o envio de eventos externos para instâncias, limpeza do histórico de instâncias, etc. Este artigo aborda os detalhes de todas as operações de gerenciamento 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.

Gorjeta

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

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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
}

Nota

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

index.js

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

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

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

Python

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

function.json

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

Nota

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
}

Nota

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

Azure Functions Core Tools

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.

Nota

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 parâmetros e task-hub-name , poderá executar os connection-string-setting 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 start-new comando enfileira uma mensagem inicial no 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ção em execução que possa processar a mensagem.

Nota

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 será 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 da falha. 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 recomeçou-se com uma nova história. 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.

Nota

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

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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.

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 func durable get-runtime-status comando em Core Tools.

Nota

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 comando para recuperar o durable get-history histórico de uma instância de orquestração. Ele leva 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.
}

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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.

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

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

PowerShell

Nota

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

Azure Functions Core Tools

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

Nota

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

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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.

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

Nota

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

Azure Functions Core Tools

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

Nota

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/datas aceites formatadas ISO 8601.
• created-before (opcional): Recupere as instâncias criadas antes desta data/hora (UTC). Datas/datas aceites formatadas ISO 8601.
• runtime-status (opcional): recupere as instâncias com um status específico (por exemplo, em execução ou concluídas). Pode fornecer vários status (espaço separado).
• 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 você não fornecer nenhum filtro (created-after, , ou ), o comando simplesmente recuperará top instâncias, created-beforesem considerar o status do tempo de execução ou runtime-statuso 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);
}

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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.

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 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á enfileirada no hub de tarefas junto com outras operações para essa instância. Você pode usar as APIs de consulta de instância para saber quando uma instância encerrada realmente atingiu o Terminated estado.

Nota

Atualmente, o encerramento da instância não se propaga. As funções de atividade e as suborquestrações são executadas até a conclusão, independentemente de você 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)
{
    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á 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á 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 é retomado, seu status será alterado novamente para Running.

Azure Functions Core Tools

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

Nota

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 usando a API de evento raise do cliente de orquestração. As orquestrações podem ouvir e responder a esses eventos usando a API do orquestrador de eventos externo de espera.

Os parâmetros para o evento raise 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);
}

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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 Iniciar instâncias para a configuração function.json.

Python

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

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

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

PowerShell

param($Request, $TriggerMetadata)

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

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

Java

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

Nota

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.

Azure Functions Core Tools

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.

Nota

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, o estado da orquestração deve ser retornado em vez dos resultados.

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

Aqui está um exemplo de função 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.

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

Nota

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"

Nota

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

Nota

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 se comunicar com funções duráveis por meio das URLs de webhook que fazem parte da resposta padrão descrita na descoberta de URL de API HTTP. Como alternativa, as URLs do webhook podem ser acessadas programaticamente usando a associação do cliente de orquestração. Especificamente, a API de carga útil de gerenciamento HTTP de criação pode ser usada para obter um objeto serializável que contenha essas URLs de webhook.

A API de carga útil de gerenciamento HTTP create tem 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: A URL de "evento de aumento" da instância de orquestração.
• TerminatePostUri: A URL "terminate" da instância de orquestração.
• PurgeHistoryDeleteUri: A URL "purge history" da instância de orquestração.
• suspendPostUri: A 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 };
}

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar em vez de , você deve usar o atributo em vez do atributo e você deve usar DurableActivityContext o DurableOrchestrationClientOrchestrationClient tipo de DurableClient parâmetro em vez de IDurableOrchestrationClientIDurableActivityContext. 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.

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

Nota

Este recurso não é suportado atualmente em Java.

Retroceder instâncias (visualização)

Se você tiver uma falha de orquestração por um motivo inesperado, poderá retroceder a instância para um estado anteriormente íntegro usando uma API criada para essa finalidade.

Nota

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, TerminatedCompleted) 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 RewindAsync método (.NET) ou rewind (JavaScript) da ligação do cliente de orquestração para colocar a orquestração de volta no estado de execução . 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 API (.NET) ou rewind (JavaScript), um administrador de aplicativo pode corrigir o erro de configuração e retroceder a RewindAsync 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.

Nota

O recurso de retrocesso não oferece suporte a instâncias de orquestração de rebobinagem 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);
}

Nota

O código C# anterior é para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar atributo em vez do atributo DurableClient e deve usar OrchestrationClient o DurableOrchestrationClient tipo de parâmetro 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.

Python

Nota

Este recurso não é suportado atualmente em Python.

PowerShell

Nota

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

Java

Nota

Este recurso não é suportado atualmente em Java.

Azure Functions Core Tools

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

Nota

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

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

Nota

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

Nota

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

JavaScript

O purgeInstanceHistoryBy método pode ser usado para limpar condicionalmente o histórico de instâncias 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
}

Nota

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

Nota

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

Python

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

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

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

Java

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

Nota

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.

Azure Functions Core Tools

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 limpas por status de tempo de execução.

Nota

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/datas aceites formatadas ISO 8601.
• created-before (opcional): Limpe o histórico de instâncias criadas antes dessa data/hora (UTC). Datas/datas aceites formatadas ISO 8601.
• 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 vários status (espaço separado).
• 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.

Nota

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