PI Web API 2015 User Guide

OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA 94577 USA Tel: (01) 510-297-5800 Fax: (01) 510-357-8136 Web: http://www.osisoft.com PI Web API 2015 User Guide © 2014-2015 by OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI Web API, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC. Version: 1.4 Published: 26 February 2015

Contents PI Web API overview.................................................................................................. 1 PI Web API installation............................................................................................... 3 Operating systems.......................................................................................................................................... 3 System requirements...................................................................................................................................... 3 PI Web API distribution kit files........................................................................................................................3 Install PI Web API............................................................................................................................................ 4 Upgrade PI Web API........................................................................................................................................ 5 Change, modify, or uninstall PI Web API......................................................................................................... 6

PI Web API configuration............................................................................................7

Modify the configuration using the RESTful interface...................................................................................... 7 Modify the configuration using PI System Explorer..........................................................................................7 Authentication methods................................................................................................................................. 8 Cross-Origin Resource Sharing........................................................................................................................9 Read-only mode............................................................................................................................................ 10 Rate limit.......................................................................................................................................................10 OData database configuration....................................................................................................................... 11 Expensive OData queries............................................................................................................................... 12

Configuring debug tracing........................................................................................ 13 WebID..................................................................................................................... 15 System administration............................................................................................. 17

PI Web API Administrators.............................................................................................................................17 Protected resources....................................................................................................................................... 17

PI Web API caching.................................................................................................. 19 Cache-Control headers.................................................................................................................................. 19 Viewing cache instances................................................................................................................................ 19

PI Web API clustering............................................................................................... 21 Indexed search......................................................................................................... 23

Change the index server by editing the configuration file...............................................................................23 Administration web pages for search............................................................................................................ 24 Databases..................................................................................................................................................25 Settings.....................................................................................................................................................26 API............................................................................................................................................................ 26

OData service.......................................................................................................... 27

Data models.................................................................................................................................................. 27 Template data model................................................................................................................................ 28 Physical data model...................................................................................................................................30 Default parameter values...........................................................................................................................32 OData standard support................................................................................................................................ 33 PI Web API 2015 User Guide

iii

Contents Supported and unsupported query options................................................................................................ 33 Paging support.......................................................................................................................................... 33 PI OData URL convention.......................................................................................................................... 34 Query compendium.......................................................................................................................................34 Template model........................................................................................................................................ 35 Physical model........................................................................................................................................... 37 Using PI OData.............................................................................................................................................. 38 Use OData services with Microsoft Excel................................................................................................... 39

Troubleshooting...................................................................................................... 41 Commonly encountered problems................................................................................................................ 41 Generic troubleshooting................................................................................................................................45 Log collection............................................................................................................................................ 45

Technical support and other resources....................................................................... 47

iv

PI Web API 2015 User Guide

PI Web API overview PI Web API is a RESTful PI System access layer that provides a cross-platform programmatic interface to the PI System. RESTful interfaces enable cross-platform development of web, desktop, and mobile applications across many different programming languages. PI Web API enables you to retrieve and manipulate time series data from the PI Data Archive, and asset and event frame data from the PI AF server. PI Web API belongs to the OSIsoft PI Data Access family of products, designed to support both the implementation of custom PI System applications and the integration of PI System data with other applications and business systems, such as Microsoft Office or SQL Server, Enterprise Resource Planning systems (ERPs), reporting and analytics platforms, web portals, geospatial and maintenance systems, and so on. The PI Data Access suite covers a wide range of use cases in various environments, programming languages, operating systems and infrastructures.

Indexed search The PI Web API provides indexed search to enable you to develop a powerful search experience using this RESTful API. Indexed search finds assets by using multiple fields, such as description, template, category, point source, unit of measure, and other metadata. For example, PI Coresight uses indexed search to find points, elements, attributes, and event frames.

OData OData is a standardized protocol that builds upon the principles of HTTP and REST to provide a uniform way to expose, structure, query, and manipulate data. The OData services in PI Web API allow you to retrieve asset, event frame, and time series data in a format that is suitable for use by business intelligence and analytics tools. Note: The current release of the PI Web API software includes a prerelease version of the OData software. For more information on other PI System access products and details about licensing that is specific to these products (for example, development versus runtime solutions), please contact your account manager.

PI Web API 2015 User Guide

1

PI Web API overview

2

PI Web API 2015 User Guide

PI Web API installation Topics in this section • Operating systems • System requirements • PI Web API distribution kit files • Install PI Web API • Upgrade PI Web API • Change, modify, or uninstall PI Web API

Operating systems The preferred, supported deployment platforms are Windows Server 2012 R2 or Windows Server 2012. Windows Server 2008 R2 (Full Desktop Installation only) may also be used; however, use of Windows Server 2008 R2 is discouraged, as planned enhancements to PI Web API will require functionality that is only available in later versions of Windows. Microsoft's client operating systems, Windows 8 and later (64-bit only) may be used in a limited capacity for development and testing purposes only. Earlier versions of Windows and non-x64 versions of Windows are not supported.

System requirements Installation of this product requires the presence of .NET Framework 4.5.2. The PI AF Client 2014 R2 SP1, included in the distribution kit, is also required. The setup will not proceed if any of these components is not present.

PI Web API distribution kit files The installer is released as a self-extracting distribution kit that contains: • Installation files for .NET Framework 4.5.2 • Installation files for PI AF Client 2014 R2 SP1 (x64), which includes the AF client installer, and installers for its prerequisites: ◦ OSIsoft MS Runtime Redistributables ◦ Microsoft Visual C++ Runtimes 2008, 2010, and 2012 (x86 and x64) ◦ PI SDK 2012 (x86 and x64) ◦ PI Buffer Subsystem 4.3

PI Web API 2015 User Guide

3

PI Web API installation • Microsoft Visual C++ Runtime 2013 (x64 only) • The PI Web API Windows Installer Database (MSI) file that is signed by OSIsoft.

Install PI Web API Before you start Verify that: • The system you plan to use is running a supported operating system. • The system you plan to use has .NET Framework 4.5.2 installed. • You can run the installer as an Administrator.

Procedure 1. Double-click the installation kit to begin installation. 2. Follow the instructions to allow the prerequisites, including PI SDK, PI Buffer Subsystem, and PI AF Client to install. For detailed installation instructions for these components, consult the component's Release Notes, available from OSIsoft Technical Support (https:// techsupport.osisoft.com/), vCampus, or from your account representative. 3. When the PI Web API Setup wizard opens, select one of the following options: a. Select Typical to have the installer automatically detect and select the PI Asset Server in which to store your PI Web API configuration. The installer uses the default or recommended values for the remaining settings except for the selection of a configuration instance (see step 6 below for information about selecting a configuration instance). The installer also creates and uses a self-signed SSL certificate. b. Select Custom to have the installer proceed through the remaining steps in this topic. 4. In PI System Customer Experience Improvement Program screen, choose Yes to participate in the in the program and share anonymous usage data with OSIsoft, or No to not participate in the program and not share data. Click Next to continue. 5. On the Custom Setup screen, select the features that you want installed. You can select whether to install the Indexed Search feature and PI OData. Indexed Search is installed by default while OData must be selected to be installed. Select Entire feature will be unavailable to prevent one or both features from installing. Note: The current release of the PI Web API software includes a prerelease version of the OData software. 6. Click Next. You are prompted to select a configuration instance. 7. From the list, select the Asset Server on which to create the configuration instance. You must be an administrator on this server You can also enter the name of the instance to create. After choosing an Asset Server, you can click Connect to verify the connection or the ellipses (...) to specify a different Asset Server. 4

PI Web API 2015 User Guide

PI Web API installation 8. Click Connect when finished. If you have not elected to install the PI Web API feature (the default), you should proceed to step 14. 9. In SSL Certificate, click Select. Optionally, click Create to automatically create and select a self-signed SSL certificate. 10. In the popup window titled Windows Security, select an SSL certificate for use and click OK. You can also review the certificate properties in the Certificate Details window. 11. In SSL Certificate, verify that the following message displays: A certificate is ready for use

You can also view or change the certificate, as needed. 12. In the Firewall Exception window, select the Yes check box to have the installer create a Windows firewall exception for PI Web API (recommended) or select No to not create a Windows firewall exception. 13. In Web API Service Account, elect to use the default virtual service account (NT Service \PIWebAPI), or select A custom account and provide credentials for a custom service: a. Enter an Account Name in DOMAIN\username format. b. Enter the Password for the account. c. Click Validate. Note that in the default security mode for PI Web API, this account must be trusted for delegation to backend PI and AF servers in Active Directory. 14. If you have elected to install the PI Indexed Search Crawler feature, the Crawler Service Account dialog displays. Otherwise, you may skip to step 16. Elect to use the default virtual service account (NT Service\picrawler), or select A custom account and provide credentials for a custom service: a. Enter an Account Name in DOMAIN\username format. b. Enter the Password for the account. c. Click Validate. The account that you choose for the PI Indexed Search Crawler must be capable of reading all AF Databases and PI Data Archive servers that you wish to index. 15. In PI Web API URL, enter the URL of the PI Web API instance to which you wish to connect. The default selection is likely appropriate, unless you would like to connect your crawler to a remote PI Web API server, in which case you should enter its address here. 16. In Ready to install PI Web API 2015, click Install. 17. Click Finish to exit the setup wizard.

Upgrade PI Web API If an earlier version PI Web API is already installed, the installer will uninstall the earlier version before installing the new one. The installation procedure remains the same.

PI Web API 2015 User Guide

5

PI Web API installation

Change, modify, or uninstall PI Web API If the version of PI Web API that you are installing is the same as one that is already installed, the installer launches the maintenance dialog, in which you can change, repair, or uninstall the software. • Change Select this option to change one or more installation settings. The change options are the same as the installation options. You use this option to add or remove indexed search or OData from the installed software. You cannot change the installation or destination folder. To change the installation or destination folder, you should uninstall and then reinstall PI Web API. • Repair Select this option to repair problems with the PI Web API installation, such as restoring missing files or registry values. You cannot change installation settings using this option. • Uninstall Select this option to uninstall the PI Web API. Uninstalling the product will not remove: ◦ Any SSL certificates that were created during the installation process ◦ The binding of the selected SSL certificate to the port used by PI Web API in the Windows HTTP service’s configuration ◦ The URL reservation for PI Web API in the Windows Kernel routing table. The above items may be removed manually if desired.

6

PI Web API 2015 User Guide

PI Web API configuration PI Web API stores configuration data in the PI System. This allows the system to scale horizontally, and also allows for multiple PI Web API instances to share a common configuration space. A number of configurable properties exist.

Modify the configuration using the RESTful interface PI Web API contains resources under /piwebapi/system/configuration to view, add, modify, and remove configuration items. Consult PI Web API's online help for information about how to interact with these resources.

Modify the configuration using PI System Explorer You may also modify configuration values directly, in PI System Explorer. Using PI System Explorer, navigate to the Configuration database on the AF Server that you selected when installing PI Web API. In the element hierarchy, you should see your PI Web API configuration stored under OSIsoft, PI Web API, Configuration Instance Name. By default, your configuration instance name is the hostname of the server on which you have installed PI Web API. Configuration values may be modified by editing the attributes on the System Configuration element, and checking in.

PI Web API 2015 User Guide

7

PI Web API configuration

Authentication methods PI Web API supports three authentication methods: • Kerberos • Basic • Anonymous The meanings and effect of these authentication methods are explained in the topics that follow. The PI Web API configuration item AuthenticationMethods takes an array of authentication methods, and multiple authentication methods may be specified. If multiple methods are enabled, and multiple authentication types are supplied in a single request, PI Web API attempts to authenticate using these methods in order of most secure to least secure authentication method, that is, Kerberos first, then Basic, and finally Anonymous. In cases where the request originates from a User-Agent that is known to not support one or more authentication mechanisms, PI Web API attempts to modify its authentication challenges to remove the offending authentication type. For instance, the Safari browser does not support Kerberos, so if the both Kerberos and Basic are enabled, PI Web API suppresses the Kerberos challenge for a request that originates from Safari. This helps improve the likelihood that the request will succeed. • Kerberos Kerberos, also known as Windows Integrated Security, is the only authentication mechanism that is enabled by default in PI Web API. Kerberos provides per-user security that is native to Windows and Active Directory, and that is well supported in Microsoft clients. Kerberos does not rely on credentials being transmitted across the wire, which makes it ideal for use with untrusted connections. Use of Kerberos authentication requires the correct configuration of Active Directory delegation for the account hosting the PI Web API service in Active Directory. Correctly configured delegation requires that an Active Directory Domain Administrator grant delegation privileges to the account hosting PI Web API (or in the case of the default virtual service account, then to the computer account of the computer hosting PI Web API). Correctly configured delegation also requires that Service Principal Names be correctly set on the account hosting PI Web API. The PI Web API troubleshooting guide has detailed steps for resolving issues related to Kerberos delegation. • Basic Basic authentication is defined in RFC 2617 and is widely supported across vendors, platforms, and HTTP clients. Basic authentication as implemented in PI Web API is simple to use, provides granular, per-user security based on Windows identity, and can help avoid configuration problems like those related to Kerberos delegation. When combined with SSL, as in all PI Web API requests, Basic authentication is reasonably secure. Basic authentication is still less secure than Kerberos, since user credentials are transmitted across the wire. In addition, Basic authentication requires that PI Web API keeps the decrypted username and password in memory for the duration of the request. Even after the request is completed, the credentials may continue to reside in memory until new data

8

PI Web API 2015 User Guide

PI Web API configuration takes its place in memory. As such, Basic authentication should not be used if you are not confident of the security of the server on which you are running PI Web API. • Anonymous Anonymous indicates no authentication at all. All requests against PI Web API that use anonymous authentication will be served using the Windows account that hosts PI Web API (by default, the virtual service account NT Service\PIWebAPI). OSIsoft discourages use of the Anonymous authentication setting. When Anonymous authentication is enabled, OSIsoft strongly encourages the use of Read-only mode for PI Web API.

Cross-Origin Resource Sharing Cross-Origin Resource Sharing, or CORS, is a W3C-recommended approach for secure access to resources hosted in a remote domain. All modern web browsers enforce a Same-Origin Policy, which limits scripts running in one domain from accessing resources that are hosted in another. For example, a script that is running at http://some-questionable-site.com can only make AJAX calls to the somequestionable-site.com domain; it cannot make requests to http://your-bank.com. The Same-Origin Policy is a cornerstone of internet security and helps protect against a wide array of attacks that would otherwise be possible. Unfortunately, this means that modern, trustworthy applications that are running in one domain cannot make AJAX requests to resources that are hosted in another domain. This presents a problem if, for example, you are developing an application that will run at http://my-internal-site.internal/mygreatapp and you are trying to make AJAX calls to the PI Web API, which is running at https://my-pisystem.internal/piwebapi. The solution is to enable CORS in the PI Web API configuration, and indicate the origins from which PI Web API accepts cross-domain requests. All modern browsers support CORS as a workaround for the same-origin policy. The following CORS configuration items are available in PI Web API: • CorsOrigins A comma-separated list of domains from which CORS requests may originate. The originating browser should automatically send the domain in the HTTP Origin header of the cross-domain request. PI Web API inspects the Origin header of the request against the list of allowed origins to make an authorization decision. The default value, null or an empty string, indicates that cross-domain requests may not be accepted from any origin. This means that CORS is effectively disabled. The asterisk (*) character is a wildcard, and indicates that cross-domain requests may be accepted from any origin. This configuration is not recommended. • CorsMethods A comma-separated list of HTTP methods (verbs) that are allowed for cross-domain requests. PI Web API inspects the provided HTTP method against the list of allowed values to make an authorization decision. The default value, "GET,OPTIONS", means that only HTTP calls that use one of those two HTTP methods will be accepted. This limits cross-domain requests to read access only, for enhanced security. PI Web API 2015 User Guide

9

PI Web API configuration A value of null, or an empty string, indicates that cross-domain requests may not be accepted with any HTTP method. This means that CORS is effectively disabled. The asterisk (*) character is a wildcard, and indicates that cross-domain requests may be accepted using any HTTP method. • CorsHeaders A comma-separated list of HTTP header keys that are allowed for cross-domain requests. The client browser enforces this restriction. The default value of null, or an empty string, indicates that no HTTP headers should be sent with the request. The client browser will suppress any HTTP headers that you attempt to set manually. The asterisk (*) character is a wildcard, and means that the client browser is free to forward any HTTP headers with the request. If you are making requests that include content, for example creating or updating a resource in PI Web API, then you will almost certainly want to add the Content-Type header as an allowed header in the CorsHeaders property. • CorsSupportsCredentials A Boolean property that indicates whether or not the browser may send and receive authentication information along with a cross-origin request and response. The default value, false, means that authentication information is not sent with the request and will not be accepted in the response. If you are running PI Web API with an authentication type other than Anonymous, this will lead to PI Web API returning a 401 Unauthorized response to cross-origin requests. The value true means that the browser may send authentication information with the request, and receive it in the response. Per the CORS specification, CorsSupportsCredentials cannot be used in conjunction with a wildcard (*) value for CorsOrigins. The list of allowed origins must be explicitly defined when CorsSupportsCredentials is enabled. More information about CORS is available here (http://www.w3.org/TR/cors/), and information about its use in ASP.NET Web API is available here (http:// msdn.microsoft.com/en-us/magazine/dn532203.aspx).

Read-only mode PI Web API supports a read-only mode, whereby the ability to modify your PI System is completely disabled. This is especially desirable if PI Web API will be configured for Anonymous authentication. When the configuration item DisableWrites is set to true, only read access is enabled in PI Web API. The default setting is false.

Rate limit You can limit the rate at which clients request data by setting rate limit parameters in the System Configuration. Two parameters are used to set the rate limit:

10

PI Web API 2015 User Guide

PI Web API configuration • RateLimitMaxRequests Specifies the maximum number of requests • RateLimitDuration Specifies the duration time in seconds The rate limit per client IP is calculated by using the following formula: • Rate limit per IP = RateLimitMaxRequests / RateLimitDuration The default rate limit per client IP is 1000 requests per second. If the rate limit is reached or exceeded, a response is returned with HTTP status 429 (Too Many Requests). The response body contains the following error message: Rate limit was reached

OData database configuration The list of AF databases to be exposed through OData services in PI Web API can be configured in the configuration database. By default, the OData service exposes all AF databases from all registered AF Servers. The configuration may be modified by editing ODataDatabases. The ODataDatabases attribute value is an array of strings. An AF Server can contain one or many configuration entries. Each string entry represents a single configuration. The following entries are possible: • - exposes all databases from the AF Server. Example: AFServer1 - all databases present in AFServer1 will be exposed by OData. • | - exposes only the AF Database from the AF Server. Example: AFServer1|NuGreen - only the NuGreen database will be exposed from the AFServer1 by OData. • || - exposes only the AF Database from the AF Server and the AF Database will be listed by the OData feature as the name. Example: AFServer1|NuGreen|NuGreen2 - only the NuGreen database will be exposed from the AFServer1. The NuGreen database will be visible as NuGreen2 by OData For exposing multiple AF Databases from particular AF Server(s) multiple entries must be entered. A separate entry is required for each AF Database to be exposed. The changes take effect after the PI Web API Service is restarted.

Example Consider the following entries in the ODataDatabases attribute value:

PI Web API 2015 User Guide

11

PI Web API configuration AFServer1 AFServer2|NuGreen AFServer3|NuGreen|NuGreen2 AFServer3|Plant

OData services in PI Web API would expose all databases from AFServer1, only the NuGreen database from AFServer2 and two databases from AFServer3: the NuGreen2 database (which is an alias of the NuGreen database from AFServer3) and the Plant database.

Expensive OData queries The OData services in PI Web API assign a numeric execution cost to each query prior to executing. This numeric value is computed based on the complexity of the query's execution plan; the higher the execution cost, the more expensive the query is to complete. The OData services in PI Web API contain a limiter that is designed to prevent the service from executing queries that may consume disproportionate resources in the PI Web API server, PI Asset Server, or other back end servers in the PI System. The default value of 1000 for ODataExpensiveQueryExecutionCostThreshold provides a reasonable balance that allows most common queries to succeed. Increasing this value allows more expensive queries to pass the check.

12

PI Web API 2015 User Guide

Configuring debug tracing PI Web API can be configured to write debug information to analytic and debug logs that are accessed using the Microsoft Event Viewer.

Procedure 1. Start the Microsoft Event Viewer. a. Click Start. b. Click Control Panel. c. Click System and Security. d. Click Administrative Tools. e. Select Event Viewer. 2. Select View > Show Analytic and Debug Logs. 3. In the left panel, expand Applications and Services logs, then expand PIWebAPI, and select Analytic. 4. In the Actions window, select Enable log. You see a warning that analytic and debug logs may lose events when enabled. Proceed to enable the analytic log. 5. In the left panel, expand Applications and Services logs, then expand PIWebAPI, and select Debug. 6. In the Actions window, select Enable log. You see a warning that analytic and debug logs may lose events when enabled. Proceed to enable the debug log.

After you finish Note: To capture PI Web API logs, you may also use other event logs that are integrated with Event Tracing for Windows.

PI Web API 2015 User Guide

13

Configuring debug tracing

14

PI Web API 2015 User Guide

WebID When you retrieve information, PI Web API encodes both the ID and the path to the requested object to form a WebID. The WebID forms a new, redundant, unique identifier for use in further queries. Most PI Web API queries require that one or more WebIDs be included in the call. When you make a query with an input WebID, PI Web API decodes the WebID and finds the object's unique ID along with the object's path. PI Web API then attempts to perform the query using the object's unique ID. If the query fails, PI Web API performs the query using the path instead. This gives the PI Web API a redundancy-protected, efficient way to reference objects in the PI System. As such, it is safe to persist URLs that contain WebIDs over long periods of time.

PI Web API 2015 User Guide

15

WebID

16

PI Web API 2015 User Guide

System administration PI Web API Administrators When the setup program is run, PI Web API creates a Windows group called PI Web API Admins, whose members are the users authorized to call protected resources in the PI Web API service. The user who runs the PI Web API installer is automatically added to this group. You may add additional users to this group as desired. Because of the nature of Microsoft Windows group membership, and how such groups are added to the Windows token, the change might not appear to take effect immediately, especially if the user is logged on interactively. In such cases, logging out and back in will produce the desired change in the user's Windows token. You do not need to restart the PI Web API service.

Protected resources The following resources that are hosted in PI Web API are sensitive, and require that the calling user be a member of the PI Web API Admins group on the server that hosts PI Web API. GET /piwebapi/system/cacheinstances PUT /piwebapi/system/configuration/{key} DELETE /piwebapi/system/configuration/{key} POST PUT DELETE /piwebapi/search/sources POST /piwebapi/search/sources/crawl POST /piwebapi/search/settings

PI Web API 2015 User Guide

17

System administration

18

PI Web API 2015 User Guide

PI Web API caching PI Web API is built on top of the AF SDK, which is designed to be run within the context of a single user. To support multiple simultaneous users, PI Web API hosts multiple instances of the AF SDK. These instances of the AF SDK are provisioned automatically by PI Web API. Advanced users might need to understand the mechanisms by which caching occurs. The PI Web API allocates a separate cache to each user. Caches are marked for refresh at fiveminute intervals. After the five-minute interval has elapsed, or if an appropriate Cache-Control header is sent with the request, the cache is refreshed during the first request that is served by the cache. Each cache can serve multiple concurrent read requests. In addition, requests to write timeseries data to resources under the /piwebapi/streams hierarchy execute concurrently with read requests, because no locking is required to fulfill such writes. With the exception of writes to resources under the /piwebapi/streams hierarchy, simultaneous requests to write data to the PI System require exclusive access to the cache, which means that all concurrent read and write requests are queued. Caches expire if they have not been used for longer than 15 minutes after their most recent refresh. This frees the memory associated with the cache for use by other caches within PI Web API, or for other processes on the system. Refreshing the cache requires exclusive access to the cache instance. While the cache is refreshing, all requests to read or write from the cache are queued. Note that refreshes of the AF cache are resource-intensive and should be used with care.

Cache-Control headers To specify the operation of the cache, any request can assign a Cache-Control header. For example, to request the latest copy from the PI System, the following HTTP header may be added to the request: Cache-Control: no-cache

Alternatively, you may request a maximum age of the data served by the cache with a max-age directive in your Cache-Control header: Cache-Control: max-age=0 (Equivalent to no-cache) Cache-Control: max-age=120 (The response must be no more than 120 seconds old.) If the cache instance has not been refreshed within the time period specified in the CacheControl header, the cache instance will be refreshed before the request is served.

Viewing cache instances PI Web API contains a resource called: GET /piwebapi/system/cacheinstances that lists the cache instances currently in use and their last refresh, scheduled refresh, and expiration times.

PI Web API 2015 User Guide

19

PI Web API caching

20

PI Web API 2015 User Guide

PI Web API clustering PI Web API is designed to be clustered behind web load balancers. You may use the load balancer of your choice. You should consider the following points when configuring a cluster: • Configuration Store To prevent configuration mismatches across the cluster nodes, it is recommend that the nodes share a common configuration store in PI AF. This configuration is performed during installation by choosing the same PI Asset Server and choosing identical Instance Names across all installations. By sharing the configuration store, all nodes in the PI Web API cluster are guaranteed to have identical configurations, which might be important to client applications. • SSL certificates You must configure appropriate SSL Certificates. Simple load balancers (such as DNS, Windows Server Network Load Balancing software load balancing, and Azure Load Balancer) require that each node in the cluster be configured with an identical SSL certificate. The SSL certificate must match the DNS name of the load balancer's public endpoint address, which might mean that local interactions with PI Web API appear to have a certificate name mismatch. Advanced load balancers such as the F5 LTM, which do full request proxying, have the ability to set SSL settings at the load balancer level, so that SSL configuration of the individual cluster nodes is less important. With all load balancers, OSIsoft recommends that node affinity be retained if possible. It is more efficient when sequential requests from the same user get serviced by the same node. • Search crawlers The indexes for the PI Indexed Search functionality are stored in the filesystem on the PI Web API server. In a clustered scenario, this means that each node creates and builds its own copy of the index. State will eventually be consistent across the cluster, but between indexing operations, different nodes in the cluster might produce different results. A search crawler should be configured for each PI Web API node, and should be configured to write directly to the individual node rather than to the load balanced public endpoint.

PI Web API 2015 User Guide

21

PI Web API clustering

22

PI Web API 2015 User Guide

Indexed search The PI Web API provides indexed search to enable you to develop a powerful search experience using this RESTful API. Indexed search finds assets by using multiple fields, such as description, template, category, point source, unit of measure, and other metadata. For example, PI Coresight 2014 uses indexed search to find points, elements, attributes, and event frames. Indexed search is a module within PI Web API. Metadata from the PI System is gathered by one or many instances of the PI Indexed Search Crawler service, a Windows service application that usually resides on the same computer as PI Web API, but can be located on another server, if circumstances require. The PI Indexed Search Crawler service periodically runs the crawlers to gather metadata from which to build and maintain indexes to improve the performance of commonly used queries. The values that are always indexed are names of PI points, AF elements, attributes, templates and categories, descriptions, the unit of measure, and data type. You can configure other point attributes to be indexed, for example, you might want to filter your data by pointsource, exdesc, or location1, and so on. The following queries can benefit from indexed search: • Finding PI points, AF elements, and AF attributes by name or description. You can constrain a query by item type, data type, PI point attribute, AF template, or AF category. You can restrict the query to a list of PI servers and AF databases or to specific paths within an AF hierarchy. • Finding children of AF objects. If a query scope includes a database that is not indexed, a legacy search (using the AF SDK) is dispatched. Note: The crawler service can index only PI Servers that are configured with identity mappings, which are supported by PI Server version 3.4.380, or later. At a minimum, you could, for example, use PI SMT to create a mapping from \Everyone to pidemo. The crawler service cannot be used with earlier versions of PI Server.

Change the index server by editing the configuration file The crawler service must connect to PI Web API for a list of databases to crawl. A crawler connects to the PI Web API server specified by IndexServer in the configuration file described here, and obtains all other settings, such as the scan interval. By default, the URL of the index server is based on the fully qualified domain name (FQDN) of the machine on which you installed PI Web API: https://FQDN of local machine/piwebapi/search Usually, the PI Indexed Search Crawler service resides on the same computer as PI Web API, but you can relocate it to another server, if circumstances require:

PI Web API 2015 User Guide

23

Indexed search

Procedure 1. Edit the XML format configuration file OSisoft.Search.Crawler.exe.config located in Program files\pipc\search. 2. Find the line beginning