Skip to content

Latest commit

 

History

History
254 lines (197 loc) · 15.4 KB

durable-functions-instance-management.md

File metadata and controls

254 lines (197 loc) · 15.4 KB
title description services author manager editor tags keywords ms.service ms.devlang ms.topic ms.tgt_pltfrm ms.workload ms.date ms.author
Manage instances in Durable Functions - Azure
Learn how to manage instances in the Durable Functions extension for Azure Functions.
functions
cgillum
cfowler
functions
multiple
article
multiple
na
03/19/2018
azfuncdf

Manage instances in Durable Functions (Azure Functions)

Durable Functions orchestration instances can be started, terminated, queried, and sent notification events. All instance management is done using the orchestration client binding. This article goes into the details of each instance management operation.

Starting instances

The StartNewAsync method on the DurableOrchestrationClient starts a new instance of an orchestrator function. Instances of this class can be acquired using the orchestrationClient binding. Internally, this method enqueues a message into the control queue, which then triggers the start of a function with the specified name that uses the orchestrationTrigger trigger binding.

The task completes when the orchestration process is started. The orchestration process should start within 30 seconds. If it takes longer, a TimeoutException is thrown.

The parameters to StartNewAsync are as follows:

  • Name: The name of the orchestrator function to schedule.
  • Input: Any JSON-serializable data that should be passed as the input to the orchestrator function.
  • InstanceId: (Optional) The unique ID of the instance. If not specified, a random instance ID will be generated.

Here is a simple C# example:

[FunctionName("HelloWorldManualStart")]
public static async Task Run(
    [ManualTrigger] string input,
    [OrchestrationClient] DurableOrchestrationClient starter,
    TraceWriter log)
{
    string instanceId = await starter.StartNewAsync("HelloWorld", input);
    log.Info($"Started orchestration with ID = '{instanceId}'.");
}

For non-.NET languages, the function output binding can be used to start new instances as well. In this case, any JSON-serializable object that has the above three parameters as fields can be used. For example, consider the following JavaScript function:

module.exports = function (context, input) {
    var id = generateSomeUniqueId();
    context.bindings.starter = [{
        FunctionName: "HelloWorld",
        Input: input,
        InstanceId: id
    }];

    context.done(null);
};

Note

We recommend that you use a random identifier for the instance ID. This will help ensure an equal load distribution when scaling orchestrator functions across multiple VMs. The proper time to use non-random instance IDs is when the ID must come from an external source or when implementing the singleton orchestrator pattern.

Querying instances

The GetStatusAsync method on the DurableOrchestrationClient class queries the status of an orchestration instance. It takes an instanceId (required), showHistory (optional), and showHistoryOutput (optional) as parameters. If showHistory is set to true, the response will contain the execution history. If showHistoryOutput is set to true as well, the execution history will contain activity outputs. The method returns an object with the following properties:

  • Name: The name of the orchestrator function.
  • InstanceId: The instance ID of the orchestration (should be the same as the instanceId input).
  • CreatedTime: The time at which the orchestrator function started running.
  • LastUpdatedTime: The time at which the orchestration last checkpointed.
  • Input: The input of the function as a JSON value.
  • CustomStatus: Custom orchestration status in JSON format.
  • Output: The output of the function as a JSON value (if the function has completed). If the orchestrator function failed, this property will include the failure details. If the orchestrator function was terminated, this property will include the provided reason for the termination (if any).
  • RuntimeStatus: One of the following values:
    • Pending: The instance has been scheduled but has not yet started running.
    • Running: The instance has started running.
    • Completed: The instance has completed normally.
    • ContinuedAsNew: The instance has restarted itself with a new history. This is a transient state.
    • Failed: The instance failed with an error.
    • Terminated: The instance was abruptly terminated.
  • History: The execution history of the orchestration. This field is only populated if showHistory is set to true.

This method returns null if the instance either doesn't exist or has not yet started running.

[FunctionName("GetStatus")]
public static async Task Run(
    [OrchestrationClient] DurableOrchestrationClient client,
    [ManualTrigger] string instanceId)
{
    var status = await client.GetStatusAsync(instanceId);
    // do something based on the current status.
}

Querying all instances

You can use the GetStatusAsync method to query the statuses of all orchestration instances. It doesn't take any parameters, or you can pass a CancellationToken object in case you want to cancel it. The method returns objects with the same properties as the GetStatusAsync method with parameters, except it doesn't return history.

[FunctionName("GetAllStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")]HttpRequestMessage req,
    [OrchestrationClient] DurableOrchestrationClient client,
    TraceWriter log)
{
    IList<DurableOrchestrationStatus> instances = await starter.GetStatusAsync(); // You can pass CancellationToken as a parameter.
    foreach (var instance in instances)
    {
        log.Info(JsonConvert.SerializeObject(instance));
    };
}

Terminating instances

A running orchestration instance can be terminated using the TerminateAsync method of the DurableOrchestrationClient class. The two parameters are an instanceId and a reason string, which will be written to logs and to the instance status. A terminated instance will stop running as soon as it reaches the next await point, or it will terminate immediately if it is already on an await.

[FunctionName("TerminateInstance")]
public static Task Run(
    [OrchestrationClient] DurableOrchestrationClient client,
    [ManualTrigger] string instanceId)
{
    string reason = "It was time to be done.";
    return client.TerminateAsync(instanceId, reason);
}

Note

Instance termination does not currently propagate. Activity functions and sub-orchestrations will run to completion regardless of whether the orchestration instance that called them has been terminated.

Sending events to instances

Event notifications can be sent to running instances using the RaiseEventAsync method of the DurableOrchestrationClient class. Instances that can handle these events are those that are awaiting a call to WaitForExternalEvent.

The parameters to RaiseEventAsync are as follows:

  • InstanceId: The unique ID of the instance.
  • EventName: The name of the event to send.
  • EventData: A JSON-serializable payload to send to the instance.
#r "Microsoft.Azure.WebJobs.Extensions.DurableTask"

[FunctionName("RaiseEvent")]
public static Task Run(
    [OrchestrationClient] DurableOrchestrationClient client,
    [ManualTrigger] string instanceId)
{
    int[] eventData = new int[] { 1, 2, 3 };
    return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}

Warning

If there is no orchestration instance with the specified instance ID or if the instance is not waiting on the specified event name, the event message is discarded. For more information about this behavior, see the GitHub issue.

Wait for orchestration completion

The DurableOrchestrationClient class exposes a WaitForCompletionOrCreateCheckStatusResponseAsync API that can be used to get synchronously the actual output from an orchestration instance. The method uses default value of 10 seconds for timeout and 1 second for retryInterval when they are not set.

Here is an example HTTP-trigger function that demonstrates how to use this API:

[!code-csharpMain]

The function can be called with the following line using 2-seconds timeout and 0.5-second retry interval:

    http POST http://localhost:7071/orchestrators/E1_HelloSequence/wait?timeout=2&retryInterval=0.5

Depending on the time required to get the response from the orchestration instance there are two cases:

  1. The orchestration instances complete within the defined timeout (in this case 2 seconds), the response is the actual orchestration instance output delivered synchronously:

        HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Date: Thu, 14 Dec 2017 06:14:29 GMT
    Server: Microsoft-HTTPAPI/2.0
    Transfer-Encoding: chunked

    [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ]

  2. The orchestration instances cannot complete within the defined timeout (in this case 2 seconds), the response is the default one described in HTTP API URL discovery:

        HTTP/1.1 202 Accepted
    Content-Type: application/json; charset=utf-8
    Date: Thu, 14 Dec 2017 06:13:51 GMT
    Location: http://localhost:7071/admin/extensions/DurableTaskExtension/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
    Retry-After: 10
    Server: Microsoft-HTTPAPI/2.0
    Transfer-Encoding: chunked

    {
        "id": "d3b72dddefce4e758d92f4d411567177",
        "sendEventPostUri": "http://localhost:7071/admin/extensions/DurableTaskExtension/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
        "statusQueryGetUri": "http://localhost:7071/admin/extensions/DurableTaskExtension/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
        "terminatePostUri": "http://localhost:7071/admin/extensions/DurableTaskExtension/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
    }

Note

The format of the webhook URLs may differ depending on which version of the Azure Functions host you are running. The preceding example is for the Azure Functions 2.0 host.

Retrieving HTTP Management Webhook URLs

External systems can communicate with Durable Functions via the webhook URLs that are part of the default response described in HTTP API URL discovery. However, the webhook URLs also can be accessed programmatically in the orchestration client or in an activity function via the CreateHttpManagementPayload method of the DurableOrchestrationClient class.

CreateHttpManagementPayload has one parameter:

  • instanceId: The unique ID of the instance.

The method returns an instance of the HttpManagementPayload with the following string properties:

  • Id: The instance ID of the orchestration (should be the same as the InstanceId input).
  • StatusQueryGetUri: The status URL of the orchestration instance.
  • SendEventPostUri: The "raise event" URL of the orchestration instance.
  • TerminatePostUri: The "terminate" URL of the orchestration instance.

Activity functions can send an instance of HttpManagementPayload to external systems to monitor or raise events to an orchestration:

#r "Microsoft.Azure.WebJobs.Extensions.DurableTask"

public static void SendInstanceInfo(
    [ActivityTrigger] DurableActivityContext ctx,
    [OrchestrationClient] DurableOrchestrationClient client,
    [DocumentDB(
        databaseName: "MonitorDB",
        collectionName: "HttpManagementPayloads",
        ConnectionStringSetting = "CosmosDBConnection")]out dynamic document)
{
    HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);

    // send the payload to Cosmos DB
    document = new { Payload = payload, id = ctx.InstanceId };
}

Next steps

[!div class="nextstepaction"] Learn how to use the HTTP APIs for instance management