az iot hub digital-twin

  • Reference

Note

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

Manipulate and interact with the digital twin of an IoT Hub device.

Commands

Name Description Type Status
az iot hub digital-twin invoke-command

Invoke a root or component level command of a digital twin device.

 Extension GA
az iot hub digital-twin show

Show the digital twin of an IoT Hub device.

 Extension GA
az iot hub digital-twin update

Update the read-write properties of a digital twin device via JSON patch specification.

 Extension GA

az iot hub digital-twin invoke-command

Invoke a root or component level command of a digital twin device.

az iot hub digital-twin invoke-command --cn
                                       --device-id
                                       [--component-path]
                                       [--connect-timeout]
                                       [--hub-name]
                                       [--login]
                                       [--payload]
                                       [--resource-group]
                                       [--response-timeout]

Examples

In general, invoke command which takes a payload that includes certain property using inline JSON.

az iot hub digital-twin invoke-command --command-name {command_name} -n {iothub_name} -d {device_id} --payload '{"property_name": "property_value"}'

Invoke root level command "reboot" which takes a payload named "delay" conforming to DTDL model https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/TemperatureController.json.

az iot hub digital-twin invoke-command --command-name reboot -n {iothub_name} -d {device_id} --payload 5

Invoke command "getMaxMinReport" on component "thermostat1" that takes no input.

az iot hub digital-twin invoke-command --cn getMaxMinReport -n {iothub_name} -d {device_id} --component-path thermostat1

Required Parameters

--cn --command-name

Digital twin command name.

--device-id -d

Target Device Id.

Optional Parameters

--component-path

Digital twin component path. For example: thermostat1.

--connect-timeout --cto

Maximum interval of time, in seconds, that IoT Hub will attempt to connect to the device.

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--payload

JSON payload input for command. Provide file path or inline JSON.

default value: {}
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--response-timeout --rto

Maximum interval of time, in seconds, that the digital twin command will wait for the result.

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 iot hub digital-twin show

Show the digital twin of an IoT Hub device.

az iot hub digital-twin show --device-id
                             [--hub-name]
                             [--login]
                             [--resource-group]

Examples

Show the target device digital twin.

az iot hub digital-twin show -n {iothub_name} -d {device_id}

Required Parameters

--device-id -d

Target Device Id.

Optional Parameters

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of 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 iot hub digital-twin update

Update the read-write properties of a digital twin device via JSON patch specification.

Currently operations are limited to add, replace and remove.

az iot hub digital-twin update --device-id
                               --json-patch
                               [--etag]
                               [--hub-name]
                               [--login]
                               [--resource-group]

Examples

Update a digital twin via JSON patch specification.

az iot hub digital-twin update --hub-name {iothub_name} --device-id {device_id} --json-patch '{"op":"add", "path":"/thermostat1/targetTemperature", "value": 54}'

Update a digital twin via JSON patch specification.

az iot hub digital-twin update -n {iothub_name} -d {device_id} --json-patch '[
  {"op":"remove", "path":"/thermostat1/targetTemperature"},
  {"op":"add", "path":"/thermostat2/targetTemperature", "value": 22}
]'

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

az iot hub digital-twin update -n {iothub_name} -d {device_id} --json-patch ./my/patch/document.json

Required Parameters

--device-id -d

Target Device Id.

--json-patch --patch

An update specification described by JSON-patch. Operations are limited to add, replace and remove. Provide file path or inline JSON.

Optional Parameters

--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of 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.