Was this helpful?

The KeyValueMapOperations policy provides policy-based access to Apigee Edge's key/value store. It exposes lightweight persistence for data that needs to be accessed at runtime by policies or code running on Edge. KeyValueMapOperations are typically used to persist long-lived information that needs to be reused over multiple request/response transactions.

KeyValue refers to any arbitrary data in the format key=value, for example localhost=, zip_code=94110, or first_name=felix.

In the first example, localhost is a key, and is a value.

Each key/value pair is stored in a map as an entry. A key/value map can store multiple entries.

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

  "entry" : [ {
    "name" : "Development",
    "value" : ""
   "entry" : [ {
    "name" : "Staging",
    "value" : ""
  }  ],
  "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.

KeyValue pairs can be stored, retrieved and deleted from named maps by configuring policies that specify PUT, GET, or DELETE operations.

The following operations are supported in the KeyValueMapOperations policy.

  • PUT: Writes entries to an existing KeyValueMap
  • GET: Retrieves the value for the key specified
  • DELETE: Deletes the key or value specified

KeyValueMaps can also be managed using the Apigee Edge management API. Refer to the managerment API reference for details on the Key/Value Maps API. The API is useful, for example, for uploading large data sets to the key/value store, or creating scripts to manage key/value map entries.


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.

KeyValueMap PUT Sample

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

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

The Key in this example, requesturl.hashed, is an example of a custom variable. The hashed request URL would 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 pre-defined variable request.queryparam.url

When the policy executes at runtime, the values of the variables are 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.

To retrieve the value of key/value map entry, configure a policy to GET the KeyValueMap, as follows:

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

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.

Configuring the KeyValueMapOperation policy

Configure the KeyValueMap Operation policy using the following elements.

Field Name Description
Scope (Optional)
Valid values: organization, environment, apiproxy, policy
Default value: environment
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 (i.e., 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.
ExclusiveCache (DEPRECATED: Use Scope instead.)
Valid values: true/false
Default value: false
If false, the cache provided by the environment is used.
If true, a cache is created exclusively.
InitialEntries (Optional) Entry Key Parameter (Mandatory) Seed values for KeyValueMaps, which are populated in the KeyValueMap when it is initialized. 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.
Value (Required) Specifies the value for a key. In the example below, the map is initialized by the two key/value entries [k1] -> [v1, v2] and [k2, k3] -> [v3, v4].
Put (Required) Key Parameter (Required) Includes an entry inside a key/value map for the specified key.
Value (Required) You can specify multiple values for a key.
Valid values: true/false
Default value: false
If true, it overrides the value for a key.
Get (Required) Key Parameter (Required) Retrieves a value for the specified key.
assignTo (Required) Assigns the retrieved value to a flow variable or simply a variable.
index (Optional) You can specify an index for a multi-valued key. For example, if index=1, the value at index 1 is fetched and assigned to the variable. If not specified, all the values of that entry are assigned to the variable as java.util.List. For an example, see Samples
Delete (Required) Key Parameter (Required) Specifies the key to be deleted.

Policy-specific 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 not missing in KeyValueMapStepDefinition {0}
ValueIsMissing Value element is missing in KeyValueMapStepDefinition {0}

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.


Could you confirm that the key needs to have a minimum of 2 characters?

When I try a key with one character, like "a", I get:

{"fault":{"faultstring":"KeyValueMap entry name a is invalid","detail":{"errorcode":"keyvaluemap.service.keyvaluemap_entry_name_invalid"}}}

I'm working on getting a list of valid key name characters, which I'll add to the doc. But yes, it looks like one-char key names do throw an exception.

There is example link: http://apigee.com/docs/api-services/content/persist-data-using-keyvaluemap#example does seem to go anywhere. Please check..

I mean *does not* go anywhere

This issue has been fixed.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.