Send Docs Feedback

Key Value Map Operations policy

  About | Samples | Element reference | Error codes | Schemas | Related topics

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 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">
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>-1</ExpiryTimeInSecs>
   <InitialEntries>         
      <Entry>             
         <Key>                 
            <Parameter>key_name_literal</Parameter>             
         </Key>             
         <Value>v1</Value>         
      </Entry>         
      <Entry>             
         <Key>                 
            <Parameter ref="key_name_variable"></Parameter>             
         </Key>             
         <Value>v3</Value>             
         <Value>v4</Value>         
      </Entry>     
   </InitialEntries>     
   <Put override="false">         
      <Key>             
         <Parameter>key_name_literal</Parameter>         
      </Key>         
      <Value ref="myvalvar1"/>     
   </Put>     
   <Get assignTo="myvar" index="1">         
      <Key>             
         <Parameter ref="key_name_variable"></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">
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

This setting is only used for for internal optimization.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs. By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
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

<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

<InitialEntries>/

<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 ref="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 ref="key_name_variable"></Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>
Default: N/A
Presence: Optional
Type: N/A

<InitialEntries>/<Entry>/

<Key> element

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 create the key. For example, userID and role might be combined constitute a key.

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

<Delete>/

<Key> element

Specifies the key of the key/value pair to be deleted.

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

<Get>/

<Key> element

Specifies the key for the value to be retrieved.

<Get assignTo="myvar" index="1">         
   <Key>             
     <Parameter>key_name_literal</Parameter>         
   </Key>     
</Get>
Default: N/A
Presence: Required
Type: N/A

<Put>/

<Key> element

Specifies the key of the key/value pair to be written to an existing key value map.

<Put override="false">         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put> 
Default: N/A
Presence: Required
Type: N/A

<InitialEntries>/<Entry>/<Key>/

<Parameter> element

Specifies the key for a seed value for a map.

Be sure to see Specifying key names for guidelines.

<Entry>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
   <Value>v3</Value>
   <Value>v4</Value>
</Entry>
Default: N/A
Presence: Required
Type: String

<Delete>/<Key>/

<Parameter> element

Specifies the key of the key/value pair to be deleted.

Be sure to see Specifying key names for guidelines.

<Delete>         
   <Key>             
      <Parameter ref="myvar"></Parameter>         
   </Key>     
</Delete> 
Default: N/A
Presence: Required
Type: N/A

<Get>/<Key>/

<Parameter> element

Specifies the key for the value to be retrieved.

Be sure to see Specifying key names for guidelines.

<Get assignTo="myvar" index="1">         
   <Key>             
      <Parameter ref="myvar"></Parameter>         
   </Key>     
</Get>
Default: N/A
Presence: Required
Type: N/A

<Put>/<Key>/

<Parameter> element

Specifies the key of the key/value pair to be written to an existing key value map.

Be sure to see Specifying key names for guidelines.

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"></Parameter>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put> 
Default: N/A
Presence: Required
Type: String

Attributes

Attribute Description Default Presence
ref

 

N/A  

<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 (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.

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

<InitialEntries>/<Entry>/

<Value> element

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].

<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 not 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. 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

The <Parameter> element for key names can specify either a literal value (where the value is between the opening and closing <Parameter> tags) or specify a variable that holds the key name value (where the variable name is given as a value of the <Parameter> tag's ref attribute).

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

When getting or deleting the 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 consistentently for a given key.

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.

Related topics

Organization Key/Value Maps

 

Help or comments?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)