DigitalTwinsClient Class

Creates an instance of the Digital Twins client.

Inheritance
builtins.object
DigitalTwinsClient

Constructor

DigitalTwinsClient(endpoint: str, credential: TokenCredential, **kwargs: Any)

Parameters

endpoint
str
Required

The URL endpoint of an Azure search service

credential
TokenCredential
Required

A credential to authenticate requests to the service

Methods

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.

create_models

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

create_models(dtdl_models: List[Dict[str, object]], **kwargs: Any) -> List[DigitalTwinsModelData]

Parameters

model_list
List[Dict[str,object]]
Required

The set of models to create. Each dict corresponds to exactly one model.

Returns

The list of created models.

Return type

Exceptions

One or more of the provided models already exist.

decommission_model

Decommissions a model.

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

Parameters

model_id
str
Required

The ID for the model. The ID is globally unique and case sensitive.

Returns

None

Return type

Exceptions

There is no model with the provided ID.

delete_digital_twin

Delete a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

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

None

Return type

Exceptions

If there is no digital twin with the provided ID.

delete_event_route

Delete an event route.

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

Parameters

event_route_id
str
Required

The ID of the event route to delete.

Returns

None

Return type

Exceptions

There is no event route with the provided ID.

delete_model

Delete a model.

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

Parameters

model_id
str
Required

The ID of the model to delete.

Returns

None

Return type

Exceptions

There is no model with the provided ID.

There are dependencies on the model that prevent it from being deleted.

delete_relationship

Delete a relationship on a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

relationship_id
str
Required

The ID of the relationship to delete.

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

None

Return type

Exceptions

If there is either no digital twin or relationship with the provided ID.

get_component

Get a component on a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

component_name
str
Required

The component being retrieved.

Returns

Dictionary containing the component.

Return type

Exceptions

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

get_digital_twin

Get a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

Returns

Dictionary containing the twin.

Return type

Exceptions

If the digital twin doesn't exist.

get_event_route

Get an event route.

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

Parameters

event_route_id
str
Required

The ID of the event route.

Returns

The event route object.

Return type

Exceptions

There is no event route with the provided ID.

get_model

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

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

Parameters

model_id
str
Required

The ID of the model.

include_model_definition
bool

Include the model definition as part of the result. The default value is False.

Returns

The model data.

Return type

Exceptions

If there is no model with the provided ID.

get_relationship

Get a relationship on a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

relationship_id
str
Required

The ID of the relationship to retrieve.

Returns

Dictionary containing the relationship.

Return type

Exceptions

If there is either no digital twin or relationship with the provided ID.

list_event_routes

Retrieves all event routes.

list_event_routes(**kwargs: Any) -> ItemPaged[DigitalTwinsEventRoute]

Parameters

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

An iterator instance of event routes.

Return type

Exceptions

list_incoming_relationships

Retrieve all incoming relationships for a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

Returns

An iterator like instance of either Relationship.

Return type

Exceptions

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: Any) -> ItemPaged[DigitalTwinsModelData]

Parameters

dependencies_for
List[str]
Required

The model IDs to have dependencies retrieved. If omitted, all models are retrieved.

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

An iterator instance of list of model data.

Return type

Exceptions

list_relationships

Retrieve relationships for a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

relationship_id
str
Required

The ID of the relationship to get (if None all the relationship will be retrieved).

Returns

An iterator instance of list of relationships

Return type

Exceptions

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.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

component_name
str
Required

The name of the DTDL component.

telemetry
object
Required

The telemetry data to be sent.

message_id
str

The message ID. If not specified, a UUID will be generated.

Returns

None

Return type

Exceptions

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.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin

telemetry
object
Required

The telemetry data to be sent

message_id
str

The message ID. If not specified, a UUID will be generated.

Returns

None

Return type

Exceptions

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: Any) -> ItemPaged[Dict[str, object]]

Parameters

query_expression
str
Required

The query expression to execute.

Returns

An iterable of query results.

Return type

Exceptions

update_component

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

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

component_name
str
Required

The component being updated.

json_patch
List[Dict[str,object]]
Required

An update specification described by JSON Patch.

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

None

Return type

Exceptions

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.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

json_patch
List[Dict[str,object]]
Required

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.

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

None

Return type

Exceptions

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.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

relationship_id
str
Required

The ID of the relationship to retrieve.

json_patch
List[Dict[str,object]]
Required

JSON Patch description of the update to the relationship properties.

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

None

Return type

Exceptions

If there is either no digital twin or relationship with the provided ID.

upsert_digital_twin

Create or update a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

digital_twin
Dict[str,object]
Required

Dictionary containing the twin to create or update.

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

Dictionary containing the created or updated twin.

Return type

Exceptions

If the digital twin already exists.

upsert_event_route

Create or update an event route.

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

Parameters

event_route_id
str
Required

The ID of the event route to create or update.

event_route
DigitalTwinsEventRoute
Required

The event route data.

Returns

None

Return type

Exceptions

upsert_relationship

Create or update a relationship on a digital twin.

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

Parameters

digital_twin_id
str
Required

The ID of the digital twin.

relationship_id
str
Required

The ID of the relationship to retrieve.

relationship
Dict[str,object]
Required

Dictionary containing the relationship.

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

The created or updated relationship.

Return type

Exceptions

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