本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
内容
提供对 Apigee 中可用键值映射 (KVM) 存储区的基于政策的访问权限。您可以配置分别指定 PUT
、GET
或 DELETE
操作的 KeyValueMapOperations 政策,以便从指定的现有映射中存储、检索和删除键值对。(政策必须至少执行这些操作中的一个)。
此政策是一项可扩展政策,使用此政策可能会影响费用或使用情况,具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响,请参阅政策类型。
视频:以下视频简要介绍了 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。 如果缺少此标识符和 |
不适用 | 可选 |
下表介绍了所有政策父元素通用的特性:
属性 | 说明 | 默认值 | 状态 |
---|---|---|---|
name |
政策的内部名称。 (可选)使用 |
不适用 | 必填 |
continueOnError |
设置为 设置为 |
false | 可选 |
enabled |
设置为 设为 |
true | 可选 |
async |
此特性已弃用。 |
false | 已弃用 |
<DisplayName> 元素
除了用于 name
属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
<DisplayName>Policy Display Name</DisplayName>
默认值 |
不适用 如果省略此元素,则会使用政策的 |
---|---|
状态 | 可选 |
类型 | 字符串 |
子元素
本部分介绍了 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
- 一个
GET
操作检索“rating”的值,这会将值“10”添加到缓存中。该政策的<ExpiryTimeInSecs>
为 60。 - 30 秒后,该
GET
政策再次执行并从缓存中检索10
。 - 5 秒后,一个
PUT
政策将rating
的值更新为10
,该PUT
政策的<ExpiryTimeInSecs>
为 20。缓存会立即刷新为新值,并且新值现在设置为缓存 20 秒。(如果未进行该PUT
操作,则第一个GET
操作最初填充的缓存会再保持 30 秒,即最初的 60 秒剩余的时间。) - 15 秒后,另一个
GET
执行并检索到值8
。
<Get> 元素
检索指定键的值。必须至少使用 <Get>
、<Put>
或 <Delete>
中的一个。
Apigee 会对存储在 KVM 中的所有数据进行加密。如需了解详情,请参阅加密密钥简介。使用 <Get>
时,Apigee 会解密存储的数据,并将其分配给消息上下文中的变量。变量名称使用 assignTo
属性指定。
请务必使用根元素上的 mapIdentifier
属性或 <MapName>
元素指定 KVM 的名称。
您可以在政策中添加多个 Get
块,以从 KVM 中检索多项内容。
默认 | 不适用 |
---|---|
状态 | 如果 <Put> 或 <Delete> 不存在,则此元素是必需的。 |
类型 | 不适用 |
特性
下表介绍了 <Get> 元素的特性:
特性 | 说明 | 默认 | 状态 |
---|---|---|---|
assignTo |
检索到的值应分配到的变量。 |
不适用 | 必需 |
index |
要从多值键中提取的项的索引编号(从 1 开始的索引)。例如,指定 如需查看示例,请参阅示例中的“从 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 的名称。
例如:
<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。
默认 | 不适用 |
---|---|
状态 | 可选 |
类型 | 不适用 |
<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 override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
默认 | 不适用 |
---|---|
状态 | 如果 <Get> 或 <Delete> 不存在,则此元素是必需的。 |
类型 | 不适用 |
特性
下表介绍了 <Put>
元素的属性:
特性 | 说明 | 默认 | 状态 |
---|---|---|---|
override |
如果设置为
当且仅当 KVM 存储区中当前不存在针对该键的条目时,才会写入 |
true |
可选 |
<Scope> 元素
定义 KVM 的无障碍功能边界。默认范围是 environment
,这表示默认情况下,映射条目由一个环境(例如,test 或 prod)中运行的所有 API 代理共享。如果将范围设置为 apiproxy
,则只有将值写入映射的 API 代理才能访问 KVM 中的条目。
请注意,在访问映射或映射条目时,您必须指定在创建映射时所用的范围值。例如,如果映射是使用 apiproxy
范围创建的,则在检索其值、写入更改或删除条目时,您必须使用 apiproxy
范围。
<Scope>environment</Scope>
默认 | environment |
---|---|
状态 | 可选 |
类型 | 字符串 |
有效值 |
|
<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.
Fault code | HTTP status | Cause | Fix |
---|---|---|---|
steps.keyvaluemapoperations.UnsupportedOperationException |
500 |
This error occurs if the |
build |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
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.
|
build |
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.
|
build |
ValueIsMissing |
This error occurs if the <Value> element is missing underneath the <Entry> element of
the <InitialEntries> element of the KeyValueMapOperations policy. |
build |
架构
使用说明
如需查看 KVM 的概览,请参阅使用键值映射。
使用 Apigee 界面,您只能在环境范围内定义 KVM,如将 KVM 与 Apigee 界面搭配使用中所述。使用 Apigee API,您可以在组织、环境或 API 代理范围内定义 KVM,如以下各部分所述:
对于采用键值对形式的数据,KVM 存储区提供了一个轻量级的持久化机制。您可以通过政策或代码在运行时访问这些数据。映射包含 key=value
格式的任意数据。
例如 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"/>
。
相关主题
如需详细了解 KVM,请参阅以下主题: