browse

2 Minute Read

hisReadMany 

The hisReadMany API is used to read a time-series data from a specific historized point. 

The /hisReadMany operation is an operation in reading multiple haystack based data. It is a mere read operation, but allows for multiple IDs to be passed in the request to read data over a range of days for integrators to fetch trending data. 

Request: A grid with a single row and following columns: 

  • id: Ref identifier of historized point 
  • range: Str encoding of a date-time range 

Request Parameters are as follows:

Parameter Name In Required Type
ids query true String array
range query true String

 

Response: Rows of the result grid represent timestamp/value pairs with a DateTime ts column and a val column for each scalar value which it represents. In addition to this the grid metadata includes:

  • id: Ref of the point we read 
  • hisStart: DateTime timestamp for inclusive range start in point's time zone 
  • hisEnd: DateTime timestamp for exclusive range end in point's time zone 

The range Str is formatted as one of the following options: 

  • "today" 
  • "yesterday" 
  • "{date}" 
  • "{date},{date}" 
  • "{dateTime},{dateTime}" 
  • "{dateTime}" // anything after the given timestamp 

It should be noted that ranges are inclusive of start timestamp and exclusive of end timestamp. The  {date} and {dateTime} options must be correctly encoded. Date based ranges are always inferred to be from midnight of starting date to midnight of the day after ending date using the timezone of the point being queried. 

Clients should query the range using the configured timezone of the point. Although, if a different timezone is specified in the range, then the servers must convert to the point's configured timezone before executing the query. Let us consider an example below:

// request 
 ids,range 
@someTemp,"2012-10-01" 

@somePoint,"2012-10-01" 

Response: 200 OK 

Example: 

 hisStart:2020-01-01T00:00:00Z hisEnd:2020-01-02T00:00:00Z id,data,his,point,tz,unit  

@example-point-a,[ 

{ts:2020-01-01T12:00:00-04:00 New_York val:67.0%}, 

{ts:2020-01-01T12:01:00-04:00 New_York val:67.1%}], 

M,M,"New_York","%"  

@example-point-b,[ 

{ts:2020-01-01T12:00:00-04:00 Chicago val:71.5°F}, 

{ts:2020-01-01T12:01:00-04:00 Chicago val:71.2°F}], 

M,M,"Chicago","°F" 

Procedure to Execute a HisReadMany API request

Note: You can only sample points data or write to points data of the sites, to which you been added as secondary facility Manager, and you have access to the site via the facilisight.

 From the Developer portal home page

  • Click the Profile option.

mceclip0.png

The user profile screen is displayed with the user details, and the details related to the subscriptions subscribed for.

Under the products subscribed for, locate the subscription key for the relevant product.

For this example we are trying use the product Staging Readwrite subscription.

  • Click the option shown to view the subscription keys or simply copy the subscription key to be used to generate the Bearer token.

mceclip10.png

  • Click the API's option on the top.

The API's screen is displayed with the list of API's the user is authorized to use.

For this demo we will be using the Haystack (Staging) API.

  • Click the API Haystack (Staging).

mceclip12.png

The Haystack (Staging) API screen is displayed with the details about the API.

Note: In order to start sampling data using this Haystack (Staging) API, the user needs to generate a bearer token using the API 75Auth {Staging) as show above using the information shown in Oauth API

  • Click Try it to access the API.

mceclip9.png

The Try it window to try the API is displayed.

  • Select the Primary: Staging Readwrite under the subscription key field.

mceclip8.png

  • Access the site explorer in the Facilisight to locate a point with the historized values.

From the site explorer in Facilisight:

  • Locate a point ID for which you would like to retrieve the historized values for, as below.

mceclip7.png

For this example we are considering the current temperature and humidity point to retrieve their historized values.

  • Enter the point IDs into the ID field enter the point Id with @ as a prefix, multiple Ids can be added to fetch data, separated with commas(,) .
  • Enter a date range or today or yesterday in the range field  
  • Scroll further locate the Header section.

The header section should have the following headers.

mceclip5.png

  • Paste the subscription key copied from the profile screen into the header option  Ocp-Apim-Subscription-Key.
  • Paste the bearer token generated into the header option  Authorization  in the format shown above, with a "Bearer" and  followed by the token generated

 "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyRGF0YSI6eyJ1c2VySWQiOiI0M2JjNGRlZC01YWQxLTRkZTUtOGU1OC1mYTg1YTM4ODRhNzIiLCJlbWFpbElkIjoibWNoYW5kcmFzZWthckA3NWYuaW8iLCJzdHJhdGVneSI6InBhc3MiLCJpc1N1cHBvcnQiOjF9LCJhY2Nlc3NBbGxvd2VkIjp0cnVlLCJyb2xlIjoiYXBwIiwiZ2xvYmFsU2Vzc2lvbklEIjoicm5iTlpiMUZIelI0RXd4eHJuOFNrT3Z6MkFIX19zbVQiLCJhcHBOYW1lIjoiZ2F0ZWtlZXBlcjc1ZiIsImVudiI6InN0YWdpbmciLCJpYXQiOjE2NTE3MzYzMTQsImV4cCI6MTY1MTgyMjcxNCwiaXNzIjoiNzVmIn0.dLZIMK2R6B0JgFjDjkfR3GY1dDEzuiB82Wrvwha8bcaLH4_sUxM4Pe_cWNGES3Jth7xP4ug8_cKe-8lpNezXD-B43KxbXy9t8ng9RXkUfvrPvDAua_xEKaw3eep1MdzGtZCwau2gCJp12zq33JM8oi8RqAd-3u6b6u5DwEO6pz1HlHn1JMKcUkLXAlo61WtTcePmBR1SDky0vWQnh-clHORjKFrpJB2a-jewB7raYBrMOFUNperC-dPZViqX3dC6SdGPSgAOD14e-XfrGHj6a1jSYOh4wtsG89mz5h03VC78QJ7JcPoyqgNVKP30QlmqO0tyCrKhwkzNnS39z-xTNA"

With the below request format on:

mceclip6.png

  • Click Send to sample the data.

The response is generated along with the Historized data points information as below for part of the Humidity values,

HTTP response

HTTP/1.1 200 OK

content-encoding: gzip
content-type: application/json
date: Thu, 05 May 2022 07:43:01 GMT
transfer-encoding: chunked
vary: origin,access-control-request-method,access-control-request-headers,accept-encoding

{
    "metadata": {
        "ver": "3.0",
        "hisStart": "t:2022-05-05T00:00:00+05:30 Colombo",
        "hisEnd": "t:2022-05-05T13:13:01.365859+05:30 Colombo"
    },
    "cols": [{
        "name": "id"
    }, {
        "name": "air"
    }, {
        "name": "cpu"
    }, {
        "name": "cur"
    }, {
        "name": "current"
    }, {
        "name": "data"
    }, {
        "name": "dis"
    }, {
        "name": "equipRef"
    }, {
        "name": "floorRef"
    }, {
        "name": "group"
    }, {
        "name": "his"
    }, {
        "name": "hisInterpolate"
    }, {
        "name": "humidity"
    }, {
        "name": "hyperstat"
    }, {
        "name": "kind"
    }, {
        "name": "logical"
    }, {
        "name": "point"
    }, {
        "name": "roomRef"
    }, {
        "name": "sensor"
    }, {
        "name": "siteRef"
    }, {
        "name": "temp"
    }, {
        "name": "tz"
    }, {
        "name": "unit"
    }, {
        "name": "zone"
    }],
    "rows": [{
        "id": "r:73651d0f-f0d9-4740-99c3-37b713fc90f5",
        "air": "m:",
        "cpu": "m:",
        "cur": "m:",
        "current": "m:",
        "data": [{
            "ts": "t:2022-05-05T00:00:00+05:30 Colombo",
            "val": "n:57 %"
        }, {
            "ts": "t:2022-05-05T00:01:00+05:30 Colombo",
            "val": "n:57 %"
        }, {
            "ts": "t:2022-05-05T00:02:00+05:30 Colombo",
            "val": "n:57.1 %"
        }, {
            "ts": "t:2022-05-05T00:03:00+05:30 Colombo",
            "val": "n:57.1 %"
        }, {
            "ts": "t:2022-05-05T00:04:00+05:30 Colombo",
            "val": "n:57 %"
        }, {
            "ts": "t:2022-05-05T00:05:00+05:30 Colombo",
            "val": "n:57.1 %"
        }, {
            "ts": "t:2022-05-05T00:06:00+05:30 Colombo",
            "val": "n:57 %"

And as below for the parts of Temperature

{
        "id": "r:8797285e-7414-48ce-9907-c703ff232b31",
        "air": "m:",
        "cpu": "m:",
        "cur": "m:",
        "current": "m:",
        "data": [{
            "ts": "t:2022-05-05T00:00:00+05:30 Colombo",
            "val": null
        }, {
            "ts": "t:2022-05-05T00:01:00+05:30 Colombo",
            "val": null
        }, {
            "ts": "t:2022-05-05T00:02:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:03:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:04:00+05:30 Colombo",
            "val": "n:84.9 °F"
        }, {
            "ts": "t:2022-05-05T00:05:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:06:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:07:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:08:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:09:00+05:30 Colombo",
            "val": "n:85.1 °F"
        }, {
            "ts": "t:2022-05-05T00:10:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:11:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:12:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:13:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:14:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:15:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:16:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:17:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:18:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:19:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:20:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:21:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:22:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:23:00+05:30 Colombo",
            "val": "n:85 °F"
        }, {
            "ts": "t:2022-05-05T00:24:00+05:30 Colombo",
            "val": "n:85 °F"

And similarly an application can be connected to start reading the data using the bearer token generated and using the point ID from the sites assigned to the user

 

Previous
Next

Comments

0 comments

Please sign in to leave a comment.

Was this article helpful?

0 out of 0 found this helpful
Powered by Zendesk