IoT Time Series Client for Java¶

Introduction¶

The IoT Time Series Java client allows you to interact with time series data related to assets. Refer to IoT Time Series for more information about the service.

Hint

In the IoT context, assets are referred to as entity and aspects as propertyset.

Time Series Operations¶

Client Name: TimeseriesClient

Read latest Time Series Data¶

Read the latest value of time series data for a single entity and property set.

// Construct the TimeseriesClient object
TimeseriesClient timeseriesClient = TimeseriesClient.builder()
                                        .mindsphereCredentials(credentials)
                                        .restClientConfig(config)
                                        .build();

TimeseriesData timeseriesData = null;
try {
    timeseriesData = timeseriesClient.getLatestTimeseries(entity, propertySetName);
} catch (MindsphereException e) {
    // Exception handling
}

Read Time Series Data¶

This operation invokes the IoT Time Series API to:

Read time series data for a single entity and property set.
Return data for a specified time range.
Return the latest value, if no range is provided.
Return time series data for selected fields and limit.

//Construct TimeseriesClient object as shown above
List<TimeseriesData> timeseriesDataList = null;
try {
    timeseriesDataList = timeseriesClient.getTimeseries(entity, propertySetName, from, to, limit, select);
} catch (MindsphereException e) {
    // Exception handling
}

Write Time Series Data¶

Write the time series for a single entity and property set. The existing time series data will be overwritten.

Note

The maximum size of a write payload is 1 MB.

//Construct TimeseriesClient object as shown above

boolean success = false;
try {
    success = timeseriesClient.putTimeSeries(entity, propertySetName, timeSeriesList, sync);
} catch (MindsphereException e) {
    // Exception handling
}

Import Time Series Data¶

Import or update time series for a single entity and property set. The existing time series data is overwritten.

//Construct TimeseriesClient object as shown above

boolean success = false;
try {
    success = timeseriesClient.importTimeseries(entity, propertySetName, timeseriesFile, sync);
} catch (MindsphereException e) {
    // Exception handling
}

Delete Time Series Data¶

Delete time series entity and property set within a given time range. It also deletes data for all properties within a property set.

Note

Only data of up to 6 months can be deleted at once.

//Construct TimeseriesClient object as shown above

boolean success = false;
try {
    success = timeseriesClient.deleteTimeSeries(entity, propertySetName, from, to, sync);
} catch (MindsphereException e) {
    // Exception handling
}

Page Iterators¶

The page iterator for the IoT Time Series API client, TimeseriesPageIterator can be used to get a specific page, the next page or the previous page of data.

The page iterators currently support the following operations:

getPage(Integer pageNumber);
next();
previous();

The page iterator instantiation requires an IoT Time Series API client, an entity, a property set name, a date range (from and to dates) and a page size. If the page size is not provided, it defaults to 2000.

Code sample for the IoT Time Series page iterator instantiation and usage:

try {
    //Create the timeseries client
    TimeseriesClient timeseriesClient =  TimeseriesClient.builder()
                                            .mindsphereCredentials(credentials)
                                            .restClientConfig(config)
                                            .build();
    // Create the timeseries page iterator
    TimeseriesPageIterator timeseriesPageIterator =
        new TimeseriesPageIterator(timeseriesClient, entityId, propertySetName, fromDateString, toDateString, pageSize);

    List<TimeseriesData> timseriesDataList = timeseriesPageIterator.getPage(10);
} catch (MindsphereException e) {
    // Exception handling
}