az iot adr ns job

  • 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 job 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

Manage Device Registry namespace jobs.

Commands

Name Description Type Status
az iot adr ns job create

Create a job in a Device Registry namespace.

 Extension Preview
az iot adr ns job delete

Delete a job from a Device Registry namespace.

 Extension Preview
az iot adr ns job list

List jobs in a Device Registry namespace.

 Extension Preview
az iot adr ns job run

Manage runs of Device Registry namespace jobs.

 Extension Preview
az iot adr ns job run cancel

Cancel a Device Registry job run.

 Extension Preview
az iot adr ns job run delete

Delete a Device Registry job run.

 Extension Preview
az iot adr ns job run list

List job runs by parent job or across a namespace.

 Extension Preview
az iot adr ns job run results

Browse per-device results of a job run.

 Extension Preview
az iot adr ns job run show

Show a single run of a Device Registry job.

 Extension Preview
az iot adr ns job run summary

Show aggregate progress counts for a Device Registry job run.

 Extension Preview
az iot adr ns job run wait

Wait for a Device Registry job run to reach a desired state.

 Extension Preview
az iot adr ns job schedule

Schedule an execution of a Device Registry job.

 Extension Preview
az iot adr ns job show

Show a job in a Device Registry namespace.

 Extension Preview
az iot adr ns job update

Update tags on a job in a Device Registry namespace.

 Extension Preview
az iot adr ns job wait

Wait for a Device Registry job to reach a desired state.

 Extension Preview

az iot adr ns job create

Preview

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

Create a job in a Device Registry namespace.

PUT is a long-running operation. SoftwareUpdate jobs require a target group. OnboardingUpdate jobs target all compatible onboarding devices and do not accept a target group. Job definition fields are immutable after creation.

The target group is specified by --target-group-name and must live in the same namespace and resource group as the job (cross-namespace targets are not supported in this preview release). The Software Update identity (--update-id-provider, --update-id-name, --update-id-version) is passed opaquely to the backend; no Software Updates preflight is performed.

az iot adr ns job create --jn --job-name --name
                         --namespace --ns
                         --resource-group
                         [--acquire-policy-token]
                         [--change-reference]
                         [--description]
                         [--display-name]
                         [--location]
                         [--no-wait]
                         [--tags]
                         [--target-group-name --tg]
                         [--type {OnboardingUpdate, SoftwareUpdate}]
                         [--un --update-id-name --update-name]
                         [--up --update-id-provider --update-provider]
                         [--update-id-version --update-version --uv]

Examples

Create a SoftwareUpdate job targeting a group

az iot adr ns job create -n myJob --ns myNamespace -g myResourceGroup \
  --type SoftwareUpdate \
  --target-group-name myGroup \
  --update-id-provider Contoso --update-id-name gateway-firmware --update-id-version 1.2.3

Create an OnboardingUpdate job

az iot adr ns job create -n onboarding --ns myNamespace -g myResourceGroup \
  --type OnboardingUpdate \
  --update-id-provider Contoso --update-id-name gateway-firmware --update-id-version 1.2.3

Required Parameters

--jn --job-name --name -n

Name of the job.

--namespace --ns

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.

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

Human-readable job description.

--display-name

Human-readable display name for the job.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--no-wait

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

Property Value
Default value: False
--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--target-group-name --tg

Name of the target group. The group must live in the same namespace and resource group as the job; cross-namespace targets are not supported in this preview release.

--type

Job type: SoftwareUpdate targets a group; OnboardingUpdate targets all compatible onboarding devices.

Property Value
Default value: SoftwareUpdate
Accepted values: OnboardingUpdate, SoftwareUpdate
--un --update-id-name --update-name

Software Update updateId.name (e.g. 'gateway-firmware'). This is the update identity's name, distinct from the job's --name.

Property Value
Parameter group: Update Arguments
--up --update-id-provider --update-provider

Software Update updateId.provider (e.g. 'Contoso'). The update identity is a {provider, name, version} triple.

Property Value
Parameter group: Update Arguments
--update-id-version --update-version --uv

Software Update updateId.version (e.g. '1.2.3').

Property Value
Parameter group: Update 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 job delete

Preview

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

Delete a job from a Device Registry namespace.

DELETE is a long-running operation. If any in-flight runs (status 'Scheduled' or 'Active') exist for this job, a warning is surfaced before deletion; the backend cancels affected runs with reason 'CanceledByCustomer'.

az iot adr ns job delete --jn --job-name --name
                         --namespace --ns
                         --resource-group
                         [--acquire-policy-token]
                         [--change-reference]
                         [--no-wait]
                         [--yes {false, true}]

Examples

Delete a job

az iot adr ns job delete -n myJob --ns myNamespace -g myResourceGroup

Required Parameters

--jn --job-name --name -n

Name of the job.

--namespace --ns

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.

--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 job list

Preview

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

List jobs in a Device Registry namespace.

az iot adr ns job list --namespace --ns
                       --resource-group

Examples

List all jobs in a namespace

az iot adr ns job list --ns myNamespace -g myResourceGroup

Required Parameters

--namespace --ns

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

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 job schedule

Preview

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

Schedule an execution of a Device Registry job.

A job defines what to deploy and where; scheduling it creates a job run that tracks one execution. Schedule the same job as many times as you need.

--scheduled-time is the only writable property on a run; every other property is populated by the service. Omit it to start immediately.

--run-name is optional. When omitted, a UTC-timestamped name such as 'run-20251201080000' is generated and returned in the response. Use 'az iot adr ns job run' to show, cancel, or inspect the resulting run.

az iot adr ns job schedule --jn --job-name --name
                           --namespace --ns
                           --resource-group
                           [--acquire-policy-token]
                           [--change-reference]
                           [--no-wait]
                           [--rn --run-name]
                           [--scheduled-time --st]

Examples

Schedule a job to run immediately

az iot adr ns job schedule -n myJob --ns myNamespace -g myResourceGroup

Schedule a job for a specific UTC time with an explicit run name

az iot adr ns job schedule -n myJob --ns myNamespace -g myResourceGroup \
  --run-name myRun --scheduled-time 2025-12-01T08:00:00Z

Required Parameters

--jn --job-name --name -n

Name of the job.

--namespace --ns

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.

--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
--rn --run-name

Name of the job run to create. Defaults to a generated UTC-timestamped name such as 'run-20251201080000'.

--scheduled-time --st

Optional ISO 8601 UTC timestamp at which the run should start (e.g. '2025-12-01T08:00:00Z'). Omit to start immediately.

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 job show

Preview

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

Show a job in a Device Registry namespace.

az iot adr ns job show --jn --job-name --name
                       --namespace --ns
                       --resource-group

Examples

Show job details

az iot adr ns job show -n myJob --ns myNamespace -g myResourceGroup

Required Parameters

--jn --job-name --name -n

Name of the job.

--namespace --ns

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

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 job update

Preview

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

Update tags on a job in a Device Registry namespace.

PATCH is synchronous and tags-only by design. The job's --type, target group, update identity, and scheduling fields are immutable after creation because mutating them would have unintended effects on already-scheduled runs. To change these, delete and recreate the job.

az iot adr ns job update --jn --job-name --name
                         --namespace --ns
                         --resource-group
                         [--acquire-policy-token]
                         [--change-reference]
                         [--tags]

Examples

Update job tags

az iot adr ns job update -n myJob --ns myNamespace -g myResourceGroup --tags env=prod owner=platform

Clear all job tags

az iot adr ns job update -n myJob --ns myNamespace -g myResourceGroup --tags ""

Required Parameters

--jn --job-name --name -n

Name of the job.

--namespace --ns

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.

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

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

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 job wait

Preview

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

Wait for a Device Registry job to reach a desired state.

Without an explicit wait predicate, waits for provisioningState Succeeded.

az iot adr ns job wait --jn --job-name --name
                       --namespace --ns
                       --resource-group
                       [--acquire-policy-token]
                       [--change-reference]
                       [--created]
                       [--custom]
                       [--deleted]
                       [--exists]
                       [--interval]
                       [--timeout]
                       [--updated]

Examples

Wait until job provisioning succeeds

az iot adr ns job wait -n myJob --ns myNamespace -g myResourceGroup

Required Parameters

--jn --job-name --name -n

Name of the job.

--namespace --ns

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.

--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 provisioningState is Succeeded.

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 provisioningState is Succeeded.

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