[Extensible policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy.md.txt#policy-types)

*This page
applies to **Apigee** and **Apigee hybrid**.*


*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*
![](https://fonts.gstatic.com/s/i/googlematerialicons/help/v13/gm_grey-24dp/1x/gm_help_gm_grey_24dp.png)

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

This policy is an *Extensible policy* and use of this policy might have cost or
utilization implications, depending on your Apigee license. For information on policy types
and usage implications, see
[Policy types](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy.md.txt#policy-types).

> [!NOTE]
> **Note:** Starting with the release of Apigee hybrid version 1.4.0, Apigee encrypts all KVMs by default. Use the `private.` attribute with all variables when accessing a KVM with the `GET` command to hide the KVM information in a Debug session. If the **`private.`** attribute is not used, the KVM is still encrypted; however, the KVM information will appear decrypted in the Debug session and no exception will be thrown.

**Video:** The following video provides a high-level introduction to KVMs.
<iframe width="560" height="315" src="https://www.youtube.com/embed/l1OqKOlSqo8" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope;
picture-in-picture" allowfullscreen></iframe>

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

```
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>
```

Notice that the scope is `environment`. That means you can
see the KVM in the Google Cloud console under **Apigee
\> Management \> Environments \>
\[environment\] \> Key value maps** . The KVMs shown on that
page are all scoped to the selected environment. You can also manage
KVM entries directly in the UI (see
[Manage KVM values using the Apigee UI](https://docs.cloud.google.com/apigee/docs/api-platform/cache/key-value-maps.md.txt#managingandusingkvms-manage-values-ui)).

### 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`.

```
<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
```

### Access a KVM dynamically

This policy uses the `<MapName>` element to reference a KVM dynamically with
a flow variable. The element
obtains the KVM identifier from the flow variable. Note that the `mapIdentifier`
attribute is omitted; you cannot use `<MapName>` with
the `mapIdentifier` attribute.

```
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
```

### PUT KVM with a variable

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

This policy sample creates a KVM. The policy uses the `PUT` command to place a
key with two associated values
into a KVM named `urlMapper`.

```
<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>
```

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 KVM and entry would be generated in Apigee'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 Apigee that are running the cloud.

### GET KVM from a variable

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

To retrieve the value of KVM entry, such as the one covered on the
KeyValueMapOperations `PUT` tab, configure a policy to `GET` the KVM:

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

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 value from KVM


Use the `private.` attribute with all variables when accessing a KVM with the
`GET` command to hide the KVM information in a Debug session. If the
`private.` attribute is not used, the KVM is still encrypted; however, the KVM
information will appear decrypted in the Debug session and no exception will be thrown.

In this example, the variable
`private.encryptedVar` holds the decrypted value of the KVM's
`foo` key.

```
<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
  <Scope>apiproxy</Scope>
  <Get assignTo="private.encryptedVar" index='1'>
    <Key>
      <Parameter>foo</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
```

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

## \<KeyValueMapOperations\>

Provides policy-based access to a key value map (KVM).

### Syntax

```
<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>300</ExpiryTimeInSecs>
  <InitialEntries>
    <Entry>
      <Key>
        <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
    </Entry>
    <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Get>
  <Delete>
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Delete>
</KeyValueMapOperations>
```

## \<KeyValueMapOperations\> attributes

The following example shows the attributes of the
`<KeyValueMapOperations>` element:

```
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">
```

The following table describes the attributes of the
`<KeyValueMapOperations>` element:

> [!NOTE]
> **Note:** The `mapIdentifier` attribute specifies the name of the KVM that you want to interact with. You can also specify a KVM dynamically with the `<MapName>` element.

| Attribute | Description | Default | Presence |
|---|---|---|---|
| `mapIdentifier` | Specifies an identifier that tells the policy which KVM it should access. If both this identifier and `<MapName>` are missing, a KVM named `kvmap` is used. You cannot use this attribute if you specify the `<MapName>` element. | 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 `<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. See also: - [Fault rules are triggered ONLY in an error state (about continueOnError)](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling.md.txt#multiplefaultrulesandexecutionlogic-faultrulesaretriggeredonlyinanerrorstateaboutcontinueonerror) - [Handling faults within the current flow](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling.md.txt#continueonerror) | 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 |

## \<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 value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|

## Child elements

This section describes the elements and attributes of the KeyValueMapOperations
policy:

### \<Delete\> element

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

Be sure to specify the name of the KVM with the `mapIdentifier` attribute
on the root element or with the `<MapName>` element. For example:

```
<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>
```

| Default | N/A |
| Presence | Required if `<Get>` or `<Put>` are not present. |
| Type | N/A |
|---|---|

### \<Entry\> element

Seed values for KVMs, which are populated in the KVM when it is
initialized. For Apigee, the key size is limited to 2 KB.

For example:

```
<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 the duration in seconds after which Apigee 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:

```
<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
```

| 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, Apigee 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 `<ExpiryTimeInSecs>` 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 or the `<MapName>` element) are loaded into cache, where they remain for subsequent `GET` operations until one of
the following occurs:

- The number of seconds specified in `<ExpiryTimeInSecs>` 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
`<ExpiryTimeInSecs>` element. However, using `PUT` will only refresh the cache
in the single runtime node that services the request. To refresh the cache in each distributed runtime node,
use the `<ExpiryTimeInSecs>` element to specify refresh intervals for each node.

#### Example - Caching a KVM

1. A `GET` operation retrieves the value of "rating," which adds the value "10" to cache. The `<ExpiryTimeInSecs>` 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 `<ExpiryTimeInSecs>` 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 policy-level mechanism to manually flush the KVM cache, and there is no way to invalidate a cached entry across all runtime nodes from a single policy execution. The cache is an in-memory L1 cache scoped to each individual runtime node and to each key, and `<ExpiryTimeInSecs>` controls only the TTL of that local cache entry. Cached entries are only refreshed when their configured `<ExpiryTimeInSecs>` elapses on each node.
>
>   > [!CAUTION]
>   > **Caution:** Do not attempt to "expire" a KVM value by issuing a `PUT` of a placeholder with a short `<ExpiryTimeInSecs>`. The placeholder value is written to the KVM permanently (KVM values have no server-side TTL) and will overwrite the previous value. `<ExpiryTimeInSecs>` affects only the local cache TTL on the node that executed the policy.
>
> - Updating a KVM with the Apigee UI or API does not reset the KVM cache.
> - You can use multiple operations in the same policy. If you do, the policy executes the operations in order. If you use a `PUT` followed by a `GET` in the same policy using the same key, the `PUT`, when it writes, will implicitly reset the cache expiration.

### \<Get\> element

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


Apigee encrypts all data stored in the KVM. For details, see [About
encryption keys](https://cloud.google.com/apigee/docs/api-platform/security/encryption-keys). When using `<Get>`, Apigee decrypts the stored data and
assigns it to a variable in the message context. The variable name is specified using the
`assignTo` attribute.

Be sure to specify the name of the KVM either with the `mapIdentifier` attribute on the
root element or with the `<MapName>` element.

You can include multiple `Get` blocks in the policy to retrieve multiple items
from a KVM.

> [!NOTE]
> **Note:** You can use multiple operations in the same policy. If you do, the policy executes the operations in order. If you use a `PUT` followed by a `GET` in the same policy using the same key, the `PUT`, when it writes, will implicitly reset the cache expiration. See the [`ExpiryTimeInSecs`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#ExpiryTimeInSecsElement) element for more information.

| Default | N/A |
| Presence | Required if `<Put>` or `<Delete>` are not present. |
| Type | N/A |
|---|---|

#### Attributes

The following table describes the attributes of the \<Get\> element:

| 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 *Get Value from KVM* tab in [Samples](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#samples). | N/A | Optional |

#### Get a single item from a KVM


With this example step configuration, the policy reads and decrypts the value of a single key
in the KVM and assigns the decrypted value to a variable named `myvar`.

```
<Get assignTo="myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>
```

#### Excluding retrieved data from Debug Sessions

In some cases, data stored in the KVM is sensitive. To prevent the retrieved data
from appearing in a
[Debug session](https://cloud.google.com/apigee/docs/api-platform/debug/trace),
use the `private.` prefix on the variable name specified in the
`assignTo` attribute. If you do not use
the `private.` prefix, the data retrieved from the KVM will appear in
cleartext, in any Debug session you create.


With this example step configuration, the policy reads and decrypts the value associated to
a single key in the KVM and assigns that value to a variable. The assignment will not appear in
a Debug session.

```
<Get assignTo="private.myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>
```

#### 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 |

You will notice that the value associated to the `top_movies` key contains multiple
movie names, separated by commas.

With this example configuration, the policy retrieves the current top movie
and the name of its director:

```
<Get assignTo="top.movie.pick" index="1">
  <Key>
    <Parameter>top_movies</Parameter>
  </Key>
</Get>
<Get assignTo="movie.director">
  <Key>
    <Parameter ref="top.movie.pick"/>
  </Key>
</Get>
```

When the API proxy is called, Apigee creates the following variables with
corresponding values, that can be used later in the API proxy flow:

- `top.movie.pick=Princess Bride`
- `movie.director=Rob Reiner`

The value for `top.movie.pick` is just the first item in the comma-separated list,
because the first `<Get>` element uses an `index` attribute of 1.
Then, the second `<Get>` element uses the value assigned to
`top.movie.pick` as the key for retrieving a value into `movie.director`.

### \<InitialEntries\> element

Seed values for KVMs, which are populated in the KVM when it is initialized.
Be sure to specify the name of the KVM with the `mapIdentifier` attribute on
the root element.

> [!NOTE]
> **Note:** The `<InitialEntries>` is not allowed if the `<MapName>` element is used.

For example:

```
<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>
```

When using this element, when you save the policy in the Apigee UI on a deployed version
of the API proxy, or deploy the API proxy bundle containing the policy with this element, the key(s)
are automatically created in the KVM. If the values in the policy are different
than the values in the KVM, the values in the KVM are overwritten when the API 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, `<Parameter
ref="request.queryparam.key">` isn't supported within this element.

The key size is limited to 2 KB.

| Default | N/A |
| Presence | Optional |
| Type | N/A |
|---|---|

### \<Key\> element

Specifies the key in a KVM entry. This element appears as a child of [`<Get>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#GetElement),
[`<Put>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#PutElement), or [`<Delete>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#DeleteElement), or
as a child of the [`<Entry>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#InitialEntries_EntryElement) element
that is a child of [`<InitialEntries>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#InitialEntriesElement).
Here's an example of a fixed key:

```
<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>
```

A key can be composite, with dynamic elements, which means that more than one
`<Parameter>` can be appended to create the key. For example, the contents of the
variables `userID` and `role` might be combined to create a
dynamic key. Here's an example step configuration that specifies a composite, dynamically
determined key:

```
<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>
```

Be sure to see the [`<Parameter>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#parameter) element for
specifics about how to set the key name.

The key size is limited to 2 KB.

> [!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.html).

| Default | N/A |
| Presence | Optional |
| Type | N/A |
|---|---|

### \<MapName\> element

The `<MapName>` element enables the policy to identify which KVM to use dynamically, at runtime.
The ability to select KVMs dynamically gives you the flexibility to design one `KeyValueMapOperations` policy that can access
different KVMs, depending on the context in which the policy executes.

Some examples:

```
<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>
```

The first line specifies the KVM name as a literal string. The second line gets the name
from a flow variable. In the third line, if the flow variable resolves to an empty value, the literal string is used
instead.

Do not specify the `mapIdentifier` attribute if you use
`<MapName>` in your policy. See [policy attributes](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#keyvaluemapoperations_attributes) for more information.

If the map does not exist when the proxy is deployed, the map won't be created and Apigee throws a
runtime error when the policy is executed. If the flow variable is provided, the
`<InitialEntries>` element is not allowed. You will get a validation error during
deployment.

### `<Parameter>` element

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

You can specify the name by using:

- A literal string

  ```
  <Key>
    <Parameter>literal</Parameter>
  </Key>
  ```
- A variable to be retrieved at run time, using the `ref` attribute

  ```
  <Key>
    <Parameter ref="variable_name"/>
  </Key>
  ```
- A combination of literals and variable references

  ```
  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>
  ```

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 KVM. See [Specifying and
retrieving key names](https://docs.cloud.google.com/apigee/docs/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 `<Parameter>` 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. |

### \<Put\> element

Writes a key/value pair to a KVM. If the KVM specified in the `mapIdentifier` attribute on the
root element doesn't exist and if the `<MapName>` element is not used, the map is automatically created. If the key value
map already exists, the key/value are added to it.

To create a KVM using the UI or API, see:

- [Using KVMs with the Apigee UI](https://docs.cloud.google.com/apigee/docs/api-platform/cache/key-value-maps.md.txt#ui) to create encrypted environment-scoped KVMs in the UI
- [Organization-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.keyvaluemaps.md.txt)
- [Environment-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.environments.keyvaluemaps.md.txt)
- [API proxy-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.apis.keyvaluemaps.md.txt)

> [!NOTE]
> **Note:** You can use multiple operations in the same policy. If you do, the policy executes the operations in order. If you use a `PUT` followed by a `GET` in the same policy using the same key, the `PUT`, when it writes, will implicitly reset the cache expiration. See the [`ExpiryTimeInSecs`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#ExpiryTimeInSecsElement) element for more information.
>
> The key size is limited to 2 KB.

```
<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>
```

| Default | N/A |
| Presence | Required if `<Get>` or `<Delete>` are not present. |
| Type | N/A |
|---|---|

> [!WARNING]
> **Warning:** If the policy used the `PUT` command to place 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 `PUT` commands 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 `<Put>` element:

| Attribute | Description | Default | Presence |
|---|---|---|---|
| override | If set to `true`, it overrides the value for a key. `<Put override="false">` will write if and only if there is no entry currently persisted in the KVM store for that key. | `true` | Optional |

### \<Scope\> element

Defines the boundary of accessibility for KVMs. 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
KVM 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` (API proxy revision) |
|---|---|

> [!IMPORTANT]
> If you need to use the same KVM in multiple Proxies, consider adding your KVM policy to a SharedFlow and using the SharedFlow in the Proxies.

### \<Value\> 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:

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

or:

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

You can also include multiple `<Value>` 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`

```
<InitialEntries>
  <Entry>
    <Key>
      <Parameter>k1</Parameter>
    </Key>
    <Value>v1</Value>
    <Value>v2</Value>
  </Entry>
  <Entry>
    <Key>
      <Parameter>k2</Parameter>
    </Key>
    <Value>v3</Value>
    <Value>v4</Value>
  </Entry>
</InitialEntries>
```

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`

```
<Put>
  <Key>
    <Parameter ref="organization.name"/>
  </Key>
  <Value ref="apiproxy.name"/>
  <Value ref="environment.name"/>
</Put>
```

| Default | N/A |
| Presence | Required |
| Type | String |
|---|---|

#### Attributes

The following table describes the attributes of the `<Value>` 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


This section describes the fault codes and error messages that are returned and fault variables
that are set by Apigee 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.cloud.google.com/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors.md.txt) and [Handling faults](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/fault-handling.md.txt).

### Runtime errors

These errors can occur when the policy executes.

> [!IMPORTANT]
> **Tip:** Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

| Fault code | HTTP status | Cause | Fix |
|---|---|---|---|
| `steps.keyvaluemapoperations.UnsupportedOperationException` | `500` | This error occurs if the `mapIdentifier` attribute is set to empty string in the `KeyValueMapOperations` policy. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/runtime/key-value-map-runtime-errors.md.txt#unsupportedoperationexception) |

### Deployment errors

These errors can occur when you deploy a proxy containing this policy.

> [!IMPORTANT]
> **Tip:** 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 `<Get>` element of `KeyValueMapOperations` 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.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/deployment/key-value-map-deployment-errors.md.txt#invalidindex) |
| `KeyIsMissing` | This error occurs if the `<Key>` element is completely missing or `<Parameter>` element is missing within `<Key>` element underneath the `<Entry>` of the `<InitialEntries>` element of the `KeyValueMapOperations` policy. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/deployment/key-value-map-deployment-errors.md.txt#keyismissing) |
| `ValueIsMissing` | This error occurs if the `<Value>` element is missing underneath the `<Entry>` element of the `<InitialEntries>` element of the `KeyValueMapOperations` policy. | [](https://docs.cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/deployment/key-value-map-deployment-errors.md.txt#valueismissing) |

<br />

## 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 KVMs, see [Using key value maps](https://docs.cloud.google.com/apigee/docs/api-platform/cache/key-value-maps.md.txt).

Using the [Apigee UI](https://apigee.google.com), you can define KVMs at the environment scope only, as described in
[Using KVMs with the Apigee UI](https://docs.cloud.google.com/apigee/docs/api-platform/cache/key-value-maps.md.txt#ui).
Using the [Apigee API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest.md.txt), you can define KVMs at the organization, environment, or API proxy
scope, as described in the following sections:

- [Organization-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.keyvaluemaps.md.txt)
- [Environment-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.environments.keyvaluemaps.md.txt)
- [API proxy-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.apis.keyvaluemaps.md.txt)

A KVM 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`.

> [!WARNING]
> **Note:** The key size is limited to 2 KB.

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 KVM 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 KVM 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/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.

KVMs can be manipulated via the KeyValueMapOperations policy, or directly via the
Apigee API. You can use the API to, for
example, upload large data sets to the key/value store, or create scripts to manage key value
map entries. You will need to create a KVM with the API before accessing it with the
KeyValueMapOperations policy.

### Specifying and retrieving key names

With the [`<Parameter>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#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.

The [`<Parameter>`](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#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:

```
<Parameter>KEY_NAME_LITERAL</Parameter>
<Parameter ref="key.name.variable"/>
```

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

To retrieve the key and a key value with a `GET` operation (or remove with a
`DELETE` operation), the value of the `<Parameter>` element must match the key
name in the KVM. For example, if the key name in the KVM is `my_key`, you can either
specify the literal value with `<Parameter>my_key</Parameter>` or specify a
variable that contains the exact value `mny_key`, like this:
`<Parameter ref="variable.containing.foo"/>`.

> [!NOTE]
> **Note:** The name `ratelimit` is reserved. For more information, see [Quota
> Policy - Throws NullPointerException](https://discuss.google.dev/t/quota-policy-throws-nullpointerexception/11361.html).

## Related topics

Refer to the following topics for more information about KVMs:

- [Using key value maps](https://docs.cloud.google.com/apigee/docs/api-platform/cache/key-value-maps.md.txt)
- [Organization-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.keyvaluemaps.md.txt)
- [Environment-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.environments.keyvaluemaps.md.txt)
- [API proxy-scoped key value maps API](https://docs.cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.apis.keyvaluemaps.md.txt)