使用键值对映射

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

有时候,您想要在运行时存储数据以供检索,但不过期的数据不应在 API 代理逻辑中进行硬编码。键值对映射 (KVM) 非常适合这一点。KVM 是已加密或未加密的键/值字符串配对的自定义集合。以下是两个示例:

如需了解其他类型的持久化,请参阅添加缓存和持久化

KVM 场景

在下面这几种情况下,KVM 可以派上用场:

  • 您的 API 代理需要调用一个测试环境中的目标(或服务调用程序)网址,并在生产环境中调用另一个目标网址。您可以让代理检测其所处的环境,执行相关的键值对映射操作政策,并从您创建的一个 KVM 中检索正确的目标网址,而不是在代理中对网址进行硬编码。之后,如果您的一个或两个目标都发生更改,您只需使用新的网址更新 KVM。代理将提取新值,而无需重新部署代理。
  • 您想要存储凭据、私钥或令牌,例如外部服务的令牌、生成 OAuth 令牌所需的凭据,或 Java 调用程序或 JavaScript 中用于加密或 JSON 网络令牌 (JWT) 签名的私钥。您无需在请求中传递凭据、密钥或令牌,也不必在代理逻辑中对其进行硬编码,而是将它们存储在 KVM(始终加密)中,并在对需要它们的目标的调用中动态检索它们。

您会发现在其他情况下存储键/值字符串对是有用的。一般来说,在以下情况中,请考虑使用 KVM:

  • 代码中的特定位置在运行时需要不同的值。
  • 敏感数据需要不进行硬编码即可传递。
  • 您希望存储不会过期的值(例如缓存)。

KVM 具有范围

范围是指“KVM 可用的位置”。可以在以下范围内创建 KVM:organizationenvironmentapiproxy

例如,如果只有一个 API 代理需要 KVM 中的数据,您可以在 apiproxy 范围内创建该 KVM,此时只有该 API 代理可以访问数据。

或者,您可能希望测试环境中的所有 API 代理都有权访问键值对映射,在这种情况下,您将在环境范围内创建键值对映射。部署在“prod”环境中的代理无法访问“测试”环境范围内的 KVM。如果您希望在生产环境中使用相同的 KVM 密钥,请创建一个范围限定为“prod”环境的并行 KVM。

如果您希望所有环境中的所有代理都访问同一 KVM,请在 organization 范围内创建 KVM。

关于加密的 KVM

加密的 KVM 使用 Apigee 生成的 AES-128 加密密钥进行加密。用于加密 KVM 的密钥存储在 KVM 的范围内。例如,在组织内,您在环境范围内创建的所有加密 KVM 都使用相同的环境范围的密钥进行创建。

Edge 通过以下方式处理加密值的显示。 (如需了解如何创建加密 KVM,请参阅管理和使用 KVM)。

Edge 界面

加密的键值对映射在界面中显示用星号遮盖的值 (*****)。例如:

Management API

在 Management API 中,返回的加密值会经过遮盖处理。以下是针对“获取加密 KVM 调用”的管理 API 响应示例:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

跟踪和调试

使用键值对映射操作政策检索加密的 KVM 值时,您需要提供变量的名称来存储该值。要获取加密值,您需要在变量名称中添加“private.”前缀,这可以防止 KVM 键/值出现在跟踪和调试会话中。

限制

在启用了核心持久性服务 (CPS) 的组织中:

  • KVM 名称/标识符区分大小写。
  • 密钥大小上限为 2 KB。
  • 值的大小上限为 10 KB。

对于适用于私有云的 Apigee Edge,每个 KVM 不得超过 15MB(这是键和值的总大小)。如果超出此限制,适用于私有云的 Apigee Edge 将返回错误。如需确定 KVM 的大小,您可以使用 nodetool cfstats 命令。

较大的 KVM 可能会导致性能下降。因此,您应该将大型单体式 KVM 拆分为多个较小的 KVM,以提高性能。

管理和使用 KVM

您可以通过多种方式创建、管理和使用 KVM。本部分介绍用于创建和检索加密和未加密 KVM 的不同选项。

创建和更新 KVM

您可以通过以下方式创建和更新 KVM:

  • 键值对映射操作政策(不加密)

    如需通过 API 代理创建和更新运行时 KVM,请使用键值对映射操作政策。 (在政策中,您可以在父元素的 mapIdentifier 属性中指定 KVM 的名称)。

    当您在界面中保存政策或部署 API 代理后,<InitialEntries> 元素可让您在新的 KVM 中创建并填充条目的基准组(如果您离线开发)。如果政策中的值发生变化,则现有值会被覆盖。任何新的键/值都将与现有的键/值一起添加到现有的 KVM 中。

    如果 KVM 尚不存在,则 <Put> 元素会创建一个新的 KVM,它会创建一个具有一个或多个值的键。如果 KVM 已存在,则会添加键/值(如果键已存在,则会更新其值)。您可以在 KVM 政策中使用多个 <Put> 元素。

  • Management API

    Management API 适用于以管理员身份使用 KVM,而不是在运行时在 API 代理中与 KVM 配合使用。例如,您可能有一个内部脚本,该脚本使用 Management API 在测试环境中删除和重新创建 KVM,或者您可能需要重置 KVM 中某个键的值,以便所有代理都使用这些代理。(如需对 KVM 进行运行时操作,请在代理中使用键值对映射操作政策)。

    借助 Key/Value Maps Management API,您可以在所有范围(组织、环境和 apiproxy)中创建、更新和删除加密的 KVM 和键/值。

    如需使用 Management API 创建加密 KVM,请将 "encrypted" : "true" 添加到 JSON 载荷。您只能在创建 KVM 时对其进行加密。您无法加密现有的 KVM。

  • 管理界面

    在边缘管理界面中,您可以创建和更新环境范围的 KVM,这是界面中显示的唯一 KVM 范围。管理界面是在运行时手动管理 API 代理的 KVM 数据的好方法。 如需了解详情,请参阅创建和修改环境键值对映射

检索 KVM

您使用键值对映射操作政策进行检索时,以相同的方式检索加密和未加密的键值对映射,但略有不同。

  • 政策:使用键值对映射操作政策中的 <Get> 元素检索已加密和未加密的 KVM。唯一的一点区别是使用政策检索加密值,您必须在包含所检索值的变量的名称中添加“private.”前缀,如参考主题的“获取”操作部分中所述。在您调试 API 代理时,该前缀会在跟踪和调试会话中隐藏相应值。
  • Management API:出于管理目的,您可以使用创建和修改环境键值对映射来获取 KVM 和键/值。例如,如果要通过获取和存储 JSON 定义来备份 KVM,请使用 Management API。但请注意,加密值在 API 响应中显示为 *****。
  • 管理界面:您可以在管理界面中查看环境范围的 KVM,方法是依次前往 API > 环境配置 > 键值对映射(传统边缘)或管理 > 环境 > 键值对映射(新版边缘)。

KVM 示例

如需查看使用 KVM 填充网址中值的示例,请参阅 https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html