Analogsummary

Description

Retrieves analog statistics for the specified tags.

URL

/AnalogSummary

Method

GET 

Required Parameters

• FQN=[string ]
  The fully qualified name for the tag. A fully qualified name uses the format: datasource.tagname.

• StartDateTime=[DateTimeOffset]
  The starting date and time. This is always specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 1985-04-12T23:20:50.52435Z

• EndDateTime=[DateTimeOffset]
  The ending date and time. This is always specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 1985-04-12T23:20:50.52435Z

Optional Parameters

• RetrievalMode=[string]
  Possible values are: Cyclic, Full.
  Default is Cyclic.

• Resolution=[Int]
  In milliseconds. Any positive integer.

• SliceBy=[Int|Discrete|String]
  Performs dynamic resolution/cycle computation by tags. Returns one Analog Summary value per tag per dynamic cycle with start and end date time.
  SliceBy can support up to 10 tags.

• SliceByValue=[string]
  Specifies the filter criterion to get the summary values for SlicedBy, based on that filter value.

• OPCQuality=[Int32]
  Defines the OPC quality for the data.

  Normal OPC quality retrieval logic is applied if all the point found and processed for this row have GOOD quality. If they all have the same GOOD quality, then that quality is returned.

  If there is a gap in the entire calculation cycle, then BAD quality is returned for the tag.

  For any other scenario with any mixture of GOOD and BAD points, a DOUBTFUL OPC quality (64) is returned.

• PercentGood=[Double]
  The ratio of the number of rows that have "good" quality to the total number of rows in the retrieval cycle, expressed as a percentage in the range 0 to 100.

• First=[Double]
  If at least one non-NULL point exists for the tag in question within the retrieval cycle, then the value returned is the first point stored with a time stamp within the retrieval cycle. If no points exist within the retrieval cycle, then the value returned is the current value at the cycle start time.

  If no non-NULL points can be found, then NULL is returned.

• FirstDateTime=[DateTimeOffset]
  Timestamp associated with first value. This might be earlier than StartDateTime if this is the initial value for the retrieval cycle.

• Last=[Double]
  If at least one non-NULL point exists for the tag in question within the retrieval cycle, then the value returned is the last point stored with a time stamp within the retrieval cycle. If no points exist within the retrieval cycle, then the value returned is the current value at the cycle start time.

  If no non-NULL points can be found, then NULL is returned.

• LastDateTime=[DateTimeOffset]
  Timestamp associated with last value. This might be earlier than StartDateTime if this is the initial value for the retrieval cycle.

• Minimum=[Double]
  If at least one non-NULL point exists for the tag in question within the retrieval cycle, then the value returned is the minimum point stored with a time stamp within the retrieval cycle. If no points exist within the retrieval cycle, then the value returned is the current value at the cycle start time.

  If no non-NULL points can be found, then NULL is returned.

• MinDateTime=[DateTimeOffset]
  Timestamp associated with Min value. NULL if Min is NULL.

• Maximum=[Double]
  If at least one non-NULL point exists for the tag in question within the retrieval cycle, then the value returned is the maximum point stored with a time stamp within the retrieval cycle. If no points exist within the retrieval cycle, then the value returned is the current value at the cycle start time.

  If no non-NULL points can be found, then NULL is returned.

• MaxDateTime=[DateTimeOffset]
  Timestamp associated with Max value. NULL if Max is NULL.

• Average=[Double]
  Time weighted average value of retrieval cycle. This is calculated by using the individual summary averages. The calculation is "Sum(average * delta t) / Total time of average in all cycles" - delta t is prorated for any partially contained storage cycles For analog tags, the calculation is "Sum(value * delta t) / Total time. (This is like the values returned by an Average query against the History table for a cycle of the same length, where the History row DateTime is the same as the EndDateTime here.)

• StdDev=[Double]
  Time weighted standard deviation value of the retrieval cycle. The value is calculated using time weighted sums (Integrals) and time weighted sums of squares (IntegralOfSquares) values, prorated for any partially contained storage cycles.

  For analog tags, similar StdDev values are produced for each cycle.

• Integral=[Double]
  Area under value curve of retrieval cycle. The calculation is "Sum(value * delta t) / Total time of integral in all cycles" - delta t is prorated for any partially contained storage cycles For analog tags, the calculation is "Sum(value * delta t) / Total time. (This is like the values returned by an Integral query against the History table for a cycle of the same length, where the History row DateTime is the same as the EndDateTime here.)

  For analog tags, similar Integral values are produced for each cycle.

• Count=[Double]
  Number of values in a particular cycle.

Sample Query

Scenario 1

This query produces a list of tags that end with "level". In this case, the user doesn’t know the fully qualified name (FQN) of a specific tag and wants a short list of possible matches.

https://online.wonderware.[DOMAINSUFFIX]/apis/historian/v2/AnalogSummary?TagFilter=
endswith(FQN, 'level').

See more TagFilter examples.

Scenario 2

This query produces a list of values with analog summary for the tank_level tag.

Notice that this example uses a fully qualified name ("Baytown.tank_level"), which is a combination of a data source name ("Baytown") and a tagname ("tank_level").

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/AnalogSummary
?$filter=FQN+eq+'Baytown.tank_level'

Because this query specifies no start or end time and no resolution, these defaults are used for the returned results:

• EndTime defaults to DateTime.UtcNow

• StartTime defaults to one hour before EndTime

• Resolution defaults toTimespan

• Count defaults to1 (number of returned rows)

Scenario 3

This query produces a list of tag values with analog summary data. The "$filter" clause narrows the results further by specifying these parameters:

• Fully qualified name of the tag (FQN+eq+'Baytown.tank_level')

• Start and end times

• Result set returned at 1 hour intervals (Resolution=3600000). There are 3.6 million milliseconds in an hour.

  https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/AnalogSummary
  ?$filter=FQN+eq+'Baytown.tank_level'+and+StartDateTime+ge+2017-05-14T00:00:00.000Z
  +and+EndDateTime+le+2017-05-16T00:00:00.000Z&Resolution=3600000

Scenario 4

This query specifies only StartTime and Resolution (600000 ms, or 10 minutes), but no EndTime.

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/AnalogSummary
?$filter=FQN+eq+'Baytown.tank_level'
and StartDateTime ge 2017-06-29T00:00:00Z&Resolution=600000

In this case, Insight assumes:

• EndTime defaults to DateTime.UtcNow

The number of rows returned (Count) depends on the StartTime and EndTime.

Scenario 5

This query specifies only EndTime, but no StartTime or Resolution.

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/AnalogSummary
?$filter=FQN+eq+'Baytown.tank_level'and EndDateTime le 2017-06-29T00:00:00Z'

In this case, Insight assumes:

• StartTime defaults to one hour before EndTime

• Resolution defaults toTimespan

• Count defaults to1 (number of returned rows)

Scenario 6

This query specifies uses SliceBy.

https://online.wonderware.com/apis/Historian/v2/AnalogSummary?$
filter=FQN+eq+'Baytown.R21.Level'+and+StartDateTime+ge+2019-03-05T00:00:00.000Z+
and+EndDateTime+le+2019-03-05T12:00:00.000Z&SliceBy=Baytown.R21.Batch

In this case, Insight calculates an analog summary for the Baytown..R21.Level tag and batches the results per value for the Baytown.R21.Batch tag.