KeyValueMapOperations 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

提供对 Apigee 中可用键值映射 (KVM) 存储区的基于政策的访问权限。您可以配置分别指定 PUT、GET 或 DELETE 操作的 KeyValueMapOperations 政策，以便从指定的现有映射中存储、检索和删除键值对。（政策必须至少执行这些操作中的一个）。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

注意：从 Apigee Hybrid 1.4.0 版开始，默认情况下，Apigee 会对所有 KVM 进行加密。通过 GET 命令访问 KVM 时，将 private. 特性与所有变量一起使用，以在调试会话中隐藏 KVM 信息。如果未使用 private. 特性，则 KVM 仍被加密；但是，KVM 信息将在调试会话中显示为解密，并且不会抛出任何异常。

视频：以下视频简要介绍了 KVM。

示例

PUT 具有字面量的 KVM

以下政策运行后，会创建一个名为 FooKVM 的加密 KVM，然后创建一个名为 FooKey_1 的键，该键具有两个使用字面量字符串 foo 和 bar 设置的值（这两个值不是使用变量中提取的值进行设置的）。在下一个示例中通过 GET 操作获取该键时，您需要指定索引编号以检索所需的值。

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

请注意，范围是 environment。这意味着您可以在管理界面的 APIs > Environment Configuration > Key Value Maps 下查看该 KVM。该页面上显示的 KVM 的范围均限定为所选环境。

从字面量 GET KVM

此政策对上一个示例中的 FooKVM 映射进行操作，从 FooKey_1 键中获取第二个值 (index="2")，并将其存储在名为 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>

动态访问 KVM

此政策使用 <MapName> 元素通过流变量动态引用 KVM。元素从流变量中获取 KVM 标识符。请注意，mapIdentifier 属性省略；您不能将 <MapName> 与 mapIdentifier 属性一起使用。

<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

网址缩短服务就是一个简单实用的 KVM 示例。KVM 可以配置为存储缩短的网址以及相应的完整网址。

此政策示例创建了一个 KVM。该政策会使用 PUT 命令将具有两个关联值的键放置在名为 urlMapper 的 KVM 中。

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

此示例中的键 urlencoding.requesturl.hashed 是自定义变量的示例。经过哈希处理的请求网址将由代码（例如 JavaScript 或 Java）生成并存储在此变量中，KeyValueMapOperations 政策可以进行访问。

对于每个键 requesturl.hashed，将存储两个值：

• 名为 urlencoding.longurl.encoded 的自定义变量的内容
• 预定义变量 request.queryparam.url 的内容

例如，当该政策在运行时执行时，变量的值可能如下所示：

• urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
• urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
• request.queryparam.url: http://apigee.com

以下 KVM 和条目将在 Apigee 的键/值存储区中生成，其范围仅限于政策附加至的 API 代理：

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

此条目在删除之前会一直保留。键值对存储区条目分布在云端运行的 Apigee 实例中。

从变量 GET KVM

网址缩短服务就是一个简单实用的 KVM 示例。KVM 可以配置为存储缩短的网址以及相应的完整网址。

如需检索 KVM 条目的值（例如 KeyValueMapOperations PUT 标签页上所包含的值），请将政策配置为 GET KVM：

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

执行此政策时，如果 urlencoding.requesturl.hashed 变量的值为 ed24e12820f2f900ae383b7cc4f2b31c402db1be，则名为 urlencoding.shorturl 的自定义变量的值将被设置为 http://tinyurl.com/38lwmlr。

现在数据已被检索，其他政策和代码可以通过从这些变量中提取值来访问这些数据。

从 KVM 获取值

通过 GET 命令访问 KVM 时，将 private. 特性与所有变量一起使用，以在调试会话中隐藏 KVM 信息。如果未使用 private. 特性，则 KVM 仍被加密；但是，KVM 信息将在调试会话中显示为解密，并且不会抛出任何异常。

在此示例中，变量 private.encryptedVar 包含 KVM 的 foo 键的解密值。

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

现在数据已被检索，其他政策和代码可以通过从该变量中提取值来访问这一数据。

<KeyValueMapOperations>

提供对键值映射 (KVM) 的基于政策的访问权限。

语法

<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> 属性

以下示例展示了 <KeyValueMapOperations> 元素的特性：

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

下表介绍了 <KeyValueMapOperations> 元素的特性：

注意：mapIdentifier 特性指定您要与之交互的 KVM 的名称。您也可以使用 <MapName> 元素动态指定 KVM。

属性	说明	默认	状态
mapIdentifier	指定一个标识符，其可告知政策应访问哪个 KVM。 如果缺少此标识符和 <MapName>，则使用名为 kvmap 的 KVM。如果您指定 <MapName> 元素，则无法使用此属性。	不适用	可选

下表介绍了所有政策父元素通用的特性：

特性	说明	默认	状态
name	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必填
continueOnError	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。 设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	是	可选
async	此特性已弃用。	false	已弃用

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

默认	不适用 如果省略此元素，则会使用政策的 name 属性的值。
状态	可选
类型	字符串

子元素

本部分介绍了 KeyValueMapOperations 政策的元素和特性：

<Delete> 元素

删除指定的键值对。必须至少使用 <Get>、<Put> 或 <Delete> 中的一个。

请务必使用根元素上的 mapIdentifier 属性或 <MapName> 元素指定 KVM 的名称。例如：

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

默认	不适用
状态	如果 <Get> 或 <Put> 不存在，则此元素是必需的。
类型	不适用

<Entry> 元素

KVM 的种子值，该值在初始化时填充在 KVM 中。对于 Apigee，键大小的上限为 2 KB。

例如：

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

默认	不适用
状态	可选
类型	不适用

<ExclusiveCache> 元素

已弃用。请改用 <Scope> 元素。

<ExpiryTimeInSecs> 元素

指定一个以秒为单位的时长，在此时长后，Apigee 从指定的 KVM 刷新其缓存值。

值为 0 或 -1，或者如果不包括此元素，则意味着使用 300 秒的默认值。例如：

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

默认	300（5 分钟）
状态	可选
类型	整数

KVM 是用于将键和值存储在 NoSQL 数据库中的长期持久性机制。因此，在运行时从 KVM 读取数据可能会导致代理性能下降。为了提升性能，Apigee 内置了在运行时在内存中缓存 KVM 键值对的机制。对于 GET 操作，此 KVM 操作政策始终从缓存中读取数据。

通过 <ExpiryTimeInSecs> 元素，您可以控制政策中使用的键值对在缓存中存储多长时间后才会从 KVM 中刷新。但是，GET 和 PUT 操作对缓存到期时间的影响有所不同。

GET - 第一次执行 KVM GET 操作时，从 KVM 请求的键/值（在政策的根 mapIdentifier 属性中或 <MapName> 元素中指定其名称）加载到缓存中，其中后续 GET 操作会一直存在，直到发生以下情况之一：

• <ExpiryTimeInSecs> 中指定的秒数到期。
  或
• KVM 政策中的 PUT 操作覆盖现有值（详见下文的说明）。

PUT - PUT 操作将键值对写入指定的 KVM。如果 PUT 向缓存中已存在的键写入数据，则缓存会立即刷新，并且现在将新值保存政策的 <ExpiryTimeInSecs> 元素指定的秒数。但是，使用 PUT 只会刷新为请求提供服务的单个运行时节点中的缓存。如需刷新每个分布式运行时节点中的缓存，请使用 <ExpiryTimeInSecs> 元素为每个节点指定刷新间隔。

示例 - 缓存 KVM

1. 一个 GET 操作检索“rating”的值，这会将值“10”添加到缓存中。该政策的 <ExpiryTimeInSecs> 为 60。
2. 30 秒后，该 GET 政策再次执行并从缓存中检索 10。
3. 5 秒后，一个 PUT 政策将 rating 的值更新为 10，该 PUT 政策的 <ExpiryTimeInSecs> 为 20。缓存会立即刷新为新值，并且新值现在设置为缓存 20 秒。（如果未进行该 PUT 操作，则第一个 GET 操作最初填充的缓存会再保持 30 秒，即最初的 60 秒剩余的时间。）
4. 15 秒后，另一个 GET 执行并检索到值 8。

注意

• 为获得最佳性能，请平衡缓存到期时间与预期的 API 流量。例如，如果流量很大，您可能需要设置较长的缓存到期间隔，以避免频繁从数据库刷新。
• 您无法手动重置 KVM 缓存。但是，您可以创建临时政策，以使用较短的 <ExpiryTimeInSecs> 执行一次性 PUT 操作。这会以您指定的秒数重置缓存，其中包含要 PUT 的值。
• 使用 Apigee 界面或 API 更新 KVM 不会重置 KVM 缓存。
• 您可以在同一政策中使用多个操作。如果您这样做，则该政策会按顺序执行这些操作。如果您在同一政策中使用 PUT 并使用相同的键后跟 GET，则 PUT 在写入时会隐式重置缓存到期时间。

<Get> 元素

检索指定键的值。必须至少使用 <Get>、<Put> 或 <Delete> 中的一个。

Apigee 会对存储在 KVM 中的所有数据进行加密。如需了解详情，请参阅加密密钥简介。使用 <Get> 时，Apigee 会解密存储的数据，并将其分配给消息上下文中的变量。变量名称使用 assignTo 属性指定。

请务必使用根元素上的 mapIdentifier 属性或 <MapName> 元素指定 KVM 的名称。

您可以在政策中添加多个 Get 块，以从 KVM 中检索多项内容。

注意：您可以在同一政策中使用多个操作。如果您这样做，则该政策会按顺序执行这些操作。如果您在同一政策中使用 PUT 并使用相同的键后跟 GET，则 PUT 在写入时会隐式重置缓存到期时间。如需了解详情，请参阅 ExpiryTimeInSecs 元素。

默认	不适用
状态	如果 <Put> 或 <Delete> 不存在，则此元素是必需的。
类型	不适用

特性

下表介绍了 <Get> 元素的特性：

特性	说明	默认	状态
assignTo	检索到的值应分配到的变量。	不适用	必需
index	要从多值键中提取的项的索引编号（从 1 开始的索引）。例如，指定 index=1 将返回第一个值并将其分配给 assignTo 变量。如果未指定索引值，则该条目的所有值都将作为 java.util.List 分配给变量。 如需查看示例，请参阅示例中的“从 KVM 获取值”标签页。	不适用	可选

从 KVM 获取单个项

通过以下步骤配置示例，该政策会读取并解密 KVM 中单个键的值，并将解密后的值分配给名为 myvar 的变量。

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

从调试会话中排除检索到的数据

在某些情况下，存储在 KVM 中的数据是敏感数据。为了防止检索到的数据显示在调试会话中，请对 assignTo 属性中指定的变量名称使用 private. 前缀。如果您不使用 private. 前缀，则从 KVM 检索的数据会以明文形式显示在您创建的任何调试会话中。

通过以下步骤配置示例，该政策会读取并解密与 KVM 中的单个键关联的值，并将该值分配给变量。分配不会显示在调试会话中。

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

从 KVM 获取多个项

在以下示例中，假设一个 KVM 具有以下键和值。除了存储有史以来最受欢迎的电影列表之外，此 KVM 还存储了所有主要电影的导演姓名。

键	值
top_movies	Princess Bride,The Godfather,Citizen Kane
Citizen Kane	Orson Welles
Princess Bride	Rob Reiner
The Godfather	Francis Ford Coppola

您会注意到，与 top_movies 键关联的值包含多个电影名称（以英文逗号分隔）。

使用以下配置示例，该政策会检索当前热门电影及其导演的姓名：

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

调用 API 代理时，Apigee 会创建以下使用相应值的变量，这些变量之后可用于 API 代理流：

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

top.movie.pick 的值只是英文逗号分隔列表中的第一项，因为第一个 <Get> 元素使用的 index 属性为 1。然后，第二个 <Get> 元素使用分配给 top.movie.pick 的值作为键，以将值检索到 movie.director 中。

<InitialEntries> 元素

KVM 的种子值，这些值在初始化时填充在 KVM 中。请务必使用根元素的 mapIdentifier 特性指定 KVM 的名称。

注意：如果使用 <MapName> 元素，则不允许使用 <InitialEntries>。

例如：

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

使用此元素时，如果您在 Apigee 界面中将政策保存在已部署的 API 代理版本中，或者部署了包含具有此元素的政策的 API 代理软件包，则 KVM 中会自动创建键。如果政策中的值与 KVM 中的值不同，则在部署 API 代理时，KVM 中的值会被覆盖。任何新的键值对都将与现有的键值对一起添加到现有的 KVM 中。

此元素填充的键和值必须是字面量。例如，此元素不支持 <Parameter ref="request.queryparam.key">。

键大小的上限为 2 KB。

默认	不适用
状态	可选
类型	不适用

<Key> 元素

指定 KVM 条目中的键。此元素显示为 <Get>、<Put> 或 <Delete> 的子级，或显示为 <Entry> 元素的子级，后者是 <InitialEntries> 的子级。以下是一个固定键示例：

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

键可以是复合的，具有动态元素，这意味着可以附加多个 <Parameter> 来创建键。例如，可以组合 userID 和 role 变量的内容来创建一个动态键。下面是一个指定动态确定的复合键的步骤配置示例：

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

请务必查看 <Parameter> 元素，详细了解如何设置键名。

键大小的上限为 2 KB。

注意：名称 ratelimit 已被保留。如需了解详情，请参阅这篇 Apigee 社区帖子。

默认	不适用
状态	可选
类型	不适用

<MapName> 元素

<MapName> 元素使政策能够在运行时确定使用哪个 KVM。动态选择 KVM 可让您灵活地设计一个可访问不同 KVM 的 KeyValueMapOperations 政策，具体取决于执行政策的上下文。

一些示例：

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

<MapName>literal_string</MapName>

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

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

第一行以字面量字符串形式指定 KVM 名称。第二行从流变量获取名称。在第三行，如果流变量解析为空值，则使用字面量字符串。

如果您在政策中使用 <MapName>，请勿指定 mapIdentifier 属性。如需了解详情，请参阅政策属性。

如果在部署代理时不存在映射，则不会创建映射，并且在执行政策时 Apigee 会抛出运行时错误。如果提供了流变量，则不允许使用 <InitialEntries> 元素。您将在部署期间收到验证错误。

<Parameter> 元素

指定键值对中键的组成部分。该元素指定创建、更新、检索或删除键值对时的名称。

您可以使用以下形式指定名称：

• 字面量字符串

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• 变量，在运行时使用 ref 属性检索

  <Key>
    <Parameter ref="variable_name"/>
  </Key>
  

• 字面量和变量引用的组合

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

当 <Key> 元素包含多个 <Parameter> 元素时，有效的键字符串是每个参数值的串联（通过双下划线连接）。例如，在上面的示例中，如果 apiproxy.name 变量的值为 abc1，则有效的键将为 targeturl__abc1__weight。

无论您是获取、更新还是删除键值对条目，键名称必须与 KVM 中的键名称匹配。如需了解相关准则，请参阅指定和检索键名称。

默认	不适用
状态	必需
类型	字符串

属性

下表介绍了 <Parameter> 元素的属性：

特性	说明	默认	状态
ref	指定变量的名称，该变量的值包含要创建、获取或删除的键的确切名称。	不适用	如果起始标记和结束标记之间未提供字面量值，则该属性是必需的。

<Put> 元素

将键值对写入 KVM。如果根元素上的 mapIdentifier 属性指定的 KVM 不存在，并且未使用 <MapName> 元素，则系统会自动创建映射。如果键值映射已存在，则会向其添加键值对。

如需使用界面或 API 创建 KVM，请参阅：

• 将 KVM 与 Apigee 界面搭配使用，在界面中创建加密的环境范围 KVM
• 组织级范围键值映射 API
• 环境范围键值映射 API
• API 代理范围键值映射 API

注意：您可以在同一政策中使用多个操作。如果您这样做，则该政策会按顺序执行这些操作。如果您在同一政策中使用 PUT 并使用相同的键后跟 GET，则 PUT 在写入时会隐式重置缓存到期时间。如需了解详情，请参阅 ExpiryTimeInSecs 元素。

键大小的上限为 2 KB。

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

默认	不适用
状态	如果 <Get> 或 <Delete> 不存在，则此元素是必需的。
类型	不适用

警告：如果政策使用了 PUT 命令来使用 null 键在 KVM 中放置键值对，则会自动创建以下键：__$$_EDGE_KVM_EMPTY_KEY_$$__

例如，如果您使用变量引用填充键且引用的变量为 null，则会发生这种情况。当尝试使用 null 键执行新的 PUT 操作时，系统只会使用该键，因此每次执行政策时，该键的现有值都可能会被覆盖。

特性

下表介绍了 <Put> 元素的属性：

特性	说明	默认	状态
override	如果设置为 true，则它会替换键的值。 当且仅当 KVM 存储区中当前不存在针对该键的条目时，才会写入 <Put override="false">。	true	可选

<Scope> 元素

定义 KVM 的无障碍功能边界。默认范围是 environment，这表示默认情况下，映射条目由一个环境（例如，test 或 prod）中运行的所有 API 代理共享。如果将范围设置为 apiproxy，则只有将值写入映射的 API 代理才能访问 KVM 中的条目。

请注意，在访问映射或映射条目时，您必须指定在创建映射时所用的范围值。例如，如果映射是使用 apiproxy 范围创建的，则在检索其值、写入更改或删除条目时，您必须使用 apiproxy 范围。

<Scope>environment</Scope>

默认	environment
状态	可选
类型	字符串
有效值	organization environment apiproxy policy（API 代理修订版本）

<Value> 元素

指定键的值。您可以将值指定为字面量字符串，或者使用 ref 属性将值指定为要在运行时检索的变量：

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

或者：

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

您还可以添加多个 <Value> 元素来指定一个多部分值。这些值会在运行时合并。

以下示例向 KVM 添加两个键：

• 值为 v1,v2 的键 k1
• 值为 v3,v4 的键 k2

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

以下示例创建一个具有两个值的键。假设组织名称为 foo_org，API 代理名称为 bar，环境为 test，则创建：

• 值为 bar,test 的键 foo_org

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

默认	不适用
状态	必需
类型	字符串

属性

下表介绍了 <Value> 元素的属性：

特性	说明	默认	状态
ref	指定变量的名称，该变量的值包含要设置的键值对。	不适用	如果起始标记和结束标记之间未提供字面量值，则该属性是必需的。如果提供了字面量值，则禁止使用该属性。

错误参考信息

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 and Handling faults.

Runtime errors

These errors can occur when the policy executes.

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.

Deployment errors

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

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.
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.
ValueIsMissing	This error occurs if the <Value> element is missing underneath the <Entry> element of the <InitialEntries> element of the KeyValueMapOperations policy.

架构

示例：查看我们的 GitHub 代码库示例，了解最新架构。

使用说明

如需查看 KVM 的概览，请参阅使用键值映射。

使用 Apigee 界面，您只能在环境范围内定义 KVM，如将 KVM 与 Apigee 界面搭配使用中所述。使用 Apigee API，您可以在组织、环境或 API 代理范围内定义 KVM，如以下各部分所述：

• 组织级范围键值映射 API
• 环境范围键值映射 API
• API 代理范围键值映射 API

对于采用键值对形式的数据，KVM 存储区提供了一个轻量级的持久化机制。您可以通过政策或代码在运行时访问这些数据。映射包含 key=value 格式的任意数据。

注意：键大小的上限为 2 KB。

例如 localhost=127.0.0.1、zip_code=94110 或 first_name=felix。在第一个示例中，localhost 是键，127.0.0.1 是值。每个键值对都以条目的形式存储在键值映射中。一个 KVM 可以存储多个条目。

例如，假设您需要存储与各种后端环境关联的 IP 地址列表。您可以创建一个名为 ipAddresses 的 KVM，其中包含键值对条目的列表。例如，下面的 JSON 可以表示以下映射：

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

您可以使用此结构来创建 IP 地址存储区，供政策在运行时用于实施 IP 许可名单和禁止名单、动态选择后端目标地址等。KeyValueMapOperations 政策通常用于存储或检索需要在多个请求/响应事务中重复使用的长期信息。

KVM 可以通过 KeyValueMapOperations 政策操作，也可以直接通过 Apigee API 操作。例如，您可以使用 API 将大型数据集上传到键值对存储区，或创建脚本来管理键值映射条目。您需要先使用 API 创建 KVM，然后才能通过 KeyValueMapOperations 政策访问它。

指定和检索键名称

通过 <Parameter> 和 <Value> 元素，您可以指定字面量值（值位于起始标记和结束标记之间），或使用 ref 属性指定其值应在运行时使用的变量的名称。

请特别注意 <Parameter> 元素，因为它决定了要创建的键的名称以及要检索或删除的键的名称。以下是两个示例。第一个示例以字面量指定键名称，第二个示例使用变量指定键名称。假设以下示例用于在 KVM 中创建键：

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

在第一个例子中，字面量值 KEY_NAME_LITERAL 作为键名称存储在 KVM 中。在第二个例子中，key.name.variable 中的任何值都将成为 KVM 中的键名称。例如，如果 key.name.variable 包含值 foo，则键名将为 foo。

如需通过 GET 操作检索键和键值对（或使用 DELETE 操作进行移除），<Parameter> 元素的值必须与 KVM 中的键名匹配。例如，如果 KVM 中的键名称为 my_key，您可以使用 <Parameter>my_key</Parameter> 指定字面量值，也可以指定包含 mny_key 这一确切值的变量，例如：<Parameter ref="variable.containing.foo"/>。

注意：名称 ratelimit 已被保留。如需了解详情，请参阅配额政策 - 抛出 NullPointerException。

相关主题

如需详细了解 KVM，请参阅以下主题：

• 使用键值映射
• 组织级范围键值映射 API
• 环境范围键值映射 API
• API 代理范围键值映射 API