az iot hub job

Manage IoT Hub jobs (v2).

Commands

az iot hub job cancel

Cancel an IoT Hub job.

az iot hub job create

Create and schedule an IoT Hub job for execution.

az iot hub job list

List the historical jobs of an IoT Hub.

az iot hub job show

Show details of an existing IoT Hub job.

az iot hub job cancel

Cancel an IoT Hub job.

az iot hub job cancel --job-id
                      [--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

--hub-name -n

IoT Hub name.

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

--resource-group -g

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

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.

az iot hub job create --job-id
                      --job-type {scheduleDeviceMethod, scheduleUpdateTwin}
                      [--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 "2020-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"

Required Parameters

--job-id

IoT Hub job Id.

--job-type --jt

The type of scheduled job.

accepted values: scheduleDeviceMethod, scheduleUpdateTwin

Optional Parameters

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

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

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

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

az iot hub job list

List the historical jobs of an IoT Hub.

az iot hub job list [--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

--hub-name -n

IoT Hub name.

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

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

az iot hub job show

Show details of an existing IoT Hub job.

az iot hub job show --job-id
                    [--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

--hub-name -n

IoT Hub name.

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

--resource-group -g

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