使用键值对映射

您正在查看 Apigee Edge 文档。
请查看 Apigee X 文档。

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

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

KVM 场景

在以下情况下，KVM 派上用场：

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

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

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

KVM 具有范围

范围是指“KVM 可用的位置”。可以在以下范围内创建 KVM：organization、environment 和 apiproxy。

例如，如果只有一个 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。）

边缘界面

加密的键值对会映射在界面中以星号遮盖的值 (*****)。例如：

Management API

在 Management API 中，加密的值会被遮盖。以下是针对获取加密的 KVM 调用的示例 Management API 响应：

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

跟踪和调试

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

限制

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

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

对于适用于私有云的 Apigee Edge，每个 KVM 不应超过 15MB（这是密钥和值的总大小）。如果超出此限制，Apigee Edge for Private Cloud 将返回错误。如要确定 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 代理。例如，您可能有一个使用 Management API 删除内部环境并在测试环境中重新创建 KVM 的内部脚本，或者可能想要在 KVM 中重置密钥的值以供所有代理使用。（如需对 KVM 的运行时操作，请在代理中使用键值对映射操作政策）。

    利用 Key/Value Maps Management API，您可以在所有范围（组织、环境和 apiproxy）中创建、更新和删除加密的 KVM 和密钥/值。

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

  • 管理界面

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

检索 KVM

使用键值对映射操作政策进行检索时，检索加密和未加密的键值对的过程相同，只有细微差别。

  • 政策：使用键值对映射操作政策中的 <Get> 元素来检索加密和未加密的 KVM。一个细微差别是在政策中检索加密值，您必须在该变量名称中添加“private.”前缀，以包含所检索值的变量名称，如参考主题的“获取操作”部分中所述。在调试 API 代理时，该前缀会在 Trace 和调试会话中隐藏值。
  • 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。