Share via

Jobs - Create Scheduled Job

  • Reference
Service:
IoT Hub
API Version:
2021-04-12

Creates a new job to schedule twin updates or direct methods on the IoT Hub at a scheduled time. See https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-jobs for more information.

PUT https://fully-qualified-iothubname.azure-devices.net/jobs/v2/{id}?api-version=2021-04-12

URI Parameters

Name In Required Type Description
id
 path True

string

The unique identifier of the job.
api-version
 query True

string

Version of the Api.

Request Body

Name Type Description
cloudToDeviceMethod

CloudToDeviceMethod

The method type and parameters. This is required if the job type is cloudToDeviceMethod.
jobId

string

The unique identifier of the job.
maxExecutionTimeInSeconds

integer

The maximum execution time in secounds.
queryCondition

string

The condition for devices to execute the job. This is required if the job type is updateTwin or cloudToDeviceMethod.
startTime

string

The start date and time of the job in ISO 8601 standard.
type enum:
  • unknown
  • export
  • import
  • backup
  • readDeviceProperties
  • writeDeviceProperties
  • updateDeviceConfiguration
  • rebootDevice
  • factoryResetDevice
  • firmwareUpdate
  • scheduleDeviceMethod
  • scheduleUpdateTwin
  • restoreFromBackup
  • failoverDataCopy

The job type.
updateTwin

Twin

The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.

Responses

Name Type Description
200 OK

JobResponse

OK.

Definitions

Name Description
CloudToDeviceMethod

The parameters to execute a direct method on the device.
DeviceCapabilities

The status of capabilities enabled on the device.
DeviceJobStatistics

The job statistics regarding execution status.
JobRequest
JobResponse
Twin

The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.
TwinProperties

The desired and reported properties of the twin. The maximum depth of the object is 10.
X509Thumbprint

CloudToDeviceMethod

The parameters to execute a direct method on the device.

Name Type Description
connectTimeoutInSeconds

integer

methodName

string

The name of the method to execute.
payload

object

The JSON-formatted direct method payload, up to 128kb in size.
responseTimeoutInSeconds

integer

DeviceCapabilities

The status of capabilities enabled on the device.

Name Type Description
iotEdge

boolean

The property that determines if the device is an edge device or not.

DeviceJobStatistics

The job statistics regarding execution status.

Name Type Description
deviceCount

integer

The number of devices targeted by the job.
failedCount

integer

The number of failed jobs.
pendingCount

integer

The number of pending (scheduled) jobs.
runningCount

integer

The number of running jobs.
succeededCount

integer

The number of succeeded jobs.

JobRequest

Name Type Description
cloudToDeviceMethod

CloudToDeviceMethod

The method type and parameters. This is required if the job type is cloudToDeviceMethod.
jobId

string

The unique identifier of the job.
maxExecutionTimeInSeconds

integer

The maximum execution time in secounds.
queryCondition

string

The condition for devices to execute the job. This is required if the job type is updateTwin or cloudToDeviceMethod.
startTime

string

The start date and time of the job in ISO 8601 standard.
type enum:
  • backup
  • export
  • factoryResetDevice
  • failoverDataCopy
  • firmwareUpdate
  • import
  • readDeviceProperties
  • rebootDevice
  • restoreFromBackup
  • scheduleDeviceMethod
  • scheduleUpdateTwin
  • unknown
  • updateDeviceConfiguration
  • writeDeviceProperties

The job type.
updateTwin

Twin

The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.

JobResponse

Name Type Description
cloudToDeviceMethod

CloudToDeviceMethod

The method type and parameters. This is required if job type is cloudToDeviceMethod.
createdTime

string

System generated. Ignored at creation. The creation date and time of the job.
deviceJobStatistics

DeviceJobStatistics

The details regarding job execution status.
endTime

string

System generated. Ignored at creation. The end date and time of the job in UTC.
failureReason

string

The reason for the failure, if a failure occurred.
jobId

string

System generated. Ignored at creation. The unique identifier of the job.
maxExecutionTimeInSeconds

integer

The maximum execution time in secounds.
queryCondition

string

The device query condition.
startTime

string

The start date and time of the scheduled job in UTC.
status enum:
  • cancelled
  • completed
  • enqueued
  • failed
  • queued
  • running
  • scheduled
  • unknown

System generated. Ignored at creation. The status of the job.
statusMessage

string

The status message of the job.
type enum:
  • backup
  • export
  • factoryResetDevice
  • failoverDataCopy
  • firmwareUpdate
  • import
  • readDeviceProperties
  • rebootDevice
  • restoreFromBackup
  • scheduleDeviceMethod
  • scheduleUpdateTwin
  • unknown
  • updateDeviceConfiguration
  • writeDeviceProperties

The job type.
updateTwin

Twin

The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.

Twin

The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.

Name Type Description
authenticationType enum:
  • certificateAuthority
  • none
  • sas
  • selfSigned

The authentication type used by the device.
capabilities

DeviceCapabilities

The status of capabilities enabled on the device.
cloudToDeviceMessageCount

integer

The number of cloud-to-device messages sent.
connectionState enum:
  • Connected
  • Disconnected

The connection state of the device.
deviceEtag

string

The string representing a ETag for the device, as per RFC7232.
deviceId

string

The unique identifier of the device in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
deviceScope

string

The scope of the device.
etag

string

The string representing a ETag for the device twin, as per RFC7232.
lastActivityTime

string

The date and time when the device last connected or received or sent a message. The date and time is sepecified in ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This value is not updated if the device uses the HTTP/1 protocol to perform messaging operations.
moduleId

string

The unique identifier of the module in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
parentScopes

string[]

The scopes of the upper level edge devices if applicable. Only available for edge devices.
properties

TwinProperties

The desired and reported properties of the twin.
status enum:
  • disabled
  • enabled

The enabled status of the device. If disabled, the device cannot connect to the service.
statusReason

string

The reason for the current status of the device, if any.
statusUpdateTime

string

The date and time when the status of the device was last updated.
tags

object

The collection of key-value pairs read and written by the solution back end. They are not visible to device apps. They keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The values are JSON objects, up-to 4KB in length.
version

integer

The version for the device twin including tags and desired properties
x509Thumbprint

X509Thumbprint

The X509 thumbprint of the device.

TwinProperties

The desired and reported properties of the twin. The maximum depth of the object is 10.

Name Type Description
desired

object

The collection of desired property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The desired porperty values are JSON objects, up-to 4KB in length.
reported

object

The collection of reported property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The reported property values are JSON objects, up-to 4KB in length.

X509Thumbprint

Name Type Description
primaryThumbprint

string

The X509 client certificate primary thumbprint.
secondaryThumbprint

string

The X509 client certificate secondary thumbprint.