az iot hub configuration

Manage IoT automatic device management configuration at scale.

Commands

az iot hub configuration create

Create an IoT automatic device management configuration in a target IoT Hub.

az iot hub configuration delete

Delete an IoT device configuration.

az iot hub configuration list

List IoT automatic device management configurations in an IoT Hub.

az iot hub configuration show

Get the details of an IoT automatic device management configuration.

az iot hub configuration show-metric

Evaluate a target user or system metric defined in an IoT device configuration.

az iot hub configuration update

Update specified properties of an IoT automatic device management configuration.

Use --set followed by property assignments for updating a configuration.

Note: Configuration content is immutable. Configuration properties that can be updated are 'labels', 'metrics', 'priority' and 'targetCondition'.

az iot hub configuration create

Create an IoT automatic device management configuration in a target IoT Hub.

Configuration content is json and slighty varies based on device or module intent.

Device configurations are in the form of {"deviceContent":{...}} or {"content":{"deviceContent":{...}}}

Module configurations are in the form of {"moduleContent":{...}} or {"content":{"moduleContent":{...}}}

Configurations can be defined with user provided metrics for on demand evaluation. User metrics are json and in the form of {"queries":{...}} or {"metrics":{"queries":{...}}}.

az iot hub configuration create --config-id
                                --content
                                [--hub-name]
                                [--lab]
                                [--login]
                                [--metrics]
                                [--pri]
                                [--resource-group]
                                [--target-condition]

Examples

Create a device configuration with a priority of 3 that applies on condition when a device is tagged in building 9 and the environment is 'test'.

az iot hub configuration create -c {config_name} -n {iothub_name} --content device_content.json --target-condition "tags.building=9 and tags.environment='test'" --priority 3

Create a device configuration with labels and provide user metrics inline (bash syntax example)

az iot hub configuration create -c {config_name} -n {iothub_name} --content device_content.json --target-condition "tags.building=9" --labels '{"key0":"value0", "key1":"value1"}' --priority 10 --metrics '{"metrics": {"queries": {"mymetric": "select deviceId from devices where tags.location='US'"}}}'

Create a module configuration with labels and provide user metrics inline (cmd syntax example)

az iot hub configuration create -c {config_name} -n {iothub_name} --content module_content.json --target-condition "tags.building=9" --labels "{\"key0\":\"value0\", \"key1\":\"value1\"}" --metrics "{\"metrics\": {\"queries\": {\"mymetric\": \"select deviceId from devices where tags.location='US'\"}}}"

Create a module configuration with content and user metrics inline (powershell syntax example)

az iot hub configuration create -c {config_name} -n {iothub_name} --content '{\"moduleContent\": {\"properties.desired.chillerWaterSettings\": {\"temperature\": 38, \"pressure\": 78}}}' --target-condition "tags.building=9" --priority 1 --metrics '{\"metrics\": {\"queries\": {\"mymetric\":\"select deviceId from devices where tags.location=''US''\"}}}'

Required Parameters

--config-id -c

Target device configuration name.

--content -k

Device configuration content. Provide file path or raw json.

Optional Parameters

--hub-name -n

IoT Hub name.

--lab --labels

Map of labels to be applied to target configuration. Format example: {"key0":"value0", "key1":"value1"}.

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

--metrics -m

Device configuration metric definitions. Provide file path or raw json.

--pri --priority

Weight of the device configuration in case of competing rules (highest wins).

--resource-group -g

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

--target-condition --tc -t

Target condition in which a device configuration applies to.

az iot hub configuration delete

Delete an IoT device configuration.

az iot hub configuration delete --config-id
                                [--hub-name]
                                [--login]
                                [--resource-group]

Required Parameters

--config-id -c

Target device configuration name.

Optional Parameters

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

az iot hub configuration list

List IoT automatic device management configurations in an IoT Hub.

az iot hub configuration list [--hub-name]
                              [--login]
                              [--resource-group]
                              [--top]

Optional Parameters

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

--top

Maximum number of configurations to return.

default value: 10

az iot hub configuration show

Get the details of an IoT automatic device management configuration.

az iot hub configuration show --config-id
                              [--hub-name]
                              [--login]
                              [--resource-group]

Required Parameters

--config-id -c

Target device configuration name.

Optional Parameters

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

az iot hub configuration show-metric

Evaluate a target user or system metric defined in an IoT device configuration.

az iot hub configuration show-metric --config-id
                                     --metric-id
                                     [--hub-name]
                                     [--login]
                                     [--metric-type {system, user}]
                                     [--resource-group]

Examples

Evaluate the user defined 'warningLimit' metric

az iot hub configuration show-metric -m warningLimit -c {configuration_name} -n {iothub_name}

Evaluate the system 'appliedCount' metric

az iot hub configuration show-metric --metric-id appliedCount -c {configuration_name} -n {iothub_name} --metric-type system

Required Parameters

--config-id -c

Target device configuration name.

--metric-id -m

Target metric for evaluation.

Optional Parameters

--hub-name -n

IoT Hub name.

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

--metric-type --mt

Indicates which metric collection should be used to lookup a metric.

accepted values: system, user
default value: user
--resource-group -g

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

az iot hub configuration update

Update specified properties of an IoT automatic device management configuration.

Use --set followed by property assignments for updating a configuration.

Note: Configuration content is immutable. Configuration properties that can be updated are 'labels', 'metrics', 'priority' and 'targetCondition'.

az iot hub configuration update --config-id
                                [--add]
                                [--force-string]
                                [--hub-name]
                                [--login]
                                [--remove]
                                [--resource-group]
                                [--set]

Examples

Alter the priority of a device configuration and update its target condition

az iot hub configuration update -c {configuration_name} -n {iothub_name} --set priority=10 targetCondition="tags.building=43 and tags.environment='dev'"

Required Parameters

--config-id -c

Target device configuration name.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

--hub-name -n

IoT Hub name.

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

--remove

Remove a property or an element from a list. Example: --remove property.list OR --remove propertyToRemove.

--resource-group -g

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

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.