The following shows how to generate the iotectraffic-by-time report using either the Reporting API's Generate a report POST operation or the Get a cacheable report GET operation. Details about each report's supported products, metrics, filters, and available data intervals are also available dynamically by running the API's Get a report type operation, also shown below. See also other available reports.

Report definition

Provides traffic information on the messages published and received over HTTP and MQTT for a selected period of time that is no longer than 90 days.

This report allows you to configure the aggregation interval for each data record. Available interval values are: MONTH, WEEK, DAY, HOUR, FIVE_MINUTES.

Business object: cpcode

Data available for: 90 days

Required products: IoT Edge Connect

Available metrics

Metric	Description
Data metrics
`msgCount`	Messages traffic.
Summary metrics
`msgCountMax`	Maximum number of messages.
`msgCountMin`	Minimum number of messages.
`msgCountSlope`	Message count slope.
`msgCountTotal`	Total number of messages.
`msgSizeAvg`	Average single message size.
`msgSizeAvgSlope`	Average single message size.
`msgSizeMax`	Message volume maximum.
`msgSizeMin`	Message volume minimum.
`msgSizeSlope`	Message volume slope.
`msgSizeTotal`	Message volume.

Available filters

Filter	Type	Description
Optional filters
`jurisdictions`	Integer	A geographically distributed set of servers.
`msg_type`	Enumeration	Message type.
`namespaces`	Integer	A unique, user-defined identifier indicating a particular configuration.

POST request

POST /reporting-api/v1/reports/iotectraffic-by-time/versions/1/report-data{?start,end,interval}

Sample: /reporting-api/v1/reports/iotectraffic-by-time/versions/1/report-data?start=2020-06-26T13%3A40%3A00Z&end=2020-06-26T14%3A00%3A00Z&interval=FIVE_MINUTES

Query parameters

Parameter	Type	Sample	Description
Required
`start`	String	`2020-06-26T13:40:00Z`	Specifies the start of the reported period as an ISO-8601 timestamp with optional time zone. The report includes data that matches the `start` value's timestamp.
`end`	String	`2020-06-26T14:00:00Z`	Specifies the end of the reported period as an ISO-8601 timestamp with optional time zone. The report excludes any data that matches the `end` value's timestamp.
`interval`	Enumeration	`FIVE_MINUTES`	The duration of each data record. Available values: `MONTH`, `WEEK`, `DAY`, `HOUR`, `FIVE_MINUTES`.

JSON request members

Member	Type	Description
`objectIds`	Array	Specifies the set of `cpcode` values you want to report on.
`objectIds`	Enumeration	As an alternative to an array of ID values, specify `all` as a string for unfiltered data. Either way, `objectIds` is required.
`metrics`	Array	The set of desired metrics. If omitted, the report includes all available metrics.
`filters`	Map of Arrays	Specifies a set of custom filters, with each filter's name keying an array with each filter's set of values.

Request body:

{
    "objectIds": [
        "55232",
        "23433",
        "32433"
    ],
    "metrics": [
        "msgCount",
        "msgCountMax",
        "msgCountMin",
        "msgCountSlope",
        "msgCountTotal",
        "msgSizeAvg",
        "msgSizeAvgSlope",
        "msgSizeMax",
        "msgSizeMin",
        "msgSizeSlope",
        "msgSizeTotal"
    ],
    "filters": {
        "jurisdictions": [
            "0",
            "1"
        ],
        "msg_type": [
            "http_publish",
            "http_delivery"
        ],
        "namespaces": [
            "namespace_mqtt",
            "name1"
        ]
    }
}

GET request

GET /reporting-api/v1/reports/iotectraffic-by-time/versions/1/report-data{?start,end,interval,objectIds,allObjectIds,metrics,filters}

Sample: /reporting-api/v1/reports/iotectraffic-by-time/versions/1/report-data?start=2020-06-26T13%3A40%3A00Z&end=2020-06-26T14%3A00%3A00Z&interval=FIVE_MINUTES&objectIds=55232,23433,32433&metrics=msgCount%2CmsgCountMax&filters=jurisdictions%3D0%2Cjurisdictions%3D1%2Cmsg_type%3Dhttp_publish%2Cmsg_type%3Dhttp_delivery

Query parameters

Parameter	Type	Sample	Description
Required
`start`	String	`2022-06-23T13:55:00Z`	Specifies the start of the reported period as an ISO-8601 timestamp with optional time zone. The report includes data that matches the `start` value’s timestamp.
`end`	String	`2022-06-23T14:15:00Z`	Specifies the end of the reported period as an ISO-8601 timestamp with optional time zone. The report excludes any data that matches the `end` value’s timestamp.
`interval`	Enumeration	`FIVE_MINUTES`	The duration of each data record. Available values: `MONTH`, `WEEK`, `DAY`, `HOUR`, `FIVE_MINUTES`.
Optional
`allObjectIds`	Boolean	`true`	As an alternative to `objectIds`, enabling this generates a report that includes all IDs available for the `cpcode` objectType. This parameter is ignored if the request also specifies a set of objectIds.
`objectIds`	String	`55232,23433,32433`	As an alternative to `allObjectIds`, specifies the set of unique IDs for the `cpcode` objectType you want to report on, formatted as a comma-delimited list.
`metrics`	String	`msgCount,msgCountMax`	Specifies a comma-separated list of metrics to include in the report, otherwise all metrics if omitted. The set of available metrics depends on the type of report. URL-encode the entire value in the GET request.
`filters`	String	`jurisdictions=0,jurisdictions=1,msg_type=http_publish,msg_type=http_delivery`	Specifies criteria to filter the report's data. The set of available filters depends on the type of report. Separate each filter name and value with an equals (`=`) character, and separate various name/value pairs with commas (`,`). To specify more than one filter value, repeat the filter name. See the accompanying example for guidance. URL-encode the entire value in the GET request.

JSON response

Status 200 application/json

Response body:

{
    "metadata": {
        "name": "iotectraffic-by-time",
        "version": "1",
        "outputType": "FLAT",
        "groupBy": [
            "startdatetime"
        ],
        "interval": "FIVE_MINUTES",
        "start": "2020-06-26T13:40:00Z",
        "end": "2020-06-26T14:00:00Z",
        "availableDataEnds": null,
        "suggestedRetryTime": null,
        "rowCount": 4,
        "filters": [
            {
                "name": "jurisdictions",
                "values": [
                    "0",
                    "1"
                ]
            },
            {
                "name": "msg_type",
                "values": [
                    "http_publish",
                    "http_delivery"
                ]
            },
            {
                "name": "namespaces",
                "values": [
                    "namespace_mqtt",
                    "name1"
                ]
            }
        ],
        "columns": [
            {
                "name": "groupBy",
                "label": "startdatetime"
            },
            {
                "name": "msgCount",
                "label": "Messages Traffic"
            }
        ],
        "objectType": "cpcode",
        "objectIds": [
            "55232",
            "23433",
            "32433"
        ]
    },
    "data": [
        {
            "startdatetime": "2020-06-26T13:40:00Z",
            "msgCount": "225"
        },
        {
            "startdatetime": "2020-06-26T13:45:00Z",
            "msgCount": "4823"
        },
        {
            "startdatetime": "2020-06-26T13:50:00Z",
            "msgCount": "4930"
        },
        {
            "startdatetime": "2020-06-26T13:55:00Z",
            "msgCount": "2620"
        }
    ],
    "summaryStatistics": {
        "msgCountMax": {
            "value": "1257",
            "details": {}
        },
        "msgCountMin": {
            "value": "2915",
            "details": {}
        },
        "msgCountSlope": {
            "value": "3386",
            "details": {}
        },
        "msgCountTotal": {
            "value": "2968",
            "details": {}
        },
        "msgSizeAvg": {
            "value": "3518",
            "details": {}
        },
        "msgSizeAvgSlope": {
            "value": "1655",
            "details": {}
        },
        "msgSizeMax": {
            "value": "4563",
            "details": {}
        },
        "msgSizeMin": {
            "value": "2153",
            "details": {}
        },
        "msgSizeSlope": {
            "value": "310",
            "details": {}
        },
        "msgSizeTotal": {
            "value": "616",
            "details": {}
        }
    }
}

CSV response

Status 200 text/csv

Response Body:

#METADATA_START
name,iotectraffic-by-time
version,1
source,iotectraffic-by-time/versions/1
groupBy,startdatetime
start,2020-06-26T13:40:00Z
end,2020-06-26T14:00:00Z
interval,`FIVE_MINUTES`
availableDataEnds,
suggestedRetryTime,
rowCount,4
objectType,cpcode
objectIds,55232,23433,32433
jurisdictions,0,1
msg_type,http_publish,http_delivery
namespaces,namespace_mqtt,name1
#METADATA_END

#SUMMARYSTATISTICS_START
msgCountMax,1257
msgCountMin,2915
msgCountSlope,3386
msgCountTotal,2968
msgSizeAvg,3518
msgSizeAvgSlope,1655
msgSizeMax,4563
msgSizeMin,2153
msgSizeSlope,310
msgSizeTotal,616
#SUMMARYSTATISTICS_END

#COLUMNS_START
startdatetime,msgCount
#COLUMNS_END

#DATA_START
2020-06-26T13:40:00Z,225
2020-06-26T13:45:00Z,4823
2020-06-26T13:50:00Z,4930
2020-06-26T13:55:00Z,2620
#DATA_END

Get report details

This sample Get a report type operation gets the same information you need to run the iotectraffic-by-time report as provided in this reference documentation, but available dynamically to your API client application.

GET /reporting-api/v1/reports/iotectraffic-by-time/versions/1

Status 200 application/json

Response body:

{
    "name": "iotectraffic-by-time",
    "description": "Provides traffic information on the messages published and received over HTTP and MQTT for a selected period of time that is no longer than 90 days.",
    "businessObjectName": "cpcode",
    "version": 1,
    "status": "PUBLISHED",
    "deprecated": false,
    "timeBased": true,
    "outputType": "FLAT",
    "requiredProducts": [
        "IoT Edge Connect"
    ],
    "requiredRoles": [
        "DCP Read"
    ],
    "available": true,
    "metrics": [
        {
            "name": "msgCount",
            "description": "Messages traffic.",
            "label": "Messages Traffic",
            "unit": "COUNT",
            "summaryStatistic": false
        },
        {
            "name": "msgCountMax",
            "description": "Maximum number of messages.",
            "label": "Maximum Number of Messages",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgCountMin",
            "description": "Minimum number of messages.",
            "label": "Minimum Number of Messages",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgCountSlope",
            "description": "Message count slope.",
            "label": "Message Count Slope",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgCountTotal",
            "description": "Total number of messages.",
            "label": "Total Messages",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgSizeAvg",
            "description": "Average single message size.",
            "label": "Average Single Message Size",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgSizeAvgSlope",
            "description": "Average single message size.",
            "label": "Average Single Message Size",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgSizeMax",
            "description": "Message volume maximum.",
            "label": "Message Volume Maximum",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgSizeMin",
            "description": "Message volume minimum.",
            "label": "Message Volume Minimum",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgSizeSlope",
            "description": "Message volume slope.",
            "label": "Message Volume Slope",
            "unit": "COUNT",
            "summaryStatistic": true
        },
        {
            "name": "msgSizeTotal",
            "description": "Message volume.",
            "label": "Message Volume",
            "unit": "COUNT",
            "summaryStatistic": true
        }
    ],
    "groupOutlyingValues": {
        "enabled": false
    },
    "groupBy": [
        "startdatetime"
    ],
    "filters": [
        {
            "name": "msg_type",
            "type": "enum",
            "description": "Message type.",
            "values": [
                {
                    "value": "http_publish"
                },
                {
                    "value": "mqtt_delivery"
                },
                {
                    "value": "mqtt_publish"
                },
                {
                    "value": "http_delivery"
                }
            ],
            "required": false
        },
        {
            "name": "namespaces",
            "type": "int",
            "description": "A unique, user-defined identifier indicating a particular configuration.",
            "required": false
        },
        {
            "name": "jurisdictions",
            "type": "int",
            "description": "A geographically distributed set of servers.",
            "required": false
        }
    ],
    "intervals": [
        "MONTH",
        "WEEK",
        "DAY",
        "HOUR",
        "FIVE_MINUTES"
    ],
    "dataRetentionDays": 90,
    "links": [
        {
            "rel": "self",
            "href": "/reporting-api/v1/reports/iotectraffic-by-time/versions/1"
        },
        {
            "rel": "versions",
            "href": "/reporting-api/v1/reports/iotectraffic-by-time/versions"
        },
        {
            "rel": "all-reports",
            "href": "/reporting-api/v1/reports"
        },
        {
            "rel": "execute-report",
            "href": "/reporting-api/v1/reports/iotectraffic-by-time/versions/1/report-data"
        }
    ]
}