digital_twins

Creates, updates, deletes, gets or lists a digital_twins resource.

Overview

Name	digital_twins
Type	Resource
Id	azure.digital_twins_core.digital_twins

Fields

The following fields are returned by SELECT queries:

list_incoming_relationships

Name	Datatype	Description
$relationshipId	string	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.
$relationshipLink	string	Link to the relationship, to be used for deletion.
$relationshipName	string	The name of the relationship.
$sourceId	string	The id of the source digital twin.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_incoming_relationships	select	id, endpoint	traceparent, tracestate	Retrieves all incoming relationship for a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.
update	update	id, endpoint	traceparent, tracestate, If-Match	Updates a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or payload is invalid. * JsonPatchInvalid - The JSON Patch provided is invalid. * ValidationFailed - Applying the patch results in an invalid digital twin. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
delete	delete	id, endpoint	traceparent, tracestate, If-Match	Deletes a digital twin. All relationships referencing the digital twin must already be deleted. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * RelationshipsNotDeleted - The digital twin contains relationships. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
list_relationships	exec	id, endpoint	traceparent, tracestate, relationshipName	Retrieves the relationships from a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.
get_by_id	exec	id, endpoint	traceparent, tracestate	Retrieves a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.
add	exec	id, endpoint	traceparent, tracestate, If-None-Match	Adds or replaces a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id or payload is invalid. * ModelDecommissioned - The model for the digital twin is decommissioned. * TwinLimitReached - The maximum number of digital twins allowed has been reached. * ValidationFailed - The digital twin payload is not valid. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
get_relationship_by_id	exec	id, relationship_id, endpoint	traceparent, tracestate	Retrieves a relationship between two digital twins. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id or relationship id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * RelationshipNotFound - The relationship was not found.
add_relationship	exec	id, relationship_id, endpoint	traceparent, tracestate, If-None-Match	Adds a relationship between two digital twins. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id, relationship id, or payload is invalid. * InvalidRelationship - The relationship is invalid. * OperationNotAllowed - The relationship cannot connect to the same digital twin. * ValidationFailed - The relationship content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * TargetTwinNotFound - The digital twin target of the relationship was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
delete_relationship	exec	id, relationship_id, endpoint	traceparent, tracestate, If-Match	Deletes a relationship between two digital twins. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or relationship id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * RelationshipNotFound - The relationship was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
update_relationship	exec	id, relationship_id, endpoint	traceparent, tracestate, If-Match	Updates the properties on a relationship between two digital twins. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or relationship id is invalid. * InvalidRelationship - The relationship is invalid. * JsonPatchInvalid - The JSON Patch provided is invalid. * ValidationFailed - The relationship content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * RelationshipNotFound - The relationship was not found. * 409 Conflict * RelationshipAlreadyExists - The relationship already exists. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
get_component	exec	id, component_path, endpoint	traceparent, tracestate	Retrieves a component from a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id or component path is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * ComponentNotFound - The component path was not found.
update_component	exec	id, component_path, endpoint	traceparent, tracestate, If-Match	Updates a component on a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id, component path, or payload is invalid. * JsonPatchInvalid - The JSON Patch provided is invalid. * ValidationFailed - Applying the patch results in an invalid digital twin. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
send_telemetry	exec	id, Message-Id, endpoint	traceparent, tracestate, Telemetry-Source-Time	Sends telemetry on behalf of a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or message id is invalid. * ValidationFailed - The telemetry content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.
send_component_telemetry	exec	id, component_path, Message-Id, endpoint	traceparent, tracestate, Telemetry-Source-Time	Sends telemetry on behalf of a component in a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id, message id, or component path is invalid. * ValidationFailed - The telemetry content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * ComponentNotFound - The component path was not found.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
Message-Id	string	A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating messages. Required.
component_path	string	The name of the DTDL component. Required.
endpoint	string	The service endpoint host (no scheme). (default: )
id	string	The id of the digital twin. The id is unique within the service and case sensitive. Required.
relationship_id	string	The id of the relationship. The id is unique within the digital twin and case sensitive. Required.
If-Match	string
If-None-Match	string
Telemetry-Source-Time	string	An RFC 3339 timestamp that identifies the time the telemetry was measured. Default value is None.
relationshipName	string	The name of the relationship. Default value is None.
traceparent	string
tracestate	string

SELECT examples

list_incoming_relationships

Retrieves all incoming relationship for a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.

SELECT
$relationshipId,
$relationshipLink,
$relationshipName,
$sourceId
FROM azure.digital_twins_core.digital_twins
WHERE id = '{{ id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND traceparent = '{{ traceparent }}'
AND tracestate = '{{ tracestate }}'
;

UPDATE examples

update

Updates a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or payload is invalid. * JsonPatchInvalid - The JSON Patch provided is invalid. * ValidationFailed - Applying the patch results in an invalid digital twin. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

UPDATE azure.digital_twins_core.digital_twins
SET 
traceparent = '{{ traceparent }}',
tracestate = '{{ tracestate }}',
If-Match = '{{ If-Match }}'
WHERE 
id = '{{ id }}' --required
AND endpoint = '{{ endpoint }}' --required
AND traceparent = '{{ traceparent}}'
AND tracestate = '{{ tracestate}}'
AND If-Match = '{{ If-Match}}';

DELETE examples

delete

Deletes a digital twin. All relationships referencing the digital twin must already be deleted. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * RelationshipsNotDeleted - The digital twin contains relationships. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

DELETE FROM azure.digital_twins_core.digital_twins
WHERE id = '{{ id }}' --required
AND endpoint = '{{ endpoint }}' --required
AND traceparent = '{{ traceparent }}'
AND tracestate = '{{ tracestate }}'
AND If-Match = '{{ If-Match }}'
;

Lifecycle Methods

list_relationships

Retrieves the relationships from a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.

EXEC azure.digital_twins_core.digital_twins.list_relationships 
@id='{{ id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@relationshipName='{{ relationshipName }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}"
}'
;

get_by_id

Retrieves a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.

EXEC azure.digital_twins_core.digital_twins.get_by_id 
@id='{{ id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}"
}'
;

add

Adds or replaces a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id or payload is invalid. * ModelDecommissioned - The model for the digital twin is decommissioned. * TwinLimitReached - The maximum number of digital twins allowed has been reached. * ValidationFailed - The digital twin payload is not valid. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

EXEC azure.digital_twins_core.digital_twins.add 
@id='{{ id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@If-None-Match='{{ If-None-Match }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}", 
"If-None-Match": "{{ If-None-Match }}"
}'
;

get_relationship_by_id

Retrieves a relationship between two digital twins. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id or relationship id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * RelationshipNotFound - The relationship was not found.

EXEC azure.digital_twins_core.digital_twins.get_relationship_by_id 
@id='{{ id }}' --required, 
@relationship_id='{{ relationship_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}"
}'
;

add_relationship

Adds a relationship between two digital twins. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id, relationship id, or payload is invalid. * InvalidRelationship - The relationship is invalid. * OperationNotAllowed - The relationship cannot connect to the same digital twin. * ValidationFailed - The relationship content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * TargetTwinNotFound - The digital twin target of the relationship was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

EXEC azure.digital_twins_core.digital_twins.add_relationship 
@id='{{ id }}' --required, 
@relationship_id='{{ relationship_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@If-None-Match='{{ If-None-Match }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}", 
"If-None-Match": "{{ If-None-Match }}"
}'
;

delete_relationship

Deletes a relationship between two digital twins. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or relationship id is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * RelationshipNotFound - The relationship was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

EXEC azure.digital_twins_core.digital_twins.delete_relationship 
@id='{{ id }}' --required, 
@relationship_id='{{ relationship_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@If-Match='{{ If-Match }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}", 
"If-Match": "{{ If-Match }}"
}'
;

update_relationship

Updates the properties on a relationship between two digital twins. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or relationship id is invalid. * InvalidRelationship - The relationship is invalid. * JsonPatchInvalid - The JSON Patch provided is invalid. * ValidationFailed - The relationship content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * RelationshipNotFound - The relationship was not found. * 409 Conflict * RelationshipAlreadyExists - The relationship already exists. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

EXEC azure.digital_twins_core.digital_twins.update_relationship 
@id='{{ id }}' --required, 
@relationship_id='{{ relationship_id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@If-Match='{{ If-Match }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}", 
"If-Match": "{{ If-Match }}"
}'
;

get_component

Retrieves a component from a digital twin. Status codes: * 200 OK * 400 Bad Request * InvalidArgument - The digital twin id or component path is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * ComponentNotFound - The component path was not found.

EXEC azure.digital_twins_core.digital_twins.get_component 
@id='{{ id }}' --required, 
@component_path='{{ component_path }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}"
}'
;

update_component

Updates a component on a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id, component path, or payload is invalid. * JsonPatchInvalid - The JSON Patch provided is invalid. * ValidationFailed - Applying the patch results in an invalid digital twin. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * 412 Precondition Failed * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.

EXEC azure.digital_twins_core.digital_twins.update_component 
@id='{{ id }}' --required, 
@component_path='{{ component_path }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@If-Match='{{ If-Match }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}", 
"If-Match": "{{ If-Match }}"
}'
;

send_telemetry

Sends telemetry on behalf of a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id or message id is invalid. * ValidationFailed - The telemetry content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found.

EXEC azure.digital_twins_core.digital_twins.send_telemetry 
@id='{{ id }}' --required, 
@Message-Id='{{ Message-Id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@Telemetry-Source-Time='{{ Telemetry-Source-Time }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}"
}'
;

send_component_telemetry

Sends telemetry on behalf of a component in a digital twin. Status codes: * 204 No Content * 400 Bad Request * InvalidArgument - The digital twin id, message id, or component path is invalid. * ValidationFailed - The telemetry content is invalid. * 404 Not Found * DigitalTwinNotFound - The digital twin was not found. * ComponentNotFound - The component path was not found.

EXEC azure.digital_twins_core.digital_twins.send_component_telemetry 
@id='{{ id }}' --required, 
@component_path='{{ component_path }}' --required, 
@Message-Id='{{ Message-Id }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@traceparent='{{ traceparent }}', 
@tracestate='{{ tracestate }}', 
@Telemetry-Source-Time='{{ Telemetry-Source-Time }}' 
@@json=
'{
"traceparent": "{{ traceparent }}", 
"tracestate": "{{ tracestate }}"
}'
;