注意:此产品的某些方面处于 Beta 版阶段。Hybrid 安装选项是 GA。要加入 Beta 版计划,请与您的 Apigee 代表联系。

使用键值映射

本部分介绍如何使用键/值映射 (KVM)。

概览

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

KVM 具有三种广泛的用例(此列表只是一些使用 KVM 的不同方式的指南):

  • 用户会话数据:由运行时创建(并销毁)的数据。KVM 条目可以加密或清除,因此无法在运行时外部查看或管理条目。例如购物车内容。
  • 配置(例如路由规则和查找表):数据通常在运行时之外创建,但由运行时读取。此数据由界面或 API 提供,然后可供网关使用(作为变量和只读)。

    例如:您有一个 API 代理,需要调用测试环境中的一个目标(或服务标注)网址,并在生产环境中调用另一个目标网址。您可以让代理检测所在的环境,执行相关 KeyValueMapOperations 政策,并从其中一个您创建的 KVM 中检索正确的目标 URL,而不是对代理中的 URL 进行硬编码。

    之后,如果您的一个或两个目标发生变化,则只需使用新网址更新 KVM 即可。代理会选取新的值,而无需代理重新部署。

  • 凭据:存储凭据、私钥或令牌,例如外部服务的令牌、生成 OAuth 令牌所需的凭据,或者 Java 标注或 JavaScript 中用于加密的私钥或 JSON 网络令牌 (JWT) 签名。您可以将它们存储在 KVM(始终加密)中,并在调用需要它们的目标时动态地检索它们,而不是在请求中传递凭据、密钥或令牌,或者在代理逻辑中对其进行硬编码。

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

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

在某些情况下,属性集是 KVM 的一个很好的替代,因为它们更易于使用。如需了解详情,请参阅缓存

KVM 范围简介

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

例如,如果键/值对将用于组织中的所有 API,则在组织范围内创建 KVM;如果只有特定的 API 代理有权访问键/值,请在 apiproxy 范围内创建 KVM,只有该 API 代理才能访问数据。

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

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

使用 KVM

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

将 KVM 与 Apigee 界面搭配使用

您可以使用 Apigee 界面执行以下与 KVM 相关的任务:

  • 在环境中查看 KVM 列表
  • 创建一个新的(空)KVM

请注意,界面中的 KVM 的范围仅限于环境。

您目前无法向 KVM(即使是在界面中创建的 KVM)添加数据、删除 KVM 或使用 Apigee 界面查看 KVM 中的数据。您必须使用 KVM 政策向 KVM 添加数据。

如需创建一个新的(空的)KVM 或查看 KVM 列表,请执行以下操作

  1. 在浏览器中打开 Apigee 界面
  2. 依次选择管理 > 环境 > 键值对映射
  3. 从环境下拉列表中,选择所需的环境。

    键值对映射视图会显示现有 KVM 的列表。如果您尚未创建任何 KVM,则 KVM 列表为空。

  4. 要创建新的(空的)KVM,请点击右上角的 +Key value map 按钮。

    此时会出现添加键值对映射对话框:

    在界面中添加 KVM

  5. 名称字段中,输入 KVM 的名称。

    名称只能包含字母、数字和连字符。不能包含空格或其他特殊字符。例如,输入“my-kvm-1”。

  6. (可选)选中加密复选框。如果选中此复选框,Apigee 会对 KVM 中的数据进行加密;否则,存储为明文。如需了解详情,请参阅关于加密的 KVM
  7. 点击添加

    Apigee 会创建新的 KVM。您无法修改新的 KVM,也不能向其添加数据。

将 KVM 与 Apigee API 搭配使用

您可以使用 Apigee API 创建、列出和删除以下范围的 KVM:

借助 /keyvaluemaps Apigee API,您可以在所有范围(组织、环境和 apiproxy)中创建和删除 KVM。您无法使用 API 添加数据或更新 KVM 数据。

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

将 KVM 与 KeyValueMapOperations 政策搭配使用

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

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

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

跟踪和调试

使用 KeyValueMapOperations 政策检索加密的 KVM 值时,您需要提供变量名称来存储值。要获取加密值,您需要将 private. 前缀添加到变量名称中,以阻止 KVM 键/值显示在跟踪和调试会话中。

检索 KVM

您可以使用 KeyValueMapOperations 政策检索已加密和未加密的键值对映射。使用政策的 <Get> 元素检索已加密和未加密的 KVM。要检索该政策的加密值,如参考主题的获取操作部分中所述,请向包含检索到的值的变量名称添加 private. 前缀。在您调试 API 代理时,该前缀隐藏跟踪和调试会话中的值。

关于加密的 KVM

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

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

在 Apigee API 中,加密的值返回时被遮盖。以下是关于“获取加密的 KVM 调用”的 Apigee API 响应示例:

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