az iot hub job

  • Reference

Note

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

Manage IoT Hub jobs (v2).

Commands

Name Description Type Status
az iot hub job cancel

Cancel an IoT Hub job.

 Extension GA
az iot hub job create

Create and schedule an IoT Hub job for execution.

 Extension GA
az iot hub job list

List the historical jobs of an IoT Hub.

 Extension GA
az iot hub job show

Show details of an existing IoT Hub job.

 Extension GA

az iot hub job cancel

Cancel an IoT Hub job.

az iot hub job cancel --job-id
                      [--auth-type {key, login}]
                      [--hub-name]
                      [--login]
                      [--resource-group]

Examples

Cancel an IoT Hub job.

az iot hub job cancel --hub-name {iothub_name} --job-id {job_id}

Required Parameters

--job-id

IoT Hub job Id.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--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. Required if --hub-name is not provided.

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

--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 hub job create

Create and schedule an IoT Hub job for execution.

When scheduling a twin update job, the twin patch is a required argument. When scheduling a device method job, the method name and payload are required arguments. PLEASE NOTE: Using a custom start time that's in the past may cause the operation to fail.

az iot hub job create --job-id
                      --job-type {scheduleDeviceMethod, scheduleUpdateTwin}
                      [--auth-type {key, login}]
                      [--duration]
                      [--hub-name]
                      [--interval]
                      [--login]
                      [--mct]
                      [--method-name]
                      [--method-payload]
                      [--method-response-timeout]
                      [--patch]
                      [--query-condition]
                      [--resource-group]
                      [--start]
                      [--ttl]
                      [--wait {false, true}]

Examples

Create and schedule a job to update the twin tags of all devices.

az iot hub job create --job-id {job_id} --job-type scheduleUpdateTwin -n {iothub_name} -q "*" --twin-patch '{"tags": {"deviceType": "Type1, Type2, Type3"}}'

Schedule job and block for result of "completed", "failed" or "cancelled". Specify poll interval in seconds.

az iot hub job create --job-id {job_id} --job-type scheduleUpdateTwin -n {iothub_name} -q "*" --twin-patch '{"tags": {"deviceType": "Type1, Type2, Type3"}}' --wait --poll-interval 30

Create a job to update a desired twin property on a subset of devices, scheduled to run at an arbitrary future time.

az iot hub job create --job-id {job_name} --job-type scheduleUpdateTwin -n {iothub_name} --twin-patch '{"properties":{"desired": {"temperatureF": 65}}}' --start-time "2050-01-08T12:19:56.868Z" --query-condition "deviceId IN ['MyDevice1', 'MyDevice2', 'MyDevice3']"

Create and schedule a job to invoke a device method for a set of devices meeting a query condition.

az iot hub job create --job-id {job_name} --job-type scheduleDeviceMethod -n {iothub_name} --method-name setSyncIntervalSec --method-payload 30 --query-condition "properties.reported.settings.syncIntervalSec != 30"

Create and schedule a job to invoke a device method for all devices.

az iot hub job create --job-id {job_name} --job-type scheduleDeviceMethod -q "*" -n {iothub_name} --method-name setSyncIntervalSec --method-payload '{"version":"1.0"}'

Required Parameters

--job-id

IoT Hub job Id.

--job-type --jt

The type of scheduled job.

accepted values: scheduleDeviceMethod, scheduleUpdateTwin

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--duration --poll-duration

Total duration in seconds where job status will be checked if --wait flag is passed in.

default value: 600
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--interval --poll-interval

Interval in seconds that job status will be checked if --wait flag is passed in.

default value: 10
--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. Required if --hub-name is not provided.

--mct --method-connect-timeout

Maximum number of seconds to wait on device connection.

default value: 30
--method-name --mn

Target method for invocation.

--method-payload --mp

Json payload to be passed to method. Must be file path or raw json.

--method-response-timeout --mrt

Maximum number of seconds to wait for device method result.

default value: 30
--patch --twin-patch

The desired twin patch. Provide file path or raw json.

--query-condition -q

Condition for device query to get devices to execute the job on. Required if job type is scheduleDeviceMethod or scheduleUpdateTwin. Note: The service will prefix "SELECT * FROM devices WHERE " to the input.

--resource-group -g

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

--start --start-time

The scheduled start of the job in ISO 8601 date time format. If no start time is provided, the job is queued for asap execution. Using a custom start time that's in the past may cause the operation to fail.

--ttl

Max execution time in seconds, before job is terminated.

default value: 3600
--wait -w

Block until the created job is in a completed, failed or cancelled state. Will regularly poll on interval specified by --poll-interval.

accepted values: false, true
default value: False
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 hub job list

List the historical jobs of an IoT Hub.

az iot hub job list [--auth-type {key, login}]
                    [--hub-name]
                    [--job-status {cancelled, completed, enqueued, failed, queued, running, scheduled, unknown}]
                    [--job-type {export, import, scheduleDeviceMethod, scheduleUpdateTwin}]
                    [--login]
                    [--resource-group]
                    [--top]

Examples

List all archived jobs within retention period (max of 30 days).

az iot hub job list --hub-name {iothub_name}

List all archived jobs projecting specific properties

az iot hub job list --hub-name {iothub_name} --query "[*].[jobId,type,status,startTime,endTime]"

List only update twin type jobs

az iot hub job list --hub-name {iothub_name} --job-type scheduleDeviceMethod

List device method jobs which have status "scheduled"

az iot hub job list --hub-name {iothub_name} --job-type scheduleDeviceMethod --job-status scheduled

List device export jobs which have status "completed"

az iot hub job list --hub-name {iothub_name} --job-type export --job-status completed

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--job-status --js

The status of a scheduled job.

accepted values: cancelled, completed, enqueued, failed, queued, running, scheduled, unknown
--job-type --jt

The type of scheduled job.

accepted values: export, import, scheduleDeviceMethod, scheduleUpdateTwin
--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. Required if --hub-name is not provided.

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

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

Show details of an existing IoT Hub job.

az iot hub job show --job-id
                    [--auth-type {key, login}]
                    [--hub-name]
                    [--login]
                    [--resource-group]

Examples

Show the details of a created job.

az iot hub job show --hub-name {iothub_name} --job-id {job_id}

Required Parameters

--job-id

IoT Hub job Id.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--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. Required if --hub-name is not provided.

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

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