Share via

az iot du update

  • 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 iot du update command. Learn more about extensions.

Device Update update management.

Commands

Name Description Type Status
az iot du update calculate-hash

Calculate the base64 hashed representation of a file.

 Extension GA
az iot du update delete

Delete a specific update version.

 Extension GA
az iot du update file

Update file operations.

 Extension GA
az iot du update file list

List update file Ids with respect to update provider, name and version.

 Extension GA
az iot du update file show

Show the details of a specific update file with respect to update provider, name and version.

 Extension GA
az iot du update import

Import a new update version into the Device Update instance.

 Extension GA
az iot du update init

Utility for import manifest initialization.

 Extension Preview
az iot du update init v5

Initialize a v5 import manifest with the desired state.

 Extension Preview
az iot du update list

List updates that have been imported to the Device Update instance.

 Extension GA
az iot du update show

Show a specific update version.

 Extension GA
az iot du update stage

Stage an update for import to a target instance.

 Extension Preview

az iot du update calculate-hash

Calculate the base64 hashed representation of a file.

az iot du update calculate-hash --file-path
                                [--hash-algo {sha256}]

Examples

Calculate the base64 representation of a sha256 digest for a target update file.

az iot du update calculate-hash --file-path /path/to/file

Calculate the base64 representation of a sha256 digest for multiple target update files.

az iot du update calculate-hash --file-path /path/to/file1 --file-path /path/to/file2 --file-path /path/to/file3

Required Parameters

--file-path -f

Local path to target file for hash calculation. --file-path can be used 1 or more times.

Optional Parameters

--hash-algo

Cryptographic algorithm to use for hashing.

Accepted values: sha256
Default value: sha256
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 du update delete

Delete a specific update version.

az iot du update delete --account
                        --instance
                        --un
                        --up
                        --update-version
                        [--no-wait]
                        [--resource-group]
                        [--yes {false, true}]

Examples

Delete a target update with respect to update provider, name and version.

az iot du update delete -n {account_name} -i {instance_name} --update-provider {provider_name} --update-name {update_name} --update-version {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}.

--instance -i

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

--un --update-name

The update name.

--up --update-provider

The update provider.

--update-version --uv

The update version.

Optional Parameters

--no-wait

Do not wait for the long-running operation to finish.

Default value: False
--resource-group -g

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

--yes -y

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

Accepted values: false, true
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 du update import

Import a new update version into the Device Update instance.

This command supports the --defer capability. When used the command will store the object payload intended to be sent to Azure in a local cache. The next usage of this command without --defer will combine the new request payload with the cached objects sending them together.

Upon success the corresponding local cache entry will be purged. If failure occurs cached contents will not be removed. Use az cache commands to manage local cache entries independently.

Defer support is intended primarily for updates with multiple reference steps, such that parent and child updates can be submitted together.

az iot du update import --account
                        --instance
                        --url
                        [--defer]
                        [--file]
                        [--friendly-name]
                        [--hashes]
                        [--no-wait]
                        [--resource-group]
                        [--size]

Examples

Import an update with two related files and no reference steps, explicitly providing manifest hash value and manifest size in bytes.

az iot du update import -n {account_name} -i {instance_name} --hashes sha256={hash_value} --size {size_in_bytes} --url {manifest_location} --file filename={file1_name} url={file1_url} --file filename={file2_name} url={file2_url}

Import an update with two related files and no reference steps, letting the CLI calculate the import manifest hash value and size in bytes.

az iot du update import -n {account_name} -i {instance_name} --url {manifest_location} --file filename={file1_name} url={file1_url} --file filename={file2_name} url={file2_url}

Import a parent update with two child update reference steps, where all three import manifests have one related file. Let the CLI calculate hash value and size in bytes for all. This operation will rely on the `--defer` capability.

az iot du update import -n {account_name} -i {instance_name} --url {parent_manifest_location} --file filename={parent_file_name} url={parent_file_url} --defer

az iot du update import -n {account_name} -i {instance_name} --url {child1_manifest_location} --file filename={child1_file_name} url={child1_file_url} --defer

az iot du update import -n {account_name} -i {instance_name} --url {child2_manifest_location} --file filename={child2_file_name} url={child2_file_url}

Required Parameters

--account -n

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

--instance -i

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

--url

Routable location from which the import manifest can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 3 hours.

Optional Parameters

--defer

Temporarily store the object in the local cache instead of sending to Azure. Use az cache commands to view/clear.

--file

Space-separated key=value pairs corresponding to import manifest metadata file properties. Required keys include filename and url. --file can be used 1 or more times.

--friendly-name

Friendly name associated with the update definition.

--hashes

Space-separated key=value pairs where the key is the hash algorithm used and the value is the base64 encoded import manifest file hash. At least a sha256 entry is required. If not provided it will by calculated from the provided url.

--no-wait

Do not wait for the long-running operation to finish.

Default value: False
--resource-group -g

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

--size

File size in number of bytes. If not provided it will by calculated from the provided url.

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 du update list

List updates that have been imported to the Device Update instance.

When listing update providers only the --by-provider flag needs to be supplied in addition to the common instance look up arguments. When listing update names the update provider must be supplied. When listing update versions the update provider and update name must be supplied.

az iot du update list --account
                      --instance
                      [--by-provider {false, true}]
                      [--filter]
                      [--resource-group]
                      [--search]
                      [--un]
                      [--up]

Examples

List all updates.

az iot du update list -n {account_name} -i {instance_name}

List all updates satisfying a free-text search criteria, in this case the update provider of Contoso.

az iot du update list -n {account_name} -i {instance_name} --search 'Contoso'

List all updates satisfying an odata filter, in this case filtering for non-deployable updates.

az iot du update list -n {account_name} -i {instance_name} --filter 'isDeployable eq false'

List all update providers.

az iot du update list -n {account_name} -i {instance_name} --by-provider

List all update names by update provider.

az iot du update list -n {account_name} -i {instance_name} --update-provider {provider_name}

List all update versions by update provider and update name.

az iot du update list -n {account_name} -i {instance_name} --update-provider {provider_name} --update-name {update_name}

Required Parameters

--account -n

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

--instance -i

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

Optional Parameters

--by-provider

Flag indicating the result set should be constrained to update providers.

Accepted values: false, true
--filter

Restricts the set of updates returned by property values. Supported when listing updates with no constraints or when listing by version.

--resource-group -g

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

--search

Request updates matching a free-text search expression. Supported when listing updates with no constraints.

--un --update-name

The update name.

--up --update-provider

The update provider.

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 du update show

Show a specific update version.

az iot du update show --account
                      --instance
                      --un
                      --up
                      --update-version
                      [--resource-group]

Examples

Show a specific update with respect to update provider, name and version.

az iot du update show -n {account_name} -i {instance_name} --update-provider {provider_name} --update-name {update_name} --update-version {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}.

--instance -i

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

--un --update-name

The update name.

--up --update-provider

The update provider.

--update-version --uv

The update version.

Optional Parameters

--resource-group -g

Device Update account resource group name. You can configure the default group using az config set defaults.adu_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 du update stage

Preview

This command is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Stage an update for import to a target instance.

Staging an update refers to accelerating the pre-requisite steps of importing an update to a target instance. For a given import manifest, the process will determine relevant files, push them to a desired storage container, generate SAS URIs and cover other preparation steps for a succesful import.

This command depends on a convention based organization of update files. All update files for a target manifest are expected to be in the same directory the import manifest resides in.

Key based access is used to upload blob artifacts and to generate 3 hour duration SAS URIs with read access.

If --then-import flag is provided, the command will import the staged update. Otherwise the result of this operation is an import command to run to achieve the same result at a later time.

This command will purge and refresh any local cache entry for the target instance.

az iot du update stage --account
                       --instance
                       --manifest-path
                       --storage-account
                       --storage-container
                       [--friendly-name]
                       [--overwrite {false, true}]
                       [--resource-group]
                       [--storage-subscription]
                       [--then-import {false, true}]

Examples

Stage a stand-alone update. Update files are expected to reside in the same directory as the manifest. The resultant import command can be executed at a later time to initiate the import of the staged update prior to SAS token expiration.

az iot du update stage -n {account_name} -i {instance_name} --storage-account {storage_account_name} --storage-container {storage_container_name} --manifest-path /path/to/manifest.json

Stage a stand-alone update. After staging, import the update to the instance using a desired friendly name.

az iot du update stage -n {account_name} -i {instance_name} --storage-account {storage_account_name} --storage-container {storage_container_name} --manifest-path /path/to/manifest.json --then-import --friendly-name myAptUpdate

Stage a multi-reference update. Update files will be uploaded to a storage blob container residing in a different subscription to the update account.

az iot du update stage -n {account_name} -i {instance_name} --storage-account {storage_account_name} --storage-container {storage_container_name} --storage-subscription {storage_account_subscription} --manifest-path /path/to/parent/parent.manifest.json --manifest-path /path/to/leaf1/leaf1.manifest.json --manifest-path /path/to/leaf2/leaf2.manifest.json

Stage a multi-reference update, overwriting existing blobs if they exist. After staging, import the update to the instance.

az iot du update stage -n {account_name} -i {instance_name} --storage-account {storage_account_name} --storage-container {storage_container_name} --manifest-path /path/to/parent/parent.manifest.json --manifest-path /path/to/leaf1/leaf1.manifest.json --manifest-path /path/to/leaf2/leaf2.manifest.json --then-import --overwrite

Required Parameters

--account -n

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

--instance -i

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

--manifest-path

Local file path to the import manifest that should be staged. Can be used 1 or more times.

--storage-account

Desired storage account name to stage import manifest artifacts.

--storage-container

Desired storage container name to stage import manifest artifacts.

Optional Parameters

--friendly-name

Friendly name associated with the update definition.

--overwrite

Flag indicating whether existing blobs should be overwritten if a conflict exists.

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

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

--storage-subscription

Desired storage account subscription to stage import manifest artifacts. Applicable when the storage and device update accounts are in different subscriptions.

--then-import

Flag indicating whether the update should be imported after staging.

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