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.
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.
- 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).
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.
The Try it window to try the API is displayed.
- Select the Primary: QA-Readonly under the subscription key field.
- 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
- Scroll further locate the Header section.
The header section should have the following headers.
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:
- 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.
Comments
0 comments
Please sign in to leave a comment.