JobClient class

  • Reference
Package:
azure-iothub

Provides methods to create, update, monitor and cancel long-running jobs on an IoT Hub instance, as well as query existing jobs. The Jobs API in Azure IoT Hub allows to schedule direct method calls and twin updates on multiple devices.

SDK users are expected to create JobClient instances using the factory methods fromConnectionString(string) and fromSharedAccessSignature(string).

Methods

cancelJob(string | number)
cancelJob(string | number, TripleValueCallback<any, any>)

Cancels an existing job.
createQuery(JobType, JobStatus, number)

Creates a query that can be used to return pages of existing job based on type and status.
fromConnectionString(string)

Constructs a JobClient object from the given connection string.
fromSharedAccessSignature(string)

Constructs a JobClient object from the given shared access signature.
fromTokenCredential(string, TokenCredential)

Constructs a JobClient object from the given shared Azure TokenCredential.
getJob(string | number)
getJob(string | number, TripleValueCallback<any, any>)

Requests information about an existing job.
scheduleDeviceMethod(string | number, string, DeviceMethodParams)
scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date)
scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date, number)
scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date, number, TripleValueCallback<any, any>)

Schedules a job that will execute a device method on a set of devices.
scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date, TripleValueCallback<any, any>)
scheduleDeviceMethod(string | number, string, DeviceMethodParams, TripleValueCallback<any, any>)
scheduleTwinUpdate(string | number, string, any)
scheduleTwinUpdate(string | number, string, any, Date)
scheduleTwinUpdate(string | number, string, any, Date, number)
scheduleTwinUpdate(string | number, string, any, Date, number, TripleValueCallback<any, any>)

Schedule a job that will update a set of twins with the patch provided as a parameter.
scheduleTwinUpdate(string | number, string, any, Date, TripleValueCallback<any, any>)
scheduleTwinUpdate(string | number, string, any, TripleValueCallback<any, any>)

Method Details

cancelJob(string | number) 

function cancelJob(jobId: string | number): Promise<JobStatusResponse>

Parameters

jobId

string | number

Returns

Promise<JobStatusResponse>

cancelJob(string | number, TripleValueCallback<any, any>)

Cancels an existing job.

function cancelJob(jobId: string | number, done?: TripleValueCallback<any, any>)

Parameters

jobId

string | number

The identifier of an existing job.

done

TripleValueCallback<any, any>

The optional function to call when the operation is complete. done will be called with three arguments: an Error object (can be null), a job object, and a transport-specific response object useful for logging or debugging.

createQuery(JobType, JobStatus, number)

Creates a query that can be used to return pages of existing job based on type and status.

function createQuery(jobType?: JobType, jobStatus?: JobStatus, pageSize?: number): Query

Parameters

jobType

JobType

The type that should be used to filter results.

jobStatus

JobStatus

The status that should be used to filter results.

pageSize

number

The number of elements to return per page.

Returns

Query

fromConnectionString(string)

Constructs a JobClient object from the given connection string.

static function fromConnectionString(connectionString: string): JobClient

Parameters

connectionString

string

A connection string which encapsulates the appropriate (read and/or write) Registry permissions.

Returns

JobClient

fromSharedAccessSignature(string)

Constructs a JobClient object from the given shared access signature.

static function fromSharedAccessSignature(sharedAccessSignature: string): JobClient

Parameters

sharedAccessSignature

string

A shared access signature which encapsulates the appropriate (read and/or write) Registry permissions.

Returns

JobClient

fromTokenCredential(string, TokenCredential)

Constructs a JobClient object from the given shared Azure TokenCredential.

static function fromTokenCredential(hostName: string, tokenCredential: TokenCredential): JobClient

Parameters

hostName

string

Host name of the Azure service.

tokenCredential
TokenCredential

An Azure TokenCredential used to authenticate with the Azure service

Returns

JobClient

getJob(string | number) 

function getJob(jobId: string | number): Promise<JobStatusResponse>

Parameters

jobId

string | number

Returns

Promise<JobStatusResponse>

getJob(string | number, TripleValueCallback<any, any>)

Requests information about an existing job.

function getJob(jobId: string | number, done?: TripleValueCallback<any, any>)

Parameters

jobId

string | number

The identifier of an existing job.

done

TripleValueCallback<any, any>

The optional function to call when the operation is complete. done will be called with three arguments: an Error object (can be null), a job object, and a transport-specific response object useful for logging or debugging.

scheduleDeviceMethod(string | number, string, DeviceMethodParams) 

function scheduleDeviceMethod(jobId: string | number, queryCondition: string, methodParams: DeviceMethodParams): Promise<JobStatusResponse>

Parameters

jobId

string | number

queryCondition

string

methodParams
DeviceMethodParams

Returns

Promise<JobStatusResponse>

scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date) 

function scheduleDeviceMethod(jobId: string | number, queryCondition: string, methodParams: DeviceMethodParams, jobStartTime: Date): Promise<JobStatusResponse>

Parameters

jobId

string | number

queryCondition

string

methodParams
DeviceMethodParams
jobStartTime

Date

Returns

Promise<JobStatusResponse>

scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date, number) 

function scheduleDeviceMethod(jobId: string | number, queryCondition: string, methodParams: DeviceMethodParams, jobStartTime: Date, maxExecutionTimeInSeconds: number): Promise<JobStatusResponse>

Parameters

jobId

string | number

queryCondition

string

methodParams
DeviceMethodParams
jobStartTime

Date

maxExecutionTimeInSeconds

number

Returns

Promise<JobStatusResponse>

scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date, number, TripleValueCallback<any, any>)

Schedules a job that will execute a device method on a set of devices.

function scheduleDeviceMethod(jobId: string | number, queryCondition: string, methodParams: DeviceMethodParams, jobStartTime?: Date, maxExecutionTimeInSeconds?: number, done?: TripleValueCallback<any, any>)

Parameters

jobId

string | number

The unique identifier that should be used for this job.

queryCondition

string

A SQL query WHERE clause used to compute the list of devices on which this job should be run.

methodParams
DeviceMethodParams

An object describing the method and shall have the following properties: - methodName The name of the method that shall be invoked. - payload [optional] The payload to use for the method call. - responseTimeoutInSeconds [optional] The number of seconds IoT Hub shall wait for the device

jobStartTime

Date

Time time at which the job should start

maxExecutionTimeInSeconds

number

The maximum time alloted for this job to run in seconds.

done

TripleValueCallback<any, any>

The optional function to call when the operation is complete. done will be called with three arguments: an Error object (can be null), a job object, and a transport-specific response object useful for logging or debugging.

scheduleDeviceMethod(string | number, string, DeviceMethodParams, Date, TripleValueCallback<any, any>) 

function scheduleDeviceMethod(jobId: string | number, queryCondition: string, methodParams: DeviceMethodParams, jobStartTime: Date, done: TripleValueCallback<any, any>)

Parameters

jobId

string | number

queryCondition

string

methodParams
DeviceMethodParams
jobStartTime

Date

done

TripleValueCallback<any, any>

scheduleDeviceMethod(string | number, string, DeviceMethodParams, TripleValueCallback<any, any>) 

function scheduleDeviceMethod(jobId: string | number, queryCondition: string, methodParams: DeviceMethodParams, done: TripleValueCallback<any, any>)

Parameters

jobId

string | number

queryCondition

string

methodParams
DeviceMethodParams
done

TripleValueCallback<any, any>

scheduleTwinUpdate(string | number, string, any) 

function scheduleTwinUpdate(jobId: string | number, queryCondition: string, patch: any): Promise<JobStatusResponse>

Parameters

jobId

string | number

queryCondition

string

patch

any

Returns

Promise<JobStatusResponse>

scheduleTwinUpdate(string | number, string, any, Date) 

function scheduleTwinUpdate(jobId: string | number, queryCondition: string, patch: any, jobStartTime: Date): Promise<JobStatusResponse>

Parameters

jobId

string | number

queryCondition

string

patch

any

jobStartTime

Date

Returns

Promise<JobStatusResponse>

scheduleTwinUpdate(string | number, string, any, Date, number) 

function scheduleTwinUpdate(jobId: string | number, queryCondition: string, patch: any, jobStartTime: Date, maxExecutionTimeInSeconds?: number): Promise<JobStatusResponse>

Parameters

jobId

string | number

queryCondition

string

patch

any

jobStartTime

Date

maxExecutionTimeInSeconds

number

Returns

Promise<JobStatusResponse>

scheduleTwinUpdate(string | number, string, any, Date, number, TripleValueCallback<any, any>)

Schedule a job that will update a set of twins with the patch provided as a parameter.

function scheduleTwinUpdate(jobId: string | number, queryCondition: string, patch: any, jobStartTime?: Date, maxExecutionTimeInSeconds?: number, done?: TripleValueCallback<any, any>)

Parameters

jobId

string | number

The unique identifier that should be used for this job.

queryCondition

string

A SQL query WHERE clause used to compute the list of devices on which this job should be run.

patch

any

The twin patch that should be applied to the twins.

jobStartTime

Date

Time time at which the job should start

maxExecutionTimeInSeconds

number

The maximum time alloted for this job to run in seconds.

done

TripleValueCallback<any, any>

The optional function to call when the operation is complete. done will be called with three arguments: an Error object (can be null), a job object, and a transport-specific response object useful for logging or debugging.

scheduleTwinUpdate(string | number, string, any, Date, TripleValueCallback<any, any>) 

function scheduleTwinUpdate(jobId: string | number, queryCondition: string, patch: any, jobStartTime: Date, done: TripleValueCallback<any, any>)

Parameters

jobId

string | number

queryCondition

string

patch

any

jobStartTime

Date

done

TripleValueCallback<any, any>

scheduleTwinUpdate(string | number, string, any, TripleValueCallback<any, any>) 

function scheduleTwinUpdate(jobId: string | number, queryCondition: string, patch: any, done: TripleValueCallback<any, any>)

Parameters

jobId

string | number

queryCondition

string

patch

any

done

TripleValueCallback<any, any>