Contents
A Key Property Store (KPS) is an external data store of API Gateway policy properties, which is typically read frequently, and seldom written to. Using a KPS enables metadata-driven policies, whereby policy configuration is stored in an external data store, and looked up dynamically when policies are executed. You can specify policy configuration settings in Policy Studio using selectors, which are evaluated and expanded dynamically at runtime.
Every KPS consists of a table of data. For example, the following example shows a simple KPS table structure:
Column | Type | Description |
---|---|---|
email
|
String
|
User email address. This is the primary key used to identify a row in the table. |
password
|
String
|
User password. This confidential data is encrypted. |
firstName
|
String
|
User first name. |
lastName
|
String
|
User surname. |
age
|
Integer
|
User age. |
The following example shows some simple table data that follows this structure:
email
|
password
|
firstName
|
lastName
|
age
|
---|---|---|---|---|
jdoe@acme.com
|
*****
|
John
|
Doe
|
21
|
jbloggs@acme.com
|
*****
|
Joe
|
Bloggs
|
42
|
jdupont@acme.com
|
*****
|
Jean
|
Dupont
|
33
|
Every KPS table is assigned alias in Policy Studio so that it can be referred to from a policy.
For example, an alias used to identify the example table could be customers
. In
this example, the email
column is the primary key for the table. You can use this
primary key to look up and uniquely identify a row using a selector expression. For example, the
following selector expression evaluates to John
:
${kps.customers["jdoe@acme.com"].firstName}
The following selector expression evaluates to 42
:
${kps.customers["jbloggs@acme.com"].age}
For more details on selectors, see Selecting configuration values at runtime.
A KPS provides a consistent interface to object data in different data sources. The API Gateway provides support for the following KPS data sources:
-
Embedded Apache Cassandra database (default)—used across an API Gateway group to provide high availability in a production environment
-
JSON file system—for development use with a single API Gateway instance only
-
Relational Database—enables you to use your existing database (for example, Oracle, Microsoft SQL Server, DB2, MySQL, JPA, or database schema)
The relational database support includes the generic Java Persistence API (JPA) for serializing Java objects to a database, and an existing or custom database schema for writing beans that map keyed property attributes to the schema.
Note | |
---|---|
File-based KPS stores are cached on startup. Database-based KPS stores are read each time. |
You can configure a KPS using Policy Studio (for example, you can specify KPS collections, tables, and aliases). For web-based user interfaces, JavaScript-based KPS browser widgets are also available. You can use the KPS Service Provider Interface (SPI) to add custom stores. KPS functionality is exposed using a Java API and a REST API.
A KPS collection is a group of KPS tables. To add a KPS collection, perform the following steps:
-
In the main Policy Studio tree, right-click Key Property Stores, and select Add KPS Collection.
-
Complete the following fields in the Add KPS Collection dialog:
-
Name:
Enter the KPS name (for example,
Customer
). -
Alias prefix:
Enter an alias used to identify your KPS (for example,
customer
). -
Description:
Enter a text description of your KPS.
-
Default data source:
Select one of the following from the list:
-
Embedded (Cassandra)
-
File
-
SQL Database
Defaults to
Embedded (Cassandra)
. -
-
The newly created KPS collection is displayed on the screen on the right.
To edit a KPS collection, perform the following steps:
-
In the main Policy Studio tree, select the KPS collection that you wish to edit under Key Property Stores.
-
You can edit values for the KPS collection on the Properties tab (for example, Name, Alias prefix, or Default data source).
-
You can add or edit values for the KPS collection data sources on the Data Sources tab.
-
Click OK.
Adding a File Data Store
To add a file-based data store to a selected KPS collection, perform the following steps:
-
On the Data Sources tab, select Add > Add File at the bottom right of the screen.
-
Complete the following fields in the Add File Data Source dialog:
-
Name:
Enter the KPS name (for example,
Customer File Data Source
). -
Description:
Enter a text description of your file data source.
-
Directory Path:
Enter the full directory path to the file (for example,
c:\kps\customer.json
).
-
-
Click OK.
Note | |
---|---|
A file-based data store is for development use with a single API Gateway instance only, and should not be used in a production environment. |
Adding a Database Data Store
To add an SQL database data store to a selected KPS collection, perform the following steps:
-
On the Data Sources tab, select Add > Add Database at the bottom right of the screen.
-
Complete the following fields in the Add File Data Source dialog:
-
Name:
Enter the KPS name (for example,
Customer DB Data Source
). -
Description:
Enter a text description of your SQL database data source.
-
Database Connection:
Click the button on the right, select a database connection in the dialog (for example,
Default Database Connection
), and click OK. You can add more database connections to the list by right-clicking the Database Connections node, and selecting Add DB Connection.
-
-
Click OK.
When finished editing the KPS collection, click the Save button in the top right corner of the screen.
Further Information
For more detailed information on using a KPS, please contact the Oracle Support Team with your queries.
To add a KPS table to a KPS collection, perform the following steps:
-
In the main Policy Studio tree, right-click a KPS collection (for example Customer), and select Add Table.
-
Complete the following fields in the Add KPS Table dialog:
-
Name:
Enter the KPS name (for example,
Customer KPS
). -
Description:
Enter a text description of your KPS.
-
Aliases:
Click Add, and enter an alias used to identify your KPS (for example,
customer
). Click OK. Every KPS must have at least one alias.
-
-
Click OK.
The newly created KPS table is displayed on the screen on the right.
To define the KPS table structure, perform the following steps:
-
In the main Policy Studio tree, select a KPS table (for example Customer), and click the Structure tab in the screen on the right.
-
Click Add and complete the following fields in the Add Property dialog:
-
Name:
Enter the name of the table column (for example,
email
). -
Type:
Select the data type from the list (for example,
java.lang.String
). -
Key:
For
java.util.Map
types, select the key type from the list (for example,java.lang.Integer
). -
Value:
For
java.util.Map
andjava.util.Map
types, select the value type from the list (for example,java.lang.Boolean
).
-
-
Click OK. The newly created KPS table structure is displayed on the screen on the right.
-
Select the Primary Key setting for
email
to make this field the primary key for the table. -
Select the Encrypted setting for
password
to encrypt this field in the KPS data source.
Important | |
---|---|
Encrypted fields are always read and written in the clear. For security, use HTTPS when accessing a KPS over its REST API. |