DurableOrchestrationClient Class

Durable Orchestration Client.

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

Inheritance
builtins.object
DurableOrchestrationClient

Constructor

DurableOrchestrationClient(context: str)

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.

rewind

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

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.

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: azure.functions._http.HttpRequest, instance_id: str) -> azure.functions._http.HttpResponse

Parameters

request
<xref:HttpRequest>
Required

The HTTP request that triggered the current orchestration instance.

instance_id
str
Required

The ID of the orchestration instance to check.

Returns

An HTTP 202 response with a Location header and a payload containing instance management URLs

Return type

<xref:HttpResponse>

create_http_management_payload

Create a dictionary of orchestrator management urls.

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

Parameters

instance_id
str
Required

The ID of the orchestration instance to check.

Returns

a dictionary object of orchestrator instance management urls

Return type

<xref:Dict>[str, str]

Create a dictionary of orchestrator management urls.

get_client_response_links(request: Optional[azure.functions._http.HttpRequest], instance_id: str) -> Dict[str, str]

Parameters

request
<xref:Optional>[<xref:HttpRequest>]
Required

The HTTP request that triggered the current orchestration instance.

instance_id
str
Required

The ID of the orchestration instance to check.

Returns

a dictionary object of orchestrator instance management urls

Return type

<xref:Dict>[str, str]

get_status

Get the status of the specified orchestration instance.

get_status(instance_id: str, show_history: bool = False, show_history_output: bool = False, show_input: bool = False) -> azure.durable_functions.models.DurableOrchestrationStatus.DurableOrchestrationStatus

Parameters

instance_id
str
Required

The ID of the orchestration instance to query.

show_history
bool
default value: False

Boolean marker for including execution history in the response.

show_history_output
bool
default value: False

Boolean marker for including output in the execution history response.

show_input
bool
default value: False

Boolean marker for including the input in the response.

Returns

The status of the requested orchestration instance

Return type

get_status_all

Get the status of all orchestration instances.

get_status_all() -> List[azure.durable_functions.models.DurableOrchestrationStatus.DurableOrchestrationStatus]

Returns

The status of the requested orchestration instances

Return type

get_status_by

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

get_status_by(created_time_from: Optional[datetime.datetime] = None, created_time_to: Optional[datetime.datetime] = None, runtime_status: Optional[List[azure.durable_functions.models.OrchestrationRuntimeStatus.OrchestrationRuntimeStatus]] = None) -> List[azure.durable_functions.models.DurableOrchestrationStatus.DurableOrchestrationStatus]

Parameters

created_time_from
datetime
default value: None

Return orchestration instances which were created after this Date.

created_time_to
datetime
default value: None

Return orchestration instances which were created before this Date.

runtime_status
<xref:List>[OrchestrationRuntimeStatus]
default value: None

Return orchestration instances which match any of the runtimeStatus values in this list.

Returns

The status of the requested orchestration instances

Return type

purge_instance_history

Delete the history of the specified orchestration instance.

purge_instance_history(instance_id: str) -> azure.durable_functions.models.PurgeHistoryResult.PurgeHistoryResult

Parameters

instance_id
str
Required

The ID of the orchestration instance to delete.

Returns

The results of the request to delete the orchestration instance

Return type

purge_instance_history_by

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

purge_instance_history_by(created_time_from: Optional[datetime.datetime] = None, created_time_to: Optional[datetime.datetime] = None, runtime_status: Optional[List[azure.durable_functions.models.OrchestrationRuntimeStatus.OrchestrationRuntimeStatus]] = None) -> azure.durable_functions.models.PurgeHistoryResult.PurgeHistoryResult

Parameters

created_time_from
<xref:Optional>[datetime]
default value: None

Delete orchestration history which were created after this Date.

created_time_to
<xref:Optional>[datetime]
default value: None

Delete orchestration history which were created before this Date.

runtime_status
<xref:Optional>[<xref:List>[OrchestrationRuntimeStatus]]
default value: None

Delete orchestration instances which match any of the runtimeStatus values in this list.

Returns

The results of the request to purge history

Return type

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.

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

Parameters

instance_id
str
Required

The ID of the orchestration instance that will handle the event.

event_name
str
Required

The name of the event.

event_data
<xref:Any>, <xref:optional>
default value: None

The JSON-serializable data associated with the event.

task_hub_name
str, <xref:optional>
default value: None

The TaskHubName of the orchestration that will handle the event.

connection_name
str, <xref:optional>
default value: None

The name of the connection string associated with taskHubName.

Exceptions

event name must be a valid string.

Raises an exception if the status code is 404 or 400 when raising the event.

rewind

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

rewind(instance_id: str, reason: str, task_hub_name: Optional[str] = None, connection_name: Optional[str] = None)

Parameters

instance_id
str
Required

The ID of the orchestration instance to rewind.

reason
str
Required

The reason for rewinding the orchestration instance.

task_hub_name
<xref:Optional>[str]
default value: None

The TaskHub of the orchestration to rewind

connection_name
<xref:Optional>[str]
default value: None

Name of the application setting containing the storage connection string to use.

Exceptions

Exception:

In case of a failure, it reports the reason for the exception

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.

start_new(orchestration_function_name: str, instance_id: Optional[str] = None, client_input: Optional[Any] = None) -> str

Parameters

orchestration_function_name
str
Required

The name of the orchestrator function to start.

instance_id
<xref:Optional>[str]
default value: None

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

client_input
<xref:Optional>[<xref:Any>]
default value: None

JSON-serializable input value for the orchestrator function.

Returns

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

Return type

str

terminate

Terminate the specified orchestration instance.

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

Parameters

instance_id
str
Required

The ID of the orchestration instance to query.

reason
str
Required

The reason for terminating the instance.

Return type

Exceptions

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

wait_for_completion_or_create_check_status_response(request, instance_id: str, timeout_in_milliseconds: int = 10000, retry_interval_in_milliseconds: int = 1000) -> azure.functions._http.HttpResponse

Parameters

request
Required

The HTTP request that triggered the current function.

instance_id
Required

The unique ID of the instance to check.

timeout_in_milliseconds
default value: 10000

Total allowed timeout for output from the durable function. The default value is 10 seconds.

retry_interval_in_milliseconds
default value: 1000

The timeout between checks for output from the durable function. The default value is 1 second.