1. REST API for Oracle Internet of Things Cloud Service
  2. Tasks
  3. IoT Application Integration

Retrieve messages of a specified Integration in an Application specified by ID

get

/iot/api/v2/apps/{app-id}/integrations/{integration-id}/messages

Returns a list of device messages stored by Oracle IoT Cloud Service that match the query criteria. A query criterion can specify a device or a message type or both through query parameters "device" and "type". Messages are returned in descending order of message recorded time (either receivedTime or sentTime depending on type and direction of the message). The parameters "since" and "until" can be used with any query criteria. The "offset" and "limit" parameters are always applied. The "orderBy" parameter controls the sorting method. The "expand" parameter indicates whether the messages should include the message payload.

Request

Path Parameters
Query Parameters
  • 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".
  • The maximum number of results to return. The default value is 10, with a maximum of 200.
  • The offset from the start of the results to start returning results from. The default value is 0.
  • 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.
  • 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.
  • 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.
Header Parameters
  • The Authentication credentials for HTTP Basic authentication. The format is token_type access_token, where token_type is "Basic" and access_token is username:password encoded in Base64
Back to Top

Response

Supported Media Types

200 Response

OK. The response body consists of a list of zero or more message types, depending on the query parameters in the GET request.
Body ()
Root Schema : Message_receive_list
Type: object
Show Source
Nested Schema : items
Type: object
Show Source
  • ALERT
    ALERT messages are used to send urgent information such as error conditions and critical events, like threshold crossings.
  • 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

    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

    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.

  • 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
    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
    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
    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.
Nested Schema : ALERT
Type: object
ALERT messages are used to send urgent information such as error conditions and critical events, like threshold crossings.
Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • ALERT
Nested Schema : DATA
Type: object
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.
Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • DATA
Nested Schema : REQUEST
Type: 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.

Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • REQUEST
Nested Schema : RESOURCES_REPORT
Type: 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.

Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • RESOURCES_REPORT
Nested Schema : RESPONSE
Type: 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.

Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • RESPONSE
Nested Schema : UPDATE_BUNDLE
Type: object
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.
Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • UPDATE_BUNDLE
Nested Schema : UPDATE_BUNDLE_STATE
Type: object
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.
Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • UPDATE_BUNDLE_STATE
Nested Schema : WAKEUP
Type: object
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.
Show Source
  • An identifier assigned to the message by the client for tracking purposes.
  • The identifier of the endpoint to which the message is sent. This field is optional.
  • diagnostics
    An optional field that consists of a list of key-value pairs that provides diagnostic information.
  • 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.
  • 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).
  • eventTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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
  • 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
    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.
  • 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.
  • receivedTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • The identifier of the endpoint from which the message was sent.
  • The time, in epoch milliseconds, when the message was sent by the Oracle IoT Cloud Service instance. Only applies to direction = TO_DEVICE.
  • sentTime as a string value in ISO 8601 UTC Date format. Only messages retrieved from IOTCS have this property.
  • 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.
  • WAKEUP
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
  • 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.
  • The description field contains the description of the alert event being sent in the message.
  • 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.
  • 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".
Nested Schema : properties
Type: object
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.
Nested Schema : data
Type: object
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.
Show Source
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
  • 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.
  • 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.
Nested Schema : properties
Type: object
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.
Nested Schema : data
Type: object
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.
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
  • 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
    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.
  • The HTTP request method, for example GET, PUT, POST, DELETE, PATCH.
  • params
    The query parameters. These are simple key/value pairs.
  • The request URL, but without any query parameters.
Nested Schema : properties
Type: object
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.
Nested Schema : headers
Type: object
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.
Show Source
Nested Schema : params
Type: object
The query parameters. These are simple key/value pairs.
Nested Schema : value
Type: object
list of strings
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
Nested Schema : properties
Type: object
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.
Nested Schema : value
Type: object
Show Source
  • Specifies the identifier of the endpoint.
  • 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.
  • Specifies the kind of Resources Report Message. Possible values are UPDATE, DELETE and RECONCILIATION.
  • 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.
Nested Schema : resources
Type: 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.
Show Source
Nested Schema : resource
Type: object
Show Source
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
  • 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
    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.
  • The message id of the http request that this is a response for.
  • The status code of the HTTP request method, such as "404" or "500".
  • The request URL in the request message.
Nested Schema : properties
Type: object
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.
Nested Schema : headers
Type: object
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.
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
Nested Schema : properties
Type: object
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.
Nested Schema : value
Type: object
Show Source
  • 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.
Nested Schema : BundleInfo
Type: object
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.
Show Source
  • 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.
  • 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).
  • Returns the timestamp that shows when the bundle was last modified.
  • 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.
  • 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.
  • The start level for this bundle. The start level should always be positive.
  • The state for this bundle.
  • The version of the bundle, using the OSGi version string format.
Nested Schema : headers
Type: array
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.
Show Source
Nested Schema : items
Type: object
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
Nested Schema : properties
Type: object
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.
Nested Schema : diagnostics
Type: object
An optional field that consists of a list of key-value pairs that provides diagnostic information.
Nested Schema : payload
Type: object
Show Source
Nested Schema : properties
Type: object
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.
Nested Schema : value
Type: object
Show Source
Nested Schema : bundles
Type: array
A BundleInfo object representing the complete new state of the Bundle that was updated.
Show Source
  • 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.

400 Response

Bad Request. This error is returned if the query parameters are invalid.

401 Response

Unauthorized. This error is returned if the access token is not valid or has expired.

404 Response

Not Found. This error is returned if the application id or integration id is not found.
Back to Top

Examples

The following example shows how to get a list of messages associated with Integration 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"
      }
   ]
}
Back to Top