Retrieve messages of a specified Integration in an Application specified by ID
/iot/api/v2/apps/{app-id}/integrations/{integration-id}/messages
Request
-
app-id: string
ID for the target application
-
integration-id: string
ID for the target integration
-
expand: string
A Boolean flag indicating whether the messages should include the message payload with the core message properties. Valid values are "true" or "false". Default value is "true".
-
limit: integer(int32)
The maximum number of results to return. The default value is 10, with a maximum of 200.
-
offset: integer(int32)
The offset from the start of the results to start returning results from. The default value is 0.
-
orderBy: string
The orderBy parameter specifies the sorting method for the messages returned in the response. It is given in the form of "sortBy:sortOrder". Currently "eventTime" is the only value supported by "sortBy". Valid values for "sortOrder" are "desc" for descending order and "asc" for ascending order. Default value for orderBy is "eventTime:desc". "eventTime" is meant to represent the time when the message was created.
-
since: string
The since parameter specifies an epoch time in milliseconds. The parameter retrieves messages that have a message recorded time (either received time or sent time) that is greater than or equal to the specified epoch time.
-
until: string
The until parameter specifies an epoch time in milliseconds. The parameter retrieves messages that have a message recorded time (either received time or sent time) that is less than the specified epoch time.
-
Authorization: string
The Authentication credentials for HTTP Basic authentication. The format is
token_type access_token
, wheretoken_type
is "Basic" andaccess_token
isusername:password
encoded in Base64
Response
- application/json
200 Response
object
-
ALERT(optional):
object ALERT
ALERT messages are used to send urgent information such as error conditions and critical events, like threshold crossings.
-
DATA(optional):
object DATA
DATA is the predominant message type created by IoT devices and sent to the Oracle IoT Cloud Service instance. It consists of a format field and a series of key-value pairs, along with basic properties inherited from the Message object. Depending on how the format is defined, data messages can contain different data keys (along with their values), even when generated by the same source. For example, an IPSO 3303 Temperature sensor might sometimes send data messages with only a SensorValue key, and may at other times send the SensorValue, MinMeasuredValue, and MaxMeasuredValue keys along with their values in a single message. This can reduce the amount of network traffic when multiple data values must be sent at the same time.
-
REQUEST(optional):
object REQUEST
A request type of message is used to "tunnel" HTTP requests over the IoT messaging system. There are several reasons for wrapping an HTTP request into a request message:
- Asynchronous Messaging: Because devices may have their radio turned off for long periods of time and are therefore only occasionally connected, bundling an HTTP request into a message object allows the system to queue this request either on the server or on the client and send it when possible.
- Non-HTTP transport: Not all transport between the server and the clients will be over HTTP. It may be over SMTP when used with Iridium satellites, for example. However, it is desirable to maintain the semantics and nature of HTTP requests, even when the requests are used over other transports.
- Security: By requiring all HTTP requests to be routed through Oracle IoT Cloud Service, the service can validate each attempt to communicate between a device and any HTTP client (mobile, desktop, web).
A request message has the general capabilities of a normal HTTP request, including the URL, headers, and content. A request message includes the data that makes up an HTTP request, but does not fully implement the HTTP specification. However, for normal request/response patterns, the request message can be used as a typical HTTP request. These messages are used only in communications between a programmable device and Oracle IoT Cloud Service. These messages are not created or used by IoT enterprise applications that make HTTP requests. A web application (or mobile or desktop application) using the Endpoints API to GET/PUT/POST/DELETE a resource on a device will make a typical HTTP request. Oracle IoT Cloud Service internally converts this request into a request message and sends this message to the programmable device, which inspects the message and handles it appropriately. Likewise, if code on the programmable device needs to make an HTTP request (for example, to contact a 3rd party REST API), it creates a request message and sends this message to Oracle IoT Cloud Service, which converts it into a standard HTTP request against the target REST API. After it receives an HTTP response from the 3rd party, a response message is constructed and is sent to the programmable device to dispatch to the code that made the original request.
-
RESOURCES_REPORT(optional):
object RESOURCES_REPORT
A Resources Report message transfers information about resources that are supported by an endpoint to the Oracle IoT Cloud Service instance. The service instance contains information about all resources supported by endpoints. A Resources Report message must be sent to add resources to or remove resources from the Server Resource Directory.
This information synchronization is one-way. No information is sent back to the endpoint or Gateway, except when the service instance finds that the information about resources supported by an endpoint received in the Resources Report message differs from the information stored on the service instance. In this case, the service instance sends a Resource Reconciliation Request to the endpoint. If an endpoint receives a Resource Reconciliation Request, it must send a message with type RECONCILIATION to the service instance. The message must contain a complete list of resources that are available on the endpoint.
-
RESPOSNE(optional):
object RESPONSE
A response message is used to "tunnel" responses to request messages over the messaging system. A response message is always created as a response to a request message and maintains a reference to the message id of the request message to which it is responding.
A response message has the same structure as a normal HTTP response, including headers, status, and content. A response message includes the data that makes up an HTTP response, but it does not fully implement the HTTP specification. Response messages are only used in communications between programmable devices and Oracle IoT Cloud Service. These messages are not created or used by IoT enterprise web applications that make HTTP requests. A web application (or mobile or desktop application) that uses the Endpoints API to GET/PUT/POST/DELETE a resource on a device will make a normal HTTP request. Oracle IoT Cloud Service internally converts this request into a request message and sends this message to the programmable device, which inspects the message and handles it appropriately, returning a response message. This response is converted back into standard HTTP and is returned to the caller, either synchronously or asynchronously. See the Endpoints API for examples.
-
UPDATE_BUNDLE(optional):
object UPDATE_BUNDLE
An UPDATE_BUNDLE message is sent whenever the state on a bundle deployed and installed on a programmable device is changed. For example, if a bundle changes from "RESOLVED" to "ACTIVE", an UPDATE_BUNDLE message is sent to Oracle IoT Cloud Service to update the cached state on the server to match the state of the device.
-
UPDATE_BUNDLE_STATE(optional):
object UPDATE_BUNDLE_STATE
UPDATE_BUNDLE_STATE represents a message that updates the bundle state on the Oracle IoT Cloud Service instance. This message type includes fields that identify bundles and communicate bundle state.
-
WAKEUP(optional):
object WAKEUP
WAKEUP messages are sent from programmable devices to the Oracle IoT Cloud Service instance when the device starts. This message informs the service instance of the status of this device (it just woke up) and the currently installed set of bundles and their status. After the service instance processes the message, the service has up-to-date status information about the device.
object
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
direction:
string
An optional field that specifies the direction of the messages that go through the Oracle IoT Cloud Service instance. Valid values are TO_DEVICE and FROM_DEVICE.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
ALERT
object
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
direction:
string
An optional field that specifies the direction of the messages that go through the Oracle IoT Cloud Service instance. Valid values are TO_DEVICE and FROM_DEVICE.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
DATA
object
A request type of message is used to "tunnel" HTTP requests over the IoT messaging system. There are several reasons for wrapping an HTTP request into a request message:
- Asynchronous Messaging: Because devices may have their radio turned off for long periods of time and are therefore only occasionally connected, bundling an HTTP request into a message object allows the system to queue this request either on the server or on the client and send it when possible.
- Non-HTTP transport: Not all transport between the server and the clients will be over HTTP. It may be over SMTP when used with Iridium satellites, for example. However, it is desirable to maintain the semantics and nature of HTTP requests, even when the requests are used over other transports.
- Security: By requiring all HTTP requests to be routed through Oracle IoT Cloud Service, the service can validate each attempt to communicate between a device and any HTTP client (mobile, desktop, web).
A request message has the general capabilities of a normal HTTP request, including the URL, headers, and content. A request message includes the data that makes up an HTTP request, but does not fully implement the HTTP specification. However, for normal request/response patterns, the request message can be used as a typical HTTP request. These messages are used only in communications between a programmable device and Oracle IoT Cloud Service. These messages are not created or used by IoT enterprise applications that make HTTP requests. A web application (or mobile or desktop application) using the Endpoints API to GET/PUT/POST/DELETE a resource on a device will make a typical HTTP request. Oracle IoT Cloud Service internally converts this request into a request message and sends this message to the programmable device, which inspects the message and handles it appropriately. Likewise, if code on the programmable device needs to make an HTTP request (for example, to contact a 3rd party REST API), it creates a request message and sends this message to Oracle IoT Cloud Service, which converts it into a standard HTTP request against the target REST API. After it receives an HTTP response from the 3rd party, a response message is constructed and is sent to the programmable device to dispatch to the code that made the original request.
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
direction:
string
An optional field that specifies the direction of the messages that go through the Oracle IoT Cloud Service instance. Valid values are TO_DEVICE and FROM_DEVICE.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
REQUEST
object
A Resources Report message transfers information about resources that are supported by an endpoint to the Oracle IoT Cloud Service instance. The service instance contains information about all resources supported by endpoints. A Resources Report message must be sent to add resources to or remove resources from the Server Resource Directory.
This information synchronization is one-way. No information is sent back to the endpoint or Gateway, except when the service instance finds that the information about resources supported by an endpoint received in the Resources Report message differs from the information stored on the service instance. In this case, the service instance sends a Resource Reconciliation Request to the endpoint. If an endpoint receives a Resource Reconciliation Request, it must send a message with type RECONCILIATION to the service instance. The message must contain a complete list of resources that are available on the endpoint.
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
RESOURCES_REPORT
object
A response message is used to "tunnel" responses to request messages over the messaging system. A response message is always created as a response to a request message and maintains a reference to the message id of the request message to which it is responding.
A response message has the same structure as a normal HTTP response, including headers, status, and content. A response message includes the data that makes up an HTTP response, but it does not fully implement the HTTP specification. Response messages are only used in communications between programmable devices and Oracle IoT Cloud Service. These messages are not created or used by IoT enterprise web applications that make HTTP requests. A web application (or mobile or desktop application) that uses the Endpoints API to GET/PUT/POST/DELETE a resource on a device will make a normal HTTP request. Oracle IoT Cloud Service internally converts this request into a request message and sends this message to the programmable device, which inspects the message and handles it appropriately, returning a response message. This response is converted back into standard HTTP and is returned to the caller, either synchronously or asynchronously. See the Endpoints API for examples.
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
direction:
string
An optional field that specifies the direction of the messages that go through the Oracle IoT Cloud Service instance. Valid values are TO_DEVICE and FROM_DEVICE.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
RESPONSE
object
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
UPDATE_BUNDLE
object
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
UPDATE_BUNDLE_STATE
object
-
clientId:
string
An identifier assigned to the message by the client for tracking purposes.
-
destination:
string
The identifier of the endpoint to which the message is sent. This field is optional.
-
diagnostics(optional):
object diagnostics
An optional field that consists of a list of key-value pairs that provides diagnostic information.
-
direction(optional):
string
An optional field that specifies the direction of the messages that go through the Oracle IoT Cloud Service instance. Valid values are TO_DEVICE and FROM_DEVICE.
-
eventTime:
integer
The time that the event associated with the message occurred, as an epoch value in milliseconds. Most messages are generated as a result of an event that occurs in the system (for example, periodic recording of a sensor value, or an alert based on a sensor value).
-
eventTimeAsString(optional):
string
eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
id:
string
A universally unique identifier (UUID) assigned to a message by Oracle IoT Cloud Service when the message is received or created by Oracle IoT Cloud Service.
-
payload:
object payload
-
priority:
string
The priority level for the message. Valid values are LOWEST, LOW, MEDIUM, HIGH, and HIGHEST. The default priority is LOW. This field is not used by Oracle IoT Cloud Service.
-
properties:
object properties
An optional field that contains a list of properties in the form of key-value pairs, where the value itself is a collection of values. IoT devices or applications can use this field to send additional information (metadata) about the message to the applications that will consume the message.
-
receivedTime(optional):
integer
The time, in epoch milliseconds, when the messages are received by the Oracle IoT Cloud Service instance. The service instance stores this time when it persists the messages. This time is included as a part of the message when it is returned to an application by the service instance. Only applies to direction = FROM_DEVICE.
-
receivedTimeAsString(optional):
string
receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
reliability:
string
The delivery reliability for the message. Valid values are NO_GUARANTEE, BEST_EFFORT, and GUARANTEED_DELIVERY. The default value is BEST_EFFORT. This field is not used by Oracle IoT Cloud Service.
-
sender:
string
The identifier of the endpoint from which the message was sent.
-
sentTime(optional):
integer
The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
-
sentTimeAsString(optional):
string
sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
-
source:
string
Id of the endpoint that responded with the message. All messages must have a source endpoint id specified. This source is used to find the appropriate security policy to apply during dispatching.
-
type:
string
WAKEUP
object
object
-
data:
object data
The data field consists of a list of key-value pairs that define the alert data. The keys are always strings and the values could be any of following JSON types supports - String, Boolean and Numeric. All numeric values are internally treated as double. Note that Datetime value type is not directly supported. If Datetime value needs to be sent, it can be sent as a double value and later interpreted by the consumer as a long value corresponding to the epoch time in milliseconds.
-
description:
string
The description field contains the description of the alert event being sent in the message.
-
format:
string
The format field contains the URN of the format for the alert data being sent in the message. The format must be of ALERT type. The format essentially defines the structure of the data in terms of what keys would be part of the key-value pairs, which ones would be mandatory/optional keys and what type of values can be associated with those keys.
-
severity:
string
The severity field contains the level of severity for the alert being sent in the message. Valid values for the severity level are - "LOW", "NORMAL", "SIGNIFICANT" and "CRITICAL". If the value is not explicitly specified, then the default value assumed is - "SIGNIFICANT".
object
object
object
object
-
data:
object data
The data field consists of a list of key-value pairs that define the data. The keys are always strings and the values could be any of following JSON types supports - String, Boolean and Numeric. All numeric values are internally treated as double. Note that Datetime value type is not directly supported. If Datetime value needs to be sent, it can be sent as a double value and later interpreted by the consumer as a long value corresponding to the epoch time in milliseconds.
-
format:
string
The format field contains the URN of the format for the data being sent in the message. The format must be of DATA type. The format essentially defines the structure of the data in terms of what keys would be part of the key-value pairs, which ones would be mandatory/optional keys and what type of values can be associated with those keys. For example a format may define data captured by temperature sensor devices with keys "temperature" and "unit" and a temperature sensor might create a data message with values of "75" and "fahrenheit" for the keys temperature and unit respectively.
object
object
object
object
-
body(optional):
string
The body of the HTTP request. The value of this field must be base64 encoded binary. This payload is completely opaque to the cloud service, which simply packs and unpacks the data to bridge between real HTTP and messaging.
-
headers:
object headers
Represents HTTP headers. These are represented as a map of lists (since header values may be made up of multiple values). Even single-element header values are represented as an array.
-
method:
string
The HTTP request method, for example GET, PUT, POST, DELETE, PATCH.
-
params(optional):
object params
The query parameters. These are simple key/value pairs.
-
url:
string
The request URL, but without any query parameters.
object
object
-
key(optional):
string
-
value(optional):
object value
list of strings
object
object
object
object
object
-
endpointName:
string
Specifies the identifier of the endpoint.
-
reconciliationMark(optional):
string
Hash for resources available on client at moment of message generation. This hash value is being calculated as a MD5 hash value for lexicographicaly ordered list of pathes for all resources supported by the endpoint.
-
reportType:
string
Specifies the kind of Resources Report Message. Possible values are UPDATE, DELETE and RECONCILIATION.
-
resources:
array resources
A list of resources that are described by the message. This field is required for the UPDATE and RECONCILIATION report types, but it is not needed for the DELETE type. Each Resource object is represented by the following attributes:
- path: A URI path as defined in IETF 3986 Section 3.3: https://tools.ietf.org/html/rfc3986#section-3.3. Must be unique and must not be empty or null. For example, if this endpoint provides temperature information, it may be specified as /temperature.
- name: A human-readable description of the resource, which can be used by developers to understand how to interact with this resource.
- methods: An array of method names that are supported by the resource. The array can contain GET, PUT, POST, and DELETE.
- status: ADDED or REMOVED.
array
A list of resources that are described by the message. This field is required for the UPDATE and RECONCILIATION report types, but it is not needed for the DELETE type. Each Resource object is represented by the following attributes:
- path: A URI path as defined in IETF 3986 Section 3.3: https://tools.ietf.org/html/rfc3986#section-3.3. Must be unique and must not be empty or null. For example, if this endpoint provides temperature information, it may be specified as /temperature.
- name: A human-readable description of the resource, which can be used by developers to understand how to interact with this resource.
- methods: An array of method names that are supported by the resource. The array can contain GET, PUT, POST, and DELETE.
- status: ADDED or REMOVED.
object
-
endpointName:
string
The endpoint name or identifier for this resource.
-
methods:
string
Methods supported by the resource. Valid values include GET, POST, PUT, and DELETE.
-
name:
string
Resource name. This name should describe the resource in free form.
-
path:
string
Resource status. Possible values are ADDED and REMOVED.
-
status:
string
Path of the resource.
object
object
-
body:
string
The body of the HTTP response. The value of this field must be base64 encoded binary. This payload is completely opaque to the cloud service, which simply packs and unpacks the data to bridge between real HTTP and messaging.
-
headers:
object headers
Represents HTTP headers. These are represented as a map of lists (since header values may be made up of multiple values). Even single-element header values are represented as an array.
-
requestId:
string
The message id of the http request that this is a response for.
-
statusCode:
integer
The status code of the HTTP request method, such as "404" or "500".
-
url:
string
The request URL in the request message.
object
object
object
object
-
counter:
integer
Counter value is within the scope of one timestamp. To be used for proper state update ordering when multiple messages are created in single millisecond and thus not comparable by timestamps.
-
type:
string
JSON
-
value:
object value
object
object
-
bundle:
object BundleInfo
The BundleInfo represents an OSGi bundle installed on the system. It is used as a data type in several different message types related to software management.
object
-
headers:
array headers
Manifest headers. These may be implementation specific. For example, on an OSGi deployment, this method will return OSGi headers. On JavaME, you may see a different set of headers. Headers are simply key/value pairs of Strings.
-
id:
string
A unique identifier for a bundle on a specific gateway or device. The id of a bundle must not change when the bundle is updated, only if it is uninstalled and reinstalled. Every bundle must have an id. Ids are always non-negative. The "0" bundle may be reserved by the system (as it is in OSGi).
-
lastModified:
integer
Returns the timestamp that shows when the bundle was last modified.
-
location:
string
The URI supplied to the device at the time that the bundle was created. This must match exactly with the value stored in the cloud service.
-
name:
string
The name of the bundle (which we map to symbolic name for OSGi). This name may not be unique for all bundles deployed on a specific gateway or device, though the combination of name and version should be unique.
-
startLevel:
integer
The start level for this bundle. The start level should always be positive.
-
state:
string
The state for this bundle.
-
version:
string
The version of the bundle, using the OSGi version string format.
array
object
object
object
-
bundleId:
string
Bundle Id.
-
counter:
integer
Message order counter.
-
state:
string
State of the bundle.
object
object
object
-
counter:
integer(int32)
Message order counter
-
swVersion:
string
Gateway software version
-
type:
string
JSON
-
value:
object value
object
object
-
bundles:
array bundles
A BundleInfo object representing the complete new state of the Bundle that was updated.
array
-
Array of:
object BundleInfo
The BundleInfo represents an OSGi bundle installed on the system. It is used as a data type in several different message types related to software management.
object
-
href(optional):
string
Example:
https://iotserver/iot/api/vX/some/API/path
-
rel(optional):
string
Example:
canonical
400 Response
401 Response
404 Response
Examples
0-RYJQ
under Application
0-TMJQ
by submitting a GET request on the REST resource using cURL. For more information about cURL, see
Use cURL.
Note:
In the request and response,iotserver
will be replaced by name and port of your assigned Oracle IoT Cloud Service instance. The format of the Cloud Service instance is
myinstance-myidentitydomain.iot.us.oraclecloud.com
and the default port is
443.
curl -X GET -H 'Accept:application/json' -H 'Authorization: Basic aW90OndlbGNvbWUx' "http://iotserver:/iot/api/v2/apps/0-RYJQ/integrations/0-TMJQ/messages"
Example of Response Header
The following shows an example of the response header.
HTTP/1.1 200 OK Content-Type: application/json
Example of Response Body
The following example shows the contents of the response body containing the list of message format associations with explorations in JSON format.
{
"items":[
{
"id":"8f86bf0f-36b0-49a7-87b4-6ab34d072d68",
"clientId":"61e9811f-6331-413d-b193-e96f3566bfd0",
"source":"0-S4JQ",
"destination":"",
"priority":"LOW",
"reliability":"BEST_EFFORT",
"eventTime":1468526382104,
"eventTimeAsString":"2016-07-14T19:59:42Z",
"sender":"",
"type":"DATA",
"properties":{
},
"direction":"FROM_DEVICE",
"receivedTime":1468526382215,
"receivedTimeAsString":"2016-07-14T19:59:42Z",
"sentTime":1468526382282,
"sentTimeAsString":"2016-07-14T19:59:42Z",
"payload":{
"format":"urn:format:test:messagedeliverybyintegration:format:1:1468526374322",
"data":{
"msgText":"Test Messasge Text"
}
}
}
],
"hasMore":false,
"links":[
{
"href":"http://iotserver:7001/iot/api/v2/apps/0-RYJQ/integrations/0-TMJQ/messages",
"rel":"self"
},
{
"href":"http://iotserver:7001/iot/api/v2/apps/0-RYJQ/integrations/0-TMJQ/messages",
"rel":"canonical"
}
]
}