DurableOrchestrationClient Class

Durable Orchestration Client.

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

Inheritance

builtins.object

DurableOrchestrationClient

Constructor

DurableOrchestrationClient(context: str)

Parameters

context

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]

get_client_response_links

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.

async 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

DurableOrchestrationStatus

get_status_all

Get the status of all orchestration instances.

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

Returns

The status of the requested orchestration instances

Return type

DurableOrchestrationStatus

get_status_by

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

async 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

DurableOrchestrationStatus

purge_instance_history

Delete the history of the specified orchestration instance.

async 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

PurgeHistoryResult

purge_instance_history_by

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

async 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

PurgeHistoryResult

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: 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

ValueError

event name must be a valid string.

Exception

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.

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

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

async 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

None

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

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