-
Re: WebAPI call common practices
mfoersterNov 20, 2018 10:34 AM (in response to Adam Milton-Barker)
2 of 2 people found this helpfulHello 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
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 20, 2018 3:40 PM (in response to mfoerster)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.
-
Re: WebAPI call common practices
Jouni Nov 21, 2018 3:49 AM (in response to Adam Milton-Barker)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.
-
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 21, 2018 9:26 AM (in response to mfoerster)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
-
Re: WebAPI call common practices
gregorNov 21, 2018 10:17 AM (in response to Adam Milton-Barker)
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.
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 22, 2018 3:35 PM (in response to gregor)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
-
Re: WebAPI call common practices
gregorNov 22, 2018 4:04 PM (in response to Adam Milton-Barker)
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"
}
},
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 22, 2018 4:44 PM (in response to gregor)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.
-
Re: WebAPI call common practices
gregorNov 22, 2018 4:53 PM (in response to Adam Milton-Barker)
3 of 3 people found this helpfulHi 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 ..
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 23, 2018 9:28 AM (in response to gregor)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 ?
-
Re: WebAPI call common practices
Eugene LeeNov 23, 2018 9:34 AM (in response to Adam Milton-Barker)
There are many types of webID.
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.-
Re: WebAPI call common practices
Adam Milton-Barker Nov 23, 2018 9:55 AM (in response to Eugene Lee)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)
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 23, 2018 10:09 AM (in response to Eugene Lee)1 of 1 people found this helpfulSorry I had missed this step on the path:
.substring(2).toUpperCase(Locale.US)
The webID is now correct Thanks again for the help.
-
Re: WebAPI call common practices
Eugene LeeNov 23, 2018 10:12 AM (in response to Adam Milton-Barker)
Ah you included the "\\" haha.
-
Re: WebAPI call common practices
gregorNov 23, 2018 11:49 AM (in response to Adam Milton-Barker)
2 of 2 people found this helpfulHi 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.
-
-
-
-
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 22, 2018 4:49 PM (in response to gregor)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.
-
Re: WebAPI call common practices
gregorNov 22, 2018 5:04 PM (in response to Adam Milton-Barker)
1 of 1 people found this helpfulHi 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.
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 23, 2018 7:55 AM (in response to gregor)Thanks I have suggested already to my employers regarding the courses.
-
-
-
-
-
-
-
-
Re: WebAPI call common practices
rborgesNov 20, 2018 11:58 AM (in response to Adam Milton-Barker)
3 of 3 people found this helpfulHi 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!
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 23, 2018 1:50 PM (in response to rborges)Thank you for the input.
-
-
Re: WebAPI call common practices
Marcos Vainer LoeffNov 21, 2018 11:22 AM (in response to Adam Milton-Barker)
Hello Adam,
Which platform do you plan to develop your application on top of PI Web API?
-
Re: WebAPI call common practices
Adam Milton-Barker Nov 23, 2018 1:51 PM (in response to Marcos Vainer Loeff)Unsure which platform you are referring to, I am using Java and the software integrates OSI PI with our own platform.
-