1. REST API for Oracle Internet of Things Cloud Service
  2. Tasks
  3. Messages

Send Messages

post

/iot/api/v2/messages

Devices connected to the Internet, such as Gateways, post to this URL. These devices send messages and receive, in the response, messages intended for them, or for them to distribute to indirectly connected devices. Messages are sent as an array of JSON objects. A type field identifies the type of each message. Messages in a single request/response can be from different endpoints and can have different endpoints as their destinations. Any request can include multiple messages to be sent.

If any message fails (for example, if it can't be parsed correctly or if it lacks mandatory attributes), the entire batch of messages is rejected.

Each connection is authenticated with a token that is provided by the OAuth server. If a message fails because of a security violation (for example, if the message was not authorized to be sent to the destination), the request itself doesn't fail, but error handling is instead managed on the server. This allows the connection to be closed as quickly as possible while messages are processed.

This resource can only be called by endpoints registered with the system as programmable devices. Any physical device registered with Oracle IoT Cloud Service as a programmable device can invoke this API. Any message type can be sent from a programmable device to Oracle IoT Cloud Service.

The response could contain all the pending messages for the device itself and all indirectly connected devices to it.

Messages are sent by either Devices or Explorations. Messages sent by Devices are mapped to IoT Applications. The mapping is specified by the "sender" field and the "format" field in payload, and the message is then consumed by Enterprise Integrations or IoT Analytics that are interested in the format.

Request

Supported Media Types
Query Parameters
  • The maximum number of bytes to return. This prevents the server from sending too many messages exceeding a device's memory.
Header Parameters
  • The acceptable compression method for response. Valid values are "gzip" and "deflate". If not specified, the uncompressed content will be returned.
  • The OAuth2 Bearer token obtained from the Authentication API, where scope is empty and issuer is the directly connected device or the gateway for indirectly connected devices. The format is token_type access_token.
  • The compression method used for sending the request payload. Valid values are "gzip" and "deflate". The header is applied only if Content-Type is set to "application/json". Otherwise, an "Unsupported Media Type" error will be returned. If not specified, the uncompressed content will be sent.
  • Id of the Endpoint making the request.
Body ()
Supported message types
Root Schema : schema
Match All
Show Source
  • 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.
  • ALERT
    ALERT messages are used to send urgent information such as error conditions and critical events, like threshold crossings.
  • 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.

  • 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.
  • 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.

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 : 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 : 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 : 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 : 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 : 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
  • 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
  • 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
  • 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.
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
Back to Top

Response

Supported Media Types

202 Response

Accepted
Headers
  • The minimum number of bytes of a message. This is a hint by the IoT Service to the device about minimum value that can be used for "acceptBytes" query parameter in order to successfully retrieve the next pending message for the device.
Body ()
Root Schema : schema
Match All
Show Source
  • 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.

  • 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.

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 : 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 : 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
  • 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.

400 Response

Bad Request. This error is returned if incoming messages cannot be parsed or if the message structure is invalid.

401 Response

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

415 Response

Unsupported Media Type. This error is returned if the message type is invalid.
Back to Top

Examples

Example 1

The following example shows how to send a DATA message from Device 0-QMCA by submitting a POST request on the REST resource using cURL. Note that the device needs to be activated before making the call, and a Bearer token 2a0f612af58944f2e4acde4ac18957be is obtained from calling the Authentication API, where issuer is the Device 0-QMCA and scope is empty.

Note that in both request and response, iotserver will be replaced by the 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.

Example of Request 

POST http://iotserver/iot/api/v2/messages

Accept:application/json 
Authorization: Bearer 2a0f612af58944f2e4acde4ac18957be
Content-Type: application/json
X-EndpointId: 0-QMCA
[   
   {   
      "clientId":"c839d086-bb23-4cd3-8405-130f5fc92b5b",
      "source":"0-QMCA",
      "destination":"",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1453427902124,
      "sender":"",
      "type":"DATA",
      "properties":{   

      },
      "payload":{   
         "format":"urn:format:test:messagedeliverytoapps:format:_608232f1",
         "data":{   
            "msgText":"Test Messasge Text"
         }
      }
   }
]

Example of cURL Command

For more information about cURL, see Use cURL 
curl -X POST -H 'Content-Type: application/json' 
-H 'Accept:application/json' 
-H 'Authorization: Bearer afdc12c3259f8d2b45a11106de774bba'
-H 'X-EndpointId: 0-QMCA'
http://iotserver/iot/api/v2/messages
-d '[
   {
      "clientId":"c839d086-bb23-4cd3-8405-130f5fc92b5b",
      "source":"0-QMCA",
      "destination":"",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1453427902124,
      "sender":"",
      "type":"DATA",
      "properties":{

      },
      "payload":{
         "format":"urn:oracle:iot:device:data:thermometer",
         "data":{
            "temperature":70
         }
      }
   }
]'

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 202 Accepted
Content-Type: application/json

Example of Response Body

The following example shows the contents of the response body containing the pending messages for Device 0-QMCA in JSON format 

[
   {
      "id":"5dd56375-f6a0-4e65-8eb2-c9f34174b8dd",
      "clientId":"4d98ad5b-9e86-4fba-ab18-59e94965f8d8",
      "source":"$UBSYS-1",
      "destination":"0-QMCA",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1442966246897,
      "sender":"",
      "type":"REQUEST",
      "properties":{

      },
      "direction":"TO_DEVICE",
      "sentTime":1442966251886,
      "payload":{
         "method":"post",
         "url":"/manage/resources/",
         "headers":{

         },
         "params":{

         },
         "body":"eyJlbmRwb2ludE5hbWUiOiIwLVlZTkEiLCJzdGF0dXMiOiJPSyJ9"
      }
   },
   {
      "id":"2d3cbcb4-0106-4328-94ee-f7b2cfe0d084",
      "clientId":"37e6f83c-a0e7-401b-a1a5-f72a30368a4d",
      "source":"$UBSYS-1",
      "destination":"0-QMCA",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1442966246902,
      "sender":"",
      "type":"REQUEST",
      "properties":{

      },
      "direction":"TO_DEVICE",
      "sentTime":1442966251886,
      "payload":{
         "method":"post",
         "url":"/manage/resources/",
         "headers":{

         },
         "params":{

         },
         "body":"eyJlbmRwb2ludE5hbWUiOiIwLVlZTkEiLCJzdGF0dXMiOiJPSyJ9"
      }
   }
]

Example 2

The following example shows how to send a DATA message from Indirectly Connected Device 0-AACA via Gateway 0-7UBQ (set in the X-EndpointId header) by submitting a POST request on the REST resource using cURL.

Note that the gateway needs to be activated before making the call, and a bearer token 83e9099e5a9775e7081007d0cd46e6e9 is obtained by calling the Authentication API, where the issuer is the Gateway 0-7UBQ and the scope is empty.

Example of cURL Command

For more information about cURL, see Use cURL 
curl -X POST -H 'Content-Type: application/json' 
-H 'Accept:application/json' 
-H 'Authorization: Bearer 83e9099e5a9775e7081007d0cd46e6e9 '
-H 'X-EndpointId: 0-7UBQ'
http://iotserver/iot/api/v2/messages
-d '[
   {
      "clientId":"1fc1adee-45ab-481f-a20b-07e5f2dab35f",
      "source":"0-AACA",
      "destination":"",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1465342031146,
      "sender":"",
      "type":"DATA",
      "properties":{

      },
      "payload":{
         "format":"urn:format:test:messageresourcev2:14671596378",
         "data":{
            "msgText": "hello"
         }
      }
   }
]'

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 202 Accepted
Content-Type: application/json

Example of Response Body

The following example shows the contents of the response body containing the pending messages for Device 0-AACA in JSON format 

[
   {
      "id":"5dd56375-f6a0-4e65-8eb2-c9f34174b8dd",
      "clientId":"1fc1adee-45ab-481f-a20b-07e5f2dab35f",
      "source":"$UBSYS-1",
      "destination":"0-AACA",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1465342031146,
      "sender":"",
      "type":"REQUEST",
      "properties":{

      },
      "direction":"TO_DEVICE",
      "sentTime":1442966251886,
      "payload":{
         "method":"post",
         "url":"/manage/resources/",
         "headers":{

         },
         "params":{

         },
         "body":"eyJlbmRwb2ludE5hbWUiOiIwLVlZTkEiLCJzdGF0dXMiOiJPSyJ9"
      }
   },
   {
      "id":"2d3cbcb4-0106-4328-94ee-f7b2cfe0d084",
      "clientId":"1fc1adee-45ab-481f-a20b-07e5f2dab35f",
      "source":"$UBSYS-1",
      "destination":"0-AACA",
      "priority":"LOW",
      "reliability":"BEST_EFFORT",
      "eventTime":1442966246902,
      "sender":"",
      "type":"REQUEST",
      "properties":{

      },
      "direction":"TO_DEVICE",
      "sentTime":1442966251886,
      "payload":{
         "method":"post",
         "url":"/manage/resources/",
         "headers":{

         },
         "params":{

         },
         "body":"eyJlbmRwb2ludE5hbWUiOiIwLVlZTkEiLCJzdGF0dXMiOiJPSyJ9"
      }
   }
]
Back to Top