DurableOrchestrationClient Class
Durable Orchestration Client.
Client for starting, querying, terminating and raising events to orchestration instances.
- Inheritance
-
builtins.objectDurableOrchestrationClient
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. |
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: 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
|
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
|
The ID of the orchestration instance to check. |
Returns
Type | Description |
---|---|
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
|
The ID of the orchestration instance to check. |
Returns
Type | Description |
---|---|
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
|
The ID of the orchestration instance to query. |
show_history
|
Boolean marker for including execution history in the response. default value: False
|
show_history_output
|
Boolean marker for including output in the execution history response. default value: False
|
show_input
|
Boolean marker for including the input in the response. default value: False
|
Returns
Type | Description |
---|---|
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 |
---|---|
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 |
---|---|
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
|
The ID of the orchestration instance to delete. |
Returns
Type | Description |
---|---|
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 |
---|---|
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
|
The ID of the orchestration instance that will handle the event. |
event_name
Required
|
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 |
---|---|
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.
async rewind(instance_id: str, reason: str, task_hub_name: str | None = None, connection_name: str | None = None)
Parameters
Name | Description |
---|---|
instance_id
Required
|
The ID of the orchestration instance to rewind. |
reason
Required
|
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 |
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
|
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 |
---|---|
The ID of the new orchestration instance if successful, None if not. |
terminate
Terminate the specified orchestration instance.
async terminate(instance_id: str, reason: str) -> None
Parameters
Name | Description |
---|---|
instance_id
Required
|
The ID of the orchestration instance to query. |
reason
Required
|
The reason for terminating the instance. |
Returns
Type | Description |
---|---|
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
|
Azure SDK for Python
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for