Merge pull request #11360 from irynamatveieva/fix-time-series-text-swagger
Swagger: replaced text timeseries/time-series to time series
This commit is contained in:
Viacheslav Klimov
GitHub
commit
0b3e228e6f
@ -791,7 +791,7 @@ public class ControllerConstants {
|
||||
" * 'SHARED_ATTRIBUTE' - used for shared attributes; \n" +
|
||||
" * 'SERVER_ATTRIBUTE' - used for server attributes; \n" +
|
||||
" * 'ATTRIBUTE' - used for any of the above; \n" +
|
||||
" * 'TIME_SERIES' - used for time-series values; \n" +
|
||||
" * 'TIME_SERIES' - used for time series values; \n" +
|
||||
" * 'ENTITY_FIELD' - used for accessing entity fields like 'name', 'label', etc. The list of available fields depends on the entity type; \n" +
|
||||
" * 'ALARM_FIELD' - similar to entity field, but is used in alarm queries only; \n" +
|
||||
"\n\n Let's review the example:\n\n" +
|
||||
@ -902,7 +902,7 @@ public class ControllerConstants {
|
||||
|
||||
protected static final String KEY_FILTERS =
|
||||
"\n\n # Key Filters" +
|
||||
"\nKey Filter allows you to define complex logical expressions over entity field, attribute or latest time-series value. The filter is defined using 'key', 'valueType' and 'predicate' objects. " +
|
||||
"\nKey Filter allows you to define complex logical expressions over entity field, attribute or latest time series value. The filter is defined using 'key', 'valueType' and 'predicate' objects. " +
|
||||
"Single Entity Query may have zero, one or multiple predicates. If multiple filters are defined, they are evaluated using logical 'AND'. " +
|
||||
"The example below checks that temperature of the entity is above 20 degrees:" +
|
||||
"\n\n" + MARKDOWN_CODE_BLOCK_START +
|
||||
@ -933,7 +933,7 @@ public class ControllerConstants {
|
||||
"For example, \"find all devices with profile 'Moisture Sensor'\" or \"Find all devices related to asset 'Building A'\"" +
|
||||
"\n\nOptional **key filters** allow to filter results of the entity filter by complex criteria against " +
|
||||
"main entity fields (name, label, type, etc), attributes and telemetry. " +
|
||||
"For example, \"temperature > 20 or temperature< 10\" or \"name starts with 'T', and attribute 'model' is 'T1000', and timeseries field 'batteryLevel' > 40\"." +
|
||||
"For example, \"temperature > 20 or temperature< 10\" or \"name starts with 'T', and attribute 'model' is 'T1000', and time series field 'batteryLevel' > 40\"." +
|
||||
"\n\nLet's review the example:" +
|
||||
"\n\n" + MARKDOWN_CODE_BLOCK_START +
|
||||
"{\n" +
|
||||
@ -968,13 +968,13 @@ public class ControllerConstants {
|
||||
protected static final String ENTITY_DATA_QUERY_DESCRIPTION =
|
||||
"Allows to run complex queries over platform entities (devices, assets, customers, etc) " +
|
||||
"based on the combination of main entity filter and multiple key filters. " +
|
||||
"Returns the paginated result of the query that contains requested entity fields and latest values of requested attributes and time-series data.\n\n" +
|
||||
"Returns the paginated result of the query that contains requested entity fields and latest values of requested attributes and time series data.\n\n" +
|
||||
"# Query Definition\n\n" +
|
||||
"\n\nMain **entity filter** is mandatory and defines generic search criteria. " +
|
||||
"For example, \"find all devices with profile 'Moisture Sensor'\" or \"Find all devices related to asset 'Building A'\"" +
|
||||
"\n\nOptional **key filters** allow to filter results of the **entity filter** by complex criteria against " +
|
||||
"main entity fields (name, label, type, etc), attributes and telemetry. " +
|
||||
"For example, \"temperature > 20 or temperature< 10\" or \"name starts with 'T', and attribute 'model' is 'T1000', and timeseries field 'batteryLevel' > 40\"." +
|
||||
"For example, \"temperature > 20 or temperature< 10\" or \"name starts with 'T', and attribute 'model' is 'T1000', and time series field 'batteryLevel' > 40\"." +
|
||||
"\n\nThe **entity fields** and **latest values** contains list of entity fields and latest attribute/telemetry fields to fetch for each entity." +
|
||||
"\n\nThe **page link** contains information about the page to fetch and the sort ordering." +
|
||||
"\n\nLet's review the example:" +
|
||||
@ -1052,7 +1052,7 @@ public class ControllerConstants {
|
||||
protected static final String ALARM_DATA_QUERY_DESCRIPTION = "This method description defines how Alarm Data Query extends the Entity Data Query. " +
|
||||
"See method 'Find Entity Data by Query' first to get the info about 'Entity Data Query'." +
|
||||
"\n\n The platform will first search the entities that match the entity and key filters. Then, the platform will use 'Alarm Page Link' to filter the alarms related to those entities. " +
|
||||
"Finally, platform fetch the properties of alarm that are defined in the **'alarmFields'** and combine them with the other entity, attribute and latest time-series fields to return the result. " +
|
||||
"Finally, platform fetch the properties of alarm that are defined in the **'alarmFields'** and combine them with the other entity, attribute and latest time series fields to return the result. " +
|
||||
"\n\n See example of the alarm query below. The query will search first 100 active alarms with type 'Temperature Alarm' or 'Fire Alarm' for any device with current temperature > 0. " +
|
||||
"The query will return combination of the entity fields: name of the device, device model and latest temperature reading and alarms fields: createdTime, type, severity and status: " +
|
||||
"\n\n" + MARKDOWN_CODE_BLOCK_START +
|
||||
@ -1173,7 +1173,7 @@ public class ControllerConstants {
|
||||
protected static final String ALARM_FILTER_KEY = "## Alarm Filter Key" + NEW_LINE +
|
||||
"Filter Key defines either entity field, attribute, telemetry or constant. It is a JSON object that consists the key name and type. The following filter key types are supported:\n" +
|
||||
" * 'ATTRIBUTE' - used for attributes values;\n" +
|
||||
" * 'TIME_SERIES' - used for time-series values;\n" +
|
||||
" * 'TIME_SERIES' - used for time series values;\n" +
|
||||
" * 'ENTITY_FIELD' - used for accessing entity fields like 'name', 'label', etc. The list of available fields depends on the entity type;\n" +
|
||||
" * 'CONSTANT' - constant value specified." + NEW_LINE + "Let's review the example:" + NEW_LINE +
|
||||
MARKDOWN_CODE_BLOCK_START +
|
||||
@ -1291,7 +1291,7 @@ public class ControllerConstants {
|
||||
|
||||
protected static final String KEY_FILTERS_DESCRIPTION = "# Key Filters" + NEW_LINE +
|
||||
"Key filter objects are created under the **'condition'** array. They allow you to define complex logical expressions over entity field, " +
|
||||
"attribute, latest time-series value or constant. The filter is defined using 'key', 'valueType', " +
|
||||
"attribute, latest time series value or constant. The filter is defined using 'key', 'valueType', " +
|
||||
"'value' (refers to the value of the 'CONSTANT' alarm filter key type) and 'predicate' objects. Let's review each object:" + NEW_LINE +
|
||||
ALARM_FILTER_KEY + FILTER_VALUE_TYPE + NEW_LINE + DEVICE_PROFILE_FILTER_PREDICATE + NEW_LINE;
|
||||
|
||||
@ -1604,7 +1604,7 @@ public class ControllerConstants {
|
||||
protected static final String ATTRIBUTES_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}'. See API call description for more details.";
|
||||
|
||||
protected static final String TELEMETRY_KEYS_BASE_DESCRIPTION = "A string value representing the comma-separated list of telemetry keys.";
|
||||
protected static final String TELEMETRY_KEYS_DESCRIPTION = TELEMETRY_KEYS_BASE_DESCRIPTION + " If keys are not selected, the result will return all latest timeseries. For example, 'temperature,humidity'.";
|
||||
protected static final String TELEMETRY_KEYS_DESCRIPTION = TELEMETRY_KEYS_BASE_DESCRIPTION + " If keys are not selected, the result will return all latest time series. For example, 'temperature,humidity'.";
|
||||
protected static final String TELEMETRY_SCOPE_DESCRIPTION = "Value is deprecated, reserved for backward compatibility and not used in the API call implementation. Specify any scope for compatibility";
|
||||
protected static final String TELEMETRY_JSON_REQUEST_DESCRIPTION = "A JSON with the telemetry values. See API call description for more details.";
|
||||
|
||||
@ -1620,11 +1620,11 @@ public class ControllerConstants {
|
||||
protected static final String SAVE_ENTITY_ATTRIBUTES_STATUS_UNAUTHORIZED = "User is not authorized to save entity attributes for selected entity. Most likely, User belongs to different Customer or Tenant.";
|
||||
protected static final String SAVE_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.";
|
||||
protected static final String SAVE_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'.";
|
||||
protected static final String SAVE_ENTITY_TIMESERIES_STATUS_UNAUTHORIZED = "User is not authorized to save entity timeseries for selected entity. Most likely, User belongs to different Customer or Tenant.";
|
||||
protected static final String SAVE_ENTITY_TIMESERIES_STATUS_OK = "Time series from the request was created or updated. " +
|
||||
"Platform creates an audit log event about entity time series updates with action type 'TIMESERIES_UPDATED'.";
|
||||
protected static final String SAVE_ENTITY_TIMESERIES_STATUS_UNAUTHORIZED = "User is not authorized to save entity time series for selected entity. Most likely, User belongs to different Customer or Tenant.";
|
||||
protected static final String SAVE_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.";
|
||||
"Platform creates an audit log event about entity time series updates with action type 'TIMESERIES_UPDATED' that includes an error stacktrace.";
|
||||
|
||||
protected static final String ENTITY_ATTRIBUTE_SCOPES_TEMPLATE = " List of possible attribute scopes depends on the entity type: " +
|
||||
"\n\n * SERVER_SCOPE - supported for all entity types;" +
|
||||
|
||||
@ -125,8 +125,8 @@ public class DeviceProfileController extends BaseController {
|
||||
return checkNotNull(deviceProfileService.findDefaultDeviceProfileInfo(getTenantId()));
|
||||
}
|
||||
|
||||
@ApiOperation(value = "Get time-series keys (getTimeseriesKeys)",
|
||||
notes = "Get a set of unique time-series keys used by devices that belong to specified profile. " +
|
||||
@ApiOperation(value = "Get time series keys (getTimeseriesKeys)",
|
||||
notes = "Get a set of unique time series keys used by devices that belong to specified profile. " +
|
||||
"If profile is not set returns a list of unique keys among all profiles. " +
|
||||
"The call is used for auto-complete in the UI forms. " +
|
||||
"The implementation limits the number of devices that participate in search to 100 as a trade of between accurate results and time-consuming queries. " +
|
||||
|
||||
@ -243,8 +243,8 @@ public class TelemetryController extends BaseController {
|
||||
(result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, scope, keysStr));
|
||||
}
|
||||
|
||||
@ApiOperation(value = "Get time-series keys (getTimeseriesKeys)",
|
||||
notes = "Returns a set of unique time-series key names for the selected entity. " +
|
||||
@ApiOperation(value = "Get time series keys (getTimeseriesKeys)",
|
||||
notes = "Returns a set of unique time series key names for the selected entity. " +
|
||||
"\n\n" + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
|
||||
@PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
|
||||
@RequestMapping(value = "/{entityType}/{entityId}/keys/timeseries", method = RequestMethod.GET)
|
||||
@ -256,10 +256,10 @@ public class TelemetryController extends BaseController {
|
||||
(result, tenantId, entityId) -> Futures.addCallback(tsService.findAllLatest(tenantId, entityId), getTsKeysToResponseCallback(result), MoreExecutors.directExecutor()));
|
||||
}
|
||||
|
||||
@ApiOperation(value = "Get latest time-series value (getLatestTimeseries)",
|
||||
notes = "Returns all time-series that belong to specified entity. Use optional 'keys' parameter to return specific time-series." +
|
||||
@ApiOperation(value = "Get latest time series value (getLatestTimeseries)",
|
||||
notes = "Returns all time series that belong to specified entity. Use optional 'keys' parameter to return specific time series." +
|
||||
" The result is a JSON object. The format of the values depends on the 'useStrictDataTypes' parameter." +
|
||||
" By default, all time-series values are converted to strings: \n\n"
|
||||
" By default, all time series values are converted to strings: \n\n"
|
||||
+ MARKDOWN_CODE_BLOCK_START
|
||||
+ LATEST_TS_NON_STRICT_DATA_EXAMPLE
|
||||
+ MARKDOWN_CODE_BLOCK_END
|
||||
@ -282,8 +282,8 @@ public class TelemetryController extends BaseController {
|
||||
(result, tenantId, entityId) -> getLatestTimeseriesValuesCallback(result, user, entityId, keysStr, useStrictDataTypes));
|
||||
}
|
||||
|
||||
@ApiOperation(value = "Get time-series data (getTimeseries)",
|
||||
notes = "Returns a range of time-series values for specified entity. " +
|
||||
@ApiOperation(value = "Get time series data (getTimeseries)",
|
||||
notes = "Returns a range of time series values for specified entity. " +
|
||||
"Returns not aggregated data by default. " +
|
||||
"Use aggregation function ('agg') and aggregation interval ('interval') to enable aggregation of the results on the database / server side. " +
|
||||
"The aggregation is generally more efficient then fetching all records. \n\n"
|
||||
@ -308,7 +308,7 @@ public class TelemetryController extends BaseController {
|
||||
@RequestParam(name = "interval", defaultValue = "0") Long interval,
|
||||
@Parameter(description = "A string value representing the timezone that will be used to calculate exact timestamps for 'WEEK', 'WEEK_ISO', 'MONTH' and 'QUARTER' interval types.")
|
||||
@RequestParam(name = "timeZone", required = false) String timeZone,
|
||||
@Parameter(description = "An integer value that represents a max number of timeseries data points to fetch." +
|
||||
@Parameter(description = "An integer value that represents a max number of time series data points to fetch." +
|
||||
" This parameter is used only in the case if 'agg' parameter is set to 'NONE'.", schema = @Schema(defaultValue = "100"))
|
||||
@RequestParam(name = "limit", defaultValue = "100") Integer limit,
|
||||
@Parameter(description = "A string value representing the aggregation function. " +
|
||||
@ -406,8 +406,8 @@ public class TelemetryController extends BaseController {
|
||||
}
|
||||
|
||||
|
||||
@ApiOperation(value = "Save or update time-series data (saveEntityTelemetry)",
|
||||
notes = "Creates or updates the entity time-series data based on the Entity Id and request payload." +
|
||||
@ApiOperation(value = "Save or update time series data (saveEntityTelemetry)",
|
||||
notes = "Creates or updates the entity time series data based on the Entity Id and request payload." +
|
||||
SAVE_TIMESERIES_REQUEST_PAYLOAD +
|
||||
"\n\n 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. "
|
||||
+ INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
|
||||
@ -429,8 +429,8 @@ public class TelemetryController extends BaseController {
|
||||
return saveTelemetry(getTenantId(), entityId, requestBody, 0L);
|
||||
}
|
||||
|
||||
@ApiOperation(value = "Save or update time-series data with TTL (saveEntityTelemetryWithTTL)",
|
||||
notes = "Creates or updates the entity time-series data based on the Entity Id and request payload." +
|
||||
@ApiOperation(value = "Save or update time series data with TTL (saveEntityTelemetryWithTTL)",
|
||||
notes = "Creates or updates the entity time series data based on the Entity Id and request payload." +
|
||||
SAVE_TIMESERIES_REQUEST_PAYLOAD +
|
||||
"\n\n 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. "
|
||||
+ "\n\nThe ttl parameter takes affect only in case of Cassandra DB."
|
||||
@ -454,21 +454,21 @@ public class TelemetryController extends BaseController {
|
||||
return saveTelemetry(getTenantId(), entityId, requestBody, ttl);
|
||||
}
|
||||
|
||||
@ApiOperation(value = "Delete entity time-series data (deleteEntityTimeseries)",
|
||||
notes = "Delete time-series for selected entity based on entity id, entity type and keys." +
|
||||
" Use 'deleteAllDataForKeys' to delete all time-series data." +
|
||||
@ApiOperation(value = "Delete entity time series data (deleteEntityTimeseries)",
|
||||
notes = "Delete time series for selected entity based on entity id, entity type and keys." +
|
||||
" Use 'deleteAllDataForKeys' to delete all time series data." +
|
||||
" Use 'startTs' and 'endTs' to specify time-range instead. " +
|
||||
" Use 'deleteLatest' to delete latest value (stored in separate table for performance) if the value's timestamp matches the time-range. " +
|
||||
" Use 'rewriteLatestIfDeleted' to rewrite latest value (stored in separate table for performance) if the value's timestamp matches the time-range and 'deleteLatest' param is true." +
|
||||
" The replacement value will be fetched from the 'time-series' table, and its timestamp will be the most recent one before the defined time-range. " +
|
||||
" The replacement value will be fetched from the 'time series' table, and its timestamp will be the most recent one before the defined time-range. " +
|
||||
TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(responseCode = "200", description = "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(responseCode = "200", description = "Time series for the selected keys in the request was removed. " +
|
||||
"Platform creates an audit log event about entity time series removal with action type 'TIMESERIES_DELETED'."),
|
||||
@ApiResponse(responseCode = "400", description = "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(responseCode = "401", description = "User is not authorized to delete entity timeseries for selected entity. Most likely, User belongs to different Customer or Tenant."),
|
||||
@ApiResponse(responseCode = "401", description = "User is not authorized to delete entity time series for selected entity. Most likely, User belongs to different Customer or Tenant."),
|
||||
@ApiResponse(responseCode = "500", description = "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."),
|
||||
"Platform creates an audit log event about entity time series removal with action type 'TIMESERIES_DELETED' that includes an error stacktrace."),
|
||||
})
|
||||
@PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
|
||||
@RequestMapping(value = "/{entityType}/{entityId}/timeseries/delete", method = RequestMethod.DELETE)
|
||||
@ -649,12 +649,12 @@ public class TelemetryController extends BaseController {
|
||||
try {
|
||||
telemetryJson = JsonParser.parseString(requestBody);
|
||||
} catch (Exception e) {
|
||||
return getImmediateDeferredResult("Unable to parse timeseries payload: Invalid JSON body!", HttpStatus.BAD_REQUEST);
|
||||
return getImmediateDeferredResult("Unable to parse time series payload: Invalid JSON body!", HttpStatus.BAD_REQUEST);
|
||||
}
|
||||
try {
|
||||
telemetryRequest = JsonConverter.convertToTelemetry(telemetryJson, System.currentTimeMillis());
|
||||
} catch (Exception e) {
|
||||
return getImmediateDeferredResult("Unable to parse timeseries payload. Invalid JSON body: " + e.getMessage(), HttpStatus.BAD_REQUEST);
|
||||
return getImmediateDeferredResult("Unable to parse time series payload. Invalid JSON body: " + e.getMessage(), HttpStatus.BAD_REQUEST);
|
||||
}
|
||||
List<TsKvEntry> entries = new ArrayList<>();
|
||||
for (Map.Entry<Long, List<KvEntry>> entry : telemetryRequest.entrySet()) {
|
||||
@ -663,7 +663,7 @@ public class TelemetryController extends BaseController {
|
||||
}
|
||||
}
|
||||
if (entries.isEmpty()) {
|
||||
return getImmediateDeferredResult("No timeseries data found in request body!", HttpStatus.BAD_REQUEST);
|
||||
return getImmediateDeferredResult("No time series data found in request body!", HttpStatus.BAD_REQUEST);
|
||||
}
|
||||
SecurityUser user = getCurrentUser();
|
||||
return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.WRITE_TELEMETRY, entityIdSrc, (result, tenantId, entityId) -> {
|
||||
|
||||
@ -202,8 +202,8 @@ public class DeviceApiController implements TbTransportService {
|
||||
return responseWriter;
|
||||
}
|
||||
|
||||
@Operation(summary = "Post time-series data (postTelemetry)",
|
||||
description = "Post time-series data on behalf of device. "
|
||||
@Operation(summary = "Post time series data (postTelemetry)",
|
||||
description = "Post time series data on behalf of device. "
|
||||
+ "\n Example of the request: "
|
||||
+ TS_PAYLOAD
|
||||
+ REQUIRE_ACCESS_TOKEN)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user