Share via

az dt twin

  • Reference

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.46.0 or higher). The extension will automatically install the first time you run an az dt twin command. Learn more about extensions.

Manage and configure the digital twins of a Digital Twins instance.

Commands

Name Description Type Status
az dt twin component

Show and update the digital twin components of a Digital Twins instance.

 Extension GA
az dt twin component show

Show details of a digital twin component.

 Extension GA
az dt twin component update

Update a digital twin component via JSON patch specification.

 Extension GA
az dt twin create

Create a digital twin on an instance.

 Extension GA
az dt twin delete

Remove a digital twin. All relationships referencing this twin must already be deleted.

 Extension GA
az dt twin delete-all

Deletes all digital twins within a Digital Twins instance, including all relationships for those twins.

 Extension GA
az dt twin query

Query the digital twins of an instance. Allows traversing relationships and filtering by property values.

 Extension GA
az dt twin relationship

Manage and configure the digital twin relationships of a Digital Twins instance.

 Extension GA
az dt twin relationship create

Create a relationship between source and target digital twins.

 Extension GA
az dt twin relationship delete

Delete a digital twin relationship on a Digital Twins instance.

 Extension GA
az dt twin relationship delete-all

Deletes all digital twin relationships within a Digital Twins instance, including incoming relationships.

 Extension GA
az dt twin relationship list

List the relationships of a digital twin.

 Extension GA
az dt twin relationship show

Show details of a digital twin relationship.

 Extension GA
az dt twin relationship update

Updates the properties of a relationship between two digital twins via JSON patch specification.

 Extension GA
az dt twin show

Show the details of a digital twin.

 Extension GA
az dt twin telemetry

Test and validate the event routes and endpoints of a Digital Twins instance.

 Extension GA
az dt twin telemetry send

Sends telemetry on behalf of a digital twin. If component path is provided the emitted telemetry is on behalf of the component.

 Extension GA
az dt twin update

Update an instance digital twin via JSON patch specification.

 Extension GA

az dt twin create

Create a digital twin on an instance.

--properties can be inline JSON or file path. Note: --properties are required for twins that contain components.

az dt twin create --dt-name
                  --dtmi
                  --twin-id
                  [--if-none-match]
                  [--properties]
                  [--resource-group]

Examples

Create a digital twin from an existing (prior-created) model.

az dt twin create -n {instance_or_hostname} --dtmi "dtmi:com:example:Room;1" --twin-id {twin_id}

Create a digital twin from an existing (prior-created) model with if-none-match tag.

az dt twin create -n {instance_or_hostname} --dtmi "dtmi:com:example:Room;1" --twin-id {twin_id} --if-none-match

Create a digital twin from an existing (prior-created) model. Instantiate with property values.

az dt twin create -n {instance_or_hostname} --dtmi "dtmi:com:example:DeviceInformation;1" --twin-id {twin_id} --properties '{"manufacturer": "Microsoft"}'

Create a digital twin with component from existing (prior-created) models. Instantiate component with minimum properties.

az dt twin create -n {instance_or_hostname} --dtmi "dtmi:com:example:TemperatureController;1" --twin-id {twin_id} --properties '{
    "Thermostat": {
        "$metadata": {},
    }
}'

Create a digital twin with component from existing (prior-created) models. Instantiate with property values.

az dt twin create -n {instance_or_hostname} --dtmi "dtmi:com:example:TemperatureController;1" --twin-id {twin_id} --properties '{
    "Temperature": 10.2,
    "Thermostat": {
        "$metadata": {},
        "setPointTemp": 23.12
    }
}'

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--dtmi --model-id -m

Digital Twins model Id. Example: dtmi:com:example:Room;2.

--twin-id -t

The digital twin Id.

Optional Parameters

--if-none-match

Indicates the create operation should fail if an existing twin with the same id exists.

Default value: False
--properties -p

Initial property values for instantiating a digital twin or related components. Provide file path or inline JSON. Properties are required for twins that contain components, at the minimum you must provide an empty $metadata object for each component.

--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group={name}.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az dt twin delete

Remove a digital twin. All relationships referencing this twin must already be deleted.

az dt twin delete --dt-name
                  --twin-id
                  [--etag]
                  [--resource-group]

Examples

Remove a digital twin by Id.

az dt twin delete -n {instance_or_hostname} --twin-id {twin_id}

Remove a digital twin by Id using the etag.

az dt twin delete -n {instance_or_hostname} --twin-id {twin_id} --etag {etag}

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--twin-id -t

The digital twin Id.

Optional Parameters

--etag -e

Entity tag value. The command will succeed if the etag matches the current etag for the resource.

--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group={name}.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az dt twin delete-all

Deletes all digital twins within a Digital Twins instance, including all relationships for those twins.

az dt twin delete-all --dt-name
                      [--resource-group]
                      [--yes]

Examples

Delete all digital twins. Any relationships referencing the twins will also be deleted.

az dt twin delete-all -n {instance_or_hostname}

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

Optional Parameters

--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group={name}.

--yes -y

Do not prompt for confirmation.

Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az dt twin query

Query the digital twins of an instance. Allows traversing relationships and filtering by property values.

In many twin queries, the $ character is used to reference the $dtId property of a twin. In bash-like shells or powershell the $ character has functional meaning and must be escaped as part of the query input. Please review the Digital Twins CLI concepts document https://docs.microsoft.com/en-us/azure/digital-twins/concepts-cli for more information.

az dt twin query --dt-name
                 --query-command
                 [--cost {false, true}]
                 [--resource-group]

Examples

Query all digital twins in target instance and project all attributes. Also show cost in query units.

az dt twin query -n {instance_or_hostname} -q "select * from digitaltwins" --show-cost

Query by model and project all attributes.

az dt twin query -n {instance_or_hostname} -q "select * from digitaltwins T where IS_OF_MODEL(T, 'dtmi:com:example:Room;2')"

Query leveraging `$dtId` with bash compatible syntax

az dt twin query -n {instance_or_hostname} --query-command "SELECT * FROM DigitalTwins T Where T.\$dtId = 'room0'"

Query leveraging `$dtId` with powershell compatible syntax

az dt twin query -n {instance_or_hostname} --query-command "SELECT * FROM DigitalTwins T Where T.`$dtId = 'room0'"

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--query-command -q

User query to be executed.

Optional Parameters

--cost --show-cost

Calculates and shows the query charge.

Accepted values: false, true
Default value: False
--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group={name}.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az dt twin show

Show the details of a digital twin.

az dt twin show --dt-name
                --twin-id
                [--resource-group]

Examples

Show the details of a digital twin.

az dt twin show -n {instance_or_hostname} --twin-id {twin_id}

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--twin-id -t

The digital twin Id.

Optional Parameters

--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group={name}.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az dt twin update

Update an instance digital twin via JSON patch specification.

Updates to property values and $model elements may happen in the same request. Operations are limited to add, replace and remove.

az dt twin update --dt-name
                  --json-patch
                  --twin-id
                  [--etag]
                  [--resource-group]

Examples

Update a digital twin via JSON patch specification.

az dt twin update -n {instance_or_hostname} --twin-id {twin_id} --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Update a digital twin via JSON patch specification and using etag.

az dt twin update -n {instance_or_hostname} --twin-id {twin_id} --etag {etag} --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Update a digital twin via JSON patch specification.

az dt twin update -n {instance_or_hostname} --twin-id {twin_id} --json-patch '[
  {"op":"replace", "path":"/Temperature", "value": 20.5},
  {"op":"add", "path":"/Areas", "value": ["ControlSystem"]}
]'

Update a digital twin via JSON patch specification defined in a file.

az dt twin update -n {instance_or_hostname} --twin-id {twin_id} --json-patch ./my/patch/document.json

Required Parameters

--dt-name --dtn -n

Digital Twins instance name or hostname. If an instance name is provided, the user subscription is first queried for the target instance to retrieve the hostname. If a hostname is provided, the subscription query is skipped and the provided value is used for subsequent interaction.

--json-patch --patch

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. Provide file path or inline JSON.

--twin-id -t

The digital twin Id.

Optional Parameters

--etag -e

Entity tag value. The command will succeed if the etag matches the current etag for the resource.

--resource-group -g

Digital Twins instance resource group. You can configure the default group using az configure --defaults group={name}.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.