AnsweredAssumed Answered

WebAPI call common practices

Question asked by Adam Milton-Barker on Nov 20, 2018
Latest reply on Nov 23, 2018 by Adam Milton-Barker

Like • Show 0 Likes0
Comment • 22

Hi guys how are you, I was wondering if someone could offer advice on common practises, one question I have is regarding WebIDs. As we need web IDs to access data, is it right to think that the user would know these in advance, for instance is it really required to make many calls to access a certain piece of data or could we assume that the user already has access to webIDs in order to create a single API query, IE it should be common that the user already knows the URL to the specific data they want to retrieve?

I am trying to understand the ways that users currently use the WebAPI, it seems that if the above is not possible it could lead to situation where there could be any number of combinations of calls to retrieve a single piece of data.

No one else has this question

Outcomes

22 Replies

mfoerster

Nov 20, 2018 10:34 AM

Hello Adam,

our Web API is used programmatically to access PI System Data via REST. The developers ususally know what resource they would like access, and therefore know the Web ID. Also it is possible to use the indexed search to get the Web ID of a certain resource. Please refer to this documentation on how to retrieve the Web ID of a certain resource:

KB01128 - Introduction to PI Web API

As Of PI Web API 2017 R2, a newer format is now used for WebIDs (referred to as WebID 2.0) which can be translated into paths to AF Objects and PI Points. Please check out this documentation on it:

PI Web API - Using Web ID 2.0 to Optimize your Applications

Kind regards,

Moritz

2 people found this helpful

Actions

Adam Milton-Barker @ mfoerster on Nov 20, 2018 3:40 PM
Mark Correct
Correct Answer
Thanks I had seen that information, I was enquiring about whether customers rather than developers would know this information. I understand we can use Web ID 2.0 which I am looking into now. We have decided to make it required that the customers know the full path to the data they want to retrieve, the question about webids was whether the customers themselves (not the developers) would know the full paths, including webid, if this was the case our solution is quite simple. However it seems that the customers will not know the webid, if this is valid and generally true then it would be pointless us creating a solution where we expect the customer to know the full path including web id.

We are currently working on a solution where we generate the Web ID using info provided by the customer, replace a place holder in the REST path provided by the customer and make the call to the API, however we still have the requirement in this case the customer knows the exact path to the data that the want to retrieve.

RE Web ID 2.0, do you know of the where abouts of any example code (java) for generating the web id, I initially believed you only needed the Id and Path to generate it but am unsure after reading more if this is the case.
Like • Show 0 Likes0
Actions
- Jouni @ Adam Milton-Barker on Nov 21, 2018 3:49 AM
  Mark Correct
  Correct Answer
  WebAPI GetByPath syntax is simple enough for even end users to build simple queries, especially as PI WEB API url, AssetServer and AF Database values most likely are always the same
  
  https://[PIWEB API URL]/attributes?Path=\\AssetServer\AF_Database\ElementName|AttributeName
  https://[PIWEB API URL]/elements?Path=\\AssetServer\AF_Database\ElementName
  
  Path though should be easy enough to use if end users have access to PI System Explorer or any other tool that lists the element/attribute names.
  Modifying those 2 URLs, users should fairly easily get access to WebId's to use on final data queries.
  Like • Show 1 Like1
  Actions

Adam Milton-Barker @ mfoerster on Nov 21, 2018 9:26 AM

Regarding generating the web ID, could you point out where you find the system.IDs /analysis ID etc regarding the following: PI Web API - Web ID 2.0 Specification Tables

Actions

gregor @ Adam Milton-Barker on Nov 21, 2018 10:17 AM

Hi Adam,

Did you try the link in the Specification Tables document pointing to PI Web API - Using Web ID 2.0 to Optimize your Applications?

I suggest you to start watching the video Christopher Sawyer created. In short, you can use the GUID's but you can also just use the path information which appears to be what you like to do.

Actions

Adam Milton-Barker @ gregor on Nov 22, 2018 3:35 PM

Hi thank you for the reply, yes I watched and read both of those, I am still unable to find where we find the actual IDs, unless I have missed it they are not marked anywhere as they are called in the document. PI Web API - Web ID 2.0 Specification Tables

PI Web API - Web ID 2.0 Specification Tables

Actions

gregor @ Adam Milton-Barker on Nov 22, 2018 4:04 PM

Hi Adam,

You get them ID's with the payload returned by PI Web API e.g.

{

"WebId": "F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx",

"Id": "0b101021-e3bc-433d-9f06-a6a2db5f0803",

"Name": "PISRV1",

"Description": "",

"Path": "\\\\PISRV1",

"IsConnected": true,

"ServerVersion": "2.9.1.8106",

"ServerTime": "2018-11-22T15:58:46.7594861Z",

"ExtendedProperties": {},

"Links": {

"Self": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx",

"Databases": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/assetdatabases",

"NotificationContactTemplates": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/notificationcontacttemplates",

"SecurityIdentities": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/securityidentities",

"SecurityMappings": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/securitymappings",

"UnitClasses": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/unitclasses",

"AnalysisRulePlugIns": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/analysisruleplugins",

"TimeRulePlugIns": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/timeruleplugins",

"Security": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/security",

"SecurityEntries": "https://devdata.osisoft.com/piwebapi/assetservers/F1RSIRAQC7zjPUOfBqai218IAwUElTUlYx/securityentries"

}

Actions

Adam Milton-Barker @ gregor on Nov 22, 2018 4:44 PM

Ok thanks for the reply, I had thought this would not be the case as this way we do not save on any queries, if you have to query to retrieve the information required to generate the key then it doesn't make sense. My question was really are these available to the customer without them having to do a call, we are creating a solution where we reduce the amount of calls to the server but it appears there is no way to if you have to do a call to retrieve the data.

For specificity to my question, in the following example, where do we find in the OSI PI software:

Marker
SystemID
Analysis ID
Name Payload

I am guessing (As there doesn't seem to be docs that explain in detail) that the SystemID is the one provided in the call, I am also guessing the Name Payload is the path to the object that we need to access and the value is basically the result of the GetPath query shown, unsure where AnalySis ID and all of the other types of IDs required in the rest of the doc are found?

The task I have at the moment is generating these keys on the fly using parameters provided by the customer resulting in a single call query to retrieve the exact data the customer wants.

Actions

gregor @ Adam Milton-Barker on Nov 22, 2018 4:53 PM

Hi Adam,

I believe there is a misunderstanding. You can use the ID's but don't have to. With just the path information, you can create WebID 2.0 references to objects which you can use in your application.

Object ID's are not build based on any path information but are unique identifiers (GUID's) which can be used if known but your users will not know them and hence my suggestion is you build WebID 2.0 based on path information.

I would however suggest to check with the users if entering path information is really the way they like to work. I would personally prefer an application which offers me to somehow navigate through the hierarchy by e.g. choosing from available Asset Servers -> AF Databases -> root AF Element level -> next AF Element Level -> .. -> AF Attributes -> Sub Attributes ..

3 people found this helpful

Actions

Adam Milton-Barker @ gregor on Nov 23, 2018 9:28 AM

Hi thank you for the info, the info about using the path only is perfect for our use case! Thank you for the help! I have used the following process however the ID is incorrect. I created a string with P1Em + Base64 Encoded path (\\\\SERVER\\NUGREEN\\NUGREEN) , the Web ID not the same as the actual WebID did I miss some steps ?

Actions

Eugene Lee @ Adam Milton-Barker on Nov 23, 2018 9:34 AM

There are many types of webID.

WebID Type

You should check the PathOnly one by including

webIdType=PathOnly

in your query string. You are probably comparing it with the Full one now.

WebIdType	Description
Full	Encodes all information, similar to WebID version 1.0. Full WebIDs are longer, but are more resistant to items being moved, renamed, or deleted.
IDOnly	Encodes only object IDs into the WebID. IDOnly WebIDs are shorter, and will always refer to the same item, even if it is moved. However, IDOnly WebIDs will no longer be valid if the item is deleted.
PathOnly	Encodes only path information into the WebID. PathOnly WebIDs will always refer to the same location in the AF hierarchy, regardless of which item is located there.
LocalIDOnly	This type is similar to IDOnly, but is dedicated to resources on the local (relative to the PI Web API instance) asset or data server. The local asset/data server ID and path information is left out. Note: This type is not persistent or unique, and could represent different items on different servers. It is not compatible with load balancer configurations.
DefaultIDOnly	This type is similar to IDOnly, but is dedicated to resources on the default asset server or data server. The default asset/data server ID and path information is left out. Note: This type is not persistent or unique, and could represent different items on different servers. It is not compatible with load balancer configurations.

Actions

Adam Milton-Barker @ Eugene Lee on Nov 23, 2018 9:55 AM
Mark Correct
Correct Answer
Hi thanks I am comparing with the pathonly webid. I have accounted for different element types etc, these parameters are all passed in configuration settings to the function that generates the webid. In this case I am comparing the webID with the PathOnly one and it is not the same.

To elaborate on the function I made: P (PathOnly) + 1 (Version parameter passed to function) + Em (Element type param passed to function) + Base64 encoded Path to element (\\\\SERVER\\NUGREEN\\NUGREEN)
Like • Show 0 Likes0
Actions

Adam Milton-Barker @ Eugene Lee on Nov 23, 2018 10:09 AM
Mark Correct
Correct Answer
Sorry I had missed this step on the path:

.substring(2).toUpperCase(Locale.US)

The webID is now correct Thanks again for the help.
1 person found this helpful
Like • Show 0 Likes0
Actions
- Eugene Lee @ Adam Milton-Barker on Nov 23, 2018 10:12 AM
  Mark Correct
  Correct Answer
  Ah you included the "\\" haha.
  Like • Show 1 Like1
  Actions
- gregor @ Adam Milton-Barker on Nov 23, 2018 11:49 AM
  Mark Correct
  Correct Answer
  Hi Adam,
  
  Glad to see you figured it out now. I was thinking about how our answers confused you and believe it could help to share more insights.
  
  Does a normal PI user know the WebID of an AF object?
  No, WebID's are unique to PI Web API. They encrypt Path and GUID of an AF object. They are not something considered being held in human memory.
  
  What is the ID (GUID) displayed e.g. in the PI Web API payload?
  PI Asset Framework maintains information in a relational database (PIFD). GUID's (ID's) are unique identifiers used as primary (indexed) keys and foreign keys. The usage of Templates (Element, Attribute, Analysis .. ) help to define certain information once and to refer it each time an instance of the Template is created. Applying the concept of Templates results into way better performance compared to repeating definitions when not using Templates which meanly means creating redundancies.
  
  Does a normal PI User know the ID (GUID) of an AF object?
  No, the ID should normally not surface on the application level as it again is not something the human memory can easily deal with.
  
  What is an AF object Path?
  PI Asset Framework uses a hierarchical organization of objects where the hierarchy logic usually is dependent on the use case. Even within a single production site, users from different departments may consider a different view to assets. The full path to an AF object starts with the AF Server host, introduced with double-backslash, separated with a trailing backslash from the AF Database. Within an AF Database, AF Elements can be structured over multiple levels always separated with a backslash. AF Attributes are introduced with a pipe ('|') and again an AF Attribute can have children.
  
  Does a normal PI User know the AF object path?
  By knowing the logic assets are organized in a particular AF Database, users may be able to guess the correct object path at first attempt but may be other users don't. From a users perspective, I would assume to either see a tree view allowing to easily navigate the hierarchy or getting a search option offered to find assets and an option to pick those attributes which I like to see data for. Another option could be to indicate assets on a map and allow the user to zoom in in order to see the data for a particular asset. When designing an application, it is definitely useful to talk to those who will later have to use the application to understand which way they like to get to the data.
  
  Why do 'full' WebID's consist of Path and ID when users usually don't know the ID (GUID) of an AF object?
  Potentially an AF object becomes renamed which does not result into an ID change. Having the ID included with the WebID means a fallback option allowing PI Web API to still resolve to the correct AF object when it has been renamed. This is useful e.g. when a client application is persisting WebID's in memory.
  
  What if an AF object has been deleted and re-created with a different name?
  In this case, Path and ID will have changed and the former WebID persisted by a client application will not longer allow to resolve the AF object.
  2 people found this helpful
  Like • Show 1 Like1
  Actions

Adam Milton-Barker @ gregor on Nov 22, 2018 4:49 PM
Mark Correct
Correct Answer
Ultimately as per my original question, if the scenario was that the customer (Not developer) is able to know the full path (including WebID) this resolves the confusion, however it appears we need to create software that takes the input of the fields required to generate the web id and generates the web id, having looked around OSI Pi software, I have been unable to locate this information which we need in order to build the software and inform the customers how they can "easily" access this information to build the ID. Hope this explains well enough, thanks for the help so far.
Like • Show 0 Likes0
Actions
- gregor @ Adam Milton-Barker on Nov 22, 2018 5:04 PM
  Mark Correct
  Correct Answer
  Hi Adam,
  
  Please accept my apologies! It is difficult to guess the level of experience when questions allow to assume you've worked with a product or a similar one already and have a follow-up question.
  Please don't get this wrong but I believe we should start over and get you started at a different point.
  
  Programming in PI Web API is designed as Small Private Online Course (SPOC) and while we offer participating such an online course based on the corresponding schedule, the great thing about it is that you can consume the material and follow along exercises at any time.
  1 person found this helpful
  Like • Show 0 Likes0
  Actions
  - Adam Milton-Barker @ gregor on Nov 23, 2018 7:55 AM
    Mark Correct
    Correct Answer
    Thanks I have suggested already to my employers regarding the courses.
    Like • Show 0 Likes0
    Actions

rborges Nov 20, 2018 11:58 AM
Mark Correct
Correct Answer
Hi Adam,

This is an interesting question that may spark a lot of discussions.

as Moritz pointed out, with Web ID 2.0 you can easily convert paths to WebIDs. So, if your application already has the path of the element (or tag) that you want to get data from, there's no need to make a request to get the WebId or store it internally. You just convert it and make the request.

Regarding your comment:
if the above is not possible it could lead to situation where there could be any number of combinations of calls to retrieve a single piece of data.

That's true, but not necessarily bad. For instance, what if you don't have the path for a given element or what if you are looking for something a little bit trickier, like Event Frames? For those cases, you should definitely query, and use the result to do a second query for data. But as I mentioned, this is not that bad as you can make a single request with all your queries and follow-up requests by using the Batch controller.

Is it clear now or did I make it more confusing?

Cheers!
3 people found this helpful
Like • Show 0 Likes0
Actions
- Adam Milton-Barker @ rborges on Nov 23, 2018 1:50 PM
  Mark Correct
  Correct Answer
  Thank you for the input.
  Like • Show 0 Likes0
  Actions
Marcos Vainer Loeff Nov 21, 2018 11:22 AM
Mark Correct
Correct Answer
Hello Adam,

Which platform do you plan to develop your application on top of PI Web API?
Like • Show 0 Likes0
Actions
- Adam Milton-Barker @ Marcos Vainer Loeff on Nov 23, 2018 1:51 PM
  Mark Correct
  Correct Answer
  Unsure which platform you are referring to, I am using Java and the software integrates OSI PI with our own platform.
  Like • Show 0 Likes0
  Actions

WebAPI call common practices

Outcomes

webIdType=PathOnly

Related Content

Recommended Content