Domorela's Blog: Virtual Lab with Domorela DMRL1: Testing with REST API: Querying Historical Data

In our last article about the Virtual Lab, we'll talk about how to query Histories defined in the Virtual Lab. As we explained in the article dedicated to describe REST API Histories Service, Domorela collects historical data from the installation, stores them in its permanent memory and publishes a REST API service allowing to query them in order to obtain raw instant data with timestamps or calculated data within periods established by a query filter.

To  perform a raw query we'll send a POST to the URL of the service, including a relative URI as ref parameter, with an obix:HistoryFilter record:

$ curl --request POST -b .cookies --data-binary "@filtro.xml" "https://$host:8083/admin/api/histories?ref=P085D0_GA72/query/"

were the file filtro.xml contains an oBIX record like the below one:

<obj is="obix:HistoryFilter">
  <int name="limit" val="500" />
  <abstime name="start" val="2021-04-01T00:00:00.000+01:00" tz="Europe/Madrid"/>
  <abstime name="end" val="2021-05-08T00:00:00.000+01:00" tz="Europe/Madrid"/>
</obj>

The result of the raw query returns an obix:HistoryQueryOut object in the form:

<obj href="/obix/histories/knx/P085D0_GA71/" is="obix:HistoryQueryOut">
  <int name="count" val="192"/>
  <abstime name="start" val="2021-05-05T21:00:00.001Z"/>
  <abstime name="end" val="2021-05-07T22:54:00.001Z"/>
  <list name="data" of="#RecordDef obix:HistoryRecord">
    <obj>
      <real name="value" val="23.0" display="Temperatura CPD"/>
      <abstime name="timestamp" val="2021-05-05T21:00:00.001Z"/>
    </obj>
    <obj>
      <real name="value" val="23.0" display="Temperatura CPD"/>
      <abstime name="timestamp" val="2021-05-05T21:06:00.001Z"/>
    </obj>
    .
    .
    .
    <obj>
      <real name="value" val="23.0" display="Temperatura CPD"/>
      <abstime name="timestamp" val="2021-05-07T22:54:00.001Z"/>
    </obj>
  </list>
</obj>

To perform a rollup query we'll change the ref URI and the obix:HistoryFilter record as shown below:

$ curl --request POST -b .cookies --data-binary "@filtro-rollup.xml" "https://$host:8083/admin/api/histories?ref=P085D0_GA72/rollup/"

were the file filtro-rollup.xml contains an oBIX record like the below one:

<obj is="obix:HistoryFilter">
  <int name="limit" val="500" />
  <reltime name="interval" val="PT3600S"/>
  <abstime name="start" val="2021-05-01T00:00:00.000Z" />
  <abstime name="end" val="2021-05-09T00:00:00.000Z"/>
</obj>

So the result now is an obix:HistoryRollupOut object like the below one:

<obj href="/obix/histories/knx/P085D0_GA71/" is="obix:HistoryQueryOut">
  <int name="count" val="192"/>
  <abstime name="start" val="2021-05-01T00:00:00.000Z"/>
  <abstime name="end" val="2021-05-09T00:00:00.000Z"/>
  <list name="data" of="obix.HistoryRollupRecord">
    <obj>
      <abstime name="start" val="2021-05-01T00:00:00.000Z"/>
      <abstime name="end" val="2021-05-01T01:00:00.000Z"/>
      <int name="count" val="10"/>
      <real name="min" val="23.0"/>
      <real name="max" val="23.0"/>
      <real name="avg" val="23.0"/>
      <real name="sum" val="230.0"/>
    </obj>
    <obj>
      <abstime name="start" val="2021-05-01T01:00:00.000Z"/>
      <abstime name="end" val="2021-05-01T02:00:00.000Z"/>
      <int name="count" val="10"/>
      <real name="min" val="23.0"/>
      <real name="max" val="23.0"/>
      <real name="avg" val="23.0"/>
      <real name="sum" val="230.0"/>
    </obj>
    .
    .
    .
    <obj>
      <abstime name="start" val="2021-05-08T23:00:00.000Z"/>
      <abstime name="end" val="2021-05-09T00:00:00.000Z"/>
      <int name="count" val="9"/>
      <real name="min" val="23.0"/>
      <real name="max" val="23.0"/>
      <real name="avg" val="23.0"/>
      <real name="sum" val="207.0"/>
    </obj>
  </list>
</obj>

As seen above, queries and obtained data are referring to P085D0_GA71. This is the object name of the imported Group Address registered as History, constructed using the object name of the ETS project containing it. In order to know the name of the Group Address, we need to obtain it by querying the KNX Service of the REST API or by other means. This is out of the scope of this series of articles.

As mentioned before, this is the last article dedicated to the Virtual Lab with Domorela DMRL1. In our next article we will move to other topics.