az iot du device deployment

Note

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

Device deployment management.

Deployments will apply a desired compatible update against a target device group distributing the update across device classes within the group. Cloud-initiated rollback policy can be optionally configured.

Commands

Name	Description	Type	Status
az iot du device deployment cancel	Cancel a device class subgroup deployment.	Extension	GA
az iot du device deployment create	Create a deployment for a device group. The deployment will be multi-cast against every device class subgroup within the target group.	Extension	GA
az iot du device deployment delete	Delete a deployment by device group or device class subgroup.	Extension	GA
az iot du device deployment list	List deployments for a device group or device class subgroup.	Extension	GA
az iot du device deployment list-devices	List devices in a device class subgroup deployment along with their state. Useful for getting a list of failed devices.	Extension	GA
az iot du device deployment retry	Retry a device class subgroup deployment.	Extension	GA
az iot du device deployment show	Show a deployment for a device group or device class subgroup including status which details a breakdown of how many devices in the deployment are in progress, completed, or failed.	Extension	GA

az iot du device deployment cancel

Cancel a device class subgroup deployment.

az iot du device deployment cancel --account
                                   --cid --class-id
                                   --deployment-id --did
                                   --gid --group-id
                                   --instance
                                   [--resource-group]

Examples

Cancel the target device class subgroup deployment.

az iot du device deployment cancel -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain &, ^, [, ], {, }, |, <, >, forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False

az iot du device deployment create

Create a deployment for a device group. The deployment will be multi-cast against every device class subgroup within the target group.

az iot du device deployment create --account
                                   --deployment-id --did
                                   --gid --group-id
                                   --instance
                                   --un --update-name
                                   --up --update-provider
                                   --update-version --uv
                                   [--failed-count --fc]
                                   [--failed-percentage --fp]
                                   [--rbun --rollback-update-name]
                                   [--rbup --rollback-update-provider]
                                   [--rbuv --rollback-update-version]
                                   [--resource-group]
                                   [--start-time]

Examples

Create a device group deployment scheduled to start immediately (with respect to UTC time).

az iot du device deployment create -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --update-name {update_name} --update-provider {update_provider} --update-version {update_version}

Create a device group deployment scheduled to start on a desired iso-8601 compliant datetime.

az iot du device deployment create -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --update-name {update_name} --update-provider {update_provider} --update-version {update_version} --start-time "2022-12-20T01:00:00"

Create a device group deployment scheduled to start immediately with a defined cloud-initiated rollback policy. The cloud rollback is initiated when failed count or failed percentage targets are met.

az iot du device deployment create -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --update-name {update_name} --update-provider {update_provider} --update-version {update_version} --failed-count 10 --failed-percentage 5 --rollback-update-name {rollback_update_name} --rollback-update-provider {rollback_update_provider} --rollback-update-version {rollback_update_version}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain &, ^, [, ], {, }, |, <, >, forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--un --update-name

The update name.

Property	Value
Parameter group:	Update Id Arguments

--up --update-provider

The update provider.

Property	Value
Parameter group:	Update Id Arguments

--update-version --uv

The update version.

Property	Value
Parameter group:	Update Id Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--failed-count --fc

Integer representing the number of failed devices in a deployment before a cloud initated rollback occurs. Required when defining rollback policy.

Property	Value
Parameter group:	Update Rollback Policy Arguments

--failed-percentage --fp

Integer representing the percentage of failed devices in a deployment before a cloud initated rollback occurs. Required when defining rollback policy.

Property	Value
Parameter group:	Update Rollback Policy Arguments

--rbun --rollback-update-name

The rollback update name.

Property	Value
Parameter group:	Update Rollback Policy Arguments

--rbup --rollback-update-provider

The rollback update provider.

Property	Value
Parameter group:	Update Rollback Policy Arguments

--rbuv --rollback-update-version

The rollback update version.

Property	Value
Parameter group:	Update Rollback Policy Arguments

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--start-time

The iso-8601 compliant start time for deployment. If no value is provided the corresponding value for UTC 'now' will be used.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False

az iot du device deployment delete

Delete a deployment by device group or device class subgroup.

az iot du device deployment delete --account
                                   --deployment-id --did
                                   --gid --group-id
                                   --instance
                                   [--cid --class-id]
                                   [--resource-group]
                                   [--yes {false, true}]

Examples

Delete the target device group deployment.

az iot du device deployment delete -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id}

Delete the target device class subgroup deployment.

az iot du device deployment delete -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain &, ^, [, ], {, }, |, <, >, forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--yes -y

Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.

Property	Value
Accepted values:	false, true

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False

az iot du device deployment list

List deployments for a device group or device class subgroup.

az iot du device deployment list --account
                                 --gid --group-id
                                 --instance
                                 [--cid --class-id]
                                 [--order-by]
                                 [--resource-group]

Examples

List deployments for a device group.

az iot du device deployment list -n {account_name} -i {instance_name} --group-id {device_group_id}

List deployments for a device group ordering results by startDateTime descending.

az iot du device deployment list -n {account_name} -i {instance_name} --group-id {device_group_id} --order-by "startDateTime desc"

List deployments for a device class subgroup.

az iot du device deployment list -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--order-by

Orders the set of deployments returned. You can order by startDateTime [desc/asc].

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False

az iot du device deployment list-devices

List devices in a device class subgroup deployment along with their state. Useful for getting a list of failed devices.

az iot du device deployment list-devices --account
                                         --cid --class-id
                                         --deployment-id --did
                                         --gid --group-id
                                         --instance
                                         [--filter]
                                         [--resource-group]

Examples

List devices in a device class subgroup deployment.

az iot du device deployment list-devices -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id}

List devices in a device class subgroup deployment filtering by deviceId and deviceState.

az iot du device deployment list-devices -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id} --filter "deviceId eq 'd0' and deviceState eq 'InProgress'"

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain &, ^, [, ], {, }, |, <, >, forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--filter

Restricts the set of deployment device states returned. You can filter on deviceId and moduleId and/or deviceState.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False

az iot du device deployment retry

Retry a device class subgroup deployment.

az iot du device deployment retry --account
                                  --cid --class-id
                                  --deployment-id --did
                                  --gid --group-id
                                  --instance
                                  [--resource-group]

Examples

Retry the target device class subgroup deployment.

az iot du device deployment retry -n {account_name} -i {instance_name} --deployment-id {deployment_id} --group-id {device_group_id} --class-id {device_class_id}

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain &, ^, [, ], {, }, |, <, >, forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False

az iot du device deployment show

Show a deployment for a device group or device class subgroup including status which details a breakdown of how many devices in the deployment are in progress, completed, or failed.

az iot du device deployment show --account
                                 --deployment-id --did
                                 --gid --group-id
                                 --instance
                                 [--cid --class-id]
                                 [--resource-group]
                                 [--status {false, true}]

Examples

Show a deployment for a device group.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id}

Show the status of a device group deployment.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --deployment-id {deployment_id} --status

Show a deployment for a device class subgroup.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id}

Show the status of a device class subgroup deployment.

az iot du device deployment show -n {account_name} -i {instance_name} --group-id {device_group_id} --class-id {device_class_id} --deployment-id {deployment_id} --status

Required Parameters

--account -n

Device Update account name. You can configure the default account name using az config set defaults.adu_account={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--deployment-id --did

The caller-provided deployment Id. This cannot be longer than 73 characters, must be all lower-case, and cannot contain &, ^, [, ], {, }, |, <, >, forward slash, backslash, or double quote.

--gid --group-id

Device group Id. This is created from the value of the ADUGroup tag in the connected IoT Hub's device/module twin or $default for devices with no tag.

--instance -i

Device Update instance name. You can configure the default instance name using az config set defaults.adu_instance={name}.

Property	Value
Parameter group:	Account Identifier Arguments

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--cid --class-id

Device class Id. This is generated from the model Id and the compat properties reported by the device update agent in the Device Update PnP interface in IoT Hub. It is a hex-encoded SHA1 hash.

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_group={name}.

Property	Value
Parameter group:	Account Identifier Arguments

--status

Gets the status of a deployment including a breakdown of how many devices in the deployment are in progress, completed, or failed.

Property	Value
Accepted values:	false, true

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

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

Property	Value
Default value:	False