Поделиться через

Azure Digital Twins (Preview)

  • Reference

Azure Digital Twins is an Internet of Things (IoT) platform that enables you to create a digital representation of real-world things, places, business processes, and people. This connector enables you to perform operations on digital twins and models as well as run ADT queries.

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
     -   US Department of Defense (DoD)
Power Automate Standard All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Power Apps Standard All Power Apps regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Contact
Name Microsoft
URL https://azure.microsoft.com/support/
Connector Metadata
Publisher Microsoft Corporation
Website https://azure.microsoft.com/products/digital-twins/
Privacy policy https://privacy.microsoft.com
Categories Internet of Things

Azure Digital Twins is an Internet of Things (IoT) platform that enables you to create a digital representation of real-world things, places, business processes, and people. Gain insights that help you drive better products, optimize operations and costs, and create breakthrough customer experiences. This connectors enables to interact with the digital twins API. It will allow you to create, manage and query the twins.

Prerequisites

You will need the following to proceed:

  • A Microsoft Power Apps or Power Automate plan with custom connector feature
  • An Azure subscription
  • The Power platform CLI tools
  • Azure Digital Twin instance

How to get credentials

Use your Microsoft Entra ID user id and password that is given permission to access the Digital twins endpoints.

Get started with your connector

Known issues and limitations

  • Since the ADT deals with dynamic schema responses. The app developer should parse the json to their model before consuming it. eg: Set(jsonVal, AzureDigitalTwins.GetTwinById(TextInput1.Text).result); Set(parsedResp, ParseJSON(jsonVal)); Set( DtId, Text(parsedResp.'$dtId'));

Common errors and remedies

  • Json Parser error:
    • Incase the model doesnt match with the parsed json, you will receive a json parser error. To solve that, please check the response xml and access the values accordingly.

FAQ

  • Can we create ADT instance through connector?

    • You should go to Azure to create and delete the ADT instance.

  • Is pagenation available?

    • Pagenation is done within the app development by using the continuation token.

  • Can we access multiple ADT instance in one app?

    • In order to access the multiple ADT instance, a new connection has to be established and used it appropriately within the application.

Creating a connection

The connector supports the following authentication types:
Default Parameters for creating connection. All regions Not shareable

Default

Applicable: All regions

Parameters for creating connection.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name Type Description Required
ADT Instance Name : string Enter your ADT instance URI True

Throttling Limits

Name Calls Renewal Period
API calls per connection 300 60 seconds

Actions

Add Model

Uploads one or more models. When any error occurs, no models are uploaded.
Add Relationship

Adds a relationship between two digital twins.
Add Twin

Adds or replaces a digital twin.
Delete Model

Deletes a model. A model can only be deleted if no other models reference it.
Delete Relationship

Deletes a relationship between two digital twins.
Delete Twin

Deletes a digital twin. All relationships referencing the digital twin must already be deleted.
Get Component

Retrieves a component from a digital twin.
Get Model By Id

Retrieves model metadata and, optionally, the model definition.
Get Relationship by Id

Retrieves a relationship between two digital twins.
Get Twin by Id

Retrieves a digital twin and its data.
List Incoming Relationships

Retrieves all incoming relationships for a digital twin.
List Models

Retrieves model metadata and, optionally, model definitions.
List Relationships

Retrieves all outgoing relationships from a digital twin.
Query API

Executes a query that allows traversing relationships and filtering by property values.
Send Component Telemetry

Sends telemetry on behalf of a component in a digital twin.
Send Telemetry

Sends telemetry on behalf of a digital twin.
Update Component

Updates integer properties on a component of a twin.
Update Model's Property

Updates the metadata for a model.
Update Relationship

Updates integer properties on a relationship between two digital twins.
Update Twin

Updates properties on a twin.

Add Model

Operation ID:
AddModels

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

Parameters

Name Key Required Type Description
@id
 @id string

The id of the model as specified in the model definition.
@type
 @type string

Interface Type.
displayName
 displayName string

A language map that contains the localized display names as specified in the model definition.
@type
 @type string

Property Type.
name
 name string

Name of the property.
displayName
 displayName string

Property name.
schema
 schema string

Schema of the proerty.
@context
 @context string

Metadata context.

Returns

Name Path Type Description
array of object
id
 id string

The id of the model as specified in the model definition.
additionalProperties
 displayName.additionalProperties string

Property Values.
uploadTime
 uploadTime string

The time the model was uploaded to the service.
decommissioned
 decommissioned boolean

Indicates if the model is decommissioned. Decommissioned models cannot be referenced by newly created digital twins.

Add Relationship

Operation ID:
AddRelationship

Adds a relationship between two digital twins.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Relationship id
 relationshipId True string

The id of the relationship. The id is unique within the digital twin and case sensitive.
Request
 value string

Request for the API.

Returns

Body
TwinRelationship

Add Twin

Operation ID:
AddTwin

Adds or replaces a digital twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Request
 value string

Request for the API.

Returns

Body
TwinResult

Delete Model

Operation ID:
DeleteModel

Deletes a model. A model can only be deleted if no other models reference it.

Parameters

Name Key Required Type Description
Model id
 modelid True string

The id of the Model. The id is unique within the service and case sensitive.

Delete Relationship

Operation ID:
DeleteRelationship

Deletes a relationship between two digital twins.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Relationship id
 relationshipId True string

The id of the relationship. The id is unique within the digital twin and case sensitive.

Delete Twin

Operation ID:
DeleteTwin

Deletes a digital twin. All relationships referencing the digital twin must already be deleted.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.

Get Component

Operation ID:
GetComponent

Retrieves a component from a digital twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
DTDL component
 componentPath True string

The name of the DTDL component.

Returns

Body
GetComponentResult

Get Model By Id

Operation ID:
GetModelById

Retrieves model metadata and, optionally, the model definition.

Parameters

Name Key Required Type Description
Model id
 modelid True string

The id of the Model. The id is unique within the service and case sensitive.
Include Model Definition
 includeModelDefinition string

When true the model definition will be returned as part of the result.

Returns

Name Path Type Description
id
 id string

The id of the model as specified in the model definition.
uploadTime
 uploadTime string

The time the model was uploaded to the service.
decommissioned
 decommissioned boolean

Indicates if the model is decommissioned. Decommissioned models cannot be referenced by newly created digital twins.
@id
 model.@id string

The id of the model as specified in the model definition.
@type
 model.@type string

Interface Type.
contents
 model.contents array of object

Response contents.
@type
 model.contents.@type string

Property Type.
name
 model.contents.name string

Property name.
displayName
 model.contents.displayName string

Property displayName.
schema
 model.contents.schema string

Schema of the Property.
@context
 model.@context string

Metadata context.

Get Relationship by Id

Operation ID:
GetRelationshipById

Retrieves a relationship between two digital twins.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Relationship id
 relationshipId True string

The id of the relationship. The id is unique within the digital twin and case sensitive.

Returns

Body
TwinRelationship

Get Twin by Id

Operation ID:
GetTwinById

Retrieves a digital twin and its data.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.

Returns

Body
TwinResult

List Incoming Relationships

Operation ID:
ListIncomingRelationships

Retrieves all incoming relationships for a digital twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Continuation Token
 continuationToken string

A token which is used to retrieve the next set of results from a previous query.

Returns

Name Path Type Description
value
 value array of IncomingRelationship

The collection of Incoming relationships.
continuationToken
 continuationToken string

Continuation Token the next page of Twin Relationship.
nextLink
 nextLink string

URL to get the next page of Incoming Relationship.

List Models

Operation ID:
ListModels

Retrieves model metadata and, optionally, model definitions.

Parameters

Name Key Required Type Description
Dependencies for Model
 dependenciesFor string

The set of the models which will have their dependencies retrieved. If omitted, all models are retrieved.
Include Model Definition
 includeModelDefinition string

When true the model definition will be returned as part of the result.
Continuation Token
 continuationToken string

A token which is used to retrieve the next set of results from a previous query.

Returns

Name Path Type Description
value
 value array of object

Array values.
id
 value.id string

The id of the model as specified in the model definition.
uploadTime
 value.uploadTime string

The time the model was uploaded to the service.
decommissioned
 value.decommissioned boolean

Indicates if the model is decommissioned. Decommissioned models cannot be referenced by newly created digital twins.
@id
 value.model.@id string

The id of the model as specified in the model definition.
@type
 value.model.@type string

Interface Type.
contents
 value.model.contents array of object

Response contents.
@type
 value.model.contents.@type string

Property Type.
name
 value.model.contents.name string

Property name.
displayName
 value.model.contents.displayName string

Property displayName.
schema
 value.model.contents.schema string

Schema of the Property.
@context
 value.model.@context string

Metadata context.
displayName
 value.model.displayName string

Model displayName.
additionalProperties
 value.displayName.additionalProperties string

Property Values.
continuationToken
 continuationToken string

Continuation Token the next page of Twin Relationship.
nextLink
 nextLink string

URL to get the next page of Models.

List Relationships

Operation ID:
ListRelationships

Retrieves all outgoing relationships from a digital twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Continuation Token
 continuationToken string

A token which is used to retrieve the next set of results from a previous query.

Returns

Name Path Type Description
value
 value array of TwinRelationship

The collection of twin relationships.
continuationToken
 continuationToken string

Continuation Token the next page of Twin Relationship.
nextLink
 nextLink string

URL to get the next page of Twin Relationship.

Query API

Operation ID:
QueryTwins

Executes a query that allows traversing relationships and filtering by property values.

Parameters

Name Key Required Type Description
query
 query string

Query the Twins.
continuationToken
 continuationToken string

Link to get next set of items.

Returns

Body
QueryResult

Send Component Telemetry

Operation ID:
SendComponentTelemetry

Sends telemetry on behalf of a component in a digital twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
DTDL component
 componentPath True string

The name of the DTDL component.
Message id
 Message-Id True string

A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating messages.
Timestamp
 Telemetry-Source-Time string

An RFC 3339 timestamp that identifies the time the telemetry was measured.
Component Telemetry Request
 value string

Send Component Telemetry Inputs.

Send Telemetry

Operation ID:
SendTelemetry

Sends telemetry on behalf of a digital twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Message id
 Message-Id True string

A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating messages.
Timestamp
 Telemetry-Source-Time string

An RFC 3339 timestamp that identifies the time the telemetry was measured.
Telemetry Request
 value string

Send Telemetry Inputs.

Update Component

Operation ID:
UpdateComponent

Updates integer properties on a component of a twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
DTDL component
 componentPath True string

The name of the DTDL component.
Request
 value string

Request for the API.

Update Model's Property

Operation ID:
UpdateModel

Updates the metadata for a model.

Parameters

Name Key Required Type Description
Model id
 modelid True string

The id of the Model. The id is unique within the service and case sensitive.
Request
 value string

Request for the API.

Update Relationship

Operation ID:
UpdateRelationship

Updates integer properties on a relationship between two digital twins.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Relationship id
 relationshipId True string

The id of the relationship. The id is unique within the digital twin and case sensitive.
Request
 value string

Request for the API.

Update Twin

Operation ID:
UpdateTwin

Updates properties on a twin.

Parameters

Name Key Required Type Description
Digital twin id
 twinid True string

The id of the digital twin. The id is unique within the service and case sensitive.
Request
 value string

Request for the API.

Definitions

IncomingRelationship

Name Path Type Description
$sourceId
 $sourceId string

Source Id.
$relationshipId
 $relationshipId string

Relationship Id.
$relationshipName
 $relationshipName string

Relationship Name.
$relationshipLink
 $relationshipLink string

Relationship Link.

TwinRelationship

Name Path Type Description
$sourceId
 $sourceId string

Source Id.
$relationshipId
 $relationshipId string

Relationship Id.
$targetId
 $targetId string

Target Id.
$relationshipName
 $relationshipName string

Relationship Name.
$etag
 $etag string

E Tag Link.
additionalProperties
 additionalProperties string

Property Values.

TwinResult

Name Path Type Description
Result
 result string

Results From the Twin.

GetComponentResult

Name Path Type Description
Result
 result string

Results From the Twin.

QueryResult

Name Path Type Description
Value
 value string

Results From the Twin.
Continuation Token
 continuationToken string

Link to get next set of items.