使用键值对映射

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

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

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

KVM 场景

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

  • 您的 API 代理需要在测试中调用一个目标（或服务调用程序）网址 和生产环境中的另一个目标网址。您不必将网址硬编码到 您可以要求该代理检测其所处的环境，执行相关的密钥， 值映射操作政策，并从您目前运行的 KVM 中检索正确的目标网址。 创建。之后，如果其中有一个或两个目标发生变化，只需使用以下代码 新网址。该代理会采用新值，且无需重新部署代理。
  • 您想要存储凭据、私钥或令牌， 服务、生成 OAuth 令牌所需的凭据或私钥 Java 调用程序或 JavaScript 中用于加密或 JSON 网络令牌 (JWT) 签名的密钥。而不是 在请求中传递凭据、密钥或令牌，或者在代理逻辑中对其进行硬编码， 可以将它们存储在 KVM 中（始终加密），并在调用 需要它们的目标。

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

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

KVM 有范围

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

例如，如果 KVM 中只有一个 API 代理需要数据，您可以在 KVM 的 apiproxy 范围，其中只有该 API 代理可以访问数据。

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

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

<ph type="x-smartling-placeholder">

关于加密的 KVM

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

Edge 按以下方式处理加密值的显示。 （如需了解如何创建加密的 KVM，请参阅管理和使用 KVM）。

Edge 界面

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

Management API

在 Management API 中，系统会用掩码返回加密值。以下是管理示例 针对 Get 已加密 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> 元素。

  • 管理 API

    Management API 适合以管理员身份（而不是在运行时）与 KVM 搭配使用。 。例如，您可能有一个使用 API，用于在测试环境中删除并重新创建 KVM，或者您可能需要重置密钥的值 以便所有代理选择（对于 KVM 的运行时操作，请使用 键值对映射操作政策 ）。

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

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

  • 管理界面

    在 Edge 管理界面中，您可以创建和更新 环境级范围的 KVM，这是唯一能够控制 。通过管理界面，可以有效地为 API 手动管理 KVM 数据 使用代理。 请参阅创建和修改环境键值对映射 。

检索 KVM

您可以采用相同的方式检索已加密和未加密的密钥值映射，只不过两者略有不同 （使用键值对映射操作政策进行检索）。

  • 政策：在<Get> 键值对映射操作政策 来检索已加密和未加密的 KVM一个细微差别在于 使用此政策检索加密值，其中，您必须添加“private.” 为包含所检索值的变量名称添加前缀，如 获取操作部分 参考主题的内容。该前缀会对跟踪和调试隐藏值 会话数量。
  • Management API：出于管理管理目的，您可以使用 创建和修改环境键值对映射 以获取 KVM 和键/值例如，如果您希望 通过获取和存储 JSON 定义来备份 KVM，并使用 Management API。请注意 加密值在 API 响应中显示为 *****。
  • 管理界面：您可以在管理控制台的 API >环境配置 >键值对映射 （传统 Edge）或管理 >环境 >Key Value Maps（新边缘）。

KVM 示例

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