Each project defines "consumables" that allow tracking how much of a certain product the machine has used during its operation. Each consumable is associated with a product, which could be water, energy, air, raw materials, etc.
/apis/consumables/<assetId>
GET Method
Request
HTTP
GET https://{BASE_URL}/apis/consumables/<assetId>
dove:
assetId : id della sotto macchina da considerare.
Query
JSON
{
"subAssetId": "subAssetId"
}
dove:
subAssetId : id della sotto macchina da considerare. Questo campo può essere omesso se l'asset considerato non è multi macchina.
By invoking this endpoint with the GET method, you can retrieve the list of all consumables for the specified machine, potentially filtered by sub-machine. This functionality is useful to identify the consumables of the machine and how they are identified, in order to request their calculation.
The response provides useful information about each consumable, such as the supported aggregators, the general and relative units of measurement, and any multipliers to be applied to the data to obtain the correct unit of measurement. An interesting key is "40ImpactOnly," which allows distinguishing between real consumables, associated with physical products, and virtual consumables, associated with other calculable values and used only for Sustainability Analysis.
The data returned in this response can be used to make a POST request to this same endpoint. The keys within the response or the "id" keys in each individual object identify the value that can be specified in the POST request under the "consumableName" key.
Example
Request
HTTP
GET https://matdev.40mat.com/apis/consumables/40-line?subAssetId=M1
Query
JSON
{
"subAssetId": "M1"
}
In this example, the goal is to obtain the list of all consumables for the machine "40-line," but only valid for the sub-machine "M1."
An example response is shown in the figure. Each object can be interpreted as follows:
"The consumable cons0 is expressed in cubic meters and represents the air used by the machine for processing. The aggregators that can be used for its aggregation are aggr0, aggr1, and aggr2. There is no need to multiply the obtained value to convert it into cubic meters, as it is originally recorded in the table in this format. The unit of measurement to use when calculating the relative consumption of cons0 is cubic meters per bundle, and again, there is no need to multiply the obtained value by a coefficient to get the correct unit of measurement."
Response
Code
OpenAPI
get
This endpoint returns the list of consumables available for the specified machine. If a submachine is specified, the consumables 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
A list of consumable resources with their details. Each key in the dict is a consumable 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/consumables/{assetId}
POST Method
The POST method of the /apis/consumables/<assetId> endpoint can be used to calculate the values of a certain consumable. The endpoint provides a set of parameters that, once passed in the body, allow the system to perform data processing.
Request
where:
assetId : ID of the machine to consider.
Query
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
The body of the request can consist of the following parameters:
consumableName : this string field indicates the name of the consumable that you want to request from the system. To obtain the possible consumables, you can invoke this same endpoint using the GET method: the keys in the response and the values associated with the "id" keys of each object can be used in this parameter as they uniquely identify a consumable. Note that this parameter can be a list of strings, where each string represents a consumable 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;
resampleBy : this parameter allows you to define the frequency with which to calculate the specified consumable. 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. 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 consumable to be calculated with a frequency of {n} minutes over the selected interval;
{n}h: allows the consumable to be calculated with a frequency of {n} hours over the selected interval;
{n}d: allows the consumable to be calculated with a frequency of {n} days over the selected interval;
{n}w: allows the consumable to be calculated with a frequency of {n} weeks over the selected interval;
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;
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;
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 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;
getRelativeValue : this boolean field allows you to specify whether the returned data should be calculated absolutely over the specified interval or normalized according to the production realized during that period;
calendar : boolean value indicating whether the calendar should be considered in data analysis. By default, this value is set to false.
Below are some usage examples of this call.
Example - groupBy
The goal of this example is to calculate how much of cons0 was consumed during the production of different products ("aggr0") in the month of April. To group the data based on the product produced, you need to perform a group by operation on the column dedicated to the produced product, which is "aggr0".
Request
Query
Body
Here is the response. As you can see, for each product produced, a value for the consumable is provided. For example, to produce the product type prod1, 915,563.960059166 cubic meters of cons0 were consumed (the unit of measurement can be retrieved from the GET method call).
Response
Example - filterBy
Request
Query
Body
The objective of this example is to show the daily trend of cons1 consumption when the operator "Luigi" is recorded. To achieve this, a filter is applied by setting the "filterBy" key and specifying that the value of the operator aggregator must be "Luigi."
The response is as follows. For each day within the selected interval, the value of cons1 filtered by the operator is provided.
Response
Example - groupBy, filterBy
Request
Query
Body
In this example, the goal is to obtain the value of cons1 based on the recorded operator, but only when the format being used was "format-A." To achieve this, in addition to performing a group by operation on the operator field ("aggr1"), a filter is applied to retain only the data for the "format-A" format using the "filterBy" key.
Response
Example - getRelativeValue
Request
Query
Body
In the example above, the goal is to obtain the value of the consumable cons1 from May 9th to the present. The "to" field is set to a null value, thereby extending the reference interval to the current moment. Additionally, in this example, "getRelativeValue" is set to false, as the interest is in the total amount of cons1 consumed.
The response is shown below. From the GET method call, we know that the unit of measurement for cons1 is kWh, so from May 9th to now, the machine has consumed 881.0794633813202 kWh.
Response
In the following example, the goal is to determine the relative consumption from May 9th to today.
Request
Query
Body
Since the relative unit of measurement for cons1 is kWh/bundle, we can conclude from the following response that the relative consumption in the reference interval was 0.1195996412032257 kWh per bundle.
Response
Example- consumableName as List
Request
Query
Body
The response will be as follows:
Response
Code
The following script can be used to make a POST request to the /apis/consumables endpoint. Be sure to configure the parameters correctly in the body of the request.
OpenAPI
post
This endpoint returns the requested consumable, 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
consumableNamestringOptional
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.
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/consumables/{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)
GET /apis/consumables/{assetId} HTTP/1.1
Host: localhost:3001
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
import requests
import json
# Example data for the header
headers = {
'App-Name': 'matdev-be',
'Authorization': 'Bearer ey....xy1w'
}
# Example data for the body
body = {
"consumableName": "cons1",
"resampleBy": "unique",
"from": "2024-03-31T22:00:00.000Z",
"to": "2024-04-05T21:59:59.999Z",
"filterBy": {"aggr2": "format-A"},
"groupBy": "aggr1",
"limit": None,
"getRelativeValue": 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/consumables/{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)