az iot adr ns su software-update

  • Preview

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.73.0 or higher). The extension will automatically install the first time you run an az iot adr ns su software-update command. Learn more about extensions.

Command group 'iot adr ns' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Import and manage Software Updates content.

Uses the data-plane serviceAddress materialized on the namespace's Software Updates link. The link must finish provisioning before these commands can run.

Commands

Name Description Type Status
az iot adr ns su software-update calculate-hash

Calculate update-file hashes locally.

 Extension Preview
az iot adr ns su software-update catalog

Discover Software Updates catalog identifiers.

 Extension Preview
az iot adr ns su software-update catalog name

Discover update names for a provider.

 Extension Preview
az iot adr ns su software-update catalog name list

List update names for a provider.

 Extension Preview
az iot adr ns su software-update catalog provider

Discover update providers.

 Extension Preview
az iot adr ns su software-update catalog provider list

List update providers in the catalog.

 Extension Preview
az iot adr ns su software-update catalog version

Discover update versions for a provider and name.

 Extension Preview
az iot adr ns su software-update catalog version list

List update versions for a provider and name.

 Extension Preview
az iot adr ns su software-update delete

Delete an imported update.

 Extension Preview
az iot adr ns su software-update file

Inspect files belonging to an imported update.

 Extension Preview
az iot adr ns su software-update file list

List file identifiers for an imported update.

 Extension Preview
az iot adr ns su software-update file show

Show an imported update file.

 Extension Preview
az iot adr ns su software-update import

Import an update into Software Updates.

 Extension Preview
az iot adr ns su software-update init

Create Software Updates import manifests locally.

 Extension Preview
az iot adr ns su software-update init v5

Create a version 5 import manifest.

 Extension Preview
az iot adr ns su software-update list

List updates imported into Software Updates.

 Extension Preview
az iot adr ns su software-update operation-status

Inspect asynchronous Software Updates operations.

 Extension Preview
az iot adr ns su software-update operation-status list

List retained Software Updates operation statuses.

 Extension Preview
az iot adr ns su software-update operation-status show

Show a Software Updates operation status.

 Extension Preview
az iot adr ns su software-update show

Show an imported update.

 Extension Preview
az iot adr ns su software-update stage

Stage local update artifacts and optionally import them.

 Extension Preview
az iot adr ns su software-update wait

Wait for an imported Software Update condition.

 Extension Preview

az iot adr ns su software-update calculate-hash

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Calculate update-file hashes locally.

az iot adr ns su software-update calculate-hash --file-path
                                                [--acquire-policy-token]
                                                [--change-reference]
                                                [--hash-algo {sha256}]

Examples

Calculate a SHA-256 hash

az iot adr ns su software-update calculate-hash --file-path ./payload.bin

Required Parameters

--file-path -f

Local file to hash. Use --file-path more than once for multiple files.

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--hash-algo

Cryptographic hash algorithm.

Property Value
Default value: sha256
Accepted values: sha256
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 adr ns su software-update delete

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Delete an imported update.

az iot adr ns su software-update delete --name --namespace --ns
                                        --resource-group
                                        --un --update-name
                                        --up --update-provider
                                        --update-version --uv
                                        [--acquire-policy-token]
                                        [--change-reference]
                                        [--no-wait]
                                        [--yes {false, true}]

Examples

Delete an update version without prompting

az iot adr ns su software-update delete --ns myNamespace -g myResourceGroup \
  --update-provider Contoso --update-name Thermostat --update-version 1.0 --yes

Required Parameters

--name --namespace --ns -n

Name of the Device Registry namespace.

--resource-group -g

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

--un --update-name

Update name.

--up --update-provider

Update provider.

--update-version --uv

Update version.

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--no-wait

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

Property Value
Default value: False
--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 adr ns su software-update import

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Import an update into Software Updates.

Imports a v5 manifest from a read-accessible URL. When --size or --hashes is omitted, the CLI streams the manifest to calculate its size and SHA-256 hash.

az iot adr ns su software-update import --name --namespace --ns
                                        --resource-group
                                        --url
                                        [--acquire-policy-token]
                                        [--change-reference]
                                        [--enable-scan {false, true}]
                                        [--file]
                                        [--friendly-name]
                                        [--hashes]
                                        [--no-wait]
                                        [--size]

Examples

Import a manifest and one payload file

az iot adr ns su software-update import --ns myNamespace -g myResourceGroup \
  --url "https://storage.example/manifest.json?<sas>" \
  --file filename=payload.bin url="https://storage.example/payload.bin?<sas>"

Required Parameters

--name --namespace --ns -n

Name of the Device Registry namespace.

--resource-group -g

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

--url

Read-accessible URL of the update import manifest.

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--enable-scan

Request malware scanning for the imported update.

Property Value
Accepted values: false, true
--file

Update file metadata as filename=FILE_NAME url=READ_ACCESSIBLE_URL. --file can be used more than once.

--friendly-name

Friendly name associated with the imported update.

--hashes

Manifest hashes as key=value pairs. A sha256 value is required. Calculated from --url when omitted.

--no-wait

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

Property Value
Default value: False
--size

Import manifest size in bytes. Calculated from --url when omitted.

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 adr ns su software-update list

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

List updates imported into Software Updates.

az iot adr ns su software-update list --name --namespace --ns
                                      --resource-group
                                      [--filter]
                                      [--search]

Examples

List all imported updates

az iot adr ns su software-update list --ns myNamespace -g myResourceGroup

List deployable updates

az iot adr ns su software-update list --ns myNamespace -g myResourceGroup --filter "isDeployable eq true"

Required Parameters

--name --namespace --ns -n

Name of the Device Registry namespace.

--resource-group -g

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

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

Filter updates by supported service properties.

Property Value
Parameter group: Filter Arguments
--search

Request updates matching a free-text search expression.

Property Value
Parameter group: Filter 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 adr ns su software-update show

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show an imported update.

az iot adr ns su software-update show --name --namespace --ns
                                      --resource-group
                                      --un --update-name
                                      --up --update-provider
                                      --update-version --uv

Examples

Show an update version

az iot adr ns su software-update show --ns myNamespace -g myResourceGroup \
  --update-provider Contoso --update-name Thermostat --update-version 1.0

Required Parameters

--name --namespace --ns -n

Name of the Device Registry namespace.

--resource-group -g

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

--un --update-name

Update name.

--up --update-provider

Update provider.

--update-version --uv

Update version.

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 adr ns su software-update stage

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Stage local update artifacts and optionally import them.

Validates local manifest payload sizes and SHA-256 hashes, uploads each manifest and its files to Azure Storage, and reuses matching staged blobs. File references must name files in the same directory as their manifest. Without --then-import, no SAS URLs are generated or returned. With --then-import, fresh read-only SAS URLs are generated and all manifests are submitted in one import request.

az iot adr ns su software-update stage --manifest-path
                                       --name --namespace --ns
                                       --resource-group
                                       --storage-account
                                       --storage-container
                                       [--acquire-policy-token]
                                       [--change-reference]
                                       [--enable-scan {false, true}]
                                       [--friendly-name]
                                       [--no-wait]
                                       [--overwrite {false, true}]
                                       [--sas-expiry-hours]
                                       [--storage-prefix]
                                       [--storage-subscription]
                                       [--then-import {false, true}]

Examples

Stage a single update without importing it

az iot adr ns su software-update stage --ns myNamespace -g myResourceGroup \
  --manifest-path ./manifest.json --storage-account mystorage \
  --storage-container updates

Stage and import a multi-reference update

az iot adr ns su software-update stage --ns myNamespace -g myResourceGroup \
  --manifest-path ./root.json --manifest-path ./leaf.json \
  --storage-account /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/mystorage \
  --storage-container updates --then-import --enable-scan

Required Parameters

--manifest-path

Local import manifest path. Use --manifest-path more than once for a multi-reference update, with the root manifest first.

--name --namespace --ns -n

Name of the Device Registry namespace.

--resource-group -g

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

--storage-account

Storage account name or ARM resource ID used to stage artifacts.

Property Value
Parameter group: Storage Arguments
--storage-container

Blob container used to stage artifacts.

Property Value
Parameter group: Storage 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.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--enable-scan

Request malware scanning when --then-import is used.

Property Value
Accepted values: false, true
--friendly-name

Friendly name applied to the first, root manifest.

--no-wait

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

Property Value
Default value: False
--overwrite

Replace staged blobs whose content differs from local artifacts.

Property Value
Parameter group: Storage Arguments
Default value: False
Accepted values: false, true
--sas-expiry-hours

Read-only SAS lifetime used by --then-import. Defaults to 4 hours.

Property Value
Parameter group: Storage Arguments
Default value: 4
--storage-prefix

Blob name prefix. Defaults to 'deviceupdate'.

Property Value
Parameter group: Storage Arguments
--storage-subscription

Storage account subscription. Use when the storage account is in a different subscription and is specified by name.

Property Value
Parameter group: Storage Arguments
--then-import

Import all staged manifests in one request after uploading.

Property Value
Default value: False
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 adr ns su software-update wait

Preview

Command group 'iot adr ns su software-update' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Wait for an imported Software Update condition.

The Software Update model has no lifecycle status. Without an explicit wait predicate, a successful GET means the imported update is materialized and ready.

az iot adr ns su software-update wait --name --namespace --ns
                                      --resource-group
                                      --un --update-name
                                      --up --update-provider
                                      --update-version --uv
                                      [--acquire-policy-token]
                                      [--change-reference]
                                      [--created]
                                      [--custom]
                                      [--deleted]
                                      [--exists]
                                      [--interval]
                                      [--timeout]
                                      [--updated]

Examples

Wait until an imported update exists

az iot adr ns su software-update wait --ns myNamespace -g myResourceGroup \
  --update-provider Contoso --update-name Thermostat --update-version 1.0

Required Parameters

--name --namespace --ns -n

Name of the Device Registry namespace.

--resource-group -g

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

--un --update-name

Update name.

--up --update-provider

Update provider.

--update-version --uv

Update version.

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--created

Wait until the software update exists. Software updates have no provisioningState.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--custom

Wait until a custom JMESPath expression evaluates to true.

Property Value
Parameter group: Wait Condition Arguments
--deleted

Wait until the resource is deleted.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--exists

Wait until the resource exists.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--interval

Polling interval in seconds.

Property Value
Parameter group: Wait Condition Arguments
Default value: 30
--timeout

Polling budget in seconds, including GET time. An in-flight GET is bounded by transport timeouts and cannot be interrupted by this polling deadline.

Property Value
Parameter group: Wait Condition Arguments
Default value: 3600
--updated

Wait until the software update exists. Software updates have no provisioningState.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
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