DigitalTwinsClient Class

Creates an instance of the Digital Twins client.

Inheritance

builtins.object

DigitalTwinsClient

Constructor

DigitalTwinsClient(endpoint: str, credential: AsyncTokenCredential, **kwargs)

Parameters

Name	Description
endpoint Required	str The URL endpoint of an Azure search service
credential Required	AsyncTokenCredential A credential to authenticate requests to the service.

Methods

close
create_models	Create one or more models. When any error occurs, no models are uploaded.
decommission_model	Decommissions a model.
delete_digital_twin	Delete a digital twin.
delete_event_route	Delete an event route.
delete_model	Delete a model.
delete_relationship	Delete a relationship on a digital twin.
get_component	Get a component on a digital twin.
get_digital_twin	Get a digital twin.
get_event_route	Get an event route.
get_model	Get a model, including the model metadata and the model definition.
get_relationship	Get a relationship on a digital twin.
list_event_routes	Retrieves all event routes.
list_incoming_relationships	Retrieve all incoming relationships for a digital twin.
list_models	Get the list of models.
list_relationships	Retrieve relationships for a digital twin.
publish_component_telemetry	Publish telemetry from a digital twin's component, which is then consumed by one or many destination endpoints (subscribers) defined under.
publish_telemetry	Publish telemetry from a digital twin, which is then consumed by one or many destination endpoints (subscribers) defined under.
query_twins	Query for digital twins. Note: that there may be a delay between before changes in your instance are reflected in queries. For more details on query limitations, see https://docs.microsoft.com/azure/digital-twins/how-to-query-graph#query-limitations
update_component	Update properties of a component on a digital twin using a JSON patch.
update_digital_twin	Update a digital twin using a JSON patch.
update_relationship	Updates the properties of a relationship on a digital twin using a JSON patch.
upsert_digital_twin	Create or update a digital twin.
upsert_event_route	Create or update an event route.
upsert_relationship	Create or update a relationship on a digital twin.

close

async close() -> None

create_models

Create one or more models. When any error occurs, no models are uploaded.

async create_models(dtdl_models: List[object], **kwargs) -> List[DigitalTwinsModelData]

Parameters

Name	Description
model_list Required	List[object] The set of models to create. Each dict corresponds to exactly one model.

Returns

Type	Description
List[DigitalTwinsModelData]	The list of created models

Exceptions

Type	Description
HttpResponseError
ResourceExistsError	One or more of the provided models already exist.

decommission_model

Decommissions a model.

async decommission_model(model_id: str, **kwargs) -> None

Parameters

Name	Description
model_id Required	str The ID for the model. The ID is globally unique and case sensitive.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	There is no model with the provided ID.

delete_digital_twin

Delete a digital twin.

async delete_digital_twin(digital_twin_id: str, **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no digital twin with the provided ID.

delete_event_route

Delete an event route.

async delete_event_route(event_route_id: str, **kwargs) -> None

Parameters

Name	Description
event_route_id Required	str The ID of the event route to delete.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	There is no event route with the provided ID.

delete_model

Delete a model.

async delete_model(model_id: str, **kwargs) -> None

Parameters

Name	Description
model_id Required	str The ID of the model to delete.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	There is no model with the provided ID.
ResourceExistsError	There are dependencies on the model that prevent it from being deleted.

delete_relationship

Delete a relationship on a digital twin.

async delete_relationship(digital_twin_id: str, relationship_id: str, **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
relationship_id Required	str The ID of the relationship to delete.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is either no digital twin or relationship with the provided ID.

get_component

Get a component on a digital twin.

async get_component(digital_twin_id: str, component_name: str, **kwargs) -> Dict[str, object]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
component_name Required	str The component being retrieved.

Returns

Type	Description
Dict[str, object]	Dictionary containing the component.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is either no digital twin with the provided ID or the component name is invalid.

get_digital_twin

Get a digital twin.

async get_digital_twin(digital_twin_id: str, **kwargs) -> Dict[str, object]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.

Returns

Type	Description
Dict[str, object]	Dictionary containing the twin.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If the digital twin doesn't exist.

get_event_route

Get an event route.

async get_event_route(event_route_id: str, **kwargs) -> DigitalTwinsEventRoute

Parameters

Name	Description
event_route_id Required	str The ID of the event route.

Returns

Type	Description
DigitalTwinsEventRoute	The event route object.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	There is no event route with the provided ID.

get_model

Get a model, including the model metadata and the model definition.

async get_model(model_id: str, **kwargs) -> DigitalTwinsModelData

Parameters

Name	Description
model_id Required	str The ID of the model.

Keyword-Only Parameters

Name	Description
include_model_definition	bool Include the model definition as part of the result. The default value is False.

Returns

Type	Description
DigitalTwinsModelData	The model data.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no model with the provided ID.

get_relationship

Get a relationship on a digital twin.

async get_relationship(digital_twin_id: str, relationship_id: str, **kwargs) -> Dict[str, object]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
relationship_id Required	str The ID of the relationship to retrieve.

Returns

Type	Description
Dict[str, object]	Dictionary containing the relationship.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is either no digital twin or relationship with the provided ID.

list_event_routes

Retrieves all event routes.

list_event_routes(**kwargs) -> AsyncItemPaged[DigitalTwinsEventRoute]

Keyword-Only Parameters

Name	Description
results_per_page	int The maximum number of items to retrieve per request. The server may choose to return less than the requested max.

Returns

Type	Description
AsyncItemPaged[DigitalTwinsEventRoute]	An iterator instance of event routes.

Exceptions

Type	Description
HttpResponseError

list_incoming_relationships

Retrieve all incoming relationships for a digital twin.

list_incoming_relationships(digital_twin_id: str, **kwargs) -> AsyncItemPaged[IncomingRelationship]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.

Returns

Type	Description
AsyncItemPaged[IncomingRelationship]	An iterator instance of list of incoming relationships.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no digital twin with the provided ID.

list_models

Get the list of models.

list_models(dependencies_for: List[str] | None = None, **kwargs) -> AsyncItemPaged[DigitalTwinsModelData]

Parameters

Name	Description
dependencies_for Required	List[str] The model IDs to have dependencies retrieved. If omitted, all models are retrieved.

Keyword-Only Parameters

Name	Description
include_model_definition	bool Include the model definition as part of the results. The default value is False.
results_per_page	int The maximum number of items to retrieve per request. The server may choose to return less than the requested max.

Returns

Type	Description
<xref:azure.core.paging.AsyncItemPaged>[DigitalTwinsModelData]	An iterator instance of list of model data.

Exceptions

Type	Description
HttpResponseError

list_relationships

Retrieve relationships for a digital twin.

list_relationships(digital_twin_id: str, relationship_id: str | None = None, **kwargs) -> AsyncItemPaged[Dict[str, object]]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
relationship_id Required	str The ID of the relationship to get (if None all the relationship will be retrieved).

Returns

Type	Description
AsyncItemPaged[Dict[str,object]]	An iterator instance of list of relationships.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no digital twin with the provided ID.

publish_component_telemetry

Publish telemetry from a digital twin's component, which is then consumed by one or many destination endpoints (subscribers) defined under.

async publish_component_telemetry(digital_twin_id: str, component_name: str, telemetry: object, **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
component_name Required	str The name of the DTDL component.
telemetry Required	object The telemetry data to be sent.

Keyword-Only Parameters

Name	Description
message_id	str The message ID. If not specified, a UUID will be generated.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no digital twin with the provided ID or the component name is invalid.

publish_telemetry

Publish telemetry from a digital twin, which is then consumed by one or many destination endpoints (subscribers) defined under.

async publish_telemetry(digital_twin_id: str, telemetry: object, **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin
telemetry Required	object The telemetry data to be sent

Keyword-Only Parameters

Name	Description
message_id	str The message ID. If not specified, a UUID will be generated.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no digital twin with the provided ID.

query_twins

Query for digital twins.

Note: that there may be a delay between before changes in your instance are reflected in queries. For more details on query limitations, see https://docs.microsoft.com/azure/digital-twins/how-to-query-graph#query-limitations

query_twins(query_expression: str, **kwargs) -> AsyncItemPaged[Dict[str, object]]

Parameters

Name	Description
query_expression Required	str The query expression to execute.

Returns

Type	Description
AsyncItemPaged[Dict[str, object]]	An iterable of query results.

Exceptions

Type	Description
HttpResponseError

update_component

Update properties of a component on a digital twin using a JSON patch.

async update_component(digital_twin_id: str, component_name: str, json_patch: List[Dict[str, object]], **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
component_name Required	str The component being updated.
json_patch Required	List[Dict[str,object]] An update specification described by JSON Patch.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is either no digital twin with the provided ID or the component name is invalid.

update_digital_twin

Update a digital twin using a JSON patch.

async update_digital_twin(digital_twin_id: str, json_patch: List[Dict[str, object]], **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
json_patch Required	List[Dict[str,object]] An update specification described by JSON Patch. Updates to property values and $model elements may happen in the same request. Operations are limited to add, replace and remove.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is no digital twin with the provided ID.

update_relationship

Updates the properties of a relationship on a digital twin using a JSON patch.

async update_relationship(digital_twin_id: str, relationship_id: str, json_patch: List[Dict[str, object]], **kwargs) -> None

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
relationship_id Required	str The ID of the relationship to retrieve.
json_patch Required	List[Dict[str,object]] JSON Patch description of the update to the relationship properties.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is either no digital twin or relationship with the provided ID.

upsert_digital_twin

Create or update a digital twin.

async upsert_digital_twin(digital_twin_id: str, digital_twin: Dict[str, object], **kwargs) -> Dict[str, object]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
digital_twin Required	Dict[str,object] Dictionary containing the twin to create or update.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
Dict[str, object]	Dictionary containing the created or updated twin.

Exceptions

Type	Description
HttpResponseError
ResourceExistsError	If the digital twin already exists.

upsert_event_route

Create or update an event route.

async upsert_event_route(event_route_id: str, event_route: DigitalTwinsEventRoute, **kwargs) -> None

Parameters

Name	Description
event_route_id Required	str The ID of the event route to create or update.
event_route Required	DigitalTwinsEventRoute The event route data.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError

upsert_relationship

Create or update a relationship on a digital twin.

async upsert_relationship(digital_twin_id: str, relationship_id: str, relationship: Dict[str, object], **kwargs) -> Dict[str, object]

Parameters

Name	Description
digital_twin_id Required	str The ID of the digital twin.
relationship_id Required	str The ID of the relationship to retrieve.
relationship Required	Dict[str,object] Dictionary containing the relationship.

Keyword-Only Parameters

Name	Description
match_condition	MatchConditions The condition under which to perform the operation.
etag	str Only perform the operation if the entity's etag matches the value provided according to the match_condition.

Returns

Type	Description
Dict[str, object]	The created or updated relationship.

Exceptions

Type	Description
HttpResponseError
ResourceNotFoundError	If there is either no digital twin, target digital twin or relationship with the provided ID.