22 Replies Latest reply on Nov 23, 2018 1:51 PM by Adam Milton-Barker

    WebAPI call common practices

    Adam Milton-Barker

      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.

        • Re: WebAPI call common practices
          mfoerster

          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 of 2 people found this helpful
            • Re: WebAPI call common practices
              Adam Milton-Barker

              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

                  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

                  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
                      gregor

                      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

                          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

                            • Re: WebAPI call common practices
                              gregor

                              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

                                  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

                                   

                                  Screenshot 2018-11-22 at 17.25.27.png

                                  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
                                      gregor

                                      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 of 3 people found this helpful
                                        • Re: WebAPI call common practices
                                          Adam Milton-Barker

                                          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 Lee

                                              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.

                                               

                                              WebIdTypeDescription
                                              FullEncodes all information, similar to WebID version 1.0. Full WebIDs are longer, but are more resistant to items being moved, renamed, or deleted.
                                              IDOnlyEncodes 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.
                                              PathOnlyEncodes 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.
                                              LocalIDOnlyThis 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.
                                              DefaultIDOnlyThis 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

                                                  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

                                                    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 of 1 people found this helpful
                                                      • Re: WebAPI call common practices
                                                        Eugene Lee

                                                        Ah you included the "\\" haha.

                                                        • Re: WebAPI call common practices
                                                          gregor

                                                          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 of 2 people found this helpful
                                                • Re: WebAPI call common practices
                                                  Adam Milton-Barker

                                                  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
                                          rborges

                                          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 of 3 people found this helpful
                                          • Re: WebAPI call common practices
                                            Marcos Vainer Loeff

                                            Hello Adam,

                                             

                                            Which platform do you plan to develop your application on top of PI Web API?