azure.digitaltwins.core package¶
-
class
azure.digitaltwins.core.DigitalTwinsClient(endpoint: str, credential: TokenCredential, **kwargs: Any)[source]¶ Creates an instance of the Digital Twins client.
- Parameters
endpoint (str) – The URL endpoint of an Azure search service
credential (TokenCredential) – A credential to authenticate requests to the service
-
create_models(dtdl_models: List[Dict[str, object]], **kwargs: Any) → List[DigitalTwinsModelData][source]¶ Create one or more models. When any error occurs, no models are uploaded.
- Parameters
model_list (List[Dict[str,object]]) – The set of models to create. Each dict corresponds to exactly one model.
- Returns
The list of created models.
- Return type
List[DigitalTwinsModelData]
- Raises
ResourceExistsError – One or more of the provided models already exist.
-
decommission_model(model_id: str, **kwargs: Any) → None[source]¶ Decommissions a model.
- Parameters
model_id (str) – The ID for the model. The ID is globally unique and case sensitive.
- Returns
None
- Return type
- Raises
ResourceNotFoundError – There is no model with the provided ID.
-
delete_digital_twin(digital_twin_id: str, **kwargs: Any) → None[source]¶ Delete a digital twin.
- Parameters
digital_twin_id (str) – The ID of the digital twin.
- Keyword Arguments
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
- Raises
ResourceNotFoundError – If there is no digital twin with the provided ID.
-
delete_event_route(event_route_id: str, **kwargs: Any) → None[source]¶ Delete an event route.
- Parameters
event_route_id (str) – The ID of the event route to delete.
- Returns
None
- Return type
- Raises
ResourceNotFoundError – There is no event route with the provided ID.
-
delete_model(model_id: str, **kwargs: Any) → None[source]¶ Delete a model.
- Parameters
model_id (str) – The ID of the model to delete.
- Returns
None
- Return type
- Raises
ResourceNotFoundError – There is no model with the provided ID.
ResourceExistsError – There are dependencies on the model that prevent it from being deleted.
-
delete_relationship(digital_twin_id: str, relationship_id: str, **kwargs: Any) → None[source]¶ Delete a relationship on a digital twin.
- Parameters
- Keyword Arguments
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
- Raises
ResourceNotFoundError – If there is either no digital twin or relationship with the provided ID.
-
get_component(digital_twin_id: str, component_name: str, **kwargs: Any) → Dict[str, object][source]¶ Get a component on a digital twin.
- Parameters
- Returns
Dictionary containing the component.
- Return type
- Raises
ResourceNotFoundError – If there is either no digital twin with the provided ID or the component name is invalid.
-
get_digital_twin(digital_twin_id: str, **kwargs: Any) → Dict[str, object][source]¶ Get a digital twin.
- Parameters
digital_twin_id (str) – The ID of the digital twin.
- Returns
Dictionary containing the twin.
- Return type
- Raises
ResourceNotFoundError – If the digital twin doesn’t exist.
-
get_event_route(event_route_id: str, **kwargs: Any) → DigitalTwinsEventRoute[source]¶ Get an event route.
- Parameters
event_route_id (str) – The ID of the event route.
- Returns
The event route object.
- Return type
- Raises
ResourceNotFoundError – There is no event route with the provided ID.
-
get_model(model_id: str, **kwargs: Any) → DigitalTwinsModelData[source]¶ Get a model, including the model metadata and the model definition.
- Parameters
model_id (str) – The ID of the model.
- Keyword Arguments
include_model_definition (bool) – Include the model definition as part of the result. The default value is False.
- Returns
The model data.
- Return type
- Raises
ResourceNotFoundError – If there is no model with the provided ID.
-
get_relationship(digital_twin_id: str, relationship_id: str, **kwargs: Any) → Dict[str, object][source]¶ Get a relationship on a digital twin.
- Parameters
- Returns
Dictionary containing the relationship.
- Return type
- Raises
ResourceNotFoundError – If there is either no digital twin or relationship with the provided ID.
-
list_event_routes(**kwargs: Any) → ItemPaged[DigitalTwinsEventRoute][source]¶ Retrieves all event routes.
- Keyword Arguments
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
- Raises
-
list_incoming_relationships(digital_twin_id: str, **kwargs: Any) → ~ azure.core.paging.ItemPaged[IncomingRelationship][source]¶ Retrieve all incoming relationships for a digital twin.
- Parameters
digital_twin_id (str) – The ID of the digital twin.
- Returns
An iterator like instance of either Relationship.
- Return type
- Raises
ResourceNotFoundError – If there is no digital twin with the provided ID.
-
list_models(dependencies_for: Optional[List[str]] = None, **kwargs: Any) → ItemPaged[DigitalTwinsModelData][source]¶ Get the list of models.
- Parameters
dependencies_for (List[str]) – The model IDs to have dependencies retrieved. If omitted, all models are retrieved.
- Keyword Arguments
- Returns
An iterator instance of list of model data.
- Return type
- Raises
-
list_relationships(digital_twin_id: str, relationship_id: Optional[str] = None, **kwargs: Any) → ~ azure.core.paging.ItemPaged[Dict[str, object]][source]¶ Retrieve relationships for a digital twin.
- Parameters
- Returns
An iterator instance of list of relationships
- Return type
- Raises
ResourceNotFoundError – If there is no digital twin with the provided ID.
-
publish_component_telemetry(digital_twin_id: str, component_name: str, telemetry: object, **kwargs: Any) → None[source]¶ Publish telemetry from a digital twin’s component, which is then consumed by one or many destination endpoints (subscribers) defined under.
- Parameters
- Keyword Arguments
message_id (str) – The message ID. If not specified, a UUID will be generated.
- Returns
None
- Return type
- Raises
ResourceNotFoundError – If there is no digital twin with the provided ID or the component name is invalid.
-
publish_telemetry(digital_twin_id: str, telemetry: object, **kwargs: Any) → None[source]¶ Publish telemetry from a digital twin, which is then consumed by one or many destination endpoints (subscribers) defined under.
- Parameters
- Keyword Arguments
message_id (str) – The message ID. If not specified, a UUID will be generated.
- Returns
None
- Return type
- Raises
ResourceNotFoundError – If there is no digital twin with the provided ID.
-
query_twins(query_expression: str, **kwargs: Any) → azure.core.paging.ItemPaged[Dict[str, object]][source]¶ 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
- Parameters
query_expression (str) – The query expression to execute.
- Returns
An iterable of query results.
- Return type
- Raises
-
update_component(digital_twin_id: str, component_name: str, json_patch: List[Dict[str, object]], **kwargs: Any) → None[source]¶ Update properties of a component on a digital twin using a JSON patch.
- Parameters
- Keyword Arguments
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
- Raises
ResourceNotFoundError – If there is either no digital twin with the provided ID or the component name is invalid.
-
update_digital_twin(digital_twin_id: str, json_patch: List[Dict[str, object]], **kwargs: Any) → None[source]¶ Update a digital twin using a JSON patch.
- Parameters
- Keyword Arguments
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
- Raises
ResourceNotFoundError – If there is no digital twin with the provided ID.
-
update_relationship(digital_twin_id: str, relationship_id: str, json_patch: List[Dict[str, object]], **kwargs: Any) → None[source]¶ Updates the properties of a relationship on a digital twin using a JSON patch.
- Parameters
- Keyword Arguments
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
- Raises
ResourceNotFoundError – If there is either no digital twin or relationship with the provided ID.
-
upsert_digital_twin(digital_twin_id: str, digital_twin: Dict[str, object], **kwargs: Any) → Dict[str, object][source]¶ Create or update a digital twin.
- Parameters
- Keyword Arguments
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
- Raises
ResourceExistsError – If the digital twin already exists.
-
upsert_event_route(event_route_id: str, event_route: DigitalTwinsEventRoute, **kwargs: Any) → None[source]¶ Create or update an event route.
- Parameters
event_route_id (str) – The ID of the event route to create or update.
event_route (DigitalTwinsEventRoute) – The event route data.
- Returns
None
- Return type
- Raises
-
upsert_relationship(digital_twin_id: str, relationship_id: str, relationship: Dict[str, object], **kwargs: Any) → Dict[str, object][source]¶ Create or update a relationship on a digital twin.
- Parameters
- Keyword Arguments
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
- Raises
ResourceNotFoundError – If there is either no digital twin, target digital twin or relationship with the provided ID.
-
class
azure.digitaltwins.core.DigitalTwinsEventRoute(*, endpoint_name: str, filter: str, **kwargs)[source]¶ A route which directs notification and telemetry events to an endpoint. Endpoints are a destination outside of Azure Digital Twins such as an EventHub.
Variables are only populated by the server, and will be ignored when sending a request.
All required parameters must be populated in order to send to Azure.
- Variables
- Keyword Arguments
-
as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)¶ Return a dict that can be JSONify using json.dump.
Advanced usage might optionaly use a callback as parameter:
Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.
The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.
See the three examples in this file:
attribute_transformer
full_restapi_key_transformer
last_restapi_key_transformer
If you want XML serialization, you can pass the kwargs is_xml=True.
- Parameters
key_transformer (function) – A key transformer function.
- Returns
A dict JSON compatible object
- Return type
-
classmethod
deserialize(data, content_type=None)¶ Parse a str using the RestAPI syntax and return a model.
-
classmethod
enable_additional_properties_sending()¶
-
classmethod
from_dict(data, key_extractors=None, content_type=None)¶ Parse a dict using given key extractor return a model.
By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)
-
classmethod
is_xml_model()¶
-
serialize(keep_readonly=False, **kwargs)¶ Return the JSON that would be sent to azure from this model.
This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).
If you want XML serialization, you can pass the kwargs is_xml=True.
-
class
azure.digitaltwins.core.DigitalTwinsModelData(*, id: str, display_name: Optional[Dict[str, str]] = None, description: Optional[Dict[str, str]] = None, upload_time: Optional[datetime.datetime] = None, decommissioned: Optional[bool] = False, model: Optional[Any] = None, **kwargs)[source]¶ A model definition and metadata for that model.
All required parameters must be populated in order to send to Azure.
- Variables
display_name (dict[str, str]) – A language map that contains the localized display names as specified in the model definition.
description (dict[str, str]) – A language map that contains the localized descriptions as specified in the model definition.
id (str) – Required. The id of the model as specified in the model definition.
upload_time (datetime) – The time the model was uploaded to the service.
decommissioned (bool) – Indicates if the model is decommissioned. Decommissioned models cannot be referenced by newly created digital twins.
model (any) – The model definition.
- Keyword Arguments
display_name (dict[str, str]) – A language map that contains the localized display names as specified in the model definition.
description (dict[str, str]) – A language map that contains the localized descriptions as specified in the model definition.
id (str) – Required. The id of the model as specified in the model definition.
upload_time (datetime) – The time the model was uploaded to the service.
decommissioned (bool) – Indicates if the model is decommissioned. Decommissioned models cannot be referenced by newly created digital twins.
model (any) – The model definition.
-
as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)¶ Return a dict that can be JSONify using json.dump.
Advanced usage might optionaly use a callback as parameter:
Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.
The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.
See the three examples in this file:
attribute_transformer
full_restapi_key_transformer
last_restapi_key_transformer
If you want XML serialization, you can pass the kwargs is_xml=True.
- Parameters
key_transformer (function) – A key transformer function.
- Returns
A dict JSON compatible object
- Return type
-
classmethod
deserialize(data, content_type=None)¶ Parse a str using the RestAPI syntax and return a model.
-
classmethod
enable_additional_properties_sending()¶
-
classmethod
from_dict(data, key_extractors=None, content_type=None)¶ Parse a dict using given key extractor return a model.
By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)
-
classmethod
is_xml_model()¶
-
serialize(keep_readonly=False, **kwargs)¶ Return the JSON that would be sent to azure from this model.
This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).
If you want XML serialization, you can pass the kwargs is_xml=True.
-
class
azure.digitaltwins.core.IncomingRelationship(*, relationship_id: Optional[str] = None, source_id: Optional[str] = None, relationship_name: Optional[str] = None, relationship_link: Optional[str] = None, **kwargs)[source]¶ An incoming relationship.
- Variables
relationship_id (str) – A user-provided string representing the id of this relationship, unique in the context of the source digital twin, i.e. sourceId + relationshipId is unique in the context of the service.
source_id (str) – The id of the source digital twin.
relationship_name (str) – The name of the relationship.
relationship_link (str) – Link to the relationship, to be used for deletion.
- Keyword Arguments
relationship_id (str) – A user-provided string representing the id of this relationship, unique in the context of the source digital twin, i.e. sourceId + relationshipId is unique in the context of the service.
source_id (str) – The id of the source digital twin.
relationship_name (str) – The name of the relationship.
relationship_link (str) – Link to the relationship, to be used for deletion.
-
as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)¶ Return a dict that can be JSONify using json.dump.
Advanced usage might optionaly use a callback as parameter:
Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.
The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.
See the three examples in this file:
attribute_transformer
full_restapi_key_transformer
last_restapi_key_transformer
If you want XML serialization, you can pass the kwargs is_xml=True.
- Parameters
key_transformer (function) – A key transformer function.
- Returns
A dict JSON compatible object
- Return type
-
classmethod
deserialize(data, content_type=None)¶ Parse a str using the RestAPI syntax and return a model.
-
classmethod
enable_additional_properties_sending()¶
-
classmethod
from_dict(data, key_extractors=None, content_type=None)¶ Parse a dict using given key extractor return a model.
By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)
-
classmethod
is_xml_model()¶
-
serialize(keep_readonly=False, **kwargs)¶ Return the JSON that would be sent to azure from this model.
This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).
If you want XML serialization, you can pass the kwargs is_xml=True.