Muokkaa

Jaa

HTTP API reference

  • Artikkeli

The Durable Functions extension exposes a set of built-in HTTP APIs that can be used to perform management tasks on orchestrations, entities, and task hubs. These HTTP APIs are extensibility webhooks that are authorized by the Azure Functions host but handled directly by the Durable Functions extension.

The base URL for the APIs mentioned in this article is the same as the base URL for your function app. When developing locally using the Azure Functions Core Tools, the base URL is typically http://localhost:7071. In the Azure Functions hosted service, the base URL is typically https://{appName}.azurewebsites.net. Custom hostnames are also supported if configured on your App Service app.

All HTTP APIs implemented by the extension require the following parameters. The data type of all parameters is string.

Parameter Parameter Type Description
taskHub Query string The name of the task hub. If not specified, the current function app's task hub name is assumed.
connection Query string The name of the connection app setting for the backend storage provider. If not specified, the default connection configuration for the function app is assumed.
systemKey Query string The authorization key required to invoke the API.

systemKey is an authorization key autogenerated by the Azure Functions host. It specifically grants access to the Durable Task extension APIs and can be managed the same way as other Azure Functions access keys. You can generate URLs that contain the correct taskHub, connection, and systemKey query string values using orchestration client binding APIs, such as the CreateCheckStatusResponse and CreateHttpManagementPayload APIs in .NET, the createCheckStatusResponse and createHttpManagementPayload APIs in JavaScript, etc.

The next few sections cover the specific HTTP APIs supported by the extension and provide examples of how they can be used.

Start orchestration

Starts executing a new instance of the specified orchestrator function.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
functionName URL The name of the orchestrator function to start.
instanceId URL Optional parameter. The ID of the orchestration instance. If not specified, the orchestrator function will start with a random instance ID.
{content} Request content Optional. The JSON-formatted orchestrator function input.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The specified orchestrator function was scheduled to start running. The Location response header contains a URL for polling the orchestration status.
  • HTTP 400 (Bad request): The specified orchestrator function doesn't exist, the specified instance ID was not valid, or request content was not valid JSON.

The following is an example request that starts a RestartVMs orchestrator function and includes JSON object payload:

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
}

The response payload for the HTTP 202 cases is a JSON object with the following fields:

Field Description
id The ID of the orchestration instance.
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.
purgeHistoryDeleteUri The "purge history" URL of the orchestration instance.
rewindPostUri (preview) The "rewind" URL of the orchestration instance.
suspendPostUri The "suspend" URL of the orchestration instance.
resumePostUri The "resume" URL of the orchestration instance.

The data type of all fields is string.

Here is an example response payload for an orchestration instance with abc123 as its ID (formatted for readability):

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

The HTTP response is intended to be compatible with the Polling Consumer Pattern. It also includes the following notable response headers:

  • Location: The URL of the status endpoint. This URL contains the same value as the statusQueryGetUri field.
  • Retry-After: The number of seconds to wait between polling operations. The default value is 10.

For more information on the asynchronous HTTP polling pattern, see the HTTP async operation tracking documentation.

Get instance status

Gets the status of a specified orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.
showInput Query string Optional parameter. If set to false, the function input will not be included in the response payload.
showHistory Query string Optional parameter. If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput Query string Optional parameter. If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom Query string Optional parameter. When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Query string Optional parameter. When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Query string Optional parameter. When specified, filters the list of returned instances based on their runtime status. To see the list of possible runtime status values, see the Querying instances article.
returnInternalServerErrorOnFailure Query string Optional parameter. If set to true, this API will return an HTTP 500 response instead of a 200 if the instance is in a failure state. This parameter is intended for automated status polling scenarios.

Response

Several possible status code values can be returned.

  • HTTP 200 (OK): The specified instance is in a completed or failed state.
  • HTTP 202 (Accepted): The specified instance is in progress.
  • HTTP 400 (Bad Request): The specified instance failed or was terminated.
  • HTTP 404 (Not Found): The specified instance doesn't exist or has not started running.
  • HTTP 500 (Internal Server Error): Returned only when the returnInternalServerErrorOnFailure is set to true and the specified instance failed with an unhandled exception.

The response payload for the HTTP 200 and HTTP 202 cases is a JSON object with the following fields:

Field Data type Description
runtimeStatus string The runtime status of the instance. Values include Running, Pending, Failed, Canceled, Terminated, Completed, Suspended.
input JSON The JSON data used to initialize the instance. This field is null if the showInput query string parameter is set to false.
customStatus JSON The JSON data used for custom orchestration status. This field is null if not set.
output JSON The JSON output of the instance. This field is null if the instance is not in a completed state.
createdTime string The time at which the instance was created. Uses ISO 8601 extended notation.
lastUpdatedTime string The time at which the instance last persisted. Uses ISO 8601 extended notation.
historyEvents JSON A JSON array containing the orchestration execution history. This field is null unless the showHistory query string parameter is set to true.

Here is an example response payload including the orchestration execution history and activity outputs (formatted for readability):

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

The HTTP 202 response also includes a Location response header that references the same URL as the statusQueryGetUri field mentioned previously.

Get all instances status

You can also query the status of all instances by removing the instanceId from the 'Get instance status' request. In this case, the basic parameters are the same as the 'Get instance status'. Query string parameters for filtering are also supported.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

GET /runtime/webhooks/durableTask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
showInput Query string Optional parameter. If set to false, the function input will not be included in the response payload.
showHistoryOutput Query string Optional parameter. If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom Query string Optional parameter. When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Query string Optional parameter. When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Query string Optional parameter. When specified, filters the list of returned instances based on their runtime status. To see the list of possible runtime status values, see the Querying instances article.
instanceIdPrefix Query string Optional parameter. When specified, filters the list of returned instances to include only instances whose instance ID starts with the specified prefix string. Available starting with version 2.7.2 of the extension.
top Query string Optional parameter. When specified, limits the number of instances returned by the query.

Response

Here is an example of response payloads including the orchestration status (formatted for readability):

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

Note

This operation can be very expensive in terms of Azure Storage I/O if you are using the default Azure Storage provider and if there are a lot of rows in the Instances table. More details on Instance table can be found in the Azure Storage provider documentation.

If more results exist, a continuation token is returned in the response header. The name of the header is x-ms-continuation-token.

Caution

The query result may return fewer items than the limit specified by top. When receiving results, you should therefore always check to see if there is a continuation token.

If you set continuation token value in the next request header, you can get the next page of results. This name of the request header is also x-ms-continuation-token.

Purge single instance history

Deletes the history and related artifacts for a specified orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.

Response

The following HTTP status code values can be returned.

  • HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (Not Found): The specified instance doesn't exist.

The response payload for the HTTP 200 case is a JSON object with the following field:

Field Data type Description
instancesDeleted integer The number of instances deleted. For the single instance case, this value should always be 1.

Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 1
}

Purge multiple instance histories

You can also delete the history and related artifacts for multiple instances within a task hub by removing the {instanceId} from the 'Purge single instance history' request. To selectively purge instance history, use the same filters described in the 'Get all instances status' request.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
createdTimeFrom Query string Filters the list of purged instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Query string Optional parameter. When specified, filters the list of purged instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Query string Optional parameter. When specified, filters the list of purged instances based on their runtime status. To see the list of possible runtime status values, see the Querying instances article.

Note

This operation can be very expensive in terms of Azure Storage I/O if you are using the default Azure Storage provider and if there are many rows in the Instances and/or History tables. More details on these tables can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

Response

The following HTTP status code values can be returned.

  • HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (Not Found): No instances were found that match the filter expression.

The response payload for the HTTP 200 case is a JSON object with the following field:

Field Data type Description
instancesDeleted integer The number of instances deleted.

Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 250
}

Raise event

Sends an event notification message to a running orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
instanceId URL The ID of the orchestration instance.
eventName URL The name of the event that the target orchestration instance is waiting on.
{content} Request content The JSON-formatted event payload.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The raised event was accepted for processing.
  • HTTP 400 (Bad request): The request content was not of type application/json or was not valid JSON.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed or failed and cannot process any raised events.

Here is an example request that sends the JSON string "incr" to an instance waiting for an event named operation:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

The responses for this API do not contain any content.

Terminate instance

Terminates a running orchestration instance.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

Field Parameter Type Description
instanceId URL The ID of the orchestration instance.
reason Query string Optional. The reason for terminating the orchestration instance.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The terminate request was accepted for processing.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed or failed.

Here is an example request that terminates a running instance and specifies a reason of buggy:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

The responses for this API do not contain any content.

Suspend instance

Suspends a running orchestration instance.

Request

In version 2.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Field Parameter Type Description
instanceId URL The ID of the orchestration instance.
reason Query string Optional. The reason for suspending the orchestration instance.

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The suspend request was accepted for processing.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed, failed, or terminated.

The responses for this API do not contain any content.

Resume instance

Resumes a suspended orchestration instance.

Request

In version 2.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Field Parameter Type Description
instanceId URL The ID of the orchestration instance.
reason Query string Optional. The reason for resuming the orchestration instance.

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The resume request was accepted for processing.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed, failed, or terminated.

The responses for this API do not contain any content.

Rewind instance (preview)

Restores a failed orchestration instance into a running state by replaying the most recent failed operations.

Request

For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

Field Parameter Type Description
instanceId URL The ID of the orchestration instance.
reason Query string Optional. The reason for rewinding the orchestration instance.

Response

Several possible status code values can be returned.

  • HTTP 202 (Accepted): The rewind request was accepted for processing.
  • HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone): The specified instance has completed or was terminated.

Here is an example request that rewinds a failed instance and specifies a reason of fixed:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

The responses for this API do not contain any content.

Signal entity

Sends a one-way operation message to a Durable Entity. If the entity doesn't exist, it will be created automatically.

Note

Durable entities are available starting in Durable Functions 2.0.

Request

The HTTP request is formatted as follows (multiple lines are shown for clarity):

POST /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
entityName URL The name (type) of the entity.
entityKey URL The key (unique ID) of the entity.
op Query string Optional. The name of the user-defined operation to invoke.
{content} Request content The JSON-formatted event payload.

Here is an example request that sends a user-defined "Add" message to a Counter entity named steps. The content of the message is the value 5. If the entity does not already exist, it will be created by this request:

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

Note

By default with class-based entities in .NET, specifying the op value of delete will delete the state of an entity. If the entity defines an operation named delete, however, that user-defined operation will be invoked instead.

Response

This operation has several possible responses:

  • HTTP 202 (Accepted): The signal operation was accepted for asynchronous processing.
  • HTTP 400 (Bad request): The request content was not of type application/json, was not valid JSON, or had an invalid entityKey value.
  • HTTP 404 (Not Found): The specified entityName was not found.

A successful HTTP request does not contain any content in the response. A failed HTTP request may contain JSON-formatted error information in the response content.

Get entity

Gets the state of the specified entity.

Request

The HTTP request is formatted as follows (multiple lines are shown for clarity):

GET /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Response

This operation has two possible responses:

  • HTTP 200 (OK): The specified entity exists.
  • HTTP 404 (Not Found): The specified entity was not found.

A successful response contains the JSON-serialized state of the entity as its content.

Example

The following example HTTP request gets the state of an existing Counter entity named steps:

GET /runtime/webhooks/durabletask/entities/Counter/steps

If the Counter entity simply contained a number of steps saved in a currentValue field, the response content might look like the following (formatted for readability):

{
    "currentValue": 5
}

List entities

You can query for multiple entities by the entity name or by the last operation date.

Request

The HTTP request is formatted as follows (multiple lines are shown for clarity):

GET /runtime/webhooks/durabletask/entities/{entityName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &lastOperationTimeFrom={timestamp}
    &lastOperationTimeTo={timestamp}
    &fetchState=[true|false]
    &top={integer}

Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

Field Parameter type Description
entityName URL Optional. When specified, filters the list of returned entities by their entity name (case-insensitive).
fetchState Query string Optional parameter. If set to true, the entity state will be included in the response payload.
lastOperationTimeFrom Query string Optional parameter. When specified, filters the list of returned entities that processed operations after the given ISO8601 timestamp.
lastOperationTimeTo Query string Optional parameter. When specified, filters the list of returned entities that processed operations before the given ISO8601 timestamp.
top Query string Optional parameter. When specified, limits the number of entities returned by the query.

Response

A successful HTTP 200 response contains a JSON-serialized array of entities and optionally the state of each entity.

By default the operation returns the first 100 entities that match the query criteria. The caller can specify a query string parameter value for top to return a different maximum number of results. If more results exist beyond what is returned, a continuation token is also returned in the response header. The name of the header is x-ms-continuation-token.

If you set continuation token value in the next request header, you can get the next page of results. This name of the request header is also x-ms-continuation-token.

Example - list all entities

The following example HTTP request lists all entities in the task hub:

GET /runtime/webhooks/durabletask/entities

The response JSON may look like the following (formatted for readability):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
    },
    {
        "entityId": { "key": "mice", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
    },
    {
        "entityId": { "key": "radio", "name": "device" },
        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
    },
]

Example - filtering the list of entities

The following example HTTP request lists just the first two entities of type counter and also fetches their state:

GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true

The response JSON may look like the following (formatted for readability):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
        "state": { "value": 9 }
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
        "state": { "value": 10 }
    }
]

Next steps

Learn how to use Application Insights to monitor your durable functions