使用键值映射

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

概览

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

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

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

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

  之后，如果您的一个或两个目标发生变化，则只需使用新网址更新 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。

注意：借助 Apigee 界面，您只能在环境范围内创建和管理 KVM。

KVM 加密简介

在 Apigee 中，API 代理、组织和环境范围的所有 KVM 条目都使用预配 Apigee 组织时提供的 Cloud KMS 密钥进行保护（请参阅组织资源中的 runtimeDatabaseEncryptionKey 字段）。Apigee 使用 AES256 作为加密标准。

在 Apigee Hybrid 中，您可以为 API 代理、组织和环境范围的所有 KVM 条目提供单独的加密密钥。Apigee 接受 AES128、AES196 或 AES256 加密大小作为加密标准。

创建 KVM

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

注意：您必须使用 KeyValueMapOperations 政策向 KVM 添加数据。

注意：Apigee 界面有一个新版本，该版本与 Google Cloud 控制台集成。新界面称为 Cloud 控制台中的 Apigee。下文前两个标签页中的说明介绍了如何使用 Cloud 控制台中的 Apigee 或经典版 Apigee。

Cloud 控制台中的 Apigee

注意：

• 您无法通过界面向 KVM 添加或从 KVM 检索数据。您必须使用 KeyValueMapOperations 政策向 KVM 添加数据或从 KVM 检索数据。
• KVM 只能限定为环境。

如需创建一个新的（空的）KVM 或查看 KVM 列表，请执行以下操作：

1. 在浏览器中打开 Cloud 控制台中的 Apigee 界面。
2. 在左侧导航窗格中，点击管理 > 环境。
3. 从可用环境列表中选择要修改的环境。
4. 点击环境详情页面上的 Key Value Maps 标签页。

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

5. 要创建新的（空）KVM，请点击 + 创建键值映射。

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

6. 在 Key value map name 字段中输入 KVM 的名称。

   名称只能包含字母、数字和连字符，且长度不得超过 255 个字符。不能包含空格或其他特殊字符。例如：my-kvm-1

7. 点击创建。

   新的 KVM 将显示在列表中。

经典版 Apigee 界面

注意：

• 您无法通过界面向 KVM 添加数据或从 KVM 检索数据。您必须使用 KeyValueMapOperations 政策向 KVM 添加数据或从 KVM 检索数据。
• KVM 只能限定为环境。

如需创建一个新的（空的）KVM 或查看 KVM 列表，请执行以下操作：

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

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

4. 要创建新的（空）KVM，请点击 + 键值映射。

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

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

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

6. 点击添加。

   新的 KVM 将显示在列表中。

Apigee API

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

• API 代理范围键值映射 API
• 环境范围键值映射 API
• 组织级范围键值映射 API

注意：

• 使用 API 创建 KVM 时，必须将 encrypted 标志设置为 true。仅支持加密的 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。

Cloud 控制台中的 Apigee

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

1. 在浏览器中打开 Cloud 控制台中的 Apigee 界面。
2. 在左侧导航窗格中，点击管理 > 环境。
3. 从可用环境列表中选择要修改的环境名称。
4. 点击环境详情页面上的 Key Value Maps 标签页。

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

5. 找到要删除的 KVM 所在的行。
6. 点击操作列中的 。
7. 点击对话框中的 Delete Key Value Map 以确认操作。

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

经典版 Apigee 界面

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

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

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

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

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

Apigee API

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

• 删除 API 代理范围内的 KVM
• 在环境范围内删除 KVM
• 删除组织范围的 KVM