az iot hub job
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 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
IoT Hub job Id.
Optional Parameters
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>
.
IoT Hub name or hostname. Required if --login is not provided.
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.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
IoT Hub job Id.
The type of scheduled job.
Optional Parameters
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>
.
Total duration in seconds where job status will be checked if --wait flag is passed in.
IoT Hub name or hostname. Required if --login is not provided.
Interval in seconds that job status will be checked if --wait flag is passed in.
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.
Maximum number of seconds to wait on device connection.
Target method for invocation.
Json payload to be passed to method. Must be file path or raw json.
Maximum number of seconds to wait for device method result.
The desired twin patch. Provide file path or raw json.
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.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
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.
Max execution time in seconds, before job is terminated.
Block until the created job is in a completed, failed or cancelled state. Will regularly poll on interval specified by --poll-interval.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
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>
.
IoT Hub name or hostname. Required if --login is not provided.
The status of a scheduled job.
The type of scheduled job.
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.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Maximum number of elements to return. Use -1 for unlimited.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
IoT Hub job Id.
Optional Parameters
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>
.
IoT Hub name or hostname. Required if --login is not provided.
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.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.