使用键值对映射

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

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

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

KVM 应用场景

在以下情况下，KVM 非常实用：

  • 您有一个 API 代理，需要调用测试环境中的一个目标（或服务标注）网址，并在生产环境中调用另一个目标网址。您可以让代理检测所在的环境，执行相关的键值对映射操作政策，并从您创建的其中一个 KVM 中检索正确的目标网址，而不是对代理中的网址进行硬编码。之后，如果您的一个或两个目标发生变化，则只需使用新网址更新 KVM 即可。代理会选取新的值，而无需代理重新部署。
  • 您想要存储凭据、私钥或令牌，例如外部服务的令牌、生成 OAuth 令牌所需的凭据，或者 Java 标注或 JavaScript 中用于加密的私钥或 JSON 网络令牌 (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。）

Edge 界面

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

Management API

在管理 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 for Private Cloud，每个 KVM 的大小不应超过 15MB（这是键和值的总大小）。如果超出此限制，Apigee Edge for Private Cloud 会返回错误。如需确定 KVM 的大小，您可以使用 nodetool cfstats 命令。

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

管理和使用 KVM

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

创建和更新 KVM

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

  • 键值对映射操作政策（未加密）

    如需通过 API 代理创建和更新运行时 KVM，请使用 Key Value Map Operations 政策。 （在政策中，您可以在父元素的 mapIdentifier 属性中指定 KVM 的名称）。

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

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

  • 管理 API

    管理 API 适用于以管理员身份处理 KVM，而不是在 API 代理的运行时处理 KVM。例如，您可能有一个内部脚本，用于使用管理 API 删除和重新创建测试环境中的 KVM；或者，您可能希望重置 KVM 中某个键的值，以便所有代理都能获取该值。（如需在运行时操控 KVM，请在代理中使用键值对映射操作政策）。

    借助键值对映射管理 API，您可以在所有范围（组织、环境和 apiproxy）中创建、更新和删除加密的 KVM 以及键/值。

    如需使用管理 API 创建加密的 KVM，请将 "encrypted" : "true" 添加到 JSON 载荷中。您只能在创建 KVM 时对其进行加密。您不能对现有的 KVM 进行加密。

  • 管理界面

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

检索 KVM

您可以使用 Key Value Map Operations 政策以相同的方式检索已加密和未加密的键值对映射，但略有不同。

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

KVM 示例

如需查看使用 KVM 在网址中填充值的示例，请参阅按环境使用 KVM 将目标网址模板化。