az iot hub job

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

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

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

Property	Value
Parameter group:	Access Control Arguments
Default value:	key
Accepted values:	key, login

--hub-name -n

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

--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 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 --jt {scheduleDeviceMethod, scheduleUpdateTwin}
                      [--auth-type {key, login}]
                      [--duration --poll-duration]
                      [--hub-name]
                      [--interval --poll-interval]
                      [--login]
                      [--mct --method-connect-timeout]
                      [--method-name --mn]
                      [--method-payload --mp]
                      [--method-response-timeout --mrt]
                      [--patch --twin-patch]
                      [--query-condition]
                      [--resource-group]
                      [--start --start-time]
                      [--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.

Property	Value
Accepted values:	scheduleDeviceMethod, scheduleUpdateTwin

Optional Parameters

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

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

Property	Value
Parameter group:	Access Control Arguments
Default value:	key
Accepted values:	key, login

--duration --poll-duration

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

Property	Value
Default value:	600

--hub-name -n

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

--interval --poll-interval

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

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

--mct --method-connect-timeout

Maximum number of seconds to wait on device connection.

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

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

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

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

List the historical jobs of an IoT Hub.

az iot hub job list [--auth-type {key, login}]
                    [--hub-name]
                    [--job-status --js {cancelled, completed, enqueued, failed, queued, running, scheduled, unknown}]
                    [--job-type --jt {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

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

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

Property	Value
Parameter group:	Access Control Arguments
Default value:	key
Accepted values:	key, login

--hub-name -n

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

--job-status --js

The status of a scheduled job.

Property	Value
Accepted values:	cancelled, completed, enqueued, failed, queued, running, scheduled, unknown

--job-type --jt

The type of scheduled job.

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

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

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

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

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

Property	Value
Parameter group:	Access Control Arguments
Default value:	key
Accepted values:	key, login

--hub-name -n

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

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

Property	Value
Parameter group:	IoT Hub Identifier Arguments

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