Skip to main content
Sign in

Read API

Abhishek Deb
  • Updated

2 Minute Read

Read API

read is a GET API which is provided for reading haystack entities created in the 75F system. 

The read op is used to read a set of entity records either by their unique identifier or by using a filter. The user can query based on a particular id or can make group queries based on tags within the system. 

 

Format 

https://api-management-75f-dev.azure-api.net/ph/read?filter=Tag1<AND / OR> {Tag2 .. <AND / OR> Tag3......}

 

Request (by filter)

A grid with a single row and following columns: 

  • filter: required Str encoding of filter
  • limit: optional Number that specifies maximum number of entities to return in response 

 

Request (by id): a grid of one or more rows and one column: 

  • id: a Ref identifier 

 

Response: It's a grid with a row for each entity read. If the request is a filter read and no matches were found, it will be an empty grid with no rows. If a read is by id, then each row corresponds to the request grid and its respective row ordering. If an id from the request is not found, the response includes a row of all null cells. 

 

Example of filter read request: 

 
filter,limit 
"point and siteRef==@siteA",1000 

 

Example of read by id with three identifiers: 

 
id 
@vav101.zoneTemp 
@vav102.zoneTemp 
@vav103.zoneTemp 

 

Example of a read response where an id is not found: 

 id,dis,curVal 
@vav101.zoneTemp, "VAV-101 ZoneTemp",74.2°F 
N,N,N 
@vav103.zoneTemp, "VAV-103 ZoneTemp",73.8°F 

Procedure to Execute a Read 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 to use the product QA-Readonly.

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

mceclip6.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 (QA) API.

  • Click the API Haystack (QA).

mceclip5.png

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

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

  • Click Try it to access the API.

mceclip4.png

The Try it window to try the API is displayed.

  • Select the Primary: QA-Readonly under the subscription key field.

mceclip0.png

  • Access the site explorer.

From the site explorer in Facilisight:

  • Try out a filter option as below, so that you can query the same using the API and confirm

mceclip1.png

  • Scroll further locate the Header section.

The header section should have the following headers.

mceclip2.png

The query used under the parameter filter is "siteRef==@70e78150-5699-4598-90a0-de86ec649457 and vav and zone and current and temp.

  • 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.eyJ1c2VyRGF0YSI6eyJ1c2VySWQiOiI5YzAxMjdlNC0zZGZiLTQyMzAtYjEzOC03ZjY2N2ZlMTVkOWEiLCJlbWFpbElkIjoibWNoYW5kcmFzZWthckA3NWYuaW8iLCJzdHJhdGVneSI6InBhc3MiLCJpc1N1cHBvcnQiOjF9LCJhY2Nlc3NBbGxvd2VkIjp0cnVlLCJyb2xlIjoiYXBwIiwiZ2xvYmFsU2Vzc2lvbklEIjoiOTlReXdCNHE4dmNkNVVfZ3RtN0tHY20yMnFoOVh1MUsiLCJhcHBOYW1lIjoiZ2F0ZWtlZXBlcjc1ZiIsImVudiI6InFhIiwiaWF0IjoxNjUxNzQwMjU4LCJleHAiOjE2NTE4MjY2NTgsImlzcyI6Ijc1ZiJ9.KRvpKnyjQNXG8JAnvCVRmn1Kzd2mLR2EKpSYfYogDj-9_JHpD24TyhKcCBEDQiorRqOueaokhKR1nLGM50UeLg4LFr2KWACTlFv6iyT85VclYisVRBnrACIJVvFmNCGdIdt4F5UTLyTNKz03-FAUfBL8JC6z3k_YrzFDhupbISHJCQ5TpaHlAt7j8mx7rcI-m3tmAxnL1vNI4Gz2MzW_oSZ0pRsrFBZhdk2lC63Lnsm9kAlrsxKeuKyDDct-8mBbX-kLLGFwBfoSbgAAgDVDP8_ys-0JZadyX8rFzrm-UGIyIrV7G5DCTQXYsaauICw0hvCiyhpAetaAogssgjXemw"

With the below request format on:

mceclip3.png

  • Click Send to sample 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 08:55:03 GMT
transfer-encoding: chunked
vary: origin,access-control-request-method,access-control-request-headers,accept-encoding

{
    "metadata": {
        "ver": "3.0"
    },
    "cols": [{
        "name": "id"
    }, {
        "name": "air"
    }, {
        "name": "cur"
    }, {
        "name": "curVal"
    }, {
        "name": "current"
    }, {
        "name": "dis"
    }, {
        "name": "equipRef"
    }, {
        "name": "floorRef"
    }, {
        "name": "group"
    }, {
        "name": "his"
    }, {
        "name": "hisInterpolate"
    }, {
        "name": "kind"
    }, {
        "name": "logical"
    }, {
        "name": "parallel"
    }, {
        "name": "point"
    }, {
        "name": "roomRef"
    }, {
        "name": "sensor"
    }, {
        "name": "series"
    }, {
        "name": "siteRef"
    }, {
        "name": "temp"
    }, {
        "name": "tz"
    }, {
        "name": "unit"
    }, {
        "name": "vav"
    }, {
        "name": "zone"
    }],
    "rows": [{
        "id": "r:2c460ffa-4a43-4972-97db-22a2177e3885",
        "air": "m:",
        "cur": "m:",
        "curVal": "n:72 °F",
        "current": "m:",
        "dis": "ValidationOfSchedules-VAV-1700-currentTemp",
        "equipRef": "r:2379d7a7-0281-45fe-88cd-66a01f2aab95",
        "floorRef": "r:6e68a6e4-b5f3-4d2c-9011-4849de96cd2c",
        "group": "1700",
        "his": "m:",
        "hisInterpolate": "cov",
        "kind": "Number",
        "logical": "m:",
        "point": "m:",
        "roomRef": "r:ac01293a-df4f-4c36-87b1-5946809f95a3",
        "sensor": "m:",
        "siteRef": "r:70e78150-5699-4598-90a0-de86ec649457",
        "temp": "m:",
        "tz": "Kolkata",
        "unit": "°F",
        "vav": "m:",
        "zone": "m:"
    }, {
        "id": "r:48f19926-0b70-412a-b559-5f67cbaf13a4",
        "air": "m:",
        "cur": "m:",
        "curVal": "n:72 °F",
        "current": "m:",
        "dis": "ValidationOfSchedules-VAV-1701-currentTemp",
        "equipRef": "r:381880fe-45c4-41a0-a00a-e99c5a574dd2",
        "floorRef": "r:6e68a6e4-b5f3-4d2c-9011-4849de96cd2c",
        "group": "1701",
        "his": "m:",
        "hisInterpolate": "cov",
        "kind": "Number",
        "logical": "m:",
        "parallel": "m:",
        "point": "m:",
        "roomRef": "r:6037667a-bdbe-4ec9-bfea-b01e1b406b95",
        "sensor": "m:",
        "siteRef": "r:70e78150-5699-4598-90a0-de86ec649457",
        "temp": "m:",
        "tz": "Kolkata",
        "unit": "°F",
        "vav": "m:",
        "zone": "m:"
    }, {
        "id": "r:2caac7a8-69e6-455b-9bb0-555fdfc67662",
        "air": "m:",
        "cur": "m:",
        "curVal": "n:72 °F",
        "current": "m:",
        "dis": "ValidationOfSchedules-VAV-1702-currentTemp",
        "equipRef": "r:6fd5d1f3-91a6-481f-a8a0-bc8df0f59cd4",
        "floorRef": "r:6e68a6e4-b5f3-4d2c-9011-4849de96cd2c",
        "group": "1702",
        "his": "m:",
        "hisInterpolate": "cov",
        "kind": "Number",
        "logical": "m:",
        "point": "m:",
        "roomRef": "r:a5576bff-34f1-4902-a8c4-11770f9f8bec",
        "sensor": "m:",
        "series": "m:",
        "siteRef": "r:70e78150-5699-4598-90a0-de86ec649457",
        "temp": "m:",
        "tz": "Kolkata",
        "unit": "°F",
        "vav": "m:",
        "zone": "m:"
    }, {
        "id": "r:64ef7fb6-02b7-40a7-95dc-69ac5f309399",
        "air": "m:",
        "cur": "m:",
        "curVal": "n:72 °F",
        "current": "m:",
        "dis": "ValidationOfSchedules-VAV-1709-currentTemp",
        "equipRef": "r:7f63f974-5735-4db5-acb9-1054c7de70c2",
        "floorRef": "r:f738acf1-7af0-4cdd-9b9d-b2ac10495174",
        "group": "1709",
        "his": "m:",
        "hisInterpolate": "cov",
        "kind": "Number",
        "logical": "m:",
        "point": "m:",
        "roomRef": "r:beda2643-39fd-407e-8b11-0edde45ebc9c",
        "sensor": "m:",
        "series": "m:",
        "siteRef": "r:70e78150-5699-4598-90a0-de86ec649457",
        "temp": "m:",
        "tz": "Kolkata",
        "unit": "°F",
        "vav": "m:",
        "zone": "m:"
    }]
}

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

 

 

 

 

 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk