Send Docs Feedback

Key Value Map Operations policy

What

Provides policy-based access to a key/value map store available in Apigee Edge. Key/value pairs can be stored, retrieved, and deleted from named existing maps by configuring KeyValueMapOperations policies that specify PUT, GET, or DELETE operations. (At least one of these operations must be performed by the policy.)

Where

This policy can be attached in the following locations. 

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

A simple example of a useful KeyValueMap is a URL shortening service. The KeyValueMap could be configured to store shortened URLs along with corresponding full URLs.

This policy sample creates a KeyValueMap. The policy PUTs a key with two associated values into a key/value map named "urlMapper".

The key in this example, urlencoding.requesturl.hashed, is an example of a custom variable. The hashed request URL would be generated by code (JavaScript or Java, for example) and then stored in this variable, where the KeyValueMapOperations policy can access it.

For each key, requesturl.hashed, two values are stored:

  • The contents of the custom variable named urlencoding.longurl.encoded
  • The contents of the predefined variable request.queryparam.url

For example, when the policy executes at runtime, the values of the variables may be as follows:

  • urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
  • urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
  • request.queryparam.url: http://apigee.com

The following key/value map and entry would be generated in Edge's key/value store and scoped to the API proxy to which the policy is attached:

{
    "entry" :[ 
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

The entry will persist until it is deleted. Key/value store entries are distributed across instances of Edge that are running the cloud.

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/> 
      </Key>
   </Get>
</KeyValueMapOperations>

A simple example of a useful KeyValueMap is a URL 'shortening' service. The KeyValueMap could be configured to store shortened URLs along with corresponding full URLs.

To retrieve the value of key/value map entry, such as the one covered on the KeyValueMapOperations PUT tab, configure a policy to GET the KeyValueMap, as shown above.

When this policy is executed, if the value of the urlencoding.requesturl.hashed variable is ed24e12820f2f900ae383b7cc4f2b31c402db1be, then the custom variable named urlencoding.shorturl will be set with the value http://tinyurl.com/38lwmlr.

Now that the data has been retrieved, other policies and code can access it by extracting the value from those variables.


Element reference

The element reference describes the elements and attributes of the KeyValueMapOperation policy.

<KeyValueMapOperations async="false" continueOnError="false" 
    enabled="true" name="Key-Value-Map-Operations-1" 
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>-1</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter ref="variable_name"></Parameter>
         </Key>
         <Value>value_literal</Value>
         <Value ref="variable_name"></Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"></Parameter>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

<KeyValueMapOperations> attributes

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">
Attribute Description Default Presence
mapIdentifier

Specifies an identifier to be used when accessing, via APIs, a map created by this policy.

By default, this policy can be accessed through APIs via the name "kvmap". Within a scope of organization/environment/apiproxy, you can use the mapIdentifier attribute to specify your own map name.

N/A Optional.

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

Note: This attribute does not make the policy execute asynchronously.

When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching.

To use asynchronous behavior in API proxies, see JavaScript callouts.

false Optional

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<Delete> element

Deletes the specified key/value pair. (At least one of <Get>, <Put>, or <Delete> must be used.)

<Delete>         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>     
</Delete> 
Default: N/A
Presence: Required if <Get> or <Put> are not present.
Type: N/A

<DisplayName> element

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>Key Value Map Operations 1</DisplayName>
Default: Policy name attribute value.
Presence: Optional
Type: String

<Entry> element

Seed values for KeyValueMaps, which are populated in the KeyValueMap when it is initialized.

<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>
Default: N/A
Presence: Optional
Type: N/A

<ExclusiveCache> element

Deprecated. Use the <Scope> element instead.

<ExpiryTimeInSecs> element

Specifies when a PUT to the KeyValueMap should expire, if at all.

<ExpiryTimeInSecs>-1</ExpiryTimeInSecs>
Default: -1 (no expiration)
Presence: Optional
Type: Integer

<Get> element

Retrieves the value for the key specified. (At least one of <Get>, <Put>, or <Delete> must be used.)

<Get assignTo="myvar" index="1">         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>     
</Get>
Default: N/A
Presence: Required if <Put> or <Delete> are not present.
Type: N/A

Attributes

Attribute Description Default Presence
assignTo

The variable to which the retrieved value should be assigned.

N/A Required
index

The index number (in a 1-based index) of the item to fetch from a multi-valued key. For example, specifying index=1 will return the first value and assign it to the assignTo variable. If no index value is specified, all the values of that entry are assigned to the variable as a java.util.List.

For an example, see the KeyValueMapOperations GET tab in Samples.

N/A Optional

<InitialEntries> element

Seed values for KeyValueMaps, which are populated in the KeyValueMap when it is initialized.

<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>
Default: N/A
Presence: Optional
Type: N/A

<Key> element

Specifies the key in a key/value map entry. A key can be composite, which means that more than one parameter can be appended to create the key. For example, userID and role might be combined to create a key.

Be sure to see <Parameter> for specifics about how to set the key name.

The name ratelimit is reserved. For more information, see this Apigee Community post.

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>
Default: N/A
Presence: Optional
Type: N/A

<Parameter> element

Specifies the key name in a key/value pair. This element specifies the name when creating, putting, retrieving, or deleting the key/value pair.

A key can be composite, which means that more than one parameter can be appended to make the key. For example, userID and role might be combined constitute a key.

You can specify the name as either a literal string or, using the ref attribute, as a variable to be retrieved at run time.

<!-- Specify a literal value -->
<Parameter>literal<Parameter>

OR

<!-- Specify the name of variable value to be populated at run time. -->
<Parameter ref="variable_name"><Parameter>

Whether you're getting, updating, or deleting a key/value entry, remember that you need to specify the key name in the same way you did when you created the entry. For example, if you created the key name from a variable, you must use the same variable to get it. See Specifying key names for guidelines.

Default: N/A
Presence: Required
Type: String

Attributes

Attribute Description Default Presence
ref Specifies the name of a variable whose value should be used for the key name. N/A Required if no literal value is given between the opening and closing tags. Prohibited if a literal value is given.

<Put> element

Writes a key/value pair to an existing key value map. (At least one of <Get>, <Put>, or <Delete> must be used.)

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"></Parameter>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>
Default: N/A
Presence: Required if <Get> or <Delete> are not present.
Type: N/A

Attributes

Attribute Description Default Presence
override

If set to true, it overrides the value for a key.

false Optional

<Scope> element

Defines the boundary of accessibility for KeyValueMaps. The default scope is environment, meaning that, by default, maps entries are shared by all API proxies running in an environment (for example, test or prod). If you set the scope to apiproxy, then entries in the KeyValueMap are accessible only by the API proxy that writes the values to the map.

Note that when accessing a map or map entry, you must specify the same scope value you used when the map was created. For example, if the map was created with a scope of apiproxy, you must use the apiproxy scope when retrieving its values, putting changes, or deleting entries.

<Scope>environment</Scope>
Default: environment
Presence: Optional
Type: String
Valid values:
  • organization
  • environment
  • apiproxy
  • policy

<Value> element

Specifies the value in a key/value pair.

You can specify the value as either a literal string or, using the ref attribute, as a variable to be retrieved at run time.

<!-- Specify a literal value -->
<Value>literal<Value>

OR

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"><Value>

You can also include multiple <Value> elements to specify a multi-part value. Values are combined at run time.

In the example below, the map is initialized by the two key/value entries [k1] -> [v1, v2] and [k2, k3] -> [v3, v4].

<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>	
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Key>
         <Parameter>k3</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>
Default: N/A
Presence: Required
Type: String

Error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The KeyValueMap Policy type defines the following error codes:

Error Code Message
SetVariableFailed Failed to set variable {0} in KeyValueMapStepDefinition {1}
RemoveVariableFailed Failed to remove variable {0} in KeyValueMapStepDefinition {1}
InvalidIndex Invalid index {0} in KeyValueMapStepDefinition {1}
KeyIsMissing Key element is missing in KeyValueMapStepDefinition {0}
ValueIsMissing Value element is missing in KeyValueMapStepDefinition {0}

Schemas

See our GitHub repository samples for the most recent schemas.

Usage notes

A key value map store provides a lightweight persistence mechanism for data formatted as key/value pairs. You can access these at runtime through policies or code. A map contains any arbitrary data in the format key=value.

A key value map has a 15 MB limit. Writing to the map may fail close to or beyond this limit. If the amount of data might grow beyond 15 MB, be sure to use the ExpiryTimeInSecs element to expire entries before exceeding the limit.

For example localhost=127.0.0.1, zip_code=94110, or first_name=felix. In the first example, localhost is a key, and 127.0.0.1 is a value. Each key/value pair is stored as an entry in a key value map. A key value map can store many entries.

For example, say you need to store a list of IP addresses associated with various backend environments. You could create a key value map called ipAddresses that contains a list of key/value pairs as entries. For example, this JSON can represent such a map:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

You could use this structure to create a store of IP addresses that could be used by policies at runtime to enforce IP whitelisting or blacklisting, to dynamically select a backend target address, and so on. Typically, the KeyValueMapOperations policy is used to store or retrieve long-lived information that needs to be reused over multiple request/response transactions.

Key/value maps can be manipulated via the KeyValueMapOperations policy, or directly via the Apigee Edge management API. Refer to the management API reference for details on the Organization Key/Value Maps API. You can use the API to, for example, upload large data sets to the key/value store, or creating scripts to manage key/value map entries. You will need to create a key/value map with the API before accessing it with the KeyValueMapOperations policy.

Specifying key names

With the <Parameter> and <Value> elements, you can specify either a literal value (where the value is between the opening and closing tags) or use the ref attribute to specify the name of a variable whose value should be used at runtime.

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"></Parameter>

When getting or deleting a key's value, you must specify the key name in the same way you did when initializing the key and putting the value. In other words, while either of the <Parameter> forms is acceptable, you must use one form consistently for a given key.

The name ratelimit is reserved. For more information, see this Apigee Community post.

Related topics

Organization Key/Value Maps

 

Help or comments?