本頁適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
本節將說明如何使用鍵/值對應 (KVM)。
總覽
有時您可能需要儲存資料，以便在執行階段擷取資料，而不會過期的資料不應在 API 代理程式邏輯中硬式編碼。鍵值對應 (KVM) 是這類情況的理想選擇。KVM 是加密鍵/值字串組合的自訂集合。
以下列出在 KVM 中儲存資料的三種廣泛用途：
- 使用者工作階段資料：僅由執行階段建立及刪除的資料；您無法在執行階段以外的地方查看或管理 KVM 項目。例如購物車內容。
- 設定 (例如轉送規則和查閱表)：通常是在執行階段外建立，但由執行階段讀取的資料。這類資料會透過 UI 或 API 設定，然後提供給閘道 (做為變數或唯讀內容)。
舉例來說，假設您有一個 API 代理程式，需要在測試環境中呼叫一個目標 (或服務呼籲) 網址，並在實際執行環境中呼叫另一個目標網址。您可以讓 API Proxy 偵測所在環境，執行相關的 KeyValueMapOperations 政策，並從適當的 KVM 擷取正確的目標網址，而非在 API Proxy 中硬式編碼網址。
日後，如果其中一個或兩個目標發生變更，您只需將 KVM 更新為新的網址即可。API 代理會擷取新的值，因此不必重新部署。
- 憑證：儲存憑證、私密金鑰或權杖，例如外部服務的權杖、產生 OAuth 權杖所需的憑證，或是用於 JavaCallout 政策或 JavaScript 的私密金鑰，以便進行加密或 JSON Web Token (JWT) 簽署。您可以將憑證、金鑰或符記儲存在 KVM 中，並在呼叫需要這些憑證、金鑰或符記的目標時，動態擷取這些項目，而非在要求中傳遞憑證、金鑰或符記，或在 Proxy 邏輯中以硬式編碼方式處理這些項目。
您會發現，在其他情況下儲存鍵/值字串組合也很實用。一般來說，在下列情況下，請考慮使用 KVM：
- 程式碼中的特定部分在執行階段需要不同的值。
- 您必須在不硬式編碼的情況下傳遞機密資料。
- 您希望儲存的值不會過期，就像快取一樣。
在某些情況下，物件集是 KVM 的絕佳替代方案，因為物件集更容易使用。詳情請參閱「使用資源集」。
關於 KVM 範圍
範圍定義 KVM 可用的範圍。KVM 可在下列範圍建立：
| 範圍 | 說明 |
|---|---|
| API Proxy | 只有 API 代理程式才能存取 KVM。 |
| 環境 | 特定環境中的所有 API 代理程式都可以存取 KVM。舉例來說，您可能不希望在 prod 環境中部署的 API Proxy 能存取 test 環境中的 KVM。如果您希望在實際工作環境中使用相同的 KVM 鍵，請建立以 prod 環境為範圍的平行 KVM。 |
| 機構 | 所有環境中的所有 API 代理程式都可以存取 KVM。 |
關於 KVM 加密
在 Apigee 中，API 代理程式、機構和環境範圍的所有 KVM 項目都會使用 Cloud KMS 金鑰進行保護，這項金鑰是在 Apigee 機構佈建時提供 (請參閱 Organization 資源中的 runtimeDatabaseEncryptionKey 欄位)。Apigee 使用 AES256 做為加密標準。
在 Apigee hybrid 中，您可以為 API 代理程式、機構和環境範圍的所有 KVM 項目提供個別的加密金鑰。Apigee 接受 AES128、AES196 或 AES256 的加密區塊大小做為加密標準。
建立 KVM
按照下列各節所述建立 KVM。
Cloud 控制台中的 Apigee
如要建立新的 (空白) KVM，或查看 KVM 清單，請按照下列步驟操作：
- 在瀏覽器中開啟 Cloud 控制台中的 Apigee UI。
- 在左側導覽窗格中，依序按一下「管理」>「環境」。
- 從可用環境清單中選取要編輯的環境。
- 在「環境詳細資料」頁面上，按一下「鍵/值對應」分頁標籤。
「鍵/值對應」頁面會顯示現有的 KVM 清單。如果您尚未建立任何 KVM，清單會為空白。
- 如要建立新的 (空白) KVM，請按一下「+ 建立鍵值對應」。
系統隨即會顯示「新增鍵值對應」對話方塊。
- 在「Key value map name」欄位中輸入 KVM 的名稱。
名稱只能包含英文字母、數字和連字號，長度不得超過 255 個字元。不得包含空格或其他特殊字元。例如：
my-kvm-1 - 按一下 [建立]。
清單中會顯示新的 KVM。
傳統版 Apigee UI
如要建立新的 (空白) KVM，或查看 KVM 清單，請按照下列步驟操作：
- 登入 Apigee UI。
- 依序選取「管理」>「環境」>「鍵值對應表」。
- 在環境下拉式清單中，選取要建立 KVM 的環境。
「鍵/值對應」頁面會顯示現有的 KVM 清單。如果您尚未建立任何 KVM，清單會是空白的。
- 如要建立新的 (空白) KVM，請按一下「+Key value map」。
系統隨即會顯示「新增鍵值對應」對話方塊。
- 在「Name」欄位中輸入 KVM 的名稱。
名稱只能包含英文字母、數字和連字號。不得包含空格或其他特殊字元。例如：
my-kvm-1 - 按一下「新增」。
清單中會顯示新的 KVM。
Apigee API
使用 Apigee API 建立、列出及刪除下列範圍的 KVM：
KVM 政策
如要在執行階段建立 KVM，並在 API 代理程式中更新 KVM，請使用 KeyValueMapOperations 政策。在政策中，您可以在父項元素的 mapIdentifier 屬性中指定 KVM 名稱。
只要在 UI 中儲存政策或部署 API Proxy (如果您是在離線狀態下開發)，<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，請按照下列步驟操作：
- 在瀏覽器中開啟 Cloud 控制台中的 Apigee UI。
- 在左側導覽窗格中，依序按一下「管理」>「環境」。
- 從可用環境清單中選取要編輯的環境名稱。
- 在「環境詳細資料」頁面上，按一下「鍵/值對應」分頁標籤。
「Key Value Maps」頁面會顯示現有的鍵/值對應清單。
- 找出要刪除的 KVM 資料列。
- 按一下「動作」欄中的 delete。
- 在對話方塊中按一下「Delete Key Value Map」，確認要執行這項操作。
系統會刪除 KVM 並從清單中移除。
傳統版 Apigee UI
如要刪除 KVM，請按照下列步驟操作：
- 登入 Apigee UI。
- 依序選取「管理」>「環境」>「鍵值對應表」。
- 在環境下拉式清單中，選取要刪除 KVM 的環境。
「鍵/值對應」頁面會顯示現有的 KVM 清單。
- 將滑鼠游標懸停在要刪除的 KVM 上。
- 按一下 delete「刪除」。
- 按一下「刪除」確認操作。
系統會刪除 KVM 並從清單中移除。
Apigee API
請使用下列其中一個 Apigee API，根據 KVM 的範圍刪除 KVM：