* add more notes to TelemetryController
* add detailed notes to Telemetryontroller and try to fix Inline Model
* remove responsecontainer from @ApiOperaion
* description updated for Telemetry Controller API calls
Co-authored-by: ShvaykaD <dshvaika@thingsboard.io>
@ -113,12 +116,43 @@ public class TelemetryController extends BaseController {
privatestaticfinalStringATTRIBUTES_KEYS_DESCRIPTION="A string value representing the comma-separated list of attributes keys. For example, 'active,inactivityAlarmTime'.";
privatestaticfinalStringATTRIBUTES_JSON_REQUEST_DESCRIPTION="A string value representing the json object. For example, '{\"key\":\"value\"}'";
privatestaticfinalStringTELEMETRY_KEYS_DESCRIPTION="A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all latest timeseries. For example, 'temp,humidity'.";
privatestaticfinalStringTELEMETRY_SCOPE_DESCRIPTION="Value is not used in the API call implementation";
privatestaticfinalStringTELEMETRY_JSON_REQUEST_DESCRIPTION="A string value representing the json object. For example, '{\"key\":\"value\"}' or '{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}'";
privatestaticfinalStringSTRICT_DATA_TYPES_DESCRIPTION="A boolean value to specify if values of selected timeseries keys will representing a string (by default) or use strict data type.";
privatestaticfinalStringATTRIBUTE_DATA_CLASS_DESCRIPTION="AttributeData class represents information regarding a particular attribute and includes the next parameters: 'lastUpdatesTs' - a long value representing the timestamp of the last attribute modification in milliseconds. 'key' - attribute key name, and 'value' - attribute value.";
privatestaticfinalStringGET_ALL_ATTRIBUTES_BASE_DESCRIPTION="Returns a JSON structure that represents a list of AttributeData class objects for the selected entity based on the specified comma-separated list of attribute key names. "+ATTRIBUTE_DATA_CLASS_DESCRIPTION;
privatestaticfinalStringGET_ALL_ATTRIBUTES_BY_SCOPE_BASE_DESCRIPTION="Returns a JSON structure that represents a list of AttributeData class objects for the selected entity based on the attributes scope selected and a comma-separated list of attribute key names. "+ATTRIBUTE_DATA_CLASS_DESCRIPTION;
privatestaticfinalStringTS_DATA_CLASS_DESCRIPTION="TsData class is a timeseries data point for specific telemetry key that includes 'value' - object value, and 'ts' - a long value representing timestamp in milliseconds for this value. ";
privatestaticfinalStringTELEMETRY_KEYS_BASE_DESCRIPTION="A string value representing the comma-separated list of telemetry keys.";
privatestaticfinalStringTELEMETRY_KEYS_DESCRIPTION=TELEMETRY_KEYS_BASE_DESCRIPTION+" If keys are not selected, the result will return all latest timeseries. For example, 'temp,humidity'.";
privatestaticfinalStringTELEMETRY_SCOPE_DESCRIPTION="Value is not used in the API call implementation. However, you need to specify whatever value cause scope is a path variable.";
privatestaticfinalStringTELEMETRY_JSON_REQUEST_DESCRIPTION="A string value representing the json object. For example, '{\"key\":\"value\"}' or '{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}' or [{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}, {\"ts\":1527863053000,\"values\":{\"key1\":\"value3\",\"key2\":\"value4\"}}]";
privatestaticfinalStringSTRICT_DATA_TYPES_DESCRIPTION="A boolean value to specify if values of selected telemetry keys will represent string values(by default) or use strict data type.";
privatestaticfinalStringINVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION="Referencing a non-existing entity Id or invalid entity type will cause an error. ";
privatestaticfinalStringSAVE_ENTITY_ATTRIBUTES_DESCRIPTION="Creates or updates the entity attributes based on entity id, entity type, specified attributes scope "+
"and request payload that represents a JSON object with key-value format of attributes to create or update. "+
"For example, '{\"temperature\": 26}'. Key is a unique parameter and cannot be overwritten. Only value can be overwritten for the key. ";
privatestaticfinalStringSAVE_ATTIRIBUTES_STATUS_OK="Attribute from the request was created or updated. ";
privatestaticfinalStringINVALID_STRUCTURE_OF_THE_REQUEST="Invalid structure of the request";
privatestaticfinalStringSAVE_ATTIRIBUTES_STATUS_BAD_REQUEST=INVALID_STRUCTURE_OF_THE_REQUEST+" or invalid attributes scope provided.";
privatestaticfinalStringSAVE_ENTITY_ATTRIBUTES_STATUS_OK="Platform creates an audit log event about entity attributes updates with action type 'ATTRIBUTES_UPDATED', "+
"and also sends event msg to the rule engine with msg type 'ATTRIBUTES_UPDATED'.";
privatestaticfinalStringSAVE_ENTITY_ATTRIBUTES_STATUS_UNAUTHORIZED="User is not authorized to save entity attributes for selected entity. Most likely, User belongs to different Customer or Tenant.";
privatestaticfinalStringSAVE_ENTITY_ATTRIBUTES_STATUS_INTERNAL_SERVER_ERROR="The exception was thrown during processing the request. "+
"Platform creates an audit log event about entity attributes updates with action type 'ATTRIBUTES_UPDATED' that includes an error stacktrace.";
privatestaticfinalStringSAVE_ENTITY_TIMESERIES_DESCRIPTION="Creates or updates the entity timeseries based on entity id, entity type "+
"and request payload that represents a JSON object with key-value or ts-values format. "+
"For example, '{\"temperature\": 26}' or '{\"ts\":1634712287000,\"values\":{\"temperature\":26, \"humidity\":87}}', "+
"or JSON array with inner objects inside of ts-values format. "+
"For example, '[{\"ts\":1634712287000,\"values\":{\"temperature\":26, \"humidity\":87}}, {\"ts\":1634712588000,\"values\":{\"temperature\":25, \"humidity\":88}}]'. "+
"The scope parameter is not used in the API call implementation but should be specified whatever value because it is used as a path variable. ";
privatestaticfinalStringSAVE_ENTITY_TIMESERIES_STATUS_OK="Timeseries from the request was created or updated. "+
"Platform creates an audit log event about entity timeseries updates with action type 'TIMESERIES_UPDATED'.";
privatestaticfinalStringSAVE_ENTITY_TIMESERIES_STATUS_UNAUTHORIZED="User is not authorized to save entity timeseries for selected entity. Most likely, User belongs to different Customer or Tenant.";
privatestaticfinalStringSAVE_ENTITY_TIMESERIES_STATUS_INTERNAL_SERVER_ERROR="The exception was thrown during processing the request. "+
"Platform creates an audit log event about entity timeseries updates with action type 'TIMESERIES_UPDATED' that includes an error stacktrace.";
@Autowired
privateTimeseriesServicetsService;
@ -146,7 +180,10 @@ public class TelemetryController extends BaseController {
}
@ApiOperation(value="Get all attribute keys (getAttributeKeys)",
notes="Returns key names for the selected entity.")
notes="Returns a list of all attribute key names for the selected entity. "+
"In the case of device entity specified, a response will include merged attribute key names list from each scope: "+
notes="Returns JSON array of AttributeData objects for the selected entity.")
notes=GET_ALL_ATTRIBUTES_BASE_DESCRIPTION+" If 'keys' parameter is omitted, AttributeData class objects will be added to the response for all existing keys of the selected entity. "+
notes="Returns JSON object with mapping timeseries keys to JSON arrays of TsData objects based on specified filters for the selected entity.")
notes="Returns a JSON structure that represents a Map, where the map key is a telemetry key name "+
"and map value - is a list of TsData class objects. "+TS_DATA_CLASS_DESCRIPTION+
"This method allows us to group original data into intervals and aggregate it using one of the aggregation methods or just limit the number of TsData objects to fetch for each key specified. "+
"See the desription of the request parameters for more details. "+
"The result can also be sorted in ascending or descending order. "+INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION,
@ApiResponse(code=401,message="User is not authorized to save device attributes for selected device. Most likely, User belongs to different Customer or Tenant."),
@ApiResponse(code=500,message="The exception was thrown during processing the request. "+
"Platform creates an audit log event about device attributes updates with action type 'ATTRIBUTES_UPDATED' that includes an error stacktrace."),
@ -315,7 +407,14 @@ public class TelemetryController extends BaseController {
}
@ApiOperation(value="Save or update telemetry with TTL (saveEntityTelemetryWithTTL)",
notes="The TTL parameter is used to extract the number of days to store the data.")
notes=SAVE_ENTITY_TIMESERIES_DESCRIPTION+"The ttl parameter used only in case of Cassandra DB use for timeseries data storage. "+INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION,
notes="Delete timeseries in the specified time range for selected entity.")
notes="Delete timeseries for selected entity based on entity id, entity type, keys "+
"and removal time range. To delete all data for keys parameter 'deleteAllDataForKeys' should be set to true, "+
"otherwise, will be deleted data that is in range of the selected time interval. ",
produces=MediaType.APPLICATION_JSON_VALUE)
@ApiResponses(value={
@ApiResponse(code=200,message="Timeseries for the selected keys in the request was removed. "+
"Platform creates an audit log event about entity timeseries removal with action type 'TIMESERIES_DELETED'."),
@ApiResponse(code=400,message="Platform returns a bad request in case if keys list is empty or start and end timestamp values is empty when deleteAllDataForKeys is set to false."),
@ApiResponse(code=401,message="User is not authorized to delete entity timeseries for selected entity. Most likely, User belongs to different Customer or Tenant."),
@ApiResponse(code=500,message="The exception was thrown during processing the request. "+
"Platform creates an audit log event about entity timeseries removal with action type 'TIMESERIES_DELETED' that includes an error stacktrace."),
@ApiParam(value="If the parameter is set to true, the latest telemetry will be rewritten if the current latest value was removed, otherwise, the new latest value will not set.")
@ApiParam(value="If the parameter is set to true, the latest telemetry will be rewritten in case that current latest value was removed, otherwise, in case that parameter is set to false the new latest value will not set.")
notes="Delete attributes of specified scope for selected device.")
notes="Delete device attributes from the specified attributes scope based on device id and a list of keys to delete. "+
"Selected keys will be deleted only if there are exist in the specified attribute scope. Referencing a non-existing device Id will cause an error",
produces=MediaType.APPLICATION_JSON_VALUE)
@ApiResponses(value={
@ApiResponse(code=200,message="Device attributes was removed for the selected keys in the request. "+
"Platform creates an audit log event about device attributes removal with action type 'ATTRIBUTES_DELETED'."),
@ApiResponse(code=400,message="Platform returns a bad request in case if keys or scope are not specified."),
@ApiResponse(code=401,message="User is not authorized to delete device attributes for selected entity. Most likely, User belongs to different Customer or Tenant."),
@ApiResponse(code=500,message="The exception was thrown during processing the request. "+
"Platform creates an audit log event about device attributes removal with action type 'ATTRIBUTES_DELETED' that includes an error stacktrace."),
notes="Delete attributes of specified scope for selected entity.")
notes="Delete entity attributes from the specified attributes scope based on entity id, entity type and a list of keys to delete. "+
"Selected keys will be deleted only if there are exist in the specified attribute scope."+INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION,
produces=MediaType.APPLICATION_JSON_VALUE)
@ApiResponses(value={
@ApiResponse(code=200,message="Entity attributes was removed for the selected keys in the request. "+
"Platform creates an audit log event about entity attributes removal with action type 'ATTRIBUTES_DELETED'."),
@ApiResponse(code=400,message="Platform returns a bad request in case if keys or scope are not specified."),
@ApiResponse(code=401,message="User is not authorized to delete entity attributes for selected entity. Most likely, User belongs to different Customer or Tenant."),
@ApiResponse(code=500,message="The exception was thrown during processing the request. "+
"Platform creates an audit log event about entity attributes removal with action type 'ATTRIBUTES_DELETED' that includes an error stacktrace."),
Mariia Synelnyk
5 years ago
GitHub