<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息

内容
提供对 Apigee Edge 中可用的键值对映射 (KVM) 存储区的基于政策的访问权限。 您可以配置指定 PUT、GET 或 DELETE 操作的 KeyValueMapOperations 政策,以便从指定的现有映射中存储、检索和删除键值对。(政策必须至少执行这些操作中的一个)。
视频
观看以下视频,详细了解 KVM。
视频 | 说明 |
---|---|
为何使用键值映射? | 了解为何需要 KVM 及其工作原理。 |
使用界面创建 KVM 并在运行时检索 KVM | 创建 KVM,使用 KVM 政策检索其值,并使用流变量将值注入 API 请求。 |
在 API 运行时中创建和更新 KVM | 使用 KVM 政策在 API 运行时中创建 KVM。 |
缓存 KVM 以提升性能 | 通过缓存数据提升 KVM 政策的性能。 |
存储加密的 KVM | 将敏感信息以加密格式存储在 KVM 中,并使用 KVM 政策和非公开变量在运行时检索相应值。 |
使用 KVM 范围管理访问权限 | 使用 KVM 政策范围属性限制 KVM 的组织、环境、API 代理或 API 代理修订版本。 |
删除 API 运行时中的 KVM 条目 | 使用 KVM 政策 DELETE 操作删除 API 运行时中的 KVM 条目。 |
示例
PUT 具有字面量的 KVM
以下政策在运行时会创建一个加密的 KVM,其名称为
FooKVM
,然后创建一个名为 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>
PUT 具有变量的 KVM
一个有用的键值映射的简单示例是网址缩短服务。键值映射可以配置为存储缩短的网址以及相应的完整网址。
此政策示例创建一个键值映射。政策会将具有两个关联值的键 PUT 到名为“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>
此示例中的键 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
以下键值对映射和条目将在 Edge 的键值对存储区中生成,并且 将范围限定为关联该政策的 API 代理:
{ "entry" :[ { "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be", "value" : "http://tinyurl.com/38lwmlr,http://apigee.com" } ], "name" : "urlMapper" }
此条目在删除之前会一直保留。键值对存储区条目分布于 运行云的 Edge 实例。
从变量 GET KVM
一个有用的键值映射的简单示例是网址缩短服务。键值映射可以配置为存储缩短的网址以及相应的完整网址。
要检索键值映射条目的值(例如 KeyValueMapOperations PUT 标签页上所描述的条目),请配置政策以获取键值映射:
<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 加密值
如果键值映射已加密,请在 assignTo
属性值中使用“private.
”前缀来检索值。在此示例中,变量 private.encryptedVar
存储键值映射的 foo
键的解密值。如需了解如何创建加密的键值对映射,请参阅
请参阅“键/值映射”的主题
Management API。
<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map"> <Scope>apiproxy</Scope> <Get assignTo="private.encryptedVar" index='1'> <Key> <Parameter>foo</Parameter> </Key> </Get> </KeyValueMapOperations>
现在数据已被检索,其他政策和代码可以通过从该变量中提取值来访问这一数据。
元素参考
元素参考介绍了 KeyValueMapOperations 政策的元素和属性:
<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>variable_name</Parameter> </Key> <Value>value_1_literal</Value> <Value>value_2_literal</Value> </Entry> </InitialEntries> <Put override="false"> <Key> <Parameter>key_name_literal</Parameter> </Key> <Value ref="variable_name"/> </Put> <Get assignTo="myvar" index="1"> <Key> <Parameter ref="variable_name"/> </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 |
指定在访问由此创建的地图时要使用的标识符。 政策或管理界面。 在适用于公有云的 Apigee Edge 中,KVM 名称区分大小写。
例如, 如果您不包括此属性,则会使用名为 在 organization/environment/apiproxy 范围内,您可以使用 |
无 | 可选 |
下表介绍了所有政策父元素通用的特性:
属性 | 说明 | 默认 | 状态 |
---|---|---|---|
name |
政策的内部名称。 (可选)使用 |
不适用 | 必填 |
continueOnError |
设置为 设置为 |
false | 可选 |
enabled |
设置为 设为 |
是 | 可选 |
async |
此特性已弃用。 |
false | 已弃用 |
<DisplayName> 元素
除了用于 name
属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
<DisplayName>Policy Display Name</DisplayName>
默认 |
不适用 如果省略此元素,则会使用政策的 |
---|---|
状态 | 可选 |
类型 | 字符串 |
<Delete> 元素
删除指定的键值对。必须至少使用 <Get>
、<Put>
或 <Delete>
中的一个。
请务必使用父元素上的 mapIdentifier
属性指定 KVM 的名称。例如:
<Delete> <Key> <Parameter>key_name_literal</Parameter> </Key> </Delete>
默认 | 不适用 |
---|---|
状态 | 如果 <Get> 或 <Put> 不存在,则此元素是必需的。 |
类型 | 不适用 |
<Entry> 元素
键值映射的种子值,该值在初始化时填充在键值映射中。
对于适用于公有云的 Edge,密钥大小上限为 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> 元素
指定 Edge 在多少秒后刷新其缓存值(以秒为单位) 指定 KVM。
值为 0 或 -1,或者如果不包括此元素,则意味着使用 300 秒的默认值。例如:
<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
默认 | 300 (5 分钟) |
---|---|
状态 | 可选 |
类型 | 整数 |
KVM 是用于将键和值存储在 NoSQL 数据库中的长期持久性机制。因此,在运行时从 KVM 读取数据可能会导致代理性能下降。改善 Edge 具有内置机制,可在运行时在内存中缓存 KVM 键/值。 对于 GET 操作,此 KVM 操作政策始终从缓存中读取数据。
通过 <ExpiryTimeInSecs>
元素,您可以控制政策中使用的键值对在缓存中存储多长时间后才会从 KVM 中刷新。但是,GET 和 PUT 操作对缓存到期时间的影响有所不同。
GET - KVM GET 操作第一次执行时,从 KVM(其名称在政策的根 mapIdentifier
属性中指定)中请求的键值对会加载到缓存中。除非发生以下任一情况,否则它们会一直用于后续 GET 操作:
<ExpiryTimeInSecs>
中指定的秒数到期。
或- KVM 政策中的 PUT 操作覆盖现有值(详见下文的说明)。
PUT - PUT 操作将键值对写入指定的 KVM。如果 PUT 操作向缓存中已存在的键写入数据,则缓存会立即刷新,并将新值保存政策的 <ExpiryTimeInSecs>
元素所指定的秒数。
示例 - 缓存 KVM
- 一个 GET 操作检索“rating”的值,这会将值“10”添加到缓存中。该政策的
<ExpiryTimeInSecs>
为 60。 - 30 秒后,该 GET 政策再次执行并从缓存中检索“10”。
- 5 秒后,一个 PUT 政策将“rating”的值更新为“8”,该 PUT 政策的
<ExpiryTimeInSecs>
为 20。缓存会立即刷新为新值,并且新值现在设置为缓存 20 秒。(如果未进行该 PUT 操作,则第一个 GET 操作最初填充的缓存会再保持 30 秒,即最初的 60 秒剩余的时间。) - 15 秒后,另一个 GET 执行并检索到值“8”。
<Get> 元素
检索指定键的值。必须至少使用 <Get>
、<Put>
或 <Delete>
中的一个。
请务必使用父元素上的 mapIdentifier
属性指定 KVM 的名称。
您可以在政策中添加多个 Get
块,以从 KVM 中检索多项内容。
默认 | 不适用 |
---|---|
状态 | 如果 <Put> 或 <Delete> 不存在,则此元素是必需的。 |
类型 | 不适用 |
从 KVM 获取单个项
<Get assignTo="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 |
下面是一个 KVM 政策配置,可用于检索当前最热门的电影及其导演的姓名:
<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 代理时,Edge 会创建以下 变量:
top.movie.pick=Princess Bride
movie.director=Rob Reiner
属性
下表介绍了 <Get>
元素的属性:
特性 | 说明 | 默认 | 状态 |
---|---|---|---|
assignTo |
检索到的值应分配到的变量。 如果键值映射已加密,则 assignTo 名称应以“ <Get assignTo="private.myvar"> 如果您尝试在不使用该前缀的情况下检索加密键值映射,则政策会抛出错误。前缀会在 API 代理跟踪记录和调试会话中隐藏加密值。出于基本安全目的,前缀在调试过程中是必需的。 如需了解如何创建加密的键值映射,请参阅键值映射管理 API 的“创建”主题以及创建和修改环境键值映射。 |
无 | 必需 |
索引 |
要从多值键中提取的项的索引编号(从 1 开始的索引)。例如,指定 如需查看示例,请参阅示例中的“从 KVM 获取加密值”标签页。 |
无 | 可选 |
<InitialEntries> 元素
键值映射的种子值,该值在初始化时填充在键值映射中。请务必使用父元素上的 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>
使用此元素时,当您在已部署版本的管理界面中保存政策时 或使用此元素(密钥)来部署包含政策的 API 代理软件包。 会在 KVM 中自动创建(未加密)。如果政策中的值与 KVM 中的值不同,则在部署代理时,KVM 中的值会被覆盖。任何新的键值对都将与现有的键值对一起添加到现有的 KVM 中。
此元素填充的键和值必须是字面量。例如,此元素不支持 <Parameter
ref="request.queryparam.key">
。
对于用于公有云的 Edge 和 私下交易市场的边缘。KVM 值不得超过 2 KB。
如需创建加密的 KVM,请使用 Key/Value Maps Management API。
默认 | 不适用 |
---|---|
状态 | 可选 |
类型 | 不适用 |
<Key> 元素
指定键值映射条目中的键。键可以是复合的,这意味着可以附加多个参数来创建键。例如,您可以将 userID
和 role
组合起来创建一个 key
。例如:
<Key> <Parameter>key_name_literal</Parameter> </Key>
请务必参阅 <Parameter> 元素,详细了解如何设置键名称。
对于适用于公有云的 Edge,密钥大小上限为 2 KB。 如需了解详情,请参阅适用于公共 Cloud API 的 Edge 与 Private Cloud API 之间的差异。
默认 | 不适用 |
---|---|
状态 | 可选 |
类型 | 无 |
<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
。
无论您是获取、更新还是删除键值对条目,键名称必须与键值映射中的键名称匹配。如需了解相关准则,请参阅指定和检索键名称。
默认 | 不适用 |
---|---|
状态 | 必填 |
类型 | 字符串 |
属性
下表介绍了 <Parameter>
元素的属性:
特性 | 说明 | 默认 | 状态 |
---|---|---|---|
ref | 指定变量的名称,该变量的值包含要创建、获取或删除的键的确切名称。 | 无 | 如果起始标记和结束标记之间未提供字面量值,则该属性是必需的。如果提供了字面量值,则禁止使用该属性。 |
<Put> 元素
将键值对写入键值映射(无论键值映射是加密还是未加密)。如果父元素上的 mapIdentifier
属性指定的键值映射不存在,则自动创建未加密的映射。如果键值映射已存在,则会向其添加键值对。
如需创建加密的键值对映射,请使用 Key/Value Maps Management API; 或参阅创建和修改环境键值对映射 在界面中创建加密环境范围的 KVM。
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
默认 | 不适用 |
---|---|
状态 | 如果 <Get> 或 <Delete> 不存在,则此元素是必需的。 |
类型 | 无 |
属性
下表介绍了 <Put>
元素的属性:
特性 | 说明 | 默认 | 状态 |
---|---|---|---|
override |
如果设置为 |
false |
可选 |
<Scope> 元素
定义键值映射的无障碍功能边界。默认范围是 environment
,这表示默认情况下,映射条目由一个环境(例如,test 或 prod)中运行的所有 API 代理共享。如果您将范围设置为 apiproxy
,则只有将值写入映射的 API 代理才能访问键值映射中的条目。
请注意,在访问映射或映射条目时,您必须指定在创建映射时所用的范围值。例如,如果映射是使用 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 | 指定变量的名称,该变量的值包含要设置的键值对。 | 无 | 如果起始标记和结束标记之间未提供字面量值,则该属性是必需的。如果提供了字面量值,则禁止使用该属性。 |
错误参考信息
Edge 政策返回的错误采用一致的格式,如错误代码参考文档中所述。
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 and Handling faults.
Runtime errors
These errors can occur when the policy executes.
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 |
build |
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 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.
|
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 Key Value Map Operations policy.
|
build |
ValueIsMissing |
This error occurs if the <Value> element is missing underneath the <Entry> element of
the <InitialEntries> element of the Key Value Map Operations policy. |
build |
架构
使用说明
如需大致了解键值映射,请参阅使用键值映射。
对于采用键值对形式的数据,键值映射存储区提供了一个轻量级的持久化机制。您可以通过政策或代码在运行时访问这些数据。映射包含 key=value
格式的任意数据。
例如 localhost=127.0.0.1
、zip_code=94110
或 first_name=felix
。在第一个示例中,localhost
是键,127.0.0.1
是值。每个键值对都以条目的形式存储在键值映射中。一个键值映射可以存储多个条目。
下面是一个使用键值对映射的示例。假设您需要存储 IP 地址列表
与各种后端相关联
环境您可以创建一个名为 ipAddresses
的键值映射,其中包含键值对条目的列表。例如,下面的 JSON 可以表示以下映射:
{ "entry" : [ { "name" : "Development", "value" : "65.87.18.18" }, { "name" : "Staging", "value" : "65.87.18.22" } ], "name" : "ipAddresses" }
您可以使用此结构创建可供政策使用的 IP 地址存储区 可在运行时强制执行 IP 许可名单或拒绝名单,以动态选择后端目标 地址等信息。KeyValueMapOperations 政策通常用于存储或检索需要在多个请求/响应事务中重复使用的长期信息。
可以通过 KeyValueMapOperations 策略来操作键/值映射,或直接通过 Apigee Edge Management API。如需详细了解 Organization key/value maps API,请参阅 Management API 参考文档。例如,您可以使用 API 将大型数据集上传到键值对存储区,或创建脚本来管理键值映射条目。您需要先使用 API 创建键值映射,然后才能通过 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 中的键名称为“foo”,您可以使用 <Parameter>foo</Parameter>
指定字面量值,也可以指定包含“foo”这一确切值的变量,例如:<Parameter ref="variable.containing.foo"/>
。