Differences

This shows you the differences between two versions of the page.

--- dev:app_store_data_requests [2017/08/01 11:42] – created su
+++ dev:app_store_data_requests [2019/06/26 13:49] – su
@@ Line 1: / Line 1: @@
-**GET Gestalt/api/data/values/{dsn}?tag[0]={tag[0]}&tag[1]={tag[1]}&function={function}&start={start}&end={end}&points={points}&step={step}&annotations={annotations}
+**GET Gestalt/api/data/values/{dsn}?tag={tag_name_1}&tag={tag_name_2}&function={function}&start={start}&end={end}&step={step}
 **
-For //function// field supported values vary from driver to driver, but it's safe to assume that the following values will be supported:
+Performs a tag data query on a data source.
-  * **RAW** - for raw historical data
+//For .NET developers, we recommend that you use the ''IntelligentPlant.AppStore.Client'' NuGet package to query for data, available on the App Store NuGet feed (https://appstore.intelligentplant.com/nuget/nuget/).//
+For the //function// field supported values vary from driver to driver, but it's safe to assume that the following values will be supported:
+  * **RAW** - for raw historical data (**not recommended** due to the potential high volume of data returned)
   * **NOW** - for the current snapshot value
   * **INTERP** - for interpolated data
@@ Line 12: / Line 16: @@
   * **AVG** - mean value calculated at each sample interval over a time range.
-For start and end, you can specify either an absolute value or a relative value.  Absolute values should be specified in ISO 8601 format (i.e. yyyy-MM-ddTHH:mm:ss).  You can also include a suffix of Z to indicate a UTC time stamp, or you can specify an offset from UTC.  If no time zone information is provided, the date is assumed to be UTC.  For example, if you wanted to specify 3:30:35am today in Central US time, you could specify 2017-08-01T03:30:35-06:00.
+For ''start'' and ''end'', you can specify either an absolute value or a relative value.  Absolute values should be specified in ISO 8601 format (i.e. ''yyyy-MM-ddTHH:mm:ss'').  You can also include a suffix of ''Z'' to indicate a UTC time stamp, or you can specify an offset from UTC.  If no time zone information is provided, the date is assumed to be UTC.  For example, if you wanted to specify 3:30:35am on 01 August 2017 in Central US time, you could specify ''2017-08-01T03:30:35-06:00''.
-Relative values can be specified using * to represent the current time, *-1d = "1 day before current time", *-27.5m = "27.5 minutes before current time", and so on.  Possible time units when specifying a relative time stamp are: d, h, m, s, ms.
+Relative values can be specified using ''*'' to represent the current time.  For example: ''*-1d'' = "1 day before current time", ''*-27.5m'' = "27.5 minutes before current time", and so on.  Possible time units when specifying a relative time stamp are: ''d'', ''h'', ''m'', ''s'', ''ms''.
-For the current value, specify NOW for the function parameter.  When you use NOW, you don't need to specify a start or end time.  Additionally, you don't need to specify tag[0], tag[1] and so on for the tag names; you should just keep on repeating the tag parameter e.g. to get the current snapshot value for tags called Tag1 and Tag2, you would use:
+For the current value, specify ''NOW'' for the ''function'' parameter.  When you use ''NOW'', you don't need to specify a start or end time.  For example, to get the current snapshot value for tags called //Tag1// and //Tag2//, you would use:
-gestalt/api/data/values/{my_dsn}?function=NOW&tag=Tag1&tag=Tag2
+''gestalt/api/data/values/{my_dsn}?function=NOW&tag=Tag1&tag=Tag2''
-To get all raw data in a time period, you use the RAW function.  When asking for raw data, you don't need to specify a sample interval or a point count. RAW queries should be considered unsafe – any code that requires this will likely perform badly in the appstore – and the developer should consider how to make use of aggregates to be able to efficiently request data and process it. Basically RAW data requests are discouraged, due to the high size of data that might potentially be returned:
+To get all raw data in a time period, you use the ''RAW'' function.  When asking for raw data, you don't need to specify a sample interval or a point count:
-gestalt/api/data/values/{my_dsn}?function=RAW&tag=Tag1&start=*-1d&end=*
+''gestalt/api/data/values/{my_dsn}?function=RAW&tag=Tag1&start=*-1d&end=*''
-For other functions, you need to provide either a step parameter that specifies the sample interval (e.g. 1m, 5m, 8h, 3d), or a points parameter that specified the number of samples you want to be returned:
+''RAW'' queries are **strongly discouraged**, due to the potentially large data set that must be sent over the wire.
-gestalt/api/data/values/{my_dsn}?function=INTERP&tag=Tag1&tag=tag2&start=*-1d&end=*&step=1h
+For other functions, you need to provide either a ''step'' parameter that specifies the sample interval (e.g. ''1m'', ''5m'', ''8h'', ''3d''), or a ''points'' parameter that specified the number of samples you want to be returned:
-gestalt/api/data/values/{my_dsn}?function=PLOT&tag=Tag1&tag=tag2&start=*-1d&end=*&points=750
-We also offer an interface that can stream real-time value changes to you as they occur, instead of you having to make periodic polling requests for NOW data, although this requires a client for Microsoft's SignalR platform. SignalR clients are available for Java, Python, and various other languages, if this would be of interest.
+''gestalt/api/data/values/{my_dsn}?function=INTERP&tag=Tag1&tag=tag2&start=*-1d&end=*&step=1h''
+''gestalt/api/data/values/{my_dsn}?function=PLOT&tag=Tag1&tag=tag2&start=*-1d&end=*&points=750''
-More info on App Store API can be found [[https://appstore.intelligentplant.com/ApiHelp/Api/GET-Gestalt-api-data-values-dsn_tag[0]_tag[1]_function_start_end_points_step_annotations|here]]
+More info on App Store API can be found [[https://appstore.intelligentplant.com/ApiHelp]]