AWS IoT jobs APIs - AWS IoT Core

AWS IoT jobs APIs

AWS IoT Jobs API can either be used for management and control of jobs, or for devices executing those jobs.

Job management and control uses an HTTPS protocol API. Devices can use either an MQTT or an HTTPS protocol API. The HTTPS API is designed for a low volume of calls typical when creating and tracking jobs. It usually opens a connection for a single request, and then closes the connection after the response is received. The MQTT API allows long polling. It is designed for large amounts of traffic that can scale to millions of devices.

Each AWS IoT Jobs HTTPS API has a corresponding command that allows you to call the API from the AWS CLI. The commands are lowercase, with hyphens between the words that make up the name of the API. For example, you can invoke the CreateJob API on the CLI by typing:

aws iot create-job ...

Job management and control API

The following commands are available for Job management and control in the CLI and over the HTTPS protocol.

    To determine the endpoint-url parameter for your CLI commands, run this command.

    aws iot describe-endpoint --endpoint-type=iot:Jobs

    This command returns the following output.

    { "endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com" }
    Note

    The Jobs endpoint doesn't support ALPN z-amzn-http-ca.

    Use the following API operations or CLI commands:

    Job management and control data types

    The following data types are used by management and control applications to communicate with AWS IoT Jobs.

    Jobs device MQTT and HTTPS APIs

    Jobs device commands can be issued by publishing MQTT messages to the Reserved topics used for Jobs commands. Your client is automatically subscribed to the response message topics of these commands, which means that the message broker will publish response message topics to the client that published the command message whether your client has subscribed to the response message topics or not. When subscribing to the job and jobExecution event topics for your fleet-monitoring solution, first enable job and job execution events to receive any events on the cloud side.

    Because the message broker publishes response messages, even without an explicit subscription to them, your client must be configured to receive and identify the messages it receives. Your client must also confirm that the thingName in the incoming message topic applies to the client's thing name before the client acts on the message.

    Messages that AWS IoT sends in response to MQTT Jobs API command messages are charged to your account, whether you subscribed to them explicitly or not.

    The following commands are available over the MQTT and HTTPS protocols.

    When you use the MQTT protocol, you can also perform the following updates:

    Sent whenever a job execution is added to or removed from the list of pending job executions for a thing.

    Use the topic:

    $aws/things/thingName/jobs/notify

    Message payload:

    { "jobs" : { "JobExecutionState": [ DescribeJobExecution ... ] }, "timestamp": timestamp, }

    Sent whenever there is a change to which job execution is next on the list of pending job executions for a thing, as defined for DescribeJobExecution with jobId $next. This message is not sent when the next job's execution details change, only when the next job that would be returned by DescribeJobExecution with jobId $next has changed. Consider job executions J1 and J2 with state QUEUED. J1 is next on the list of pending job executions. If the state of J2 is changed to IN_PROGRESS while the state of J1 remains unchanged, then this notification is sent and contains details of J2.

    Use the topic:

    $aws/things/thingName/jobs/notify-next

    Message payload:

    { "execution" : JobExecution, "timestamp": timestamp, }

    Jobs device MQTT and HTTPS data types

    The following data types are used to communicate with the AWS IoT Jobs service over the MQTT and HTTPS protocols.

    For errors occured during an operation, you get an error response that contains information about the error.

    Contains information about an error that occurred during an AWS IoT Jobs service operation.

    Following shows the syntax of this operation:

    { "code": "ErrorCode", "message": "string", "clientToken": "string", "timestamp": timestamp, "executionState": JobExecutionState }

    Following is a description of this ErrorResponse:

    code

    ErrorCode can be set to:

    InvalidTopic

    The request was sent to a topic in the AWS IoT Jobs namespace that does not map to any API.

    InvalidJson

    The contents of the request could not be interpreted as valid UTF-8-encoded JSON.

    InvalidRequest

    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.

    InvalidStateTransition

    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 SUCCEEDED to state IN_PROGRESS). In this case, the body of the error message also contains the executionState field.

    ResourceNotFound

    The JobExecution specified by the request topic does not exist.

    VersionMismatch

    The expected version specified in the request does not match the version of the job execution in the AWS IoT Jobs service. In this case, the body of the error message also contains the executionState field.

    InternalError

    There was an internal error during the processing of the request.

    RequestThrottled

    The request was throttled.

    TerminalStateReached

    Occurs when a command to describe a job is performed on a job that is in a terminal state.

    message

    An error message string.

    clientToken

    An arbitrary string used to correlate a request with its reply.

    timestamp

    The time, in seconds since the epoch.

    executionState

    A JobExecutionState object. This field is included only when the code field has the value InvalidStateTransition or VersionMismatch. This makes it unnecessary in these cases to perform a separate DescribeJobExecution request to obtain the current job execution status data.