使用键值映射

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

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

概览

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

下面列出了在 KVM 中存储数据的三种广泛用例:

  • 用户会话数据:仅由运行时创建和删除的数据;您无法在运行时之外查看或管理 KVM 条目。例如购物车内容。
  • 配置(例如路由规则和查找表):通常在运行时外创建但由运行时读取的数据。这些数据是通过界面或 API 配置的,然后可供网关使用(作为变量或只读内容)。

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

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

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

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

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

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

KVM 范围简介

范围定义了 KVM 的适用范围。可以在以下范围内创建 KVM:

范围 说明
API 代理 只有 API 代理可以访问 KVM。
环境 特定环境中的所有 API 代理均可访问 KVM。例如,您可能希望在 prod 环境中部署的 API 代理无法访问 test 环境中的 KVM。如果您希望在生产环境中使用相同的 KVM 密钥,请创建一个范围限定为 prod 环境的并行 KVM。
组织 所有环境中的所有 API 代理均可访问 KVM。

KVM 加密简介

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

返回遮盖的加密值:

  • 以下是使用 Apigee 界面的示例加密信息:

    显示加密数据的界面摘录。

  • 以下是使用 Apigee API 时,响应中的示例加密信息:
    {
      "encrypted": true,
      "entry": [
        {
          "name": "Key1",
          "value": "*****"
        },
        {
          "name": "Key2",
          "value": "*****"
        }
      ],
      "name": "secretMap"
    }
    

创建 KVM

按照以下部分所述创建 KVM。

Apigee 界面

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

  1. 登录 Apigee 界面
  2. 依次选择管理 > 环境 > 键值对映射
  3. 从环境下拉列表中,选择要为其创建 KVM 的环境。

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

  4. 要创建新的(空)KVM,请点击 + 键值映射

    此时会打开添加键值对映射对话框:

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

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

  6. 点击添加

    新的 KVM 将显示在列表中。

Apigee API

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

KVM 政策

如要在运行时创建 KVM 并在 API 代理中更新这些 KVM,请使用 KeyValueMapOperations 政策。在政策中,您可以在父元素的 mapIdentifier 属性中指定 KVM 的名称。

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

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

调试

使用 KeyValueMapOperations 政策检索加密的 KVM 值时,您需要提供变量名称来存储值。由于所有 KVM 值都已加密,因此您需要将 private. 前缀添加到变量名称中,以防 KVM 键值对出现在调试会话中。

检索 KVM

使用 KeyValueMapOperations 政策<Get> 元素检索 KVM。由于所有 KVM 值都已加密,因此请将 private. 前缀添加到包含检索到的值的变量名称中。在调试 API 代理时,该前缀会在调试会话中隐藏值。如需了解详情,请参阅 <Get> 元素

删除 KVM

按照以下部分所述删除 KVM。

Apigee 界面

如需删除 KVM,请执行以下操作

  1. 登录 Apigee 界面
  2. 依次选择管理 > 环境 > 键值对映射
  3. 从环境下拉列表中,选择要为其删除 KVM 的环境。

    键值对映射信息页会显示现有 KVM 的列表。

  4. 将光标放在要删除的 KVM 上方。
  5. 点击 删除
  6. 点击删除以确认操作。

    KVM 将被删除并从列表中移除。

Apigee API

使用以下任一 Apigee API 根据 KVM 的范围删除 KVM: