使用键值对映射

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 info

有时候，您想要在运行时存储数据以供检索，但不过期的数据 不应在 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 界面

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

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，请使用 键值对映射操作政策。 （在政策中，您可以在父元素的 mapIdentifier 属性中指定 KVM 的名称）。

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

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

  • Management 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

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

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

KVM 示例

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