Telemetry Data

When we talk about telemetry, we refer to the real-time collection and transmission of data measured by sensors installed on various machines and devices. This section explains how to obtain telemetry information for the selected machine or plant.

/apis/telemetry/<assetId>

GET Method

By invoking this endpoint using the HTTP GET method, you can retrieve the list of all available telemetry variables for the selected machine, and optionally the sub-machine.

Request

HTTP
GET https://{BASE_URL}/apis/telemetry/<assetId>

where:

assetId : ID of the machine to consider.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

subAssetId : ID of the sub-machine to consider. This field can be omitted if the asset being considered is not a multi-machine system.

Note that a variable is defined as a telemetry variable when it represents a descriptive parameter of the machine and tracks its changes in real time. This category includes variables such as temperatures, speeds, pressures, etc. Each variable is identified by the name of the table where it is recorded, followed by the name of the variable itself, in the format "tableName.variableName". This unique identifier can be used when invoking the endpoint with the POST method within the parameter named "variableName".

Example

Request

HTTP
GET https://matdev.40mat.com/apis/telemetry/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

An example response for the request mentioned above is provided below. Each key in the object represents the unique identifier for a variable, and the associated value contains a series of supplementary information, such as the unit of measurement for that variable and its meaning. The values returned in this call can indeed be used in the "variableName" key when invoking the endpoint with the POST method.

Response

JSON
{
    "rawData_M1.var_M1_0": {
        "id": "rawData_M1.var_M1_0",
        "meaning": "Motor 1 - Temperature",
        "measurement_unit": "°C"
    },
    "rawData_M1.var_M1_1": {
        "id": "rawData_M1.var_M1_1",
        "meaning": "Motor 1 - Current",
        "measurement_unit": "A"
    },
    "rawData_M1.var_M1_10": {
        "id": "rawData_M1.var_M1_10",
        "meaning": "Motor 3 - Temperature",
        "measurement_unit": "°C"
    },
    "rawData_M1.var_M1_11": {
        "id": "rawData_M1.var_M1_11",
        "meaning": "Motor 3 - Current",
        "measurement_unit": "A"
    },
    ...
}

Code

import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/telemetry/{myAssetId}'
url = f'https://{myDomain}{endpoint}'


# Make the POST request
response = requests.get(url, headers=headers, )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)

OpenAPI

get

This endpoint returns data about all the telemetry variables available for the specified machine. If a submachine is specified, the telemetry variables will pertain to that specific submachine.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

assetIdstringRequired

Query parameters

subAssetIdstringOptional

Sub-machine ID. If the machine for which the assetId has been specified is a multi-machine, then this field must always be specified as well.

Responses

200

An object with all the variable names and info about their meaning

application/json

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

get

/apis/telemetry/{assetId}

GET /apis/telemetry/{assetId} HTTP/1.1
Host: localhost:3001
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "rawData_M1.var_M1_0",
  "measurement_unit": "°C",
  "meaning": "Temperature of the Motor 1."
}

POST Method

The POST method of the /apis/telemetry endpoint can be used to retrieve the value of a specified telemetry variable. In addition to obtaining the current value of the variable, it is also possible to retrieve its historical trend, either in its original form or as an averaged value.

Request

HTTP
POST https://{BASE_URL}/apis/telemetry/<assetId>

where:

assetId : ID of the sub-machine to consider.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

subAssetId : ID of the sub-machine to consider. This field can be omitted if the asset being considered is not a multi-machine system.

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-10T14:00:00.000Z",
    "resampleBy": "unique",
    "limit": null,
    "calendar": 0,
    "autoResample": 0
}

The parameters that can be specified in the body of the request are as follows:

variableName: this parameter allows you to specify the name of the variable for which you want to retrieve data. If you do not know the variable name, you can retrieve all available variables by invoking this same endpoint using the HTTP GET method. This field can also be a list of strings, where each string represents a variable for which data is being requested;
resampleBy: this parameter allows you to define the frequency with which to calculate the specified variable. The allowed values for this parameter are listed below. If a value is specified, the data will be averaged over that time interval and returned to the user, averaged for each resample unit within the selected interval. For example, if an entire day is requested with a resample of '1h', then 24 values will be returned, each representing the average of the values recorded in the respective hour. The allowed values for this field are:
- unique: this parameter indicates that you want to obtain a single numerical value calculated over the entire interval;
- {n}m: allows the variable to be calculated with a frequency of {n} minutes over the selected interval;
- {n}h: allows the variable to be calculated with a frequency of {n} hours over the selected interval;
- {n}d: allows the variable to be calculated with a frequency of {n} days over the selected interval;
- {n}w: allows the variable to be calculated with a frequency of {n} weeks over the selected interval.
from: the starting point from which you want to begin calculating the data, expressed in UTC in the format "YYYY-MM-DDThh:mm .sssZ" (ISO 8601 Standard);
to: the endpoint of the interval for which you want to calculate the data, expressed in UTC in the format "YYYY-MM-DDThh:mm .sssZ" (ISO 8601 Standard). If this field is omitted or set to null, it will automatically be set to the current time of the request;
limit: this numeric field allows you to specify a maximum number of rows of data to return. If you imagine the data as being written in tables, a "limit" operation allows you to take the last {n} rows of the table. Specifically, "limit" refers to the most recent rows written in the table. If the "resampleBy" field is present, then "limit" will be ignored and will have no effect. Additionally, this field can be used in various ways:
- "limit" without "from" and "to": the last {n} rows written in the table, or more generally, the last {n} data points available, will be retrieved;
- "limit" with "from" and without "to": the behavior in this case is the same as the previous one. The last {n} data points available will be returned;
- "limit" with "from" and with "to": in this case, the last {n} rows of data will be returned, taking the "to" field as the endpoint of the interval. The data will be the last ones written before the time specified in the "to" field;
- "limit" with "to" and without "from": this option is not allowed and will result in an error;
calendar : boolean value indicating whether the calendar should be considered in data analysis. By default, this value is set to false;
autoResample : a boolean that allows the application to automatically calculate a sensible time-based resample for the data.

When requesting a time interval, please note the following: a telemetry variable can be recorded in the table at a very high frequency. Requesting a large time interval for a variable recorded at a high frequency results in a large amount of data being requested, which may not be manageable by all the services involved in the operation. To reduce the amount of data requested, consider narrowing the requested interval or introducing resampling operations.

Example - resampleBy

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "resampleBy": "unique",
    "from": "2024-05-15T22:00:00.000Z",
    "to": "2024-05-16T21:59:59.999Z"
}

In this example, the goal is to obtain the average value of the variable rawData_M1.var_M1_0 during the day of May 16th. To achieve this, in addition to specifying the correct time interval in UTC, a "unique" resample is requested, meaning a single value is calculated for the variable over the entire interval.

The result is shown below:

Response

JSON
{
    "rawData_M1.var_M1_0": 57.89241823769205
}

If, instead, you wanted to obtain the trend of the variable over time, averaging the result hourly, the request should be as follows:

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "resampleBy": "1h",
    "from": "2024-05-15T22:00:00.000Z",
    "to": "2024-05-16T21:59:59.999Z"
}

The main difference compared to the previous example is the value associated with the "resampleBy" field, which is now set to one hour. As shown in the response below, a value is associated with each hour of the day.

Response

JSON
[
    {
        "_time": "2024-05-16T00:00:00.000",
        "rawData_M1.var_M1_0": 58.95226562063767
    },
    {
        "_time": "2024-05-16T01:00:00.000",
        "rawData_M1.var_M1_0": 59.49487390503822
    },
    {
        "_time": "2024-05-16T02:00:00.000",
        "rawData_M1.var_M1_0": 58.83312622172578
    },
    {
        "_time": "2024-05-16T03:00:00.000",
        "rawData_M1.var_M1_0": 60.979092228673515
    },
    {
        "_time": "2024-05-16T04:00:00.000",
        "rawData_M1.var_M1_0": 49.26877890133155
    },
    ...
]

Another example involves requesting the trend of the value exactly as it is written in the table, without performing any resampling. Since the write frequency in the table is very high, the requested time interval is reduced in the example.

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "from": "2024-05-16T10:00:00.000Z",
    "to": "2024-05-16T11:00:00.000Z"
}

The response is as follows.

Response

JSON
[
    {
        "_time": "2024-05-16T12:00:00.106",
        "rawData_M1.var_M1_0": 55.20000076293945
    },
    {
        "_time": "2024-05-16T12:00:00.306",
        "rawData_M1.var_M1_0": 55.20000076293945
    },
    {
        "_time": "2024-05-16T12:00:00.506",
        "rawData_M1.var_M1_0": 55.20000076293945
    },
    {
        "_time": "2024-05-16T12:00:00.706",
        "rawData_M1.var_M1_0": 55.099998474121094
    },
    {
        "_time": "2024-05-16T12:00:00.907",
        "rawData_M1.var_M1_0": 55.0
    },
```
]

Example - limit

It might be useful to know the current value of the variable, as this allows you to understand the real-time status of the machine. To retrieve this information, you can make a request like the following:

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "limit": 1
}

You will receive the last recorded value for the variable:

Response

JSON
[
    {
        "_time": "2024-05-17T12:53:40.694",
        "rawData_M1.var_M1_0": 62.1000000000001
    }
]

Example- variableName as List

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
{
    "variableName": ["rawData_M1.var_M1_0", "rawData_M1.var_M1_1", "rawData_M2.var_M2_0"],
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-15T14:00:00.000Z",
    "resampleBy": "1d"
}

The response will be in the following format. Note that the response will contain a key for each requested table. Inside each key, the variables belonging to that table will be listed.

Response

{
    "rawData_M1": [
        {
            "_time": "2024-05-10T00:00:00.000",
            "rawData_M1.var_M1_0": 57.4114633007975,
            "rawData_M1.var_M1_1": 38.279759126605654
        },
        {
            "_time": "2024-05-11T00:00:00.000",
            "rawData_M1.var_M1_0": 57.53001188059882,
            "rawData_M1.var_M1_1": 38.446850013833576
        },
        {
            "_time": "2024-05-12T00:00:00.000",
            "rawData_M1.var_M1_0": 56.82464216958232,
            "rawData_M1.var_M1_1": 37.80455809454721
        },
        {
            "_time": "2024-05-13T00:00:00.000",
            "rawData_M1.var_M1_0": 57.56077337146711,
            "rawData_M1.var_M1_1": 39.47406089777127
        },
        {
            "_time": "2024-05-14T00:00:00.000",
            "rawData_M1.var_M1_0": 57.63307987443321,
            "rawData_M1.var_M1_1": 39.166464364608764
        },
        {
            "_time": "2024-05-15T00:00:00.000",
            "rawData_M1.var_M1_0": 57.19887903403007,
            "rawData_M1.var_M1_1": 37.56201759923548
        }
    ],
    "rawData_M2": [
        {
            "_time": "2024-05-10T00:00:00.000",
            "rawData_M2.var_M2_0": 57.79168104060553
        },
        {
            "_time": "2024-05-11T00:00:00.000",
            "rawData_M2.var_M2_0": 57.427215638681
        },
        {
            "_time": "2024-05-12T00:00:00.000",
            "rawData_M2.var_M2_0": 56.6011179003562
        },
        {
            "_time": "2024-05-13T00:00:00.000",
            "rawData_M2.var_M2_0": 57.24534198318859
        },
        {
            "_time": "2024-05-14T00:00:00.000",
            "rawData_M2.var_M2_0": 57.91216370189513
        },
        {
            "_time": "2024-05-15T00:00:00.000",
            "rawData_M2.var_M2_0": 57.227600735219745
        }
    ]
}

Code

The following script can be used to make a POST request to the /apis/telemetry endpoint. Be sure to configure the parameters correctly in the body of the request.

import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# Example data for the body
body = {
    "variableName": "rawData_M1.var_M1_0",
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-10T14:00:00.000Z",
    "resampleBy": "unique",
    "limit": null
}

# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/telemetry/{myAssetId}'
url = f'https://{myDomain}{endpoint}'

# Make the POST request
response = requests.post(url, headers=headers, json=body, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)

OpenAPI

post

This endpoint returns the requested telemetry variable, calculated using the parameters specified in the request body.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

assetIdstringRequired

Query parameters

subAssetIdstringOptional

Sub-machine ID. If the machine for which the assetId has been specified is a multi-machine, then this field must always be specified as well.

Body

variableNamestringOptional

The variable that has to be calculated. This parameter is mandatory.

Example: cons0

resampleBystringOptional

The value by which the data must be resampled. Allowed values include '1min', '1hour', '1day', '7days', '1month', '1year', 'unique', None, and the aforementioned units with numbers other than 1. Remember that when performing a 'unique' resample, string fields will be concatenated using the separator '$$'.

Default: NoneExample: 3d

fromstringOptional

Initial moment of the interval within which the data must be calculated. The timestamp must be expressed in UTC and follow the format 'YYYY-MM-DDThh:mm:ssZ'.

Default: NoneExample: 2024-04-18T10:30:00Z

tostringOptional

Final moment of the interval within which the data must be calculated. The timestamp must be expressed in UTC and follow the format 'YYYY-MM-DDThh:mm:ssZ'. The value can be omitted to default to the current timestamp.

Default: Actual timestampExample: 2024-04-18T10:30:00Z

limitintegerOptional

This field can be used instead of "from" and "to" to return the last {n} rows of data. If a range is specified with "from" and "to", the last {n} rows within the indicated range will be returned. If only "from" is specified, the last {n} rows will be returned. Specifying only "to" is not allowed. The "limit" operation has no effect if a value for the "resampleBy" field is specified, as that command takes precedence over "limit". You can use "limit" by itself, with "from", and with both "from" and "to". You can never use "limit" with only "to".

Default: nullExample: 10

Responses

200

application/json

Responseone of

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

post

/apis/telemetry/{assetId}

POST /apis/telemetry/{assetId} HTTP/1.1
Host: localhost:3001
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "variableName": "cons0",
  "resampleBy": "3d",
  "from": "2024-04-18T10:30:00Z",
  "to": "2024-04-18T10:30:00Z",
  "limit": 10
}

{
  "variableName": 1
}

/apis/telemetry-graph/<assetId>

POST Method

The POST method of the /apis/telemetry-graph/<assetId> endpoint can be used to retrieve the same chart shown in the Machine Recorder section of the MAT application.In addition to plotting multiple variables over time, it is also possible to retrieve the number of events that occurred across different time intervals. The chart can be filtered based on the values assumed by the various aggregators.

Request

HTTP
POST https://{BASE_URL}/apis/telemetry-graph/<assetId>

where:

assetId : ID of the machine to be considered.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

subAssetId : ID of the sub-machine to be considered. This field can be omitted if the selected asset is not a multi-machine asset.

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-10T14:00:00.000Z",
    "filterBy": {aggr0: null, aggr1: ["Mario", "Luigi"], aggr2: null},
    "returnStates": True,
    "autoResample": 0,
    "onlyPlotData": True
}

The parameters that can be specified in the request body are the following:

variableName: this parameter allows specifying the name of the variable for which the data should be retrieved. If the variable name is not known, all available variables can be retrieved by invoking the HTTP GET method at /apis/telemetry/<assetId>. This field can also be a list of strings, where each string represents a variable for which data should be requested;
from: starting timestamp from which the data calculation should begin, expressed in UTC using the "YYYY-MM-DDThh:mm:ss.sssZ" format (ISO 8601 standard);
to:ending timestamp of the interval in which the data should be calculated, expressed in UTC using the "YYYY-MM-DDThh:mm:ss.sssZ" format (ISO 8601 standard). If this field is omitted or set to null, it will be automatically set to the current timestamp at the time of the request;
filterBy: this parameter allows filtering the data. It must be expressed as a dictionary where the keys represent the different aggregators and the associated values are lists of elements representing the aggregator values for which the data should be retained;
returnStates: boolean value indicating whether the system should return the temporal sequence of states within the selected interval;
autoResample: boolean value that allows requesting the application to automatically compute a suitable temporal resampling for the data. If set to False, the returned data will not be temporally aggregated;
onlyPlotData: boolean value indicating whether the response should omit information related to the number of events that occurred within the different time intervals of the selected period.

When requesting a time interval, please note the following: a telemetry variable may be written to the database at a very high frequency. Requesting a wide time range for a high-frequency variable may result in a large amount of data, which might not be handled correctly by all the services involved in the operation. To reduce the amount of requested data and avoid system overloads, it is recommended to set the autoResample parameter to True.

Example- filterBy

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry-graph/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "variableName": "rawData_M1.var_M1_0",
    "from": "2024-05-15T15:30:28.000Z",
    "to": "2024-05-15T15:30:30.00Z",
    "filterBy": {"aggr0": ["prod1"], "aggr1": ["Mario", "Luigi"], "aggr2": null},
    "returnStates": True,
    "autoResample": True,
    "onlyPlotData": False
}

In this example, the value of a variable is retrieved by filtering on specific operator and product values.

The result is shown below.

Response

{
    "aspects": {
        "rawData_M1": {
            "aspect": "rawData_M1",
            "means": {
                "count": 1.0,
                "var_M1_0": 60.490000534057614
            },
            "returnedAggr": false,
            "timestamps": [
                "2024-05-15T17:30:28.113000",
                "2024-05-15T17:30:28.313000",
                "2024-05-15T17:30:29.115000",
                "2024-05-15T17:30:29.315000",
                "2024-05-15T17:30:29.515000",
                "2024-05-15T17:30:29.715000",
                "2024-05-15T17:30:29.915000"
            ],
            "variables": {
                "count": [
                    1.0,
                    1.0,
                    1.0,
                    1.0,
                    1.0,
                    1.0,
                    1.0
                ],
                "var_M1_0": [
                    60.70000076293945,
                    60.5,
                    60.400001525878906,
                    60.400001525878906,
                    60.400001525878906,
                    60.29999923706055,
                    60.20000076293945
                ]
            }
        }
    },
    "eventIntervals": [
        {
            "end": "2024-05-15T17:30:29.500000",
            "eventTypes": {},
            "events": 1,
            "start": "2024-05-15T17:30:29.000000"
        }
    ],
    "filter": false,
    "filters": [
        {
            "timeEnd": "2024-05-15T17:30:28.500000",
            "timeStart": "2024-05-15T17:30:28.000000"
        },
        {
            "timeEnd": "2024-05-15T17:30:30.000000",
            "timeStart": "2024-05-15T17:30:29.000000"
        }
    ],
    "states": [
        {
            "_time": "2024-05-15T17:30:16.499",
            "aggr0": "prod1",
            "aggr1": "Luigi",
            "aggr2": "format-C",
            "count": 1.0,
            "dtE": "Wed, 15 May 2024 17:30:30 GMT",
            "dtS": "Wed, 15 May 2024 17:30:28 GMT",
            "duration": 733.501,
            "timeEnd": "2024-05-15T17:30:30",
            "timeStart": "2024-05-15T17:30:28.000000",
            "value": 0.0
        }
    ]
}

Code

The following script can be used to invoke the /apis/telemetry-graph/<assetId> endpoint using the POST method.

Make sure to correctly configure the parameters in the request body.

import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# Example data for the body
body = {
    "variableName": "rawData_M1.var_M1_0",
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-10T14:00:00.000Z",
    "filterBy": {"aggr0": ["prod1", "prod2"]},
    "returnStates": True, 
    "autoResample": True,
    "onlyPlotData": False
}

# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/telemetry-graph/{myAssetId}'
url = f'https://{myDomain}{endpoint}'

# Make the POST request
response = requests.post(url, headers=headers, json=body, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)

/apif/telemetry-event-table/<assetId>

POST Method

The POST method of the /apis/telemetry-event-table/<assetId> endpoint can be used to retrieve the same event table displayed in the Machine Recorder section of the MAT application. The table can be filtered based on the values assumed by the different aggregators.

Request

HTTP
POST https://{BASE_URL}/apis/telemetry-event-table/<assetId>

where:

assetId : ID of the machine to be considered.

Query

JSON
{
    "subAssetId": "subAssetId"
}

where:

subAssetId : ID of the sub-machine to be considered. This field can be omitted if the selected asset is not a multi-machine asset.

Body

JSON
{
    "uniqueId": ["1", "3", "7"],
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-10T14:00:00.000Z",
    "filterBy": {"aggr0": null, "aggr1": ["Mario", "Luigi"], "aggr2": null},
    "eventFilter":[{"eventType": 1,"eventCodes":["al_M1_0"]}],
    "returnStates": True,
    "lastNEvents" 10000
}

The parameters that can be specified in the request body are the following:

uniqueId: this parameter allows specifying a list containing the IDs of the events to be retrieved. If the identifiers are not known, they can be obtained by invoking the /apis/events/<assetId> endpoint using the HTTP GET method;
from: starting timestamp from which the data calculation should begin, expressed in UTC using the "YYYY-MM-DDThh:mm:ss.sssZ" format (ISO 8601 standard);
to: ending timestamp of the interval in which the data should be calculated, expressed in UTC using the "YYYY-MM-DDThh:mm:ss.sssZ" format (ISO 8601 standard). If this field is omitted or set to null, it will be automatically set to the current timestamp at the time of the request;
filterBy: this parameter allows filtering the data. It must be expressed as a dictionary where the keys represent the different aggregators and the associated values are lists of elements representing the aggregator values for which the data should be retained;
eventFilter: this structure allows specifying, for each requested event type, which event codes should be included;
returnStates: boolean value indicating whether the system should return the temporal sequence of states within the selected interval;
lastNEvents : maximum number of events to be returned. This parameter cannot exceed 10000 in order to prevent overloading the system architecture.

Example - filterBy

Request

HTTP
POST https://matdev.40mat.com/apis/telemetry-event-table/40-line?subAssetId=M1

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "uniqueId": [1],
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-12T14:00:00.000Z",
    "filterBy": {"aggr0": null, "aggr1": null, "aggr2": null},
    "eventFilter": [{"eventType": 1,"eventCodes":["al_M1_0"]}],
    "returnStates": true
}

In this example, all type 1 events occurring within the selected time range are retrieved, but only those with event code equal to "al_M1_0".

The result is shown below.

Response

{
    "aspects": {},
    "eventIntervals": [],
    "filters": [],
    "states": [],
    "table": [
        {
            "_time": "2024-05-11T12:09:18.564880",
            "aggr0": "prod5",
            "aggr1": "Mario",
            "aggr2": "format-B",
            "code": "al_M1_0",
            "count": 1.0,
            "eventId": 1,
            "isFirst": "True",
            "measurement": "alarms"
        },
        {
            "_time": "2024-05-11T12:11:38.334",
            "aggr0": "prod5",
            "aggr1": "Mario",
            "aggr2": "format-B",
            "code": "al_M1_0",
            "count": 1.0,
            "duration": 139.7691192626953,
            "eventId": 2,
            "isFirst": "True",
            "measurement": "alarms"
        }
    ]
}

Code

The following script can be used to invoke the /apis/telemetry-event-table/<assetId> endpoint using the POST method.

Make sure to correctly configure the parameters in the request body.

import requests
import json

# Example data for the header
headers = {
    'App-Name': 'matdev-be',
    'Authorization': 'Bearer ey....xy1w'
}

# Example data for the body
body = {
    "uniqueId": [1],
    "from": "2024-05-10T00:00:00.000Z",
    "to": "2024-05-12T14:00:00.000Z",
    "filterBy": {"aggr0": null, "aggr1": null, "aggr2": null},
    "eventFilter": [{"eventType": 1,"eventCodes":["al_M1_0"]}],
    "returnStates": true
}

# Example data for the query string
query_params = {
    "subAssetId": "M1"
}

# URL of the third-party API
myDomain = 'matdev.40mat.com'
myAssetId = '40-line'
endpoint = f'/apis/telemetry-event-table/{myAssetId}'
url = f'https://{myDomain}{endpoint}'

# Make the POST request
response = requests.post(url, headers=headers, json=body, params=query_params )

# Check the response status and return the data
if response.status_code == 200:
    print('Success:')
    print(json.dumps(response.json(), indent=4))
else:
    print('Request failed:')
    print(f'Status code: {response.status_code}')
    print(response.text)

PreviousAggregators Calculation NextStates and State Timeline

Last updated 8 days ago

hashtag/apis/telemetry/<assetId>

hashtagGET Method

hashtagQuery

hashtagExample

hashtagQuery

hashtagCode

hashtagOpenAPI

hashtagPOST Method

hashtagQuery

hashtagBody

hashtagExample - resampleBy

hashtagQuery

hashtagBody

hashtagQuery

hashtagBody

hashtagQuery

hashtagBody

hashtagExample - limit

hashtagQuery

hashtagBody

hashtagExample- variableName as List

hashtagQuery

hashtagBody

hashtagCode

hashtagOpenAPI

hashtag/apis/telemetry-graph/<assetId>

hashtagPOST Method

hashtagQuery

hashtagBody

hashtagExample- filterBy

hashtagQuery

hashtagBody

hashtagCode

hashtag/apif/telemetry-event-table/<assetId>

hashtagPOST Method

hashtagQuery

hashtagBody

hashtagExample - filterBy

hashtagQuery

hashtagBody

hashtagCode

/apis/telemetry/<assetId>

GET Method

Query

Example

Query

Code

OpenAPI

POST Method

Query

Body

Example - resampleBy

Query

Body

Query

Body

Query

Body

Example - limit

Query

Body

Example- variableName as List

Query

Body

Code

OpenAPI

/apis/telemetry-graph/<assetId>

POST Method

Query

Body

Example- filterBy

Query

Body

Code

/apif/telemetry-event-table/<assetId>

POST Method

Query

Body

Example - filterBy

Query

Body

Code