使用鍵/值對應

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

有時您會想要在執行階段儲存擷取用的資料,不應在 API Proxy 邏輯中以硬式編碼的方式寫入未過期的資料。金鑰值對應 (KVM) 非常適合用於這個用途。KVM 是一組已加密或未加密的鍵/值組合的自訂集合。請看以下兩個範例:

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

KVM 情境

以下是一些適合使用 KVM 的情況:

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

我們會說明其他可以儲存鍵/值字串組合的情況。一般來說,在下列情況下,請考慮使用 KVM:

  • 程式碼中特定位置的執行階段時需要使用不同的值。
  • 傳送機密資料時不需要進行硬式編碼。
  • 您希望儲存不會過期的值,就像快取一樣。

KVM 有範圍

範圍是指「可以使用 KVM 的地區」。您可以在下列範圍建立 KVM:organizationenvironmentapiproxy

舉例來說,如果只有一個 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 都會使用相同的環境範圍金鑰建立。

邊緣會透過下列方式處理加密值的顯示方式。(如要進一步瞭解如何建立加密的 KVM,請參閱管理及使用 KVM)。

Edge UI

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

Management API

在 Management API 中,系統會遮蓋加密的值。以下是對「取得加密」KVM 呼叫的 Management 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 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 名稱)。

    當您在使用者介面中儲存政策或部署 API Proxy (如果是離線開發) 時,<InitialEntries> 元素可讓您在新的 KVM 中建立並填入一組基準項目。如果政策中的值有所變更,現有值就會遭到覆寫。系統會將任何新鍵/值連同現有的鍵/值一起新增至現有的 KVM。

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

  • Management API

    Management API 適用於以管理員的身分與 KVM 合作,而非在 API Proxy 中的執行階段使用。例如,您可能有使用 Management API 的內部指令碼,用於在測試環境中刪除及重新建立 KVM。或者,您可能想要重設 KVM 中的金鑰值,讓所有 Proxy 可以使用。(如要執行 KVM 的執行階段,請使用 Proxy 中的鍵/值對應作業政策)。

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

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

  • 管理 UI

    在 Edge 管理 UI 中,您可以建立及更新適用環境的 KVM,這是 UI 中顯示的唯一 KVM 範圍。管理 UI 可讓您在執行階段手動管理 API Proxy 的 KVM 資料。詳情請參閱「建立及編輯環境金鑰值對應」一文。

擷取 KVM

擷取已加密及未加密的金鑰值對應方式相同,但使用鍵/值對應作業政策進行擷取時,會稍有不同。

  • 政策:使用金鑰值對應作業政策中的 <Get> 元素,擷取已加密及未加密的 KVM。其中稍微差異在於使用政策擷取加密值,其中必須在含有所擷取值的變數名稱中加入「private.」前置字串,如參考主題的「取得作業」一節所述。當您在對 API Proxy 進行偵錯時,這個前置字串會隱藏 Trace 和偵錯工作階段的值。
  • Management API:如要管理管理,您可以使用建立及編輯環境鍵/值對應,取得 KVM 和鍵/值。舉例來說,如果您想取得並儲存 JSON 定義來備份 KVM,請使用 Management API。另外請注意,在 API 回應中,加密值會顯示為 *****。
  • 管理 UI:您可以在管理 UI 中查看環境範圍 KVM,方法是依序前往「API」>「環境設定」>「鍵/值對應」(傳統 Edge) 或「管理」>「環境」>「鍵值對應」 (新邊緣)。

KVM 範例

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