AWS IoT Jobs Data Plane 2017-09-29
- Client: Aws\IoTJobsDataPlane\IoTJobsDataPlaneClient
- Service ID: iot-jobs-data
- Version: 2017-09-29
This page describes the parameters and results for the operations of the AWS IoT Jobs Data Plane (2017-09-29), and shows how to use the Aws\IoTJobsDataPlane\IoTJobsDataPlaneClient object to call the described operations. This documentation is specific to the 2017-09-29 API version of the service.
Operation Summary
Each of the following operations can be created from a client using
$client->getCommand('CommandName'), where "CommandName" is the
name of one of the following operations. Note: a command is a value that
encapsulates an operation and the parameters used to create an HTTP request.
You can also create and send a command immediately using the magic methods
available on a client object: $client->commandName(/* parameters */).
You can send the command asynchronously (returning a promise) by appending the
word "Async" to the operation name: $client->commandNameAsync(/* parameters */).
- DescribeJobExecution ( array $params = [] )
Gets details of a job execution.
- GetPendingJobExecutions ( array $params = [] )
Gets the list of all jobs for a thing that are not in a terminal status.
- StartNextPendingJobExecution ( array $params = [] )
Gets and starts the next pending (status IN_PROGRESS or QUEUED) job execution for a thing.
- UpdateJobExecution ( array $params = [] )
Updates the status of a job execution.
Operations
DescribeJobExecution
$result = $client->describeJobExecution([/* ... */]); $promise = $client->describeJobExecutionAsync([/* ... */]);
Gets details of a job execution.
Parameter Syntax
$result = $client->describeJobExecution([
'executionNumber' => <integer>,
'includeJobDocument' => true || false,
'jobId' => '<string>', // REQUIRED
'thingName' => '<string>', // REQUIRED
]);
Parameter Details
Members
- executionNumber
-
- Type: long (int|float)
Optional. A number that identifies a particular job execution on a particular device. If not specified, the latest job execution is returned.
- includeJobDocument
-
- Type: boolean
Optional. When set to true, the response contains the job document. The default is false.
- jobId
-
- Required: Yes
- Type: string
The unique identifier assigned to this job when it was created.
- thingName
-
- Required: Yes
- Type: string
The thing name associated with the device the job execution is running on.
Result Syntax
[
'execution' => [
'approximateSecondsBeforeTimedOut' => <integer>,
'executionNumber' => <integer>,
'jobDocument' => '<string>',
'jobId' => '<string>',
'lastUpdatedAt' => <integer>,
'queuedAt' => <integer>,
'startedAt' => <integer>,
'status' => 'QUEUED|IN_PROGRESS|SUCCEEDED|FAILED|TIMED_OUT|REJECTED|REMOVED|CANCELED',
'statusDetails' => ['<string>', ...],
'thingName' => '<string>',
'versionNumber' => <integer>,
],
]
Result Details
Members
- execution
-
- Type: JobExecution structure
Contains data about a job execution.
Errors
-
InvalidRequestException:
The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.
-
ResourceNotFoundException:
The specified resource does not exist.
-
ThrottlingException:
The rate exceeds the limit.
-
ServiceUnavailableException:
The service is temporarily unavailable.
-
CertificateValidationException:
The certificate is invalid.
-
TerminalStateException:
The job is in a terminal state.
GetPendingJobExecutions
$result = $client->getPendingJobExecutions([/* ... */]); $promise = $client->getPendingJobExecutionsAsync([/* ... */]);
Gets the list of all jobs for a thing that are not in a terminal status.
Parameter Syntax
$result = $client->getPendingJobExecutions([
'thingName' => '<string>', // REQUIRED
]);
Parameter Details
Result Syntax
[
'inProgressJobs' => [
[
'executionNumber' => <integer>,
'jobId' => '<string>',
'lastUpdatedAt' => <integer>,
'queuedAt' => <integer>,
'startedAt' => <integer>,
'versionNumber' => <integer>,
],
// ...
],
'queuedJobs' => [
[
'executionNumber' => <integer>,
'jobId' => '<string>',
'lastUpdatedAt' => <integer>,
'queuedAt' => <integer>,
'startedAt' => <integer>,
'versionNumber' => <integer>,
],
// ...
],
]
Result Details
Members
- inProgressJobs
-
- Type: Array of JobExecutionSummary structures
A list of JobExecutionSummary objects with status IN_PROGRESS.
- queuedJobs
-
- Type: Array of JobExecutionSummary structures
A list of JobExecutionSummary objects with status QUEUED.
Errors
-
InvalidRequestException:
The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.
-
ResourceNotFoundException:
The specified resource does not exist.
-
ThrottlingException:
The rate exceeds the limit.
-
ServiceUnavailableException:
The service is temporarily unavailable.
-
CertificateValidationException:
The certificate is invalid.
StartNextPendingJobExecution
$result = $client->startNextPendingJobExecution([/* ... */]); $promise = $client->startNextPendingJobExecutionAsync([/* ... */]);
Gets and starts the next pending (status IN_PROGRESS or QUEUED) job execution for a thing.
Parameter Syntax
$result = $client->startNextPendingJobExecution([
'statusDetails' => ['<string>', ...],
'stepTimeoutInMinutes' => <integer>,
'thingName' => '<string>', // REQUIRED
]);
Parameter Details
Members
- statusDetails
-
- Type: Associative array of custom strings keys (DetailsKey) to strings
A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.
- stepTimeoutInMinutes
-
- Type: long (int|float)
Specifies the amount of time this device has to finish execution of this job. If the job execution status is not set to a terminal state before this timer expires, or before the timer is reset (by calling
UpdateJobExecution, setting the status toIN_PROGRESSand specifying a new timeout value in fieldstepTimeoutInMinutes) the job execution status will be automatically set toTIMED_OUT. Note that setting this timeout has no effect on that job execution timeout which may have been specified when the job was created (CreateJobusing fieldtimeoutConfig). - thingName
-
- Required: Yes
- Type: string
The name of the thing associated with the device.
Result Syntax
[
'execution' => [
'approximateSecondsBeforeTimedOut' => <integer>,
'executionNumber' => <integer>,
'jobDocument' => '<string>',
'jobId' => '<string>',
'lastUpdatedAt' => <integer>,
'queuedAt' => <integer>,
'startedAt' => <integer>,
'status' => 'QUEUED|IN_PROGRESS|SUCCEEDED|FAILED|TIMED_OUT|REJECTED|REMOVED|CANCELED',
'statusDetails' => ['<string>', ...],
'thingName' => '<string>',
'versionNumber' => <integer>,
],
]
Result Details
Members
- execution
-
- Type: JobExecution structure
A JobExecution object.
Errors
-
InvalidRequestException:
The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.
-
ResourceNotFoundException:
The specified resource does not exist.
-
ThrottlingException:
The rate exceeds the limit.
-
ServiceUnavailableException:
The service is temporarily unavailable.
-
CertificateValidationException:
The certificate is invalid.
UpdateJobExecution
$result = $client->updateJobExecution([/* ... */]); $promise = $client->updateJobExecutionAsync([/* ... */]);
Updates the status of a job execution.
Parameter Syntax
$result = $client->updateJobExecution([
'executionNumber' => <integer>,
'expectedVersion' => <integer>,
'includeJobDocument' => true || false,
'includeJobExecutionState' => true || false,
'jobId' => '<string>', // REQUIRED
'status' => 'QUEUED|IN_PROGRESS|SUCCEEDED|FAILED|TIMED_OUT|REJECTED|REMOVED|CANCELED', // REQUIRED
'statusDetails' => ['<string>', ...],
'stepTimeoutInMinutes' => <integer>,
'thingName' => '<string>', // REQUIRED
]);
Parameter Details
Members
- executionNumber
-
- Type: long (int|float)
Optional. A number that identifies a particular job execution on a particular device.
- expectedVersion
-
- Type: long (int|float)
Optional. The expected current version of the job execution. Each time you update the job execution, its version is incremented. If the version of the job execution stored in Jobs does not match, the update is rejected with a VersionMismatch error, and an ErrorResponse that contains the current job execution status data is returned. (This makes it unnecessary to perform a separate DescribeJobExecution request in order to obtain the job execution status data.)
- includeJobDocument
-
- Type: boolean
Optional. When set to true, the response contains the job document. The default is false.
- includeJobExecutionState
-
- Type: boolean
Optional. When included and set to true, the response contains the JobExecutionState data. The default is false.
- jobId
-
- Required: Yes
- Type: string
The unique identifier assigned to this job when it was created.
- status
-
- Required: Yes
- Type: string
The new status for the job execution (IN_PROGRESS, FAILED, SUCCESS, or REJECTED). This must be specified on every update.
- statusDetails
-
- Type: Associative array of custom strings keys (DetailsKey) to strings
Optional. A collection of name/value pairs that describe the status of the job execution. If not specified, the statusDetails are unchanged.
- stepTimeoutInMinutes
-
- Type: long (int|float)
Specifies the amount of time this device has to finish execution of this job. If the job execution status is not set to a terminal state before this timer expires, or before the timer is reset (by again calling
UpdateJobExecution, setting the status toIN_PROGRESSand specifying a new timeout value in this field) the job execution status will be automatically set toTIMED_OUT. Note that setting or resetting this timeout has no effect on that job execution timeout which may have been specified when the job was created (CreateJobusing fieldtimeoutConfig). - thingName
-
- Required: Yes
- Type: string
The name of the thing associated with the device.
Result Syntax
[
'executionState' => [
'status' => 'QUEUED|IN_PROGRESS|SUCCEEDED|FAILED|TIMED_OUT|REJECTED|REMOVED|CANCELED',
'statusDetails' => ['<string>', ...],
'versionNumber' => <integer>,
],
'jobDocument' => '<string>',
]
Result Details
Members
- executionState
-
- Type: JobExecutionState structure
A JobExecutionState object.
- jobDocument
-
- Type: string
The contents of the Job Documents.
Errors
-
InvalidRequestException:
The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.
-
ResourceNotFoundException:
The specified resource does not exist.
-
ThrottlingException:
The rate exceeds the limit.
-
ServiceUnavailableException:
The service is temporarily unavailable.
-
CertificateValidationException:
The certificate is invalid.
-
InvalidStateTransitionException:
An update attempted to change the job execution to a state that is invalid because of the job execution's current state (for example, an attempt to change a request in state SUCCESS to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.
Shapes
CertificateValidationException
Description
The certificate is invalid.
Members
InvalidRequestException
Description
The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.
Members
InvalidStateTransitionException
Description
An update attempted to change the job execution to a state that is invalid because of the job execution's current state (for example, an attempt to change a request in state SUCCESS to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.
Members
JobExecution
Description
Contains data about a job execution.
Members
- approximateSecondsBeforeTimedOut
-
- Type: long (int|float)
The estimated number of seconds that remain before the job execution status will be changed to
TIMED_OUT. - executionNumber
-
- Type: long (int|float)
A number that identifies a particular job execution on a particular device. It can be used later in commands that return or update job execution information.
- jobDocument
-
- Type: string
The content of the job document.
- jobId
-
- Type: string
The unique identifier you assigned to this job when it was created.
- lastUpdatedAt
-
- Type: long (int|float)
The time, in milliseconds since the epoch, when the job execution was last updated.
- queuedAt
-
- Type: long (int|float)
The time, in milliseconds since the epoch, when the job execution was enqueued.
- startedAt
-
- Type: long (int|float)
The time, in milliseconds since the epoch, when the job execution was started.
- status
-
- Type: string
The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".
- statusDetails
-
- Type: Associative array of custom strings keys (DetailsKey) to strings
A collection of name/value pairs that describe the status of the job execution.
- thingName
-
- Type: string
The name of the thing that is executing the job.
- versionNumber
-
- Type: long (int|float)
The version of the job execution. Job execution versions are incremented each time they are updated by a device.
JobExecutionState
Description
Contains data about the state of a job execution.
Members
- status
-
- Type: string
The status of the job execution. Can be one of: "QUEUED", "IN_PROGRESS", "FAILED", "SUCCESS", "CANCELED", "REJECTED", or "REMOVED".
- statusDetails
-
- Type: Associative array of custom strings keys (DetailsKey) to strings
A collection of name/value pairs that describe the status of the job execution.
- versionNumber
-
- Type: long (int|float)
The version of the job execution. Job execution versions are incremented each time they are updated by a device.
JobExecutionSummary
Description
Contains a subset of information about a job execution.
Members
- executionNumber
-
- Type: long (int|float)
A number that identifies a particular job execution on a particular device.
- jobId
-
- Type: string
The unique identifier you assigned to this job when it was created.
- lastUpdatedAt
-
- Type: long (int|float)
The time, in milliseconds since the epoch, when the job execution was last updated.
- queuedAt
-
- Type: long (int|float)
The time, in milliseconds since the epoch, when the job execution was enqueued.
- startedAt
-
- Type: long (int|float)
The time, in milliseconds since the epoch, when the job execution started.
- versionNumber
-
- Type: long (int|float)
The version of the job execution. Job execution versions are incremented each time AWS IoT Jobs receives an update from a device.
ResourceNotFoundException
Description
The specified resource does not exist.
Members
ServiceUnavailableException
Description
The service is temporarily unavailable.
