使用鍵/值對應

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。

有時候您可能會想儲存資料，以便在執行階段擷取，也就是不會以硬式編碼的方式寫入在 API Proxy 邏輯中的資料。鍵/值對應 (KVM) 非常適合使用此功能。KVM 是一組經過加密/未加密的鍵/值字串組合。請看以下兩個範例：

如要進一步瞭解其他類型的持續性，請參閱「新增快取和持續性」。

KVM 情境

以下列舉一些 KVM 派上用場的情況：

  • 您有一個 API Proxy，需要在測試環境中呼叫一個目標 (或服務呼叫) 網址，而實際執行環境中的另一個目標網址。您可讓 Proxy 偵測所在的環境，並執行相關鍵/值對應作業政策，並從您建立的其中一個 KVM 擷取正確的目標網址，而不需要在 Proxy 中以硬式編碼的方式寫入網址。接著，如果其中一個目標或兩個目標都發生變更，只要將 KVM 更新為新網址即可。Proxy 會擷取新的值，您不需要重新部署 Proxy。
  • 您要儲存憑證、私密金鑰或權杖 (例如外部服務權杖、產生 OAuth 權杖所需的憑證，或是用於加密或 JSON Web Token (JWT) 簽署的 Java 摘要或 JavaScript 中的私密金鑰)。您可以將憑證儲存在 KVM (一律加密) 中，並在呼叫中以動態方式擷取這些目標，而不需要在要求中傳遞憑證、金鑰或權杖，或是在 Proxy 邏輯中以硬式編碼的方式寫入憑證。

並瞭解其他儲存鍵/值字串組合的情況。一般來說，請考慮在下列情況中使用 KVM：

  • 程式碼中的特定位置在執行階段需要不同的值。
  • 機密資料必須在不硬式編碼的情況下傳送。
  • 您希望儲存不會過期且像快取一樣的值。

KVM 設有範圍

範圍是指「有 KVM 的位置」。KVM 可在以下範圍內建立：organization、environment 和 apiproxy。

例如，如果只有一個 API Proxy 需要 KVM 中的資料，您可以在 apiproxy 範圍建立 KVM，而只有該 API Proxy 可存取資料。

或者，您也可以讓測試環境中的所有 API Proxy 存取鍵/值對應，在這種情況下，請在環境範圍中建立鍵/值對應。在「prod」環境中部署的 Proxy 無法存取「test」環境中的 KVM。如要在實際工作環境中使用同一個 KVM 金鑰，請建立平行範圍為「prod」環境的 KVM 金鑰。

如果希望所有環境中的所有 Proxy 存取同一個 KVM，請在 organization 範圍中建立 KVM。

關於加密 KVM

加密的 KVM 是以 Apigee 產生的 AES-128 加密金鑰進行加密。用於加密 KVM 的金鑰會儲存在 KVM 的範圍內。舉例來說，在機構內，您可以使用相同範圍範圍的金鑰建立所有在環境範圍中建立的加密 KVM。

Edge 以下列方式處理加密值的顯示方式。 (如需瞭解如何建立加密 KVM，請參閱管理及使用 KVM)。

Edge UI

加密的鍵/值對應會在使用者介面 (***) 中以星號遮蓋顯示值。例如：

Management API

在 Management API 中，系統會傳回遮蓋的值。以下是針對加密加密 KVM 呼叫的範例管理 API 回應：

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

追蹤記錄和偵錯

使用鍵/值對應作業政策擷取加密的 KVM 值時，您必須提供變數名稱來儲存值。如要取得加密值，您必須在變數名稱中新增「private.」前置字串，避免 KVM 鍵/值顯示在 Trace 和偵錯工作階段中。

限制

在已啟用核心永久服務 (CPS) 的機構中：

  • KVM 名稱/ID 須區分大小寫。
  • 金鑰大小上限為 2 KB。
  • 值的大小上限為 10 KB。

以 Apigee Edge 為私有雲來說，每個 KVM 的大小不得超過 15 MB (這是鍵與值的總計大小)。如果您超過此上限，Private Cloud Edge for Private Cloud 就會傳回錯誤。如要判斷 KVM 的大小，您可以使用 nodetool cfstats 指令。

大型 KVM 可能會導致效能降低。因此，您應將大型的單體 KVM 分割為小型群組，以改善效能。

管理及使用 KVM

您可以透過多種方式建立、管理及使用 KVM。本節說明建立、擷取及加密加密與未加密 KVM 的不同選項。

建立及更新 KVM

您可以透過下列方式建立及更新 KVM：

  • 鍵/值對應作業政策 (未加密)

    針對 API Proxy 建立及更新執行階段 KVM，請使用鍵/值對應作業政策。(在政策中，您必須在父項元素的 mapIdentifier 屬性中指定 KVM 名稱)。

    當您在 UI 中儲存政策或部署 API Proxy (您已離線開發) 時，<InitialEntries> 元素可讓您在新的 KVM 中建立及填入一組基準項目。如果政策中的值有所變更，系統就會覆寫現有值。現有的鍵/值和現有的鍵/值會加至現有 KVM。

    如果還沒有現有的 KVM，<Put> 元素會建立一個新的，並且建立一或多個值的鍵。如果 KVM 已存在，系統會新增鍵/值 (如果已有金鑰，則會更新)。您可以在 KVM 政策中使用多個 <Put> 元素。

  • Management API

    Management API 是以管理員的身分處理 KVM，而非在 API Proxy 中的執行階段。例如，您可能有一個內部指令碼，使用管理 API 刪除並重新建立測試環境中的 KVM，或是重設 KVM 中的鍵值，可供所有 Proxy 接收。(如要操控 KVM 的執行階段操控作業，請在 Proxy 中使用鍵/值對應運算政策)。

    Key/Value Maps Management API 可讓您建立、更新及刪除所有範圍 (機構、環境和 APIapi) 中的加密 KVM 和鍵/值。

    如要使用 Management API 建立加密的 KVM，請將 "encrypted" : "true" 新增至 JSON 酬載。您只能在建立 KVM 時進行加密。您無法加密現有的 KVM。

  • 管理 UI

    在邊緣管理 UI 中，您可以建立並更新環境範圍 KVM，這是 UI 中顯示的唯一 KVM 範圍。管理 UI 是在執行階段手動管理 API Proxy 的 KVM 資料。詳情請參閱建立及編輯環境鍵/值對應。

擷取 KVM

擷取加密與未加密的鍵/值對應方式相同，但透過鍵/值對應作業政策擷取時有一種差異。

  • 政策：使用鍵/值對應作業政策中的 <Get> 元素，擷取未加密的 KVM。唯一的差別在於，使用政策擷取加密值，但您必須在參照主題的「取得作業」一節中，為包含擷取值的變數名稱加上「private.」前置字串。這個前置字元會在隱藏 API Proxy 時隱藏 Trace 和偵錯工作階段的值。
  • Management API：如要進行管理，您可以使用建立及編輯環境鍵/值對應，取得 KVM 和鍵/值。舉例來說，如要取得並儲存 JSON 定義來備份 KVM，請使用 Management API。不過請注意，加密值在 API 回應中會顯示為 *****。
  • 管理 UI：您可依序前往「API」>「環境設定」>「鍵/值對應」(傳統版 Edge) 或「管理」>「環境」>「鍵/值對應」 (新邊緣)，在管理 UI 中查看環境範圍的 KVM。

KVM 範例

如需使用 KVM 填入網址值的範例，請參閱 https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html。