Estado da orquestração personalizada no Durable Functions (Funções do Azure)

  • Artigo

O estado de orquestração personalizado permite-lhe definir um valor de estado personalizado para a função do orquestrador. Este estado é fornecido através da API HTTP GetStatus ou da API do SDK equivalente no objeto de cliente orchestration.

Exemplos de casos de utilização

Visualizar o progresso

Os clientes podem consultar o ponto final de estado e apresentar uma IU de progresso que visualiza a fase de execução atual. O exemplo seguinte demonstra a partilha do progresso:

Nota

Estes exemplos de C# são escritos para Durable Functions 2.x e não são compatíveis com Durable Functions 1.x. Para obter mais informações sobre as diferenças entre versões, veja o artigo Durable Functions versões.

[FunctionName("E1_HelloSequence")]
public static async Task<List<string>> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var outputs = new List<string>();

    outputs.Add(await context.CallActivityAsync<string>("E1_SayHello", "Tokyo"));
    context.SetCustomStatus("Tokyo");
    outputs.Add(await context.CallActivityAsync<string>("E1_SayHello", "Seattle"));
    context.SetCustomStatus("Seattle");
    outputs.Add(await context.CallActivityAsync<string>("E1_SayHello", "London"));
    context.SetCustomStatus("London");

    // returns ["Hello Tokyo!", "Hello Seattle!", "Hello London!"]
    return outputs;
}

[FunctionName("E1_SayHello")]
public static string SayHello([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

Em seguida, o cliente receberá a saída da orquestração apenas quando CustomStatus o campo estiver definido como "Londres":

[FunctionName("HttpStart")]
public static async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient starter,
    string functionName,
    ILogger log)
{
    // Function input comes from the request content.
    dynamic eventData = await req.Content.ReadAsAsync<object>();
    string instanceId = await starter.StartNewAsync(functionName, (string)eventData);

    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

    DurableOrchestrationStatus durableOrchestrationStatus = await starter.GetStatusAsync(instanceId);
    while (durableOrchestrationStatus.CustomStatus.ToString() != "London")
    {
        await Task.Delay(200);
        durableOrchestrationStatus = await starter.GetStatusAsync(instanceId);
    }

    HttpResponseMessage httpResponseMessage = new HttpResponseMessage(HttpStatusCode.OK)
    {
        Content = new StringContent(JsonConvert.SerializeObject(durableOrchestrationStatus))
    };

    return httpResponseMessage;
  }
}

Personalização de saída

Outro cenário interessante é segmentar os utilizadores ao devolver uma saída personalizada com base em características ou interações exclusivas. Com a ajuda do estado de orquestração personalizado, o código do lado do cliente permanecerá genérico. Todas as principais modificações ocorrerão no lado do servidor, conforme mostrado no exemplo seguinte:

[FunctionName("CityRecommender")]
public static void Run(
  [OrchestrationTrigger] IDurableOrchestrationContext context)
{
  int userChoice = context.GetInput<int>();

  switch (userChoice)
  {
    case 1:
    context.SetCustomStatus(new
    {
      recommendedCities = new[] {"Tokyo", "Seattle"},
      recommendedSeasons = new[] {"Spring", "Summer"}
     });
      break;
    case 2:
      context.SetCustomStatus(new
      {
        recommendedCities = new[] {"Seattle, London"},
        recommendedSeasons = new[] {"Summer"}
      });
        break;
      case 3:
      context.SetCustomStatus(new
      {
        recommendedCities = new[] {"Tokyo, London"},
        recommendedSeasons = new[] {"Spring", "Summer"}
      });
        break;
  }

  // Wait for user selection and refine the recommendation
}

Especificação da instrução

O orquestrador pode fornecer instruções exclusivas aos clientes através do estado personalizado. As instruções de estado personalizado serão mapeadas para os passos no código de orquestração:

[FunctionName("ReserveTicket")]
public static async Task<bool> Run(
  [OrchestrationTrigger] IDurableOrchestrationContext context)
{
  string userId = context.GetInput<string>();

  int discount = await context.CallActivityAsync<int>("CalculateDiscount", userId);

  context.SetCustomStatus(new
  {
    discount = discount,
    discountTimeout = 60,
    bookingUrl = "https://www.myawesomebookingweb.com",
  });

  bool isBookingConfirmed = await context.WaitForExternalEvent<bool>("BookingConfirmed");

  context.SetCustomStatus(isBookingConfirmed
    ? new {message = "Thank you for confirming your booking."}
    : new {message = "The booking was not confirmed on time. Please try again."});

  return isBookingConfirmed;
}

Consultar o estado personalizado com HTTP

O exemplo seguinte mostra como os valores de estado personalizados podem ser consultados com as APIs HTTP incorporadas.

public static async Task SetStatusTest([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    // ...do work...

    // update the status of the orchestration with some arbitrary data
    var customStatus = new { nextActions = new [] {"A", "B", "C"}, foo = 2, };
    context.SetCustomStatus(customStatus);

    // ...do more work...
}

Enquanto a orquestração está em execução, os clientes externos podem obter este estado personalizado:

GET /runtime/webhooks/durabletask/instances/instance123

Os clientes receberão a seguinte resposta:

{
  "runtimeStatus": "Running",
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "output": null,
  "createdTime": "2019-10-06T18:30:24Z",
  "lastUpdatedTime": "2019-10-06T19:40:30Z"
}

Aviso

O payload de estado personalizado está limitado a 16 KB de texto JSON UTF-16. Recomendamos que utilize o armazenamento externo se precisar de um payload maior.

Passos seguintes

Saiba mais sobre os temporizadores duráveis