使用鍵/值對應

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

有時您會想儲存資料，以便在執行階段擷取，也就是不應在 API Proxy 邏輯中硬式編碼的不會過期資料。鍵值對應 (KVM) 非常適合用於此用途。KVM 是鍵/值字串組合的自訂集合，可加密或不加密。我們來看看下面兩個範例：

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

KVM 情境

以下列舉幾個適合使用 KVM 的情況：

  • 您有一個 API Proxy，需要在測試環境中呼叫一個目標 (或服務呼叫) 網址，在正式環境中呼叫另一個目標網址。您不必在 Proxy 中硬式編碼網址，而是讓 Proxy 偵測所在環境、執行相關的鍵值對應作業政策，並從您建立的其中一個 KVM 擷取正確的目標網址。之後，如果一或兩個目標有所變更，您只要使用新網址更新 KVM 即可。Proxy 會擷取新值，不需要重新部署 Proxy。
  • 您想儲存憑證、私密金鑰或權杖，例如外部服務的權杖、產生 OAuth 權杖所需的憑證，或是用於 Java Callout 或 JavaScript 的私密金鑰，以進行加密或 JSON Web Token (JWT) 簽署。您可以在 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

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

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

追蹤及偵錯

使用 Key Value Map Operations 政策擷取加密的 KVM 值時，您會提供變數名稱來儲存該值。如要取得加密值，請在變數名稱中加入「private.」前置字串，這樣 KVM 鍵/值就不會顯示在追蹤和偵錯工作階段中。

限制

在啟用核心持續性服務 (CPS) 的機構中：

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

如果是 Apigee Edge for Private Cloud，每個 KVM 不得超過 15 MB (這是鍵值組合的大小)。如果超出這項限制，Apigee Edge for Private Cloud 會傳回錯誤。如要判斷 KVM 的大小，可以使用 nodetool cfstats 指令。

較大的 KVM 可能會導致效能降低。因此，您應將大型單體 KVM 分割為較小的 KVM，以提升效能。

管理及使用 KVM

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

建立及更新 KVM

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

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

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

    您可以在 UI 中儲存政策，或部署 API Proxy (如果您是離線開發)，即可使用 <InitialEntries> 元素在新的 KVM 中建立及填入一組基準項目。如果政策中的值有所變更，現有值就會遭到覆寫。所有新鍵/值都會與現有鍵/值一起新增至現有 KVM。

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

  • 管理 API

    管理 API 適用於以管理員身分處理 KVM，而非在 API Proxy 的執行階段處理。舉例來說，您可能有一個內部指令碼，會使用管理 API 刪除及重新建立測試環境中的 KVM，或者您可能想重設 KVM 中金鑰的值，讓所有 Proxy 都能擷取。(如要執行階段操控 KVM，請在 Proxy 中使用 Key Value Map Operations 政策)。

    鍵/值對應管理 API 可讓您在所有範圍 (機構、環境和 apiproxy) 建立、更新及刪除加密的 KVM 和鍵/值。

    如要使用管理 API 建立加密 KVM，請在 JSON 酬載中加入 "encrypted" : "true"。您只能在建立 KVM 時加密。您無法加密現有的 KVM。

  • 管理 UI

    在 Edge 管理 UI 中，您可以建立及更新環境範圍的 KVM，這是唯一會顯示在 UI 中的 KVM 範圍。管理使用者介面是手動管理 API Proxy 執行階段 KVM 資料的好方法。詳情請參閱「建立及編輯環境鍵/值對應」。

擷取 KVM

您會以相同方式擷取加密和未加密的鍵/值對應，但使用「鍵/值對應作業」政策擷取時，會有一點差異。

  • 政策：在鍵/值對應作業政策中使用 <Get> 元素，擷取加密和未加密的 KVM。唯一略有不同的是使用政策擷取加密值，您必須在將包含擷取值的變數名稱中加入「private.」前置字元，如參考主題的「Get 作業」一節所述。偵錯 API Proxy 時，這個前置字元會隱藏追蹤和偵錯工作階段的值。
  • 管理 API：為進行管理，您可以透過「建立及編輯環境鍵值對應關係」取得 KVM 和鍵/值。舉例來說，如要備份 KVM，方法是取得並儲存 JSON 定義，請使用 Management API。但請注意，加密值在 API 回應中會顯示為 *****。
  • 管理使用者介面：如要透過管理使用者介面查看環境範圍的 KVM，請依序前往「APIs」>「Environment Configuration」>「Key Value Maps」(Classic Edge)，或「Admin」>「Environments」>「Key Value Maps」 (New Edge)。

KVM 範例

如要瞭解如何使用 KVM 在網址中填入值，請參閱使用 KVM 依環境將目標網址範本化。