IoTHub Manager Jobs API

Get list of jobs by status/type

GET /v1/jobs

This API accepts five optional query strings:

1. jobType - the type of job. There are two available values:
2. • device method job (ScheduleDeviceMethod)
3. • update twin job (ScheduleUpdateTwin)

Both the number value and string value in brackets are acceptable

2. jobStatus - the status of job. There are available values below:

• enqueued
• running
• completed
• failed
• cancelled
• scheduled
• queued

Both the number value and string value are acceptable

3. pageSize - the page size of job query

4. from - the lower UTC time bound of interesting period. It accept time formats below:

• NOW
• NOW-{ISO8601 duration}
• NOW+{ISO8601 duration}
• Date time offset string. Please check MSDN for detail

5. to - the upper UTC time bound of interesting period. The acceptable input format is same as from

Sample requests

• /v1/jobs?jobStatus=running

  Returns all running jobs

• /v1/jobs?jobStatus=3&from=NOW-30D

  Returns completed jobs created within last month

Response

Returns 200 OK and list of the job object. Please check API Get job status by job ID for detail of the job object

Get job status by job ID

GET /v1/jobs/{id}

This API accepts two optional query strings:

1. includeDeviceDetails - true means request for per-device job details

2. deviceJobStatus - interestring job status of the per-device job details. The available values include:

• 0 - Pending
• 1 - Scheduled
• 2 - Running
• 3 - Completed
• 4 - Failed
• 5 - Canceled

Both the number value and string value are acceptable

Sample requests

• /v1/jobs/job001

  Returns cross device summary of job job001

• /v1/jobs/job001?includeDeviceDetails=true

  Returns cross device summary and pre-device details of job job001

• /v1/jobs/job001?includeDeviceDetails=true&deviceJobStatus=failed

  Returns cross device summary and failed pre-device details of job job001

Response

Returns 200 OK and the job object:

{
  "jobId": <job ID>,
  "queryCondition": <the query condition used to schedule job>,
  "createdTimeUtc": <scheduled job start time in UTC>,
  "startTimeUtc": <job start time>,
  "endTimeUtc": <job end time>,
  "maxExecutionTimeInSeconds": <max execution time used to schedule job>,
  "type": <job type>,
  "status": <job status>,
  "methodParameter": {
    "name": <method name>,
    "jsonPayload": <parameters in JSON>,
    "responseTimeout": <response timeout>,
    "connectionTimeout": <connection timeout>    
  },
  "updateTwin: {
    "deviceId": <device ID>,
    "etag": <etag>,
    "properties": {
      "Reported": { ... },
      "Desired": { ... },
    },
    "tags": { ... },
    "isSimulated": <true for simulated device, otherwise false>
  },
  "failureReason": <if job failed, this represents a string containing the reason>,
  "statusMessage": <represents a string containing a message with status about the job execution>,
  "resultStatistics": {
    "deviceCount": <number of devices in the job>,
    "failedCount": <the number of failed jobs>,
    "succeededCount": <the number of Successed jobs>,
    "runningCount": <the number of running jobs>,
    "pendingCount": <the number of pending (scheduled) jobs>
  },
  "Devices": [
    {
      "DeviceId": <device ID>,
      "Status": <the per-device job status. Value range is same as query string `deviceJobStatus`>,
      "StartTimeUtc": <start time of the job on current device>,
      "EndTimeUtc": <end time of the job on current device>,
      "CreatedTDateTimeUtc": <create time of the job on current device>,
      "LastUpdatedDateTimeUtc": <last update time of the job on current device>,
      "Outcome": {
        "status": <method execution status>,
        "jsonPayload": <method output>
      },
      "Error": {
        "Code": <device job error code>,
        "Description": <device job error description>
      }
    }
  ]
}

Reminder:

1. Currently, it will never return any error (such as 404 Not Found) even if there is no such a job ID (depends on IoT Hub)
2. Some of fields may be null depends on IoT Hub implementation
3. methodParameter will only be meaningful for device method jobs
4. updateTwin will only be meaningful for update twin jobs
5. Devices.Outcome and Devices.Error may be missing if no such output from the device

Schedule job

POST /v1/jobs

The body should be the job object contains fields below:

• jobId
• queryCondition
• methodParameter or updateTwin

There are two more optional field are available:

• startTimeUtc (default value: now)
• maxExecutionTimeInSeconds (default vaule: 3600)

Here are some examples of the request body:

{
  "jobId": "sampleJob001",
  "queryCondition": "deviceId = 'CoolingSampleDevice003_685'",
  "methodParameter": {
    "name": "Reboot"
  }
}

{
  "jobId": "sampleJob002",
  "queryCondition": "tags.Floor = '1F'",
  "updateTwin": {
    "tags": {
      "Floor": "2F"
    }
  }
}

Response

Returns 200 OK and the full job object

Get device properties

GET /v1/deviceProperties

Response

Returns 200 OK and the definition object

{
    "Tags": [
        "IsSimulated"
    ],
    "Reported": [
        "Protocol",
        "SupportedMethods",
        "DeviceMethodStatus",
        "FirmwareUpdateStatus",
        "Type",
        "Location",
        "Latitude",
        "Longitude",
        "Firmware",
        "Model"
    ],
    "$metadata": {
        "$type": "DeviceProperties;1",
        "$url": "/v1/deviceProperties"
    }
}```