DurableOrchestrationClient Class

Durable Orchestration Client.

Client for starting, querying, terminating and raising events to orchestration instances.

Constructor

DurableOrchestrationClient(context: str)

Parameters

Name	Description
context Required

Methods

create_check_status_response	Create a HttpResponse that contains useful information for checking the status of the specified instance.
create_http_management_payload	Create a dictionary of orchestrator management urls.
get_client_response_links	Create a dictionary of orchestrator management urls.
get_status	Get the status of the specified orchestration instance.
get_status_all	Get the status of all orchestration instances.
get_status_by	Get the status of all orchestration instances that match the specified conditions.
purge_instance_history	Delete the history of the specified orchestration instance.
purge_instance_history_by	Delete the history of all orchestration instances that match the specified conditions.
raise_event	Send an event notification message to a waiting orchestration instance. In order to handle the event, the target orchestration instance must be waiting for an event named eventName using waitForExternalEvent API.
read_entity_state	Read the state of the entity.
resume	Resume the specified orchestration instance.
rewind	Return / "rewind" a failed orchestration instance to a prior "healthy" state.
signal_entity	Signals an entity to perform an operation.
start_new	Start a new instance of the specified orchestrator function. If an orchestration instance with the specified ID already exists, the existing instance will be silently replaced by this new instance.
suspend	Suspend the specified orchestration instance.
terminate	Terminate the specified orchestration instance.
wait_for_completion_or_create_check_status_response	Create an HTTP response. The response either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration. If the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of [[createCheckStatusResponse]].

create_check_status_response

Create a HttpResponse that contains useful information for checking the status of the specified instance.

create_check_status_response(request: HttpRequest, instance_id: str) -> HttpResponse

Parameters

Name	Description
request Required	<xref:azure.durable_functions.HttpRequest> The HTTP request that triggered the current orchestration instance.
instance_id Required	str The ID of the orchestration instance to check.

Returns

Type	Description
<xref:azure.durable_functions.HttpResponse>	An HTTP 202 response with a Location header and a payload containing instance management URLs

create_http_management_payload

Create a dictionary of orchestrator management urls.

create_http_management_payload(instance_id: str) -> Dict[str, str]

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to check.

Returns

Type	Description
Dict[str, str]	a dictionary object of orchestrator instance management urls

get_client_response_links

Create a dictionary of orchestrator management urls.

get_client_response_links(request: HttpRequest | None, instance_id: str) -> Dict[str, str]

Parameters

Name	Description
request Required	<xref:Optional>[<xref:HttpRequest>] The HTTP request that triggered the current orchestration instance.
instance_id Required	str The ID of the orchestration instance to check.

Returns

Type	Description
Dict[str, str]	a dictionary object of orchestrator instance management urls

get_status

Get the status of the specified orchestration instance.

async get_status(instance_id: str, show_history: bool = False, show_history_output: bool = False, show_input: bool = False) -> DurableOrchestrationStatus

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to query.
show_history	bool Boolean marker for including execution history in the response. Default value: False
show_history_output	bool Boolean marker for including output in the execution history response. Default value: False
show_input	bool Boolean marker for including the input in the response. Default value: False

Returns

Type	Description
DurableOrchestrationStatus	The status of the requested orchestration instance

get_status_all

Get the status of all orchestration instances.

async get_status_all() -> List[DurableOrchestrationStatus]

Returns

Type	Description
DurableOrchestrationStatus	The status of the requested orchestration instances

get_status_by

Get the status of all orchestration instances that match the specified conditions.

async get_status_by(created_time_from: datetime = None, created_time_to: datetime = None, runtime_status: List[OrchestrationRuntimeStatus] = None) -> List[DurableOrchestrationStatus]

Parameters

Name	Description
created_time_from	<xref:azure.durable_functions.datetime> Return orchestration instances which were created after this Date. Default value: None
created_time_to	<xref:azure.durable_functions.datetime> Return orchestration instances which were created before this Date. Default value: None
runtime_status	<xref:List>[<xref:OrchestrationRuntimeStatus>] Return orchestration instances which match any of the runtimeStatus values in this list. Default value: None

Returns

Type	Description
DurableOrchestrationStatus	The status of the requested orchestration instances

purge_instance_history

Delete the history of the specified orchestration instance.

async purge_instance_history(instance_id: str) -> PurgeHistoryResult

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to delete.

Returns

Type	Description
PurgeHistoryResult	The results of the request to delete the orchestration instance

purge_instance_history_by

Delete the history of all orchestration instances that match the specified conditions.

async purge_instance_history_by(created_time_from: datetime | None = None, created_time_to: datetime | None = None, runtime_status: List[OrchestrationRuntimeStatus] | None = None) -> PurgeHistoryResult

Parameters

Name	Description
created_time_from	<xref:Optional>[datetime] Delete orchestration history which were created after this Date. Default value: None
created_time_to	<xref:Optional>[datetime] Delete orchestration history which were created before this Date. Default value: None
runtime_status	<xref:Optional>[<xref:List>[<xref:OrchestrationRuntimeStatus>]] Delete orchestration instances which match any of the runtimeStatus values in this list. Default value: None

Returns

Type	Description
PurgeHistoryResult	The results of the request to purge history

raise_event

Send an event notification message to a waiting orchestration instance.

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using waitForExternalEvent API.

async raise_event(instance_id: str, event_name: str, event_data: Any = None, task_hub_name: str = None, connection_name: str = None) -> None

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance that will handle the event.
event_name Required	str The name of the event.
event_data	Any, optional The JSON-serializable data associated with the event. Default value: None
task_hub_name	str, optional The TaskHubName of the orchestration that will handle the event. Default value: None
connection_name	str, optional The name of the connection string associated with taskHubName. Default value: None

Exceptions

Type	Description
ValueError	event name must be a valid string.
Exception	Raises an exception if the status code is 404 or 400 when raising the event.

read_entity_state

Read the state of the entity.

async read_entity_state(entityId: EntityId, task_hub_name: str | None = None, connection_name: str | None = None) -> EntityStateResponse

Parameters

Name	Description
entityId Required	EntityId The EntityId of the targeted entity.
task_hub_name	<xref:Optional>[str] The task hub name of the target entity. Default value: None
connection_name	<xref:Optional>[str] The name of the connection string associated with [task_hub_name]. Default value: None

Returns

Type	Description
EntityStateResponse	container object representing the state of the entity

Exceptions

Type	Description
Exception:	When an unexpected status code is returned

resume

Resume the specified orchestration instance.

async resume(instance_id: str, reason: str) -> None

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to query.
reason Required	str The reason for resuming the instance.

Returns

Type	Description
None

Exceptions

Type	Description
Exception:	When the resume call failed with an unexpected status code

rewind

Return / "rewind" a failed orchestration instance to a prior "healthy" state.

async rewind(instance_id: str, reason: str, task_hub_name: str | None = None, connection_name: str | None = None)

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to rewind.
reason Required	str The reason for rewinding the orchestration instance.
task_hub_name	<xref:Optional>[str] The TaskHub of the orchestration to rewind Default value: None
connection_name	<xref:Optional>[str] Name of the application setting containing the storage connection string to use. Default value: None

Exceptions

Type	Description
Exception:	In case of a failure, it reports the reason for the exception

signal_entity

Signals an entity to perform an operation.

async signal_entity(entityId: EntityId, operation_name: str, operation_input: Any | None = None, task_hub_name: str | None = None, connection_name: str | None = None) -> None

Parameters

Name	Description
entityId Required	EntityId The EntityId of the targeted entity to perform operation.
operation_name Required	str The name of the operation.
operation_input	<xref:Optional>[<xref:Any>] The content for the operation. Default value: None
task_hub_name	<xref:Optional>[str] The task hub name of the target entity. Default value: None
connection_name	<xref:Optional>[str] The name of the connection string associated with [task_hub_name]. Default value: None

Returns

Type	Description
None

Exceptions

Type	Description
Exception:	When the signal entity call failed with an unexpected status code

start_new

Start a new instance of the specified orchestrator function.

If an orchestration instance with the specified ID already exists, the existing instance will be silently replaced by this new instance.

async start_new(orchestration_function_name: str, instance_id: str | None = None, client_input: Any | None = None) -> str

Parameters

Name	Description
orchestration_function_name Required	str The name of the orchestrator function to start.
instance_id	<xref:Optional>[str] The ID to use for the new orchestration instance. If no instance id is specified, the Durable Functions extension will generate a random GUID (recommended). Default value: None
client_input	<xref:Optional>[<xref:Any>] JSON-serializable input value for the orchestrator function. Default value: None

Returns

Type	Description
str	The ID of the new orchestration instance if successful, None if not.

suspend

Suspend the specified orchestration instance.

async suspend(instance_id: str, reason: str) -> None

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to suspend.
reason Required	str The reason for suspending the instance.

Returns

Type	Description
None

Exceptions

Type	Description
Exception:	When the suspend call failed with an unexpected status code

terminate

Terminate the specified orchestration instance.

async terminate(instance_id: str, reason: str) -> None

Parameters

Name	Description
instance_id Required	str The ID of the orchestration instance to query.
reason Required	str The reason for terminating the instance.

Returns

Type	Description
None

Exceptions

Type	Description
Exception:	When the terminate call failed with an unexpected status code

wait_for_completion_or_create_check_status_response

Create an HTTP response.

The response either contains a payload of management URLs for a non-completed instance or contains the payload containing the output of the completed orchestration.

If the orchestration does not complete within the specified timeout, then the HTTP response will be identical to that of [[createCheckStatusResponse]].

async wait_for_completion_or_create_check_status_response(request, instance_id: str, timeout_in_milliseconds: int = 10000, retry_interval_in_milliseconds: int = 1000) -> HttpResponse

Parameters

Name	Description
request Required	The HTTP request that triggered the current function.
instance_id Required	The unique ID of the instance to check.
timeout_in_milliseconds	Total allowed timeout for output from the durable function. The default value is 10 seconds. Default value: 10000
retry_interval_in_milliseconds	The timeout between checks for output from the durable function. The default value is 1 second. Default value: 1000