REST API for Oracle Internet of Things Cloud Service

Retrieve Device Count

get

/iot/api/v2/monitoring/metrics/registeredDeviceCount

Returns the total number of devices in the Registered, Activated, and temporarily Disabled states. A device is in the Registered state if it has been registered with the Service Instance. A device is in the Activated state if it has been authenticated and can participate in the service network to the extent permitted by the associated device policy. A device is in the Disabled state if it is temporarily barred from participation in the service network. A GET request, without any query parameters, returns data for last 24 hours at an hourly granularity,including the cumulative number of registered device count for the current hour with the most accurate real time data. Query parameters can be specified to change the data granularity to daily or monthly or to a specified time frame or number of data points.

Request

Query Parameters

limit(optional): integer(int32)

Overrides the default number of data points returned. It works as a multiplier for the period value specified. For example, if the period is set to Hourly, the toDate is set to 2015-04-09T08:00:00Z, and the count is set to 5, hourly data for 5 hours ending at 0800 hours on 9th April, 2015 is returned.
orderBy(optional): string

Orders the data returned as per the key-value pairs specified. The key "dateTime" (case-sensitive) can be specified to order the results by their Timestamp. The corresponding value for the keys can be "asc" or "desc" (both case-sensitive) for ascending and descending order respectively. If not specified, the default value is taken as "asc".
period(optional): string

Specifies the granularity of the period of time for which information is sought. The period can be Hourly, Daily, or Monthly (case insensitive). The default value is Hourly.
If you set the period to Hourly, the last 24 hours of data are returned at an hourly granularity. The data returned is at clock hour granularity (for example, data is returned for 01:00 hours, 00:00 hours, and so on).
If you set the period to Daily, the last 30 days of data are returned at a daily granularity. The data returned is at a calendar day granularity (for example, data is returned for an entire day, computed at an early hour of the next day). The timestamp signifies the hour when the daily information was created by the aggregation of the entire day's data. Typically, the timestamp is an early hour of the following day. For example, "dateTimeAsString":"2015-06-01T00:00:00-07:00" implies that the data is from May 31, 2015. If the current day is not yet completed, the data returned is an aggregation of the number of hours that elapsed in that day; "dateTimeAsString" contains the most recent of hour of the day.
To ensure that hourly aggregations complete before the daily data is aggregated, the daily aggregation happens at 01:00 hours every day.
If you set the period to Monthly, the last 12 months of data are returned at a monthly granularity. The data returned is at a calendar month granularity (for example, data is returned for the month of January, February, and so on). The timestamp signifies the time when the information was aggregated. For example, dateTimeAsString:"2015-05-01T00:00:00-07:00" implies that the data is for the month of April, 2015. If the current month is not yet completed, the data returned is an aggregation of the number of hours that have elapsed in the month; "dateTimeAsString" contains the most recent hour of the month.
To ensure that daily aggregations complete before the monthly data is aggregated, the monthly aggregation happens at 02:00 hours on the first day of a new calendar month.
since(optional): string

Specifies the start of the period for which information is sought, as an ISO-8601 formatted date string or epoch value. If this value is set to a time before the data collection has started, information will be returned only for the period from which data is available in the system.
until(optional): string

Specifies the end of the period for which information is sought, as an ISO-8601 formatted date string or epoch value. If this value is set to a time in the future, information will be returned only for the period up to the current time.

Response

Supported Media Types

application/json

200 Response

Root Schema : DateTimeValueList

Type: object

List of metrics records

Show Source

items(optional): array items

Array of datetime and metric value
links(optional): array links

{
    "type":"object",
    "description":"List of metrics records",
    "properties":{
        "items":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/DateTimeValue"
            },
            "description":"Array of datetime and metric value"
        },
        "links":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/Link"
            }
        }
    }
}

Nested Schema : items

Type: array

Array of datetime and metric value

Show Source

Array of: object DateTimeValue

Date, time and value

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/DateTimeValue"
    },
    "description":"Array of datetime and metric value"
}

Nested Schema : links

Type: array

Show Source

Array of: object Link

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/Link"
    }
}

Nested Schema : DateTimeValue

Type: object

Date, time and value

Show Source

dateTime(optional): integer(int64)

Specifies the datetime as int
dateTimeAsString(optional): string(date-time)

Date Time as String

Example: 2015-01-29T13:37:26Z
value(optional): integer(int32)

Metric data up to the time period of DateTimeValue from DateTimeValue of the previous object or up to the DateTimeValue if count is 1.

{
    "type":"object",
    "description":"Date, time and value",
    "properties":{
        "dateTimeAsString":{
            "type":"string",
            "format":"date-time",
            "example":"2015-01-29T13:37:26Z",
            "description":"Date Time as String"
        },
        "dateTime":{
            "type":"integer",
            "format":"int64",
            "description":"Specifies the datetime as int"
        },
        "value":{
            "type":"integer",
            "format":"int32",
            "description":"Metric data up to the time period of DateTimeValue from DateTimeValue of the previous object or up to the DateTimeValue if count is 1."
        }
    }
}

Nested Schema : Link

Type: object

Show Source

href(optional): string

Example: https://iotserver/iot/api/v2/monitoring/metrics/test
rel(optional): string

Example: canonical

{
    "properties":{
        "rel":{
            "type":"string",
            "example":"canonical"
        },
        "href":{
            "type":"string",
            "example":"https://iotserver/iot/api/v2/monitoring/metrics/test"
        }
    }
}

401 Response

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

403 Response

Forbidden. This error is returned if the operation is not allowed for the request.

Examples

The following examples show how to view the number of registered, activated, and disabled devices for the IoT Cloud Service instance using various query parameters 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.

Example 1

The following examples show how to view the total number of processed messages for the IoT Cloud Service instance using cURL. Enter the following command in a single line.

curl -X GET -k -H 'Accept: application/json'-u username@example.com:passowrd http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount

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 in JSON format.

{
    "items":[
        {
            "dateTimeAsString":"2016-07-18T10:49:00Z",
            "dateTime":"1468838940964",
            "value":"3000"
        },
        ...
        {
            "dateTimeAsString":"2016-07-17T12:30:00Z",
            "dateTime":"1468758600000",
            "value":"500"
        }
    ],
    "links":[
        {
            "rel":"canonical",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/processedMessageCount"
        },
        {
            "rel":"self",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/processedMessageCount"
        }
    ]
}

Example 2

The following example shows how to view number of registered, activated, and disabled devices for the Cloud Service instance using query parameter period by submitting a GET request on the REST resource using cURL.

The query parameter specifies the granularity of the period of time for which information is sought. The period can be hourly, daily, or monthly (case insensitive). The default value is hourly.

If you set the period to hourly, the last 24 hours of data are returned at an hourly granularity. The data returned is at clock hour granularity (for example, data is returned for 01:00 hours, 00:00 hours, and so on).

If you set the period to daily, the last 30 days of data are returned at a daily granularity. The data returned is at a calendar day granularity (for example, data is returned for an entire day, computed at an early hour of the next day). The timestamp signifies the hour when the daily information was created by the aggregation of the entire day's data. Typically, the timestamp is an early hour of the following day. For example, "dateTimeAsString":"2015-06-01T00:00:00-07:00" implies that the data is from May 31, 2015. If the current day is not yet completed, the data returned is an aggregation of the number of hours that elapsed in that day; dateTimeAsString contains the most recent of hour of the day.

To ensure that hourly aggregations complete before the daily data is aggregated, the daily aggregation happens at 01:00 hours every day. If you set the period to monthly, the last 12 months of data are returned at a monthly granularity. The data returned is at a calendar month granularity (for example, data is returned for the month of January, February, and so on).

The timestamp signifies the time when the information was aggregated. For example, dateTimeAsString:"2015-05-01T00:00:00-07:00" implies that the data is for the month of April, 2015. If the current month is not yet completed, the data returned is an aggregation of the number of hours that have elapsed in the month; "dateTimeAsString" contains the most recent hour of the month.

To ensure that daily aggregations complete before the monthly data is aggregated, the monthly aggregation happens at 02:00 hours on the first day of a new calendar month.

curl -X GET -k -H 'Accept: application/json' -u username@example.com:password http://iotserver/iot/api/v2/monitoring/monitoring/metrics/registeredDevicedCount?period=daily

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 in JSON format.

{
    "items":[
        {
            "dateTimeAsString":"2016-07-20T04:19:01Z",
            "dateTime":"1468988341999",
            "value":"5000"
        },
        ...
        {
            "dateTimeAsString":"2016-07-19T18:30:00Z",
            "dateTime":"1466533800000",
            "value":"2000"
        }
    ],
    "links":[
        {
            "rel":"canonical",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        },
        {
            "rel":"self",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        }
    ]
}

Example 3

The following example shows how to view number of registered, activated, and disabled devices for the Service Instance using query parameter orderBy by submitting a GET request on the REST resource using cURL.

The data returned is ordered as per the key-value pairs specified. The key dateTime (case-sensitive) can be specified to order the results by their Timestamp. The corresponding value for the keys can be asc or desc (both case-sensitive) for ascending and descending order respectively. If not specified, the default value is taken as asc.

curl -X GET -k -H 'Accept: application/json' -u username@example.com http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount?orderBy=dateTime:asc

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 in JSON format.

{
    "items":[
        {
            "dateTimeAsString":"2016-07-19T00:30:00Z",
            "dateTime":"1468888200000",
            "value":"3000"
        }
        ...
        {
            "dateTimeAsString":"2016-07-20T05:43:43Z",
            "dateTime":"1468993423226",
            "value":"500"
        }
    ],
    "links":[
        {
            "rel":"canonical",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        },
        {
            "rel":"self",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        }
    ]
}

Example 4

The following example shows how to view number of registered, activated, and disabled devices for the Service Instance using query parameter since and until by submitting a GET request on the REST resource using cURL.

The meaning of the two parameters are as follows:

since: Specifies the start of the period for which information is sought, as an ISO-8601 formatted date string or epoch value. If this value is set to a time before the data collection has started, information will be returned only for the period from which data is available in the system.

until: Specifies the end of the period for which information is sought, as an ISO-8601 formatted date string or epoch value. If this value is set to a time in the future, information will be returned only for the period up to the current time.

curl -X GET -k -H 'Accept: application/json' -u username@example.com http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount?since=1469428200000&until=1469441751129

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 in JSON format.

{
    "items":[
        {
            "dateTimeAsString":"2016-07-19T00:30:00Z",
            "dateTime":"1468888200000",
            "value":"3000"
        },
        ...
        {
            "dateTimeAsString":"2016-07-20T05:43:43Z",
            "dateTime":"1468993423226",
            "value":"500"
        }
    ],
    "links":[
        {
            "rel":"canonical",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        },
        {
            "rel":"self",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        }
    ]
}

Example 5

The following example shows how to view number of registered, activated, and disabled devices for the Service Instance using query parameter limit by submitting a GET request on the REST resource using cURL.

The response over-rides the default number of data points returned. It works as a multiplier for the period value specified. For example, if the period is set to Hourly, the until is set to 2015-04-09T08:00:00Z, and the limit is set to 5, hourly data for 5 hours ending at 0800 hours on 9th April, 2015 is returned.

curl -X GET -k -H 'Accept: application/json' -u username@example.com http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount?limit=2

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 in JSON format.

{
    "items":[
        {
            "dateTimeAsString":"2016-07-20T05:47:15Z",
            "dateTime":"1468993635632",
            "value":"3000"
        },
        {
            "dateTimeAsString":"2016-07-20T05:30:00Z",
            "dateTime":"1468992600000",
            "value":"2000"
        }
    ],
    "links":[
        {
            "rel":"canonical",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        },
        {
            "rel":"self",
            "href":"http://iotserver/iot/api/v2/monitoring/metrics/registeredDeviceCount"
        }
    ]
}