KeyValueMapOperations policy map 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>k1</Parameter>             
         </Key>             
         <Value>v1</Value>         
      </Entry>         
      <Entry>             
         <Key>                 
            <Parameter>k2</Parameter>             
         </Key>             
         <Value>v3</Value>             
         <Value>v4</Value>         
      </Entry>     
   </InitialEntries>     
   <Put override="false">         
      <Key>             
         <Parameter ref="mykeyvar"></Parameter>         
      </Key>         
      <Value ref="myvalvar1"/>     
   </Put>     
   <Get assignTo="myvar" index="1">         
      <Key>             
         <Parameter ref="myvar"></Parameter>         
      </Key>     
   </Get>     
   <Delete>         
      <Key>             
         <Parameter ref="myvar"></Parameter>         
      </Key>     
   </Delete>     
   <Scope>environment</Scope> 
</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.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). 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

<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

<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

<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

<InitialEntries> element

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

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

<InitialEntries>/<Entry> element

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

<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</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>k2</Parameter>
   </Key>
   <Value>v3</Value>
   <Value>v4</Value>
</Entry>
Default: N/A
Presence: Optional
Type: N/A

<InitialEntries>/<Entry>/<Key>/<Parameter> element

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.

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

<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>v1</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

<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

<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 ref="mykeyvar"></Parameter>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put> 
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.

<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  

<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 ref="myvar"></Parameter>         
   </Key>     
</Get>
Default: N/A
Presence: Required if <Put> or <Delete> are not present.
Type: N/A

Attributes

Attribute Description Default Presence
assignTo

Assigns the retrieved value to a flow variable or simply a variable.

N/A Required
index

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 the KeyValueMapOperations GET tab in Samples.

N/A Optional

<Get>/<Key> element

Specifies the key for the value to be retrieved.

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

<Get>/<Key>/<Parameter> element

Specifies the key for the value to be retrieved.

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

<Delete> element

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

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

<Delete>/<Key> element

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

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

<Delete>/<Key>/Parameter element

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

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

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, which can be accessed at runtime by policies or code running on Edge. "Key/value" refers to 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. 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. You will need to create a key/value map with the API before accessing it with the KeyValueMapOperations policy.

Related topics

Organization Key/Value Maps

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)