使用鍵/值對應

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本節將說明如何使用鍵/值對應 (KVM)。

總覽

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

以下列出三種在 KVM 中儲存資料的廣泛用途：

• 使用者工作階段資料：這類資料只能由執行階段建立及刪除，您無法在執行階段外查看或管理 KVM 項目。例如購物車內容。
• 設定 (例如轉送規則和查閱表)：通常在執行階段以外建立，但由執行階段讀取的資料。這項資料是透過使用者介面或 API 設定，然後提供給閘道 (做為變數或唯讀內容)。

  舉例來說，您有一個 API Proxy，需要在測試環境中呼叫一個目標 (或服務呼叫) 網址，在實際執行環境中呼叫另一個目標網址。您不必在 API 代理程式中對網址進行硬式編碼，而是讓 API 代理程式偵測所在環境，然後執行相關的 KeyValueMapOperations 政策，並從適當的 KVM 擷取正確的目標網址。

  之後，如果一或兩個目標有所變更，您只要使用新網址更新 KVM 即可。API 代理程式會擷取新值，無須重新部署。

• 憑證：儲存憑證、私密金鑰或權杖，例如外部服務的權杖、產生 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。

注意：使用 Apigee UI 時，您只能在環境範圍內建立及管理 KVM。

關於 KVM 加密

在 Apigee 中，API Proxy、機構和環境範圍的所有 KVM 項目，都會使用佈建 Apigee 機構時提供的 Cloud KMS 金鑰受到保護 (請參閱 Organization 資源中的 runtimeDatabaseEncryptionKey 欄位)。Apigee 使用 AES256 做為加密標準。

在 Apigee Hybrid 中，您可以為 API Proxy、機構和環境範圍的所有 KVM 項目提供個別加密金鑰。Apigee 接受 AES128、AES196 或 AES256 的密碼大小做為加密標準。

建立 KVM

請按照下列各節所述建立 KVM。

注意：您必須使用 KeyValueMapOperations 政策，才能將資料新增至 KVM。

Cloud 控制台中的 Apigee

注意：

• 您無法透過 UI 新增或擷取 KVM 中的資料。您必須使用 KeyValueMapOperations 政策，才能在 KVM 中新增或擷取資料。
• KVM 只能限定環境範圍。

如要建立新的 (空白) KVM 或查看 KVM 清單，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「管理」>「環境」頁面。

   前往「環境」

2. 從可用環境清單中選取要編輯的環境。
3. 在「環境詳細資料」頁面上，按一下「鍵/值對應」分頁標籤。

   「鍵/值對應」頁面會顯示現有 KVM 的清單。如果您尚未建立任何 KVM，清單會是空白。

4. 如要建立新的 (空白) KVM，請按一下「+ Create Key value map」(建立鍵值對應)。

   「建立鍵值對應」對話方塊隨即開啟。

5. 在「Key value map name」欄位中輸入 KVM 的名稱。

   名稱只能包含英文字母、數字和連字號，且不得超過 255 個字元。 不得包含空格或其他特殊字元，例如：my-kvm-1

6. 按一下 [建立]。

   清單中會顯示新的 KVM。

傳統版 Apigee UI

注意：

• 您無法透過使用者介面新增或擷取 KVM 中的資料。您必須使用 KeyValueMapOperations 政策，才能在 KVM 中新增或擷取資料。
• KVM 只能限定環境範圍。

如要建立新的 (空白) KVM 或查看 KVM 清單，請按照下列步驟操作：

1. 登入 Apigee 使用者介面。
2. 依序選取「Admin」>「Environments」>「Key Value Maps」。
3. 從環境下拉式清單中，選取要建立 KVM 的環境。

   「鍵/值對應」頁面會顯示現有 KVM 的清單。如果您尚未建立任何 KVM，清單會是空白。

4. 如要建立新的 (空白) KVM，請按一下「+Key value map」(+鍵/值對應表)。

   「新增鍵/值對應」對話方塊隨即開啟。

5. 在「Name」欄位中輸入 KVM 的名稱。

   名稱只能包含英文字母、數字和連字號。不得包含空格或其他特殊字元。例如：my-kvm-1

6. 按一下「新增」。

   清單中會顯示新的 KVM。

Apigee API

使用 Apigee API，為下列範圍建立、列出及刪除 KVM：

• API Proxy 範圍的鍵值對應 API
• 環境範圍鍵值對應 API
• 機構範圍的鍵值對應 API

注意：

• 使用 API 建立 KVM 時，您必須將 encrypted 旗標設為 true。僅支援加密 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

使用 KeyValueMapOperations 政策的 <Get> 元素擷取 KVM。 由於所有 KVM 值都會加密，請在將包含擷取值的變數名稱中新增 private. 前置字串。在偵錯 API 代理項目時，這個前置字元會隱藏偵錯工作階段的值。詳情請參閱「<Get> 元素」。

刪除 KVM

請按照下列各節所述刪除 KVM。

Cloud 控制台中的 Apigee

如要刪除 KVM：

1. 在 Google Cloud 控制台中，前往「管理」>「環境」頁面。

   前往「環境」

2. 從可用環境清單中，選取要編輯的環境名稱。
3. 在「環境詳細資料」頁面上，按一下「鍵/值對應」分頁標籤。

   「鍵/值對應」頁面會顯示現有 KVM 的清單。

4. 找出要刪除的 KVM 所在的資料列。
5. 按一下「動作」欄中的 。
6. 在對話方塊中按一下「Delete Key Value Map」(刪除鍵/值對應)，確認執行這項操作。

   系統會刪除 KVM 並從清單中移除。

傳統版 Apigee UI

如要刪除 KVM：

1. 登入 Apigee 使用者介面。
2. 依序選取「Admin」>「Environments」>「Key Value Maps」。
3. 在環境下拉式清單中，選取要刪除 KVM 的環境。

   「鍵/值對應」頁面會顯示現有 KVM 的清單。

4. 將游標移到要刪除的 KVM 上。
5. 按一下「刪除」圖示 。
6. 按一下「刪除」確認操作。

   系統會刪除 KVM 並從清單中移除。

Apigee API

請使用下列其中一個 Apigee API，根據 KVM 的範圍刪除 KVM：

• 在 API Proxy 範圍內刪除 KVM
• 在環境範圍刪除 KVM
• 刪除機構範圍的 KVM