az iot hub device-identity

Note

This reference is part of the azure-iot extension for Azure CLI and requires version 2.0.70 or higher. The extension will automatically install the first time you run an az iot hub device-identity command. Learn more about extensions.

Manage IoT devices.

Commands

az iot hub device-identity add-children

Add specified comma-separated list of device ids as children of specified edge device.

az iot hub device-identity children

Manage IoT device's children device.

az iot hub device-identity children add

Add specified space-separated list of device ids as children of specified edge device.

az iot hub device-identity children list

Outputs list of assigned child devices.

az iot hub device-identity children remove

Remove devices as children from specified edge device.

az iot hub device-identity connection-string

Manage IoT device's connection string.

az iot hub device-identity connection-string show

Show a given IoT Hub device connection string.

az iot hub device-identity create

Create a device in an IoT Hub.

az iot hub device-identity delete

Delete an IoT Hub device.

az iot hub device-identity export

Export all device identities from an IoT Hub to an Azure Storage blob container. For inline blob container SAS uri input, please review the input rules of your environment.

az iot hub device-identity get-parent

Get the parent device of the specified device.

az iot hub device-identity import

Import device identities to an IoT Hub from a blob. For inline blob container SAS uri input, please review the input rules of your environment.

az iot hub device-identity list

List devices in an IoT Hub.

az iot hub device-identity list-children

Outputs comma-separated list of assigned child devices.

az iot hub device-identity parent

Manage IoT device's parent device.

az iot hub device-identity parent set

Set the parent device of the specified device.

az iot hub device-identity parent show

Get the parent device of the specified device.

az iot hub device-identity remove-children

Remove devices as children from specified edge device.

az iot hub device-identity renew-key

Renew target keys of an IoT Hub device with sas authentication.

az iot hub device-identity set-parent

Set the parent device of the specified device.

az iot hub device-identity show

Get the details of an IoT Hub device.

az iot hub device-identity show-connection-string

Show a given IoT Hub device connection string.

az iot hub device-identity update

Update an IoT Hub device.

az iot hub device-identity add-children

Add specified comma-separated list of device ids as children of specified edge device.

az iot hub device-identity add-children --child-list
                                        --device-id
                                        [--force]
                                        [--hub-name]
                                        [--login]
                                        [--resource-group]

Examples

Add devices as a children to the edge device.

az iot hub device-identity add-children -d {edge_device_id} --child-list {comma_separated_device_id} -n {iothub_name}

Add devices as a children to the edge device irrespectively the device is already a child of other edge device.

az iot hub device-identity add-children -d {edge_device_id} --child-list {comma_separated_device_id} -n {iothub_name} -f

Required Parameters

--child-list --cl

Child device list (comma separated).

--device-id -d

Id of edge device.

Optional Parameters

--force -f

Overwrites the child device's parent device.

--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 device-identity create

Create a device in an IoT Hub.

az iot hub device-identity create --device-id
                                  [--add-children]
                                  [--am {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--edge-enabled {false, true}]
                                  [--force {false, true}]
                                  [--hub-name]
                                  [--login]
                                  [--od]
                                  [--pd]
                                  [--primary-thumbprint]
                                  [--resource-group]
                                  [--secondary-thumbprint]
                                  [--sta {disabled, enabled}]
                                  [--star]
                                  [--valid-days]

Examples

Create an edge enabled IoT device with default authorization (shared private key).

az iot hub device-identity create -n {iothub_name} -d {device_id} --ee

Create an edge enabled IoT device with default authorization (shared private key) and add child devices as well.

az iot hub device-identity create -n {iothub_name} -d {device_id} --ee --cl {child_device_id}

Create an IoT device with default authorization (shared private key) and set parent device as well.

az iot hub device-identity create -n {iothub_name} -d {device_id} --pd {edge_device_id}

Create an IoT device with self-signed certificate authorization, generate a cert valid for 10 days then use its thumbprint.

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --valid-days 10

Create an IoT device with self-signed certificate authorization, generate a cert of default expiration (365 days) and output to target directory.

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --output-dir /path/to/output

Create an IoT device with self-signed certificate authorization and explicitly provide primary and secondary thumbprints.

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --ptp {thumbprint_1} --stp {thumbprint_2}

Create an IoT device with root CA authorization with disabled status and reason

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_ca --status disabled --status-reason 'for reasons'

Required Parameters

--device-id -d

Target Device.

Optional Parameters

--add-children --cl

Child device list (comma separated). This command parameter has been deprecated and will be removed in a future release. Use 'az iot hub device-identity children add' instead.

--am --auth-method

The authorization type an entity is to be created with.

accepted values: shared_private_key, x509_ca, x509_thumbprint
default value: shared_private_key
--edge-enabled --ee

Flag indicating edge enablement.

accepted values: false, true
--force -f

Overwrites the device's parent device. This command parameter has been deprecated and will be removed in a future release. Use 'az iot hub device-identity parent set' instead.

accepted values: false, true
--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.

--od --output-dir

Generate self-signed cert and use its thumbprint. Output to specified target directory.

--pd --set-parent

Id of edge device. This command parameter has been deprecated and will be removed in a future release. Use 'az iot hub device-identity parent set' instead.

--primary-thumbprint --ptp

Explicit self-signed certificate thumbprint to use for primary key.

--resource-group -g

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

--secondary-thumbprint --stp

Explicit self-signed certificate thumbprint to use for secondary key.

--sta --status

Set device status upon creation.

accepted values: disabled, enabled
default value: enabled
--star --status-reason

Description for device status.

--valid-days --vd

Generate self-signed cert and use its thumbprint. Valid for specified number of days. Default: 365.

az iot hub device-identity delete

Delete an IoT Hub device.

az iot hub device-identity delete --device-id
                                  [--etag]
                                  [--hub-name]
                                  [--login]
                                  [--resource-group]

Required Parameters

--device-id -d

Target Device.

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.

--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 device-identity export

Export all device identities from an IoT Hub to an Azure Storage blob container. For inline blob container SAS uri input, please review the input rules of your environment.

For more information, see https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities.

az iot hub device-identity export --bcu
                                  --hub-name
                                  [--auth-type {identity, key}]
                                  [--ik {false, true}]
                                  [--resource-group]

Examples

Export all device identities to a configured blob container and include device keys. Uses an inline SAS uri example.

az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices?sv=2019-02-02&st=2020-08-23T22%3A35%3A00Z&se=2020-08-24T22%3A35%3A00Z&sr=c&sp=rwd&sig=VrmJ5sQtW3kLzYg10VqmALGCp4vtYKSLNjZDDJBSh9s%3D'

Export all device identities to a configured blob container using a file path which contains the SAS uri.

az iot hub device-identity export -n {iothub_name} --bcu {sas_uri_filepath}

Required Parameters

--bcu --blob-container-uri

Blob Shared Access Signature URI with write, read, and delete access to a blob container. This is used to output the status of the job and the results. Note: when using Identity-based authentication an https:// URI is still required. Input for this argument can be inline or from a file path.

--hub-name -n

IoT Hub name.

Optional Parameters

--auth-type --storage-authentication-type

Authentication type for communicating with the storage container.

accepted values: identity, key
--ik --include-keys

If set, keys are exported normally. Otherwise, keys are set to null in export output.

accepted values: false, true
--resource-group -g

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

az iot hub device-identity get-parent

Get the parent device of the specified device.

az iot hub device-identity get-parent --device-id
                                      [--hub-name]
                                      [--login]
                                      [--resource-group]

Examples

Get the parent device of the specified device.

az iot hub device-identity get-parent -d {device_id} -n {iothub_name}

Required Parameters

--device-id -d

Id of device.

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 device-identity import

Import device identities to an IoT Hub from a blob. For inline blob container SAS uri input, please review the input rules of your environment.

For more information, see https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities.

az iot hub device-identity import --hub-name
                                  --ibcu
                                  --obcu
                                  [--auth-type {identity, key}]
                                  [--resource-group]

Examples

Import all device identities from a blob using an inline SAS uri.

az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri}

Import all device identities from a blob using a file path which contains SAS uri.

az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri_filepath} --obcu {output_sas_uri_filepath}

Required Parameters

--hub-name -n

IoT Hub name.

--ibcu --input-blob-container-uri

Blob Shared Access Signature URI with read access to a blob container. This blob contains the operations to be performed on the identity registry. Note: when using Identity-based authentication an https:// URI is still required. Input for this argument can be inline or from a file path.

--obcu --output-blob-container-uri

Blob Shared Access Signature URI with write access to a blob container. This is used to output the status of the job and the results. Note: when using Identity-based authentication an https:// URI is still required. Input for this argument can be inline or from a file path.

Optional Parameters

--auth-type --storage-authentication-type

Authentication type for communicating with the storage container.

accepted values: identity, key
--resource-group -g

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

az iot hub device-identity list

List devices in an IoT Hub.

az iot hub device-identity list [--edge-enabled {false, true}]
                                [--hub-name]
                                [--login]
                                [--resource-group]
                                [--top]

Optional Parameters

--edge-enabled --ee

Flag indicating edge enablement.

accepted values: false, true
--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 elements to return. Use -1 for unlimited.

default value: 1000

az iot hub device-identity list-children

Outputs comma-separated list of assigned child devices.

az iot hub device-identity list-children --device-id
                                         [--hub-name]
                                         [--login]
                                         [--resource-group]

Examples

Show all assigned devices as comma-separated list.

az iot hub device-identity list-children -d {edge_device_id} -n {iothub_name}

Required Parameters

--device-id -d

Id of edge device.

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 device-identity remove-children

Remove devices as children from specified edge device.

az iot hub device-identity remove-children --device-id
                                           [--child-list]
                                           [--hub-name]
                                           [--login]
                                           [--remove-all]
                                           [--resource-group]

Examples

Remove all mentioned devices as children of specified device.

az iot hub device-identity remove-children -d {edge_device_id} --child-list {comma_separated_device_id} -n {iothub_name}

Remove all devices as children specified edge device.

az iot hub device-identity remove-children -d {edge_device_id} --remove-all

Required Parameters

--device-id -d

Id of edge device.

Optional Parameters

--child-list --cl

Child device list (comma separated).

--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-all -a

To remove all children.

--resource-group -g

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

az iot hub device-identity renew-key

Renew target keys of an IoT Hub device with sas authentication.

az iot hub device-identity renew-key --device-id
                                     --hub-name
                                     --key-type {primary, secondary, swap}
                                     [--etag]
                                     [--login]
                                     [--resource-group]

Examples

Renew the primary key.

az iot hub device-identity renew-key -d {device_id} -n {iothub_name} --kt primary

Swap the primary and secondary keys.

az iot hub device-identity renew-key -d {device_id} -n {iothub_name} --kt swap

Required Parameters

--device-id -d

Target Device.

--hub-name -n

IoT Hub name.

--key-type --kt

Target key type to regenerate.

accepted values: primary, secondary, swap

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.

--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 device-identity set-parent

Set the parent device of the specified device.

az iot hub device-identity set-parent --device-id
                                      --parent-device-id
                                      [--force]
                                      [--hub-name]
                                      [--login]
                                      [--resource-group]

Examples

Set the parent device of the specified device.

az iot hub device-identity set-parent -d {device_id} --pd {edge_device_id} -n {iothub_name}

Set the parent device of the specified device irrespectively the device is already a child of other edge device.

az iot hub device-identity set-parent -d {device_id} --pd {edge_device_id} --force -n {iothub_name}

Required Parameters

--device-id -d

Id of device.

--parent-device-id --pd

Id of edge device.

Optional Parameters

--force -f

Overwrites the device's parent device.

--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 device-identity show

Get the details of an IoT Hub device.

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

Required Parameters

--device-id -d

Target Device.

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 device-identity show-connection-string

Show a given IoT Hub device connection string.

az iot hub device-identity show-connection-string --device-id
                                                  [--hub-name]
                                                  [--key-type {primary, secondary}]
                                                  [--login]
                                                  [--resource-group]

Required Parameters

--device-id -d

Target Device.

Optional Parameters

--hub-name -n

IoT Hub name.

--key-type --kt

Shared access policy key type for auth.

accepted values: primary, secondary
default value: primary
--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 device-identity update

Update an IoT Hub device.

Use --set followed by property assignments for updating a device. Leverage parameters returned from 'iot hub device-identity show'.

az iot hub device-identity update --device-id
                                  [--add]
                                  [--am {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--edge-enabled {false, true}]
                                  [--etag]
                                  [--force-string]
                                  [--hub-name]
                                  [--login]
                                  [--pk]
                                  [--primary-thumbprint]
                                  [--remove]
                                  [--resource-group]
                                  [--secondary-key]
                                  [--secondary-thumbprint]
                                  [--set]
                                  [--sta {disabled, enabled}]
                                  [--star]

Examples

Turn on edge capabilities for device

az iot hub device-identity update -d {device_id} -n {iothub_name} --set capabilities.iotEdge=true

Turn on edge capabilities for device using convenience argument.

az iot hub device-identity update -d {device_id} -n {iothub_name} --ee

Disable device status

az iot hub device-identity update -d {device_id} -n {iothub_name} --set status=disabled

Disable device status using convenience argument.

az iot hub device-identity update -d {device_id} -n {iothub_name} --status disabled

In one command

az iot hub device-identity update -d {device_id} -n {iothub_name} --set status=disabled capabilities.iotEdge=true

Required Parameters

--device-id -d

Target Device.

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

--am --auth-method

The authorization type an entity is to be created with.

accepted values: shared_private_key, x509_ca, x509_thumbprint
--edge-enabled --ee

Flag indicating edge enablement.

accepted values: false, true
--etag -e

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

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

--pk --primary-key

The primary symmetric shared access key stored in base64 format.

--primary-thumbprint --ptp

Explicit self-signed certificate thumbprint to use for primary key.

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

--secondary-key --sk

The secondary symmetric shared access key stored in base64 format.

--secondary-thumbprint --stp

Explicit self-signed certificate thumbprint to use for secondary key.

--set

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

--sta --status

Set device status upon creation.

accepted values: disabled, enabled
--star --status-reason

Description for device status.