Create data filters

POST/projects/{projectId}/dataFilters

Base URL: https://api.tinkermode.com

Create a new data filters in the project

Authentication

Send an Authorization header of the form ModeCloud <AUTH_CODE>.

Must contain the API key of a user or service account who has the permission to create all data filters of a project, or a Project API Key with admin permission.

Path parameters

Name	Type	Required	Constraints	Description
`projectId`	integer	Yes		The unique ID for a specified project.

Request body

Content type: application/json

Property Type Required Constraints Description

areaDeterminationRules object No The configuration of area determination type of data filter.

Properties of areaDeterminationRules
Property	Type	Required	Constraints	Description
`forceOverwrite`	boolean	No		Force overwrite the areas field in location data when it already has any areas.
`searchKeyPrefixes`	array<string>	No		The search key prefixes to search areas in GeoTSDB.

catalogId string Yes Data Source Catalog ID of data filter.

conversionRules object No The configuration of conversion type of data filter.

Property Type Required Constraints Description

differencing array<object> No The rules for calculating the difference between a numeric value and its subsequent value.

Property Type Required Constraints Description

reset object No

Properties of reset
Property	Type	Required	Description
`initialValue`	number	No	If the source or target value is null or the previous timestamp is over the reset interval, use the initial value instead.
`resetInterval`	string	No	The interval at which data is considered lost. The previous value will be replaced with the initial value if the previous timestamp is over this interval. The format is Golang's duration format, such as '1h', '30m', '5s'.
`resetValue`	number	No	The maximum value of the counters. If the counter reset happens, the difference is calculated from this value.

source string Yes The source measurement value name. This name must be in a metric definition.

target string Yes The target measurement value name. This name must be in a metric definition.

entityClass string No The entity class to be used for conversion. If the destination entity's entityClass doesn't match, the conversion is ignored. When this field is blank, it applies to data that has any entityClass.

excludes array<string> No The metrics that should be omitted.

metricsDefinitionId string No The metrics definition ID to be used for conversion. If the destination entity's metricsDefinitionID doesn't match, the conversion is ignored. When this field is blank, it applies to data that has any metricsDefinitionId.

tags array<object> No The rules for converting tag names from measurement to metric.

Property Type Required Constraints Description

formula string No The formula to convert measurement values to metric values. The formula must be a valid expression that can be evaluated in the context of the measurement values.

metricName string Yes The name of metrics.

name string Yes The name of measurement values.

replacement array<object> No The rules for replace tag values from old to new.

Properties of replacement
Property	Type	Required	Constraints	Description
`metricName`	string	No		The to value of the replacement rule.
`name`	string	No		The from value of the replacement rule.

values array<object> No The rules for converting numeric names from measurement to metric.

Properties of values
Property	Type	Required	Description
`copyToTag`	string	No	A tag name to copy a value from the metric. If the same tag name exists in the record, this field is ignored.
`formula`	string	No	The formula to convert measurement values to metric values. The formula must be a valid expression that can be evaluated in the context of the measurement values.
`metricName`	string	No	The name of metrics.
`name`	string	Yes	The name of measurement values.

dataType string Yes read-only (server-generated) Data type of the data filter. It must be one of the supported data types: metrics and locations.

filterId string Yes read-only (server-generated) Unique Data Filter ID.

filterType string Yes one of: conversion, area_determination, ellipsoid_to_orthometric_conversion Filter type of the data filter.

name string No Display name of data filter.

projectId integer Yes read-only (server-generated) Project that this data filter belongs to.

Request example

{
  "catalogId": "custom1",
  "conversionRules": {
    "entityClass": "humidity_sensor",
    "excludes": [
      "debug_code"
    ],
    "metricsDefinitionId": "humidity_metrics",
    "tags": [
      {
        "metricName": "status",
        "name": "statusCode",
        "replacement": [
          {
            "new": "success",
            "old": "001"
          },
          {
            "new": "failure",
            "old": "002"
          }
        ]
      }
    ],
    "values": [
      {
        "metricName": "humidity",
        "name": "relative_humidity"
      }
    ]
  },
  "dataType": "metrics",
  "filterId": "filter2",
  "filterType": "conversion",
  "name": "Data Filter 2",
  "projectId": 1234
}

Responses

`201` Successful creation of data filter.

Content type: application/json

Property Type Required Constraints Description

areaDeterminationRules object No The configuration of area determination type of data filter.

Properties of areaDeterminationRules
Property	Type	Required	Constraints	Description
`forceOverwrite`	boolean	No		Force overwrite the areas field in location data when it already has any areas.
`searchKeyPrefixes`	array<string>	No		The search key prefixes to search areas in GeoTSDB.

catalogId string Yes Data Source Catalog ID of data filter.

conversionRules object No The configuration of conversion type of data filter.

Property Type Required Constraints Description

differencing array<object> No The rules for calculating the difference between a numeric value and its subsequent value.

Property Type Required Constraints Description

reset object No

Properties of reset
Property	Type	Required	Description
`initialValue`	number	No	If the source or target value is null or the previous timestamp is over the reset interval, use the initial value instead.
`resetInterval`	string	No	The interval at which data is considered lost. The previous value will be replaced with the initial value if the previous timestamp is over this interval. The format is Golang's duration format, such as '1h', '30m', '5s'.
`resetValue`	number	No	The maximum value of the counters. If the counter reset happens, the difference is calculated from this value.

source string Yes The source measurement value name. This name must be in a metric definition.

target string Yes The target measurement value name. This name must be in a metric definition.

excludes array<string> No The metrics that should be omitted.

tags array<object> No The rules for converting tag names from measurement to metric.

Property Type Required Constraints Description

formula string No The formula to convert measurement values to metric values. The formula must be a valid expression that can be evaluated in the context of the measurement values.

metricName string Yes The name of metrics.

name string Yes The name of measurement values.

replacement array<object> No The rules for replace tag values from old to new.

Properties of replacement
Property	Type	Required	Constraints	Description
`metricName`	string	No		The to value of the replacement rule.
`name`	string	No		The from value of the replacement rule.

values array<object> No The rules for converting numeric names from measurement to metric.

Properties of values
Property	Type	Required	Description
`copyToTag`	string	No	A tag name to copy a value from the metric. If the same tag name exists in the record, this field is ignored.
`formula`	string	No	The formula to convert measurement values to metric values. The formula must be a valid expression that can be evaluated in the context of the measurement values.
`metricName`	string	No	The name of metrics.
`name`	string	Yes	The name of measurement values.

dataType string Yes read-only (server-generated) Data type of the data filter. It must be one of the supported data types: metrics and locations.

filterId string Yes read-only (server-generated) Unique Data Filter ID.

filterType string Yes one of: conversion, area_determination, ellipsoid_to_orthometric_conversion Filter type of the data filter.

name string No Display name of data filter.

projectId integer Yes read-only (server-generated) Project that this data filter belongs to.

Response example

{
  "catalogId": "custom1",
  "conversionRules": {
    "entityClass": "humidity_sensor",
    "excludes": [
      "debug_code"
    ],
    "metricsDefinitionId": "humidity_metrics",
    "tags": [
      {
        "metricName": "status",
        "name": "statusCode",
        "replacement": [
          {
            "new": "success",
            "old": "001"
          },
          {
            "new": "failure",
            "old": "002"
          }
        ]
      }
    ],
    "values": [
      {
        "metricName": "humidity",
        "name": "relative_humidity"
      }
    ]
  },
  "dataType": "metrics",
  "filterId": "filter2",
  "filterType": "conversion",
  "name": "Data Filter 2",
  "projectId": 1234
}

`401` Authorization is required to access this resource.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`403` Request failed because of invalid data or denied permission.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`429` Request failed because of rate limit.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`500` An unexpected error has occurred.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`503` The service is temporarily unavailable.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

Create data filters

Authentication

Path parameters

Request body

Request example

Responses

201 Successful creation of data filter.

Response example

401 Authorization is required to access this resource.

403 Request failed because of invalid data or denied permission.

429 Request failed because of rate limit.

500 An unexpected error has occurred.

503 The service is temporarily unavailable.

`201` Successful creation of data filter.

`401` Authorization is required to access this resource.

`403` Request failed because of invalid data or denied permission.

`429` Request failed because of rate limit.

`500` An unexpected error has occurred.

`503` The service is temporarily unavailable.