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
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.
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 |
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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 |
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.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
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.
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
IoT Hub job Id.
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.
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 |
Total duration in seconds where job status will be checked if --wait flag is passed in.
Property | Value |
---|---|
Default value: | 600 |
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
Interval in seconds that job status will be checked if --wait flag is passed in.
Property | Value |
---|---|
Default value: | 10 |
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 |
Maximum number of seconds to wait on device connection.
Property | Value |
---|---|
Default value: | 30 |
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.
Property | Value |
---|---|
Default value: | 30 |
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.
Property | Value |
---|---|
Default value: | 3600 |
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
Increase logging verbosity to show all debug logs.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
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.
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.
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 |
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
The status of a scheduled job.
Property | Value |
---|---|
Accepted values: | cancelled, completed, enqueued, failed, queued, running, scheduled, unknown |
The type of scheduled job.
Property | Value |
---|---|
Accepted values: | export, import, scheduleDeviceMethod, scheduleUpdateTwin |
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 |
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.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
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.
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
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.
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 |
IoT Hub name or hostname. Required if --login is not provided.
Property | Value |
---|---|
Parameter group: | IoT Hub Identifier Arguments |
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 |
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.
Property | Value |
---|---|
Default value: | False |
Show this help message and exit.
Only show errors, suppressing warnings.
Property | Value |
---|---|
Default value: | False |
Output format.
Property | Value |
---|---|
Default value: | json |
Accepted values: | json, jsonc, none, table, tsv, yaml, yamlc |
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.
Property | Value |
---|---|
Default value: | False |