本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
本節將討論如何使用鍵/值對應 (KVM)。
總覽
有時您會想儲存資料，以便在執行階段擷取，也就是不應在 API Proxy 邏輯中硬式編碼的不會過期資料。鍵值對應 (KVM) 非常適合用於此用途。KVM 是加密鍵/值字串組合的自訂集合。
以下列出三種在 KVM 中儲存資料的廣泛用途：
- 使用者工作階段資料：這類資料只能由執行階段建立及刪除，您無法在執行階段外查看或管理 KVM 項目。例如購物車內容。
- 設定 (例如轉送規則和查閱資料表)：這類資料通常是在執行階段外建立，但會由執行階段讀取。這項資料是透過 UI 或 API 設定，然後提供給閘道 (做為變數或唯讀內容)。
舉例來說，您有一個 API Proxy，需要在測試環境中呼叫一個目標 (或服務呼叫) 網址，在實際執行環境中呼叫另一個目標網址。您不必在 API 代理程式中硬式編碼網址，而是讓代理程式偵測所在環境，執行相關的 KeyValueMapOperations 政策，然後從適當的 KVM 擷取正確的目標網址。
之後，如果一或兩個目標有所變更，您只要使用新網址更新 KVM 即可。API Proxy 會擷取新值，無須重新部署。
- 憑證：儲存憑證、私密金鑰或權杖，例如外部服務的權杖、產生 OAuth 權杖所需的憑證，或 JavaCallout 政策或 JavaScript 中用於加密或 JSON Web Token (JWT) 簽署的私密金鑰。您可以在 KVM 中儲存憑證、金鑰或權杖，並在呼叫需要這些項目的目標時動態擷取，而不是在要求中傳遞這些項目，或以硬式編碼方式將這些項目寫入 Proxy 邏輯。
您會發現儲存鍵/值字串組合的其他實用情況。一般來說，建議在下列情況使用 KVM：
- 程式碼中的特定區段在執行階段需要不同的值。
- 機密資料必須傳遞，但不得進行硬式編碼。
- 您想儲存不會過期的值，例如快取。
在某些情況下，屬性集是 KVM 的理想替代方案，因為屬性集較容易使用。詳情請參閱「使用屬性集」。
關於 KVM 範圍
範圍會定義 KVM 的適用位置。您可以在下列範圍建立 KVM：
| 範圍 | 說明 |
|---|---|
| API Proxy | 只有 API Proxy 可以存取 KVM。 |
| 環境 | 特定環境中的所有 API Proxy 都可以存取 KVM。舉例來說，您可能不希望在 prod 環境中部署的 API Proxy 存取 test 環境中的 KVM。如要在正式環境中使用相同的 KVM 金鑰，請建立範圍限定為 prod 環境的平行 KVM。 |
| 機構 | 所有環境中的所有 API Proxy 都可以存取 KVM。 |
關於 KVM 加密
在 Apigee 中，API Proxy、機構和環境範圍的所有 KVM 項目，都會使用佈建 Apigee 機構時提供的 Cloud KMS 金鑰受到保護 (請參閱 Organization 資源中的 runtimeDatabaseEncryptionKey 欄位)。Apigee 使用 AES256 做為加密標準。
在 Apigee Hybrid 中，您可以為 API Proxy、機構和環境範圍的所有 KVM 項目提供個別加密金鑰。Apigee 接受 AES128、AES196 或 AES256 的密碼大小做為加密標準。
關於 KVM 遮罩
根據預設，KVM 值會以純文字顯示。您可以開啟 KVM 遮蔽功能，以星號 (*****) 遮蔽值。
如要開啟或關閉 KVM 遮蔽功能，請使用 UI 中的「遮蔽值」設定，或 API 要求中的 maskedValues 標記。
系統會在 KVM 層級遮蓋值。您無法遮蓋個別 KVM 項目，只能遮蓋 KVM 中的所有值，或完全不遮蓋。
建立 KVM
請按照下列各節所述建立 KVM。
透過 Cloud 控制台使用 Apigee
如要建立新的 (空白) KVM 或查看 KVM 清單，請按照下列步驟操作：
在 Google Cloud 控制台，前往「管理」>「環境」頁面。
- 從可用環境清單中選取要編輯的環境。
- 在「環境詳細資料」頁面上，按一下「鍵/值對應」分頁標籤。
「鍵/值對應」頁面會顯示現有 KVM 的清單。如果您尚未建立任何 KVM，清單會是空白。
- 如要建立新的 (空白) KVM，請按一下「+ Create Key value map」(建立鍵/值對應)。
「建立鍵/值對應」對話方塊隨即開啟。
- 在「鍵/值對應名稱」欄位中輸入 KVM 的名稱。
名稱只能包含英文字母、數字和連字號，且不得超過 255 個字元。 不得包含空格或其他特殊字元，例如：
my-kvm-1 - 按一下「遮蓋值」即可遮蓋所有值。如未選取，KVM 值會以純文字顯示。詳情請參閱「關於 KVM 遮蓋」。
- 按一下 [建立]。
清單中會顯示新的 KVM。
Apigee API
使用 Apigee API 建立、列出及刪除下列範圍的 KVM：
KVM 政策
如要在執行階段建立 KVM，並在 API Proxy 中更新 KVM，請使用 KeyValueMapOperations 政策。在政策中，您會在父項元素上的 mapIdentifier 屬性中指定 KVM 的名稱。
您可以在 UI 中儲存政策，或部署 API Proxy (如果您是離線開發)，即可使用 <InitialEntries> 元素在新的 KVM 中建立及填入一組基準項目。如果政策中的值有所變更，系統會覆寫現有值。所有新的鍵/值組合都會與現有鍵/值組合一起新增至現有 KVM。
如果沒有現有的 KVM，<Put> 元素會建立新的 KVM，並建立含有一或多個值的鍵。如果 KVM 已存在，系統會新增鍵/值組合 (或更新現有鍵的值)。您可以在 KVM 政策中使用多個 <Put> 元素。
偵錯
使用 KeyValueMapOperations 政策擷取加密的 KVM 值時，您會提供變數名稱來儲存該值。由於所有 KVM 值都會經過加密，因此您需要在變數名稱中加入 private. 前置字串，避免 KVM 鍵/值組顯示在偵錯工作階段中。
取得 KVM
使用 Apigee API 取得下列範圍的 KVM：
舉例來說，如要取得 API Proxy 範圍的 KVM，請向下列網址提出 GET 要求：
https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM
更新 KVM
使用 Apigee API 更新下列範圍的 KVM：
舉例來說，如要取得 API Proxy 範圍的 KVM，請向下列網址提出 GET 要求：
https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM
管理 KVM 值
如要管理 KVM 值，可以使用 API 或 KeyValueMapOperations 政策，詳情請參閱下列各節。使用 API 管理 KVM 值
使用 Apigee API 管理下列範圍的 KVM 值：
使用 KeyValueMapOperations 政策管理 KVM 值
使用
KeyValueMapOperations policy 從 KVM 新增、取得或刪除值。
使用 KeyValueMapOperations 政策的 <Put> 元素新增 KVM 鍵和值。
如果沒有現有的 KVM，<Put> 元素會建立新的 KVM，並建立含有一或多個值的鍵。如果 KVM 已存在，系統會新增鍵/值組合 (或更新現有鍵的值)。您可以在 KVM 政策中使用多個 <Put> 元素。詳情請參閱「<Put> 元素」。
使用 KeyValueMapOperations 政策的 <Get> 元素取得 KVM 值。
由於所有 KVM 值都會加密，請在要包含擷取值的變數名稱中加入 private. 前置字串。在偵錯 API 代理項目時，這個前置字元會隱藏偵錯工作階段的值。詳情請參閱「<Get> 元素」。
使用 KeyValueMapOperations 政策的 <Delete> 元素刪除 KVM 值。
詳情請參閱<Delete> 元素。
刪除 KVM
請按照下列各節所述刪除 KVM。
透過 Cloud 控制台使用 Apigee
如要刪除 KVM：
在 Google Cloud 控制台，前往「管理」>「環境」頁面。
- 從可用環境清單中，選取要編輯的環境名稱。
- 在「環境詳細資料」頁面上，按一下「鍵/值對應」分頁標籤。
「鍵/值對應」頁面會顯示現有 KVM 的清單。
- 找出要刪除的 KVM 所在的資料列。
- 按一下「動作」欄中的 delete。
- 在對話方塊中按一下「Delete Key Value Map」(刪除鍵/值對應)，確認要執行這項操作。
系統會刪除 KVM 並從清單中移除。
傳統版 Apigee UI
如要刪除 KVM：
- 登入 Apigee UI。
- 依序選取「Admin」>「Environments」>「Key Value Maps」。
- 從環境下拉式清單中，選取要刪除 KVM 的環境。
「鍵/值對應」頁面會顯示現有 KVM 的清單。
- 將游標移到要刪除的 KVM 上。
- 按一下「刪除」圖示 delete。
- 按一下「刪除」確認操作。
系統會刪除 KVM，並從清單中移除。
Apigee API
請使用下列其中一個 Apigee API，根據 KVM 的範圍刪除 KVM：