You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info
## What
Provides policy-based access to a Key Value Map (KVM) 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.)
> [!NOTE]
> **Note on size limits for keys and KVMs:**
>
> - In Edge for Public Cloud, the size of a key is limited to 2 KB.
> - In Edge for Private Cloud, the size of a KVM, including keys and values, is limited to 15 MB. Writing to the map might fail if the KVM size is greater than this limit, resulting in the following error message:
>
> ```
> HTTP Status: 500
> "faultstring":"Error while accessing datastore;Please retry later"
> "errorcode":"datastore.ErrorWhileAccessingDataStore"
> ```
## Videos
Watch the following videos to learn more about KVMs.
| Video | Description |
|---|---|
| [Why Key Value Maps?](https://www.youtube.com/watch?v=l1OqKOlSqo8) | Learn why you need KVMs and how they work. |
| [Create KVM using UI and retrieve KVM at runtime](https://www.youtube.com/watch?v=KeAbj4BYaa4) | Create a KVM, retrieve its value using a KVM policy, and inject the value into the API request using flow variables. |
| [Create and update a KVM at API runtime](https://www.youtube.com/watch?v=e_bybNuU5mY) | Create a KVM at API runtime using a KVM policy. |
| [Cache KVM to increase performance](https://www.youtube.com/watch?v=dFzxvsBPjs0) | Improve performance of KVM Policy by caching the data. |
| [Store encrypted KVM](https://www.youtube.com/watch?v=DvZ9QlJX43o) | Store sensitive information in KVM in an encrypted format and retrieve the value at runtime using KVM policy and private variables. |
| [Manage access using KVM scope](https://www.youtube.com/watch?v=WLtHTaU85ZU) | Restrict KVM to organization, environment, API proxy, or API proxy revision using KVM policy scope attribute. |
| [Delete KVM entries at API runtime](https://www.youtube.com/watch?v=X9rQLQfXAQU) | Delete KVM entries at API runtime using the KVM policy DELETE operation. |
## Samples
### PUT KVM with a literal
When the following policy runs, it creates an encrypted KVM named
`FooKVM`, then creates a key named `FooKey_1` with
two values set with literal strings `foo` and `bar`
(not set with values extracted from variables). When you
`GET` the key in the next example, you specify an index number
to retrieve the value you want.
```
FooKVM
86400
environment
FooKey_1
foo
bar
```
Notice that the scope is "environment". That means you can see the KVM in the management
UI under **APIs \> Environment Configuration \> Key Value Maps**. The KVMs
shown on that page are all scoped to the selected environment.
### GET KVM from a literal
This policy looks at the `FooKVM` map from the previous example, gets the
second value (index="2") from the `FooKey_1` key, and stores it in a variable
called `foo_variable`.
```
GetKVM
86400
environment
FooKey_1
```
### PUT KVM with a variable
A simple example of a useful key value map is a URL shortening service. The key value map
could be configured to store shortened URLs along with corresponding full URLs.
This policy sample creates a key value map. The policy PUTs a key with two associated values
into a key/value map named "urlMapper".
```
apiproxy
```
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.
### GET KVM from a variable
A simple example of a useful key value map is a URL 'shortening' service. The key value map
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 key value map:
```
apiproxy
```
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.
### GET encrypted value from KVM
If a key value map is encrypted, retrieve values by using the "`private.`"
prefix in the `assignTo` attribute value. In this example, the variable
`private.encryptedVar` holds the decrypted value of the key value map's
`foo` key. For information on creating encrypted key value maps, see the "create"
topics of the [Key/Value Maps
management API](https://docs.apigee.com/api-reference/content/keyvalue-maps-management-api).
```
apiproxy
foo
```
Now that the data has been retrieved, other policies and code can access it by extracting
the value from that variable.
*** ** * ** ***
## Element reference
The element reference describes the elements and attributes of the KeyValueMapOperations
policy:
```
Key Value Map Operations 1
environment
300
key_name_literal
value_literal
variable_name
value_1_literal
value_2_literal
key_name_literal
key_name_literal
```
## \ attributes
The following example shows the attributes on the `` tag:
```
```
The following table describes the attributes specific to the `` tag:
> [!NOTE]
> **Note:** The `mapIdentifier` attribute specifies the name of the KVM that you want to interact with.
| Attribute | Description | Default | Presence |
|---|---|---|---|
| mapIdentifier | Specifies an identifier to be used when accessing a map created by this policy or [in the management UI](https://docs.apigee.com/api-platform/cache/key-value-maps#managing). The KVM name is **case sensitive** with Apigee Edge for Public Cloud. For example, `foobar` is different than `FooBar`. If you exclude this attribute, a KVM named `kvmap` is used. Within a scope of organization/environment/apiproxy, you can use the `mapIdentifier` attribute to specify your own map name. | N/A | Optional |
The following table describes attributes that are common to all policy parent elements:
| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `` 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` | This attribute is deprecated. | false | Deprecated |
## \ element
Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.
```
Policy Display Name
```
| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|
## \ element
Deletes the specified key/value pair. At least one of ``,
``, or `` must be used.
Be sure to specify the name of the KVM with the `mapIdentifier` attribute
on the parent element. For example:
```
key_name_literal
```
| Default | N/A |
| Presence | Required if `` or `` are not present. |
| Type | N/A |
|---|---|
## \ element
Seed values for key value maps, which are populated in the key value map when it is
initialized.
For Edge for Public Cloud, the key size is limited to 2 KB. For example:
```
key_name_literal
v1
key_name_variable
v3
v4
```
| Default | N/A |
| Presence | Optional |
| Type | N/A |
|---|---|
## \ element
Deprecated. Use the `` element instead.
## \ element
Specifies the duration in seconds after which Edge refreshes its cached value from the
specified KVM.
A value of 0 or -1, or excluding this element, means the default value of 300 seconds is
used. For example:
```
600
```
| Default | `300` (5 minutes) |
| Presence | Optional |
| Type | Integer |
|---|---|
A KVM is a long-term persistence mechanism that stores keys and values in a NoSQL database.
Because of this, reading from a KVM at runtime can potentially slow proxy performance. To improve
performance, Edge has a built-in mechanism for caching KVM keys/values in memory during runtime.
This KVM Operations policy always reads from cache for GET operations.
The `` element lets you control how long the keys/values
used in the policy are stored in cache before they're refreshed again from the KVM. However,
there are some differences between how GET and PUT operations affect cache expiration.
**GET** - The very first time a KVM GET operation executes, the requested
keys/values from the KVM (whose name is specified in the policy's root `mapIdentifier`
attribute) are loaded into cache, where they remain for subsequent GET operations until one of
the following occurs:
- The number of seconds specified in `` expires.
or
- A PUT operation in a KVM policy overwrites the existing values (explained next).
**PUT** - A PUT operation writes keys/values to the specified KVM. If the PUT
writes to a key that already exists in cache, that cache is immediately refreshed and now holds
the new value for the number of seconds specified in the policy's
`` element.
### Example - Caching a KVM
1. A GET operation retrieves the value of "rating," which adds the value "10" to cache. The `` on the policy is 60.
2. 30 seconds later, the GET policy executes again and retrieves "10" from the cache.
3. 5 seconds later, a PUT policy updates the value of "rating" to "8", and the `` on the PUT policy is 20. The cache is immediately refreshed with the new value, which is now set to remain in cache for 20 seconds. (If the PUT hadn't happened, the cache originally populated by the first GET would still exist for another 30 seconds, left over from the original 60 seconds.)
4. 15 seconds later, another GET executes and retrieves a value of "8".
> [!NOTE]
> **Notes**
>
> - For best performance, balance cache expiry time with the amount of API traffic you expect. With heavy traffic, for example, you may want to set longer cache expiration intervals to avoid frequent refreshes from the database.
> - There is no way to manually reset the KVM cache. However, you can create a temporary policy that executes a one-time PUT operation with a short ``. This will reset the cache, which contains the value you PUT, for the number of seconds you specify.
> - Updating a KVM with the management UI or API does not reset the KVM cache.
> - Don't add the PUT and GET operations in the same policy, because the PUT automatically resets the cache expiration, which doesn't allow the GET operation to read from a cache with a desired expiry time.
## \ element
Retrieves the value for the key specified. At least one of ``,
``, or `` must be used.
Be sure to specify the name of the KVM with the `mapIdentifier` attribute on the
parent element.
You can include multiple `Get` blocks in the policy to retrieve multiple items
from a KVM.
> [!NOTE]
> **Note:** Don't add PUT and GET operations in the same policy, because the PUT automatically resets the cache expiration, which doesn't allow the GET operation to read from a cache with a desired expiry time. See the [`ExpiryTimeInSecs`](https://docs.apigee.com/api-platform/reference/policies/key-value-map-operations-policy#ExpiryTimeInSecsElement) element for more information.
| Default | N/A |
| Presence | Required if `` or `` are not present. |
| Type | N/A |
|---|---|
### Get a single item from a KVM
```
key_name_literal
```
### Get multiple items from a KVM
In the following example, assume a KVM with the following keys and values. In addition
to storing a running list of the most popular movies of all time, the KVM stores
the director name for all major films.
| Key | Value |
|---|---|
| top_movies | Princess Bride,The Godfather,Citizen Kane |
| Citizen Kane | Orson Welles |
| Princess Bride | Rob Reiner |
| The Godfather | Francis Ford Coppola |
Here's a KVM policy configuration we can use to retrieve the current most popular movie
and the name of its director:
```
top_movies
```
When the API proxy is called, Edge creates the following
variables that you can use in the API proxy flow:
- `top.movie.pick=Princess Bride`
- `movie.director=Rob Reiner`
### Attributes
The following table describes the attributes of the `` element:
| Attribute | Description | Default | Presence |
|---|---|---|---|
| assignTo | The variable to which the retrieved value should be assigned. If the key value map is encrypted, begin the assignTo name with "`private.`". For example: ``` ``` The policy throws an error if you try to retrieve an encrypted key value map without using the prefix. The prefix, which is required for basic security purposes during debugging, hides the encrypted values from API proxy Trace and debug sessions. For information on creating encrypted key value maps, see the "create" topics of the [Key/Value Maps management API](https://docs.apigee.com/api-reference/content/keyvalue-maps-management-api) and [Creating and editing environment key value maps](https://docs.apigee.com/api-platform/cache/creating-and-editing-environment-keyvalue-maps). | 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 "Get Encrypted Value from KVM" tab in [Samples](https://docs.apigee.com/api-platform/reference/policies/key-value-map-operations-policy#samples). | N/A | Optional |
## \ element
Seed values for key value maps, which are populated in the key value map when it is initialized.
Be sure to specify the name of the KVM with the `mapIdentifier` attribute on
the parent element. for example:
```
key_name_literal
v1
key_name_variable
v3
v4
```
When using this element, when you save the policy in the management UI on a deployed version
of the proxy, or deploy the API proxy bundle containing the policy with this element, the key(s)
are automatically created in the KVM (as unencrypted). If the values in the policy are different
than the values in the KVM, the values in the KVM are overwritten when the proxy is deployed. Any
new keys/values are added to the existing KVM alongside the existing keys/values.
Keys and values populated by this element must be literals. For example, `` isn't supported within this element.
The key size is limited to 2 KB for both Edge for the Public Cloud and
Edge for the Private Could. The KVM value is limited to 2 KB.
To create an encrypted KVM, use the [Key/Value Maps management API](https://docs.apigee.com/api-reference/content/keyvalue-maps-management-api).
| Default | N/A |
| Presence | Optional |
| Type | N/A |
|---|---|
## \ 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`. For example:
```
key_name_literal
```
Be sure to see the [\](https://docs.apigee.com/api-platform/reference/policies/key-value-map-operations-policy#ParameterElement) element for specifics about how to
set the key name.
With Edge for Public Cloud, the key size is limited to 2 KB.
See [Differences between the Edge for Public Cloud API and Private Cloud API](https://docs.apigee.com/api-platform/reference/api-differences-public-private) for more.
> [!NOTE]
> **Note:** The name `ratelimit` is reserved. For more information, see [this
> Apigee Community post](https://discuss.google.dev/t/quota-policy-throws-nullpointerexception/11361).
| Default | N/A |
| Presence | Optional |
| Type | N/A |
|---|---|
## \ element
Specifies the key in a key/value pair. This element specifies the name when creating, putting,
retrieving, or deleting the key/value pair.
You can specify the name by using:
- A literal string
```
literal
```
- A variable to be retrieved at run time, using the `ref` attribute
```
```
- A combination of literals and variable references
```
targeturl
weight
```
When the Key element includes multiple Parameter elements, the effective key string is the
concatenation of the values of each parameter, joined with a double underscore. For example, in
the above example, if the `apiproxy.name` variable has the value "abc1", then the
effective key will be `targeturl__abc1__weight`.
Whether you're getting, updating, or deleting a key/value entry, the key name must match the
name of the key in the key value map. See [Specifying and
retrieving key names](https://docs.apigee.com/api-platform/reference/policies/key-value-map-operations-policy#specifying_key_names) for guidelines.
| Default | N/A |
| Presence | Required |
| Type | String |
|---|---|
### Attributes
The following table describes the attributes of the `` element:
| Attribute | Description | Default | Presence |
|---|---|---|---|
| ref | Specifies the name of a variable whose value contains the exact name of the key you want to create, get, or delete. | N/A | Required if no literal value is given between the opening and closing tags. Prohibited if a literal value is given. |
## \ element
Writes a key/value pair to a key value map, whether the key value map is encrypted or
unencrypted. If the key value map specified in the `mapIdentifier` attribute on the
parent element doesn't exist, the map is automatically created (as unencrypted). If the key value
map already exists, the key/value are added to it.
To create an encrypted key value map, use
the [Key/Value Maps management API](https://docs.apigee.com/api-reference/content/keyvalue-maps-management-api);
or see [Creating and editing environment key value maps](https://docs.apigee.com/api-platform/cache/creating-and-editing-environment-keyvalue-maps)
to create encrypted environment-scoped KVMs in the UI.
> [!NOTE]
> **Note:** Don't add PUT and GET operations in the same policy, because the PUT automatically resets the cache expiration, which doesn't allow the GET operation to read from a cache with a desired expiry time. See the [`ExpiryTimeInSecs`](https://docs.apigee.com/api-platform/reference/policies/key-value-map-operations-policy#ExpiryTimeInSecsElement) element for more information.
>
> With Edge for Public Cloud, the key size is limited to 2 KB.
> See [Differences between the Edge for Public Cloud API and Private Cloud API](https://docs.apigee.com/api-platform/reference/api-differences-public-private) for more.
```
```
| Default | N/A |
| Presence | Required if `` or `` are not present. |
| Type | N/A |
|---|---|
> [!WARNING]
> **Warning:** If the policy PUTs a key/value in a KVM using a null key, the following key is auto-created: `__$$_EDGE_KVM_EMPTY_KEY_$$__`
>
> This situation would happen, for example, if you're populating a key using a variable
> reference and the referenced variable is null. As new PUTs with null keys are attempted, only
> that key is used, so existing values for that key are potentially overwritten each time the
> policy is executed.
### Attributes
The following table describes the attributes of the `` element:
| Attribute | Description | Default | Presence |
|---|---|---|---|
| override | If set to `true`, it overrides the value for a key. | `false` | Optional |
## \ element
Defines the boundary of accessibility for key value maps. 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 key value map 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.
```
environment
```
| Default | `environment` |
| Presence | Optional |
| Type | String |
| Valid values: | - `organization` - `environment` - `apiproxy` - `policy` (API proxy revision) |
|---|---|
## \ element
Specifies the value of a key. You can specify the value as either a literal string or, using
the `ref` attribute, as a variable to be retrieved at run time:
```
literal
```
or:
```
```
You can also include multiple `` elements to specify a multi-part
value. Values are combined at run time.
In the following example, two keys are added to the KVM:
- Key `k1` with values `v1,v2`
- Key `k2` with values `v3,v4`
```
k1
v1
v2
k2
v3
v4
```
In the following example, one key is created with two values. Let's assume the organization
name is `foo_org`, the API proxy name is `bar`, and the environment is
`test`:
- Key `foo_org` with values `bar,test`
```
```
| Default | N/A |
| Presence | Required |
| Type | String |
|---|---|
### Attributes
The following table describes the attributes of the `` element:
| Attribute | Description | Default | Presence |
|---|---|---|---|
| ref | Specifies the name of a variable whose value contains the key value(s) you want to set. | N/A | Required if no literal value is given between the opening and closing tags. Prohibited if a literal value is given. |
## Error reference
Errors returned from Edge policies follow a consistent format as described in the [Error code reference](https://docs.apigee.com/api-platform/reference/policies/error-code-reference).
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error.
This information is important to know if you are developing fault rules to
handle faults. To learn more, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).
### Runtime errors
These errors can occur when the policy executes.
> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.
> [!IMPORTANT]
> **Tip:** Use [API Monitoring](https://docs.apigee.com/api-monitoring) to investigate fault codes and diagnose issues faster. See [Set up a policy fault code alert](https://docs.apigee.com/api-monitoring/alerts-notifications#fault-code-alert) for an example. See [Fault code reference](https://docs.apigee.com/api-monitoring/fault-codes) for a complete list of all fault codes that you can handle with API Monitoring.
| Fault code | HTTP status | Cause | Fix |
|---|---|---|---|
| `steps.keyvaluemapoperations.SetVariableFailed` | 500 | This error occurs if you try to retrieve a value from an encrypted key value map and set the value to a variable whose name does not have the prefix `private`. The prefix, which is required for basic security purposes during debugging, hides the encrypted values from API proxy Trace and debug sessions. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/key-value-map-runtime-errors#setvariablefailed) |
| `steps.keyvaluemapoperations.UnsupportedOperationException` | 500 | This error occurs if the `mapIdentifier` attribute is set to empty string in the Key Value Map Operations policy. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/key-value-map-runtime-errors#unsupportedoperationexception) |
### Deployment errors
These errors can occur when you deploy a proxy containing this policy.
> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.
| Error name | Cause | Fix |
|---|---|---|
| `InvalidIndex` | If the `index` attribute specified in the `` element of Key Value Map Operations policy is zero or a negative number, then the deployment of the API proxy fails. The index starts from `1`, so an index of zero or negative integer is considered as invalid. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/key-value-map-deployment-errors#invalidindex) |
| `KeyIsMissing` | This error occurs if the `` element is completely missing or `` element is missing within `` element underneath the `` of the `` element of the Key Value Map Operations policy. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/key-value-map-deployment-errors#keyismissing) |
| `ValueIsMissing` | This error occurs if the `` element is missing underneath the `` element of the `` element of the Key Value Map Operations policy. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/key-value-map-deployment-errors#valueismissing) |
## Schemas
> [!NOTE]
> **Sample:** See our [GitHub
> repository](https://github.com/apigee/api-platform-samples/tree/master/schemas/policy) samples for the most recent schemas.
## Usage notes
For an overview of key value maps, see [Working with key value maps](https://docs.apigee.com/api-platform/cache/key-value-maps).
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.
Here's an example of using key value maps. Suppose 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 allowlisting or denylisting, 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](https://docs.apigee.com/api/keyvalue-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 and retrieving key names
With the `` and `` 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.
The Parameter element deserves special mention, because it determines the name of the key that
gets created, as well as the key name you want to retrieve or delete. Following are two examples.
The first specifies a key name literally, and the second specifies a key name using a variable.
Let's assume the following are used to create keys in a KVM:
```
key_name_literal
```
In the first instance, the literal value of "key_name_literal" is stored in the KVM as the key
name. In the second instance, whatever value is in the `key.name.variable` becomes the
name of the key in the KVM. For example, if the `key.name.variable` contained the
value `foo`, the key would be named "foo".
When you want to retrieve the key and a key value with a GET operation (or delete with a
DELETE operation), the \ setting needs to match the key name in the KVM. For
example, if the key name in the KVM is "foo", you can either specify the literal value with
`foo` or specify a variable that contains the exact
value "foo", like this: ``.
> [!NOTE]
> **Note:** The name `ratelimit` is reserved. For more information, see [this
> Apigee Community post](https://discuss.google.dev/t/quota-policy-throws-nullpointerexception/11361).
## Related topics
- [Organization key/value maps API](https://docs.apigee.com/api/keyvalue-maps)