Aggregators Calculation

Aggregators are parameters that describe the machine and are written in all tables because they are particularly useful for filtering and aggregating data.

/apis/aggregators/<assetId>

GET Method

Request

HTTP
GET https://{BASE_URL}/apis/aggregators/<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.

By invoking this endpoint with the HTTP GET method, you can retrieve all the aggregators available for the specified machine.

An example of the response is shown below. As you can see, each key in the response indicates an available aggregator, while the associated value contains useful information such as the human-readable meaning of the aggregator and its unique ID.

Response

JSON
{
    "aggr0": {
        "id": "aggr0",
        "meaning": "Product ID"
    },
    "aggr1": {
        "id": "aggr1",
        "meaning": "Operator ID"
    },
    "aggr2": {
        "id": "aggr2",
        "meaning": "Format"
    }
}

Example

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

In this example, the goal is to obtain the list of all aggregators for the machine "40-line," but only valid for the sub-machine "M1."

An example of the response is shown in the figure.

Response

JSON
{
    "aggr0": {
        "id": "aggr0",
        "meaning": "Product ID"
    },
    "aggr1": {
        "id": "aggr1",
        "meaning": "Operator ID"
    },
    "aggr2": {
        "id": "aggr2",
        "meaning": "Format"
    }
}

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/aggregators/{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 the list of aggregators available for the specified machine. If a submachine is specified, the aggregators 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 describing aggregators available for the machine. Each key in the dict is an aggregator and the value is an object describing it.

application/json

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

get

/apis/aggregators/{assetId}

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

{
  "id": "aggr0",
  "meaning": "ProductID"
}

POST Method

This endpoint allows you to retrieve the values recorded in the table for the requested aggregator. The functionality of this endpoint is very similar to the one that allows you to retrieve KPI values (/apis/kpis/<assetId>).

Request

HTTP
POST https://{BASE_URL}/apis/aggregators/<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.

Body

JSON
{
    "aggregatorName": "aggr0",
    "resampleBy": "1d",
    "from": "2024-05-10T22:00:00.000Z",
    "to": "2024-05-13T21:59:59.999Z",
    "limit":1,
    "filterBy": {"aggr1": "Mario"},
    "groupBy": "aggr1",
    "getPossibleValues": true,
    "calendar": 0
}

The parameters that can be passed in the body are as follows:

aggregatorName: this parameter contains the identifier of the aggregator you want to download. The list of available aggregators can be retrieved by invoking the /apis/aggregators/<assetId> endpoint with the GET method. Note that this field can be a list of strings, where each string represents an aggregator to be requested;
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, "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 without "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.
resampleBy: this parameter allows you to define the frequency with which to calculate the specified KPI. Since data in the MAT ecosystem is recorded over time, it can be returned with reference to a time period or as a time series. Note that, because aggregators are often expressed as strings, if multiple values are recorded within the same resample unit, they will be presented concatenated with the "$$" character. This field allows you to specify how the data should be returned. The allowed values are:
- unique: this parameter indicates that you want to obtain a single numerical value calculated over the entire interval;
- {n}m: allows the KPI to be calculated with a frequency of {n} minutes over the selected interval;
- {n}h: allows the KPI to be calculated with a frequency of {n} hours over the selected interval;
- {n}d: allows the KPI to be calculated with a frequency of {n} days over the selected interval;
- {n}w: allows the KPI to be calculated with a frequency of {n} weeks over the selected interval;
groupBy: this field allows you to group the data according to one of the specified values. The value should be a string indicating the field on which you want to aggregate. For more advanced use, you can specify a list of strings;
filterBy: this field allows you to specify a filter to apply to the data. The value must be a dictionary where the keys represent the fields to filter on, and the value represents what you want to include for that field;
getPossibleValues: a boolean that allows you to indicate whether you want to download only the values that the aggregator has assumed over time (True) or if you are interested in their trend (False);
calendar : boolean value indicating whether the calendar should be considered in data analysis. By default, this value is set to false.

Esempio - resampleBy

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "aggregatorName": "aggr1",
    "resampleBy": "1d",
    "from": "2024-05-10T22:00:00.000Z",
    "to": "2024-05-13T21:59:59.999Z"
}

Questo esempio ritorna i valori assunti dall'aggregatore "aggr1" nel tempo resamplati per ora. Nella risposta sarà presente il separatore "$$" poiché tale aggregatore, nel nostro esempio, è di tipo stringa.

La risposta è la seguente:

Response

JSON
[
    {
        "_time": "2024-05-11T00:00:00.000",
        "aggr1": "Waluigi$$Wario$$Luigi$$Peach$$Mario$$Yoshi"
    },
    {
        "_time": "2024-05-12T00:00:00.000",
        "aggr1": "Waluigi$$Wario$$Luigi$$Peach$$Mario$$Yoshi"
    },
    {
        "_time": "2024-05-13T00:00:00.000",
        "aggr1": "Waluigi$$Wario$$Luigi$$Peach$$Mario$$Yoshi"
    }
]

Example - limit

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
    "aggregatorName": "aggr1",
    "from": "2024-05-12T22:00:00.000Z",
    "to": "2024-05-13T21:59:59.999Z",
    "limit":1
}

The objective of this example is to determine who the last active operator on the machine was on May 13th. To achieve this, in addition to specifying the correct time interval, the "limit" parameter is set to 1. This way, the last recorded operator within the final timestamp indicated in the "to" field will be returned.

The response is as follows:

Response

JSON
[
    {
        "_time": "2024-05-13T23:59:59.999",
        "aggr1": "Mario"
    }
]

Example - filterBy

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
            "from": "2024-05-20T12:00:00.000Z",
            "to": "2024-05-20T12:59:59.999Z",
            "aggregatorName": "aggr2",
            "filterBy": {"aggr1": "Mario"}
 }

In this example, I want to obtain all the formats used by the operator "Mario" in the last hour. To get this information, I filtered the data so that only the records where the operator "Mario" is active are returned.

The response is as follows:

Response

JSON
[
    {
        "_time": "2024-05-20T14:12:45.661",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:17:45.838",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:22:46.006",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:27:46.185",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:32:46.358",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:34:06.054",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:39:06.228",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:44:06.405",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:49:06.576",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:54:06.746",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:57:46.829",
        "aggr2": "format-E"
    },
    {
        "_time": "2024-05-20T14:59:59.999",
        "aggr2": "format-D"
    }
]

Example - groupBy

Below is an example of a grouping operation on the "aggr1" field. The objective is to find out which formats have been used over time by the various operators.

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
            "from": "2024-05-20T12:00:00.000Z",
            "to": "2024-05-20T12:59:59.999Z",
            "aggregatorName": "aggr2",
            "groupBy": "aggr1"
}

The response is as follows:

Response

JSON
{
    "Mario": [
        {
            "_time": "2024-05-20T14:12:45.661",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:17:45.838",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:22:46.006",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:27:46.185",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:32:46.358",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:34:06.054",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:39:06.228",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:44:06.405",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:49:06.576",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:54:06.746",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:57:46.829",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:59:59.999",
            "aggr2": "format-D"
        }
    ],
    "Yoshi": [
        {
            "_time": "2024-05-20T14:05:00.083",
            "aggr2": "format-E"
        },
        {
            "_time": "2024-05-20T14:07:45.487",
            "aggr2": "format-E"
        }
    ]
}

Example - getPossibleValues

In this example, the goal is to obtain all the operators who worked on the machine during the specified week. Specifically, by using the "getPossibleValues" parameter, you can identify all the different values that the specified aggregator has assumed within the given time interval.

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
            "from": "2024-05-12T22:00:00.000Z",
            "to": "2024-05-19T21:59:59.999Z",
            "aggregatorName": "aggr1",
            "getPossibleValues": true
}

The response will be formatted as follows:

Response

JSON
[
    "Yoshi",
    "Peach",
    "Luigi",
    "Mario",
    "Waluigi",
    "Wario"
]

Example- aggregatorName as List

Request

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

Query

JSON
{
    "subAssetId": "M1"
}

Body

JSON
{
            "from": "2024-05-12T22:00:00.000Z",
            "to": "2024-05-19T21:59:59.999Z",
            "aggregatorName": ["aggr1", "aggr2"],
            "resampleBy": "1d"
}

The response will be formatted as follows:

Response

[
    {
        "_time": "2024-05-13T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-B$$format-D$$format-A$$format-C$$format-E"
    },
    {
        "_time": "2024-05-14T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-B$$format-A$$format-D$$format-C"
    },
    {
        "_time": "2024-05-15T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-B$$format-D$$format-A$$format-C$$format-E"
    },
    {
        "_time": "2024-05-16T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-E$$format-D$$format-C"
    },
    {
        "_time": "2024-05-17T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-E$$format-B$$format-C"
    },
    {
        "_time": "2024-05-18T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-B$$format-A$$format-D$$format-C$$format-E"
    },
    {
        "_time": "2024-05-19T00:00:00.000",
        "aggr1": "Mario$$Luigi$$Yoshi$$Wario$$Waluigi$$Peach",
        "aggr2": "format-B$$format-A$$format-D$$format-C$$format-E"
    }
]

Codic

Code

The following script can be used to make a POST request to the /apis/aggregators 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 = {
    "aggregatorName": "aggr0",
    "resampleBy": "1d",
    "from": "2024-05-10T22:00:00.000Z",
    "to": "2024-05-13T21:59:59.999Z",
    "limit":1,
    "filterBy": {"aggr1": "Mario"},
    "groupBy": "aggr1",
    "getPossibleValues": 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/aggregators/{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 aggregator, calculated using the parameters specified in the request body. It can be a succession of value for the aggregator or all the possible values written until now.

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

aggregatorNamestringOptional

The consumable 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

groupBystringOptional

Aggregator to be used for grouping the data. Group by can only be applied to aggregator columns.

Default: NoneExample: aggr0

filterByobjectOptional

Object indicating for each key which value is allowed. All data that do not meet this condition will not be used to calculate the consumable. Notice that filters can only be applied to aggregator columns, i.e., those columns whose names follow the format "aggr" + number. Applying a filter to a table that doesn't have these columns will result in obtaining no data. Filters can only be applied to aggregator columns.

Default: NoneExample: {"aggr0":"Waluigi","aggr1":"recipe1"}

getPossibleValuesbooleanOptional

Boolean indicating whether all the different values that the aggregator has taken so far should be returned.

Default: false

Responses

200

application/json

Responseone of

arrayOptional

List of values representing all the values that the aggregator has assumed over time.

400

Bad Request.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

503

Service Unavailable.

504

Gateway Timeout.

post

/apis/aggregators/{assetId}

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

{
  "aggregatorName": "cons0",
  "resampleBy": "3d",
  "from": "2024-04-18T10:30:00Z",
  "to": "2024-04-18T10:30:00Z",
  "limit": 10,
  "groupBy": "aggr0",
  "filterBy": {
    "aggr0": "Waluigi",
    "aggr1": "recipe1"
  },
  "getPossibleValues": false
}

{
  "type": null,
  "properties": null
}

PreviousConsumables Calculation NextTelemetry Data

Last updated 8 months ago

hashtag/apis/aggregators/<assetId>

hashtagGET Method

hashtagQuery

hashtagExample

hashtagQuery

hashtagCode

hashtagOpenAPI

hashtagPOST Method

hashtagQuery

hashtagBody

hashtagEsempio - resampleBy

hashtagQuery

hashtagBody

hashtagExample - limit

hashtagQuery

hashtagBody

hashtagExample - filterBy

hashtagQuery

hashtagBody

hashtagExample - groupBy

hashtagQuery

hashtagBody

hashtagExample - getPossibleValues

hashtagQuery

hashtagBody

hashtagExample- aggregatorName as List

hashtagQuery

hashtagBody

hashtagCodic

hashtagCode

hashtagOpenAPI

/apis/aggregators/<assetId>

GET Method

Query

Example

Query

Code

OpenAPI

POST Method

Query

Body

Esempio - resampleBy

Query

Body

Example - limit

Query

Body

Example - filterBy

Query

Body

Example - groupBy

Query

Body

Example - getPossibleValues

Query

Body

Example- aggregatorName as List

Query

Body

Codic

Code

OpenAPI