KeyValueMapOperations 政策

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

查看 Apigee Edge 說明文件。

結果

提供以政策為依據的存取權，可存取 Apigee 中提供的鍵/值對應 (KVM) 儲存空間。 您可以設定 KeyValueMapOperations 政策，分別指定 PUT、GET 或 DELETE 作業，從現有名稱對應中儲存、擷取及刪除鍵/值組合。(政策至少須執行其中一項作業)。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

注意：自 Apigee Hybrid 1.4.0 版發布起，Apigee 預設會加密所有 KVM。使用 private. 屬性搭配所有變數，透過 GET 指令存取 KVM 時，隱藏偵錯工作階段中的 KVM 資訊。如果未使用 private. 屬性，KVM 仍會加密，但 KVM 資訊會在偵錯工作階段中解密顯示，且不會擲回例外狀況。

影片：以下影片簡要介紹了 KVM。

範例

使用文字值 PUT KVM

執行下列政策時，系統會建立名為 FooKVM 的加密 KVM，然後建立名為 FooKey_1 的金鑰，並以字串常值 foo 和 bar 設定兩個值 (不是以從變數擷取的值設定)。在下一個範例中，當您GET鍵時，您會指定索引編號來擷取所需的值。

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

請注意，範圍是 environment。也就是說，您可以在管理 UI 中，依序點選「APIs」>「Environment Configuration」>「Key Value Maps」，查看 KVM。該頁面顯示的 KVM 全都屬於所選環境。

從常值取得 KVM

這項政策會查看上一個範例中的 FooKVM 對應，從 FooKey_1 鍵取得第二個值 (index="2")，並將該值儲存在名為 foo_variable 的變數中。

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

動態存取 KVM

本政策使用 <MapName> 元素，透過流程變數動態參照 KVM。元素會從流程變數取得 KVM ID。請注意，系統會省略 mapIdentifier 屬性；您無法將 <MapName> 與 mapIdentifier 屬性搭配使用。

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

使用變數 PUT KVM

實用的 KVM 簡單範例是網址縮短服務。KVM 可設定為儲存縮短網址和對應的完整網址。

這個政策範例會建立 KVM。這項政策會使用 PUT 指令，將含有兩個相關值的鍵放入名為 urlMapper 的 KVM。

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Put override="true">
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
    <Value ref="urlencoding.longurl.encoded"/>
    <Value ref="request.queryparam.url"/>
  </Put>
</KeyValueMapOperations>

這個範例中的鍵 urlencoding.requesturl.hashed 是自訂變數的範例。系統會透過程式碼 (例如 JavaScript 或 Java) 產生雜湊要求網址，然後儲存在這個變數中，KeyValueMapOperations 政策可存取該變數。

系統會為每個鍵 requesturl.hashed 儲存兩個值：

• 名為 urlencoding.longurl.encoded 的自訂變數內容
• 預先定義變數 request.queryparam.url 的內容

舉例來說，當政策在執行階段執行時，變數的值可能如下所示：

• urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
• urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
• request.queryparam.url: http://apigee.com

Apigee 的鍵/值存放區會產生下列 KVM 和項目，並限定於附加政策的 API 代理項目：

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

除非刪除，否則系統會一直保留該筆記錄。鍵/值儲存項目會分散在執行雲端的 Apigee 執行個體中。

從變數取得 KVM

實用的 KVM 簡單範例是網址縮短服務。KVM 可設定為儲存縮短網址和對應的完整網址。

如要擷取 KVM 項目值 (例如「KeyValueMapOperations」PUT分頁中涵蓋的項目)，請設定政策來 GET KVM：

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
  <Scope>apiproxy</Scope>
  <Get assignTo="urlencoding.shorturl" index='1'>
    <Key>
      <Parameter ref="urlencoding.requesturl.hashed"/>
    </Key>
  </Get>
</KeyValueMapOperations>

執行這項政策時，如果 urlencoding.requesturl.hashed 變數的值為 ed24e12820f2f900ae383b7cc4f2b31c402db1be，系統會將名為 urlencoding.shorturl 的自訂變數設為 http://tinyurl.com/38lwmlr 值。

現在資料已擷取完畢，其他政策和程式碼可以從這些變數中擷取值，進而存取資料。

從 KVM 取得值

使用 private. 屬性搭配所有變數，透過 GET 指令存取 KVM 時，即可在偵錯工作階段中隱藏 KVM 資訊。如果未使用 private. 屬性，KVM 仍會加密，但 KVM 資訊會在偵錯工作階段中解密顯示，且不會擲回例外狀況。

在本例中，變數 private.encryptedVar 會保留 KVM foo 金鑰的解密值。

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
  <Scope>apiproxy</Scope>
  <Get assignTo="private.encryptedVar" index='1'>
    <Key>
      <Parameter>foo</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

現在資料已擷取完畢，其他政策和程式碼可以從該變數中擷取值，進而存取資料。

<KeyValueMapOperations>

提供以政策為準的金鑰值對應 (KVM) 存取權。

語法

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
  <DisplayName>Key Value Map Operations 1</DisplayName>
  <Scope>environment</Scope>
  <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
  <InitialEntries>
    <Entry>
      <Key>
        <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
    </Entry>
    <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Get>
  <Delete>
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Delete>
</KeyValueMapOperations>

<KeyValueMapOperations> 屬性

以下範例顯示 <KeyValueMapOperations> 元素的屬性：

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

下表說明 <KeyValueMapOperations> 元素的屬性：

注意：mapIdentifier 屬性會指定您要互動的 KVM 名稱。您也可以使用 <MapName> 元素動態指定 KVM。

屬性	說明	預設	存在必要性
mapIdentifier	指定識別碼，告知政策應存取哪個 KVM。 如果缺少這個 ID 和 <MapName>，系統會使用名為 kvmap 的 KVM。如果指定 <MapName> 元素，就無法使用這項屬性。	不適用	選用

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
name	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設	不適用 如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性	選用
類型	字串

子元素

本節說明 KeyValueMapOperations 政策的元素和屬性：

<Delete> 元素

刪除指定的鍵/值組合。請至少使用 <Get>、<Put> 或 <Delete> 其中一個。

請務必在根元素上使用 mapIdentifier 屬性，或使用 <MapName> 元素指定 KVM 的名稱。例如：

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>

預設	不適用
存在必要性	如果沒有 <Get> 或 <Put>，則為必要欄位。
類型	不適用

<Entry> 元素

KVM 的種子值，會在 KVM 初始化時填入。如果是 Apigee，金鑰大小上限為 2 KB。

例如：

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

預設	不適用
存在必要性	選用
類型	不適用

<ExclusiveCache> 元素

已淘汰，請改用 <Scope> 元素。

<ExpiryTimeInSecs> 元素

指定 Apigee 從指定 KVM 重新整理快取值的時間間隔 (以秒為單位)。

如果值為 0 或 -1，或是排除這個元素，系統會使用預設值 300 秒。例如：

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

預設	300 (5 分鐘)
存在必要性	選用
類型	整數

KVM 是一種長期保存機制，可將鍵和值儲存在 NoSQL 資料庫中。 因此，在執行階段從 KVM 讀取資料可能會降低 Proxy 效能。為提升效能，Apigee 內建機制，可在執行階段將 KVM 鍵/值快取到記憶體中。這項 KVM 作業政策一律會從快取讀取 GET 作業。

<ExpiryTimeInSecs> 元素可讓您控制政策中使用的鍵/值在從 KVM 重新整理前，於快取中儲存的時間長度。不過，GET 和 PUT 作業對快取到期時間的影響有所不同。

GET - 首次執行 KVM GET 作業時，系統會將 KVM 中要求的鍵/值 (名稱在政策的根層級 mapIdentifier 屬性或 <MapName> 元素中指定) 載入快取，並保留在快取中，供後續 GET 作業使用，直到發生下列其中一種情況為止：

• <ExpiryTimeInSecs> 中指定的秒數到期。
  或
• KVM 政策中的 PUT 作業會覆寫現有值 (詳見下文)。

PUT - PUT 作業會將鍵/值寫入指定的 KVM。如果 PUT 寫入的鍵已存在於快取中，該快取會立即重新整理，並在政策的 <ExpiryTimeInSecs> 元素中指定秒數內保留新值。不過，使用 PUT 只會重新整理處理要求的單一執行階段節點中的快取。如要在每個分散式執行階段節點中重新整理快取，請使用 <ExpiryTimeInSecs> 元素為每個節點指定重新整理間隔。

範例 - 快取 KVM

1. GET 作業會擷取「rating」的值，並將「10」值新增至快取。政策的 <ExpiryTimeInSecs> 為 60。
2. 30 秒後，GET 政策會再次執行，並從快取擷取 10。
3. 5 秒後，PUT 政策會將 rating 的值更新為 8，而 PUT 政策的 <ExpiryTimeInSecs> 為 20。快取會立即以新值重新整理，新值現在會保留在快取中 20 秒。(如果 PUT 尚未發生，則第一個 GET 填入的快取仍會存在 30 秒，這是原始 60 秒的剩餘時間)。
4. 15 秒後，系統會執行另一個 GET 並擷取 8 的值。

注意事項

• 為獲得最佳效能，請根據預期 API 流量調整快取到期時間。舉例來說，如果流量很大，您可能需要設定較長的快取到期間隔，避免資料庫頻繁重新整理。
• 您無法手動重設 KVM 快取。不過，您可以建立臨時政策，以較短的 <ExpiryTimeInSecs> 執行一次性 PUT 作業。這會重設快取，其中包含您 PUT 的值，重設時間為您指定的秒數。
• 使用 Apigee UI 或 API 更新 KVM 時，不會重設 KVM 快取。
• 您可以在同一項政策中使用多項作業。如果這麼做，政策會依序執行作業。如果您在同一項政策中使用相同的鍵，並依序使用 PUT 和 GET，則 PUT 在寫入時會隱含重設快取到期時間。

<Get> 元素

擷取指定鍵的值。請至少使用 <Get>、<Put> 或 <Delete> 其中一個。

Apigee 會加密 KVM 中儲存的所有資料。詳情請參閱「關於加密金鑰」。使用 <Get> 時，Apigee 會解密儲存的資料，並將其指派給訊息環境中的變數。變數名稱是使用 assignTo 屬性指定。

請務必使用根元素上的 mapIdentifier 屬性或 <MapName> 元素，指定 KVM 的名稱。

您可以在政策中加入多個 Get 區塊，從 KVM 擷取多個項目。

注意：您可以在同一項政策中使用多項作業。如果這麼做，政策會依序執行作業。如果您在同一項政策中使用相同的鍵，並依序使用 PUT 和 GET，則 PUT 在寫入時會隱含重設快取到期時間。詳情請參閱 ExpiryTimeInSecs 元素。

預設	不適用
存在必要性	如果沒有 <Put> 或 <Delete>，則為必要欄位。
類型	不適用

屬性

下表說明 <Get> 元素的屬性：

屬性	說明	預設	存在必要性
assignTo	要指派擷取值的變數。	不適用	必填
index	要從多值鍵擷取項目的索引編號 (以 1 為基準)。 舉例來說，指定 index=1 會傳回第一個值，並將該值指派給 assignTo 變數。如未指定索引值，系統會將該項目的所有值指派給變數，做為 java.util.List。 如需範例，請參閱「範例」中的「從 KVM 取得值」分頁。	不適用	選用

從 KVM 取得單一項目

透過這個範例步驟設定，政策會讀取並解密 KVM 中單一金鑰的值，然後將解密值指派給名為 myvar 的變數。

<Get assignTo="myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

排除從偵錯工作階段擷取的資料

在某些情況下，儲存在 KVM 中的資料屬於機密資料。如要防止擷取的資料顯示在偵錯工作階段中，請在 assignTo 屬性中指定的變數名稱上使用 private. 前置字串。如果您未使用 private. 前置字串，從 KVM 擷取的資料會以明文顯示在您建立的任何偵錯工作階段中。

透過這個範例步驟設定，政策會讀取並解密 KVM 中與單一金鑰相關聯的值，然後將該值指派給變數。指派內容不會顯示在偵錯工作階段中。

<Get assignTo="private.myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

從 KVM 取得多個項目

在以下範例中，假設 KVM 具有下列鍵和值。除了儲存歷來最熱門的電影清單，KVM 也會儲存所有主要電影的導演姓名。

鍵	值
top_movies	《公主新娘》、《教父》、《大國民》
大國民	奧森威爾斯
公主新娘	羅勃雷納
教父	法蘭西斯福特柯波拉

您會發現與 top_movies 鍵相關聯的值包含多個電影名稱，並以半形逗號分隔。

使用這個範例設定，政策會擷取目前的熱門電影和導演姓名：

<Get assignTo="top.movie.pick" index="1">
  <Key>
    <Parameter>top_movies</Parameter>
  </Key>
</Get>
<Get assignTo="movie.director">
  <Key>
    <Parameter ref="top.movie.pick"/>
  </Key>
</Get>

呼叫 API 代理時，Apigee 會建立下列變數和對應值，之後可在 API 代理流程中使用：

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

top.movie.pick 的值只是逗號分隔清單中的第一個項目，因為第一個 <Get> 元素使用 index 屬性 1。接著，第二個 <Get> 元素會使用指派給 top.movie.pick 的值做為鍵，將值擷取到 movie.director 中。

<InitialEntries> 元素

KVM 的種子值，會在 KVM 初始化時填入。請務必在根元素上使用 mapIdentifier 屬性指定 KVM 的名稱。

注意：如果使用 <MapName> 元素，則不允許使用 <InitialEntries>。

例如：

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>KEY_NAME_VARIABLE</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

使用這個元素時，如果您在已部署的 API Proxy 版本中，透過 Apigee UI 儲存政策，或是部署含有這個元素的政策的 API Proxy 套件，系統就會在 KVM 中自動建立金鑰。如果政策中的值與 KVM 中的值不同，部署 API Proxy 時，系統會覆寫 KVM 中的值。所有新鍵/值都會與現有鍵/值一起新增至現有 KVM。

這個元素填入的鍵和值必須是常值。舉例來說，這個元素不支援 <Parameter ref="request.queryparam.key">。

索引鍵大小上限為 2 KB。

預設	不適用
存在必要性	選用
類型	不適用

<Key> 元素

指定 KVM 項目中的鍵。這個元素會顯示為 <Get>、<Put> 或 <Delete> 的子項，或是 <Entry> 元素的子項，而 <Entry> 元素是 <InitialEntries> 的子項。以下是固定金鑰的範例：

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

金鑰可以是複合式，含有動態元素，也就是說，可以附加多個 <Parameter> 來建立金鑰。舉例來說，變數 userID 和 role 的內容可能會合併，以建立動態鍵。以下是步驟設定範例，指定複合式動態判斷鍵：

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

請務必查看 <Parameter> 元素，瞭解如何設定金鑰名稱。

索引鍵大小上限為 2 KB。

注意：名稱「ratelimit」為保留名稱，詳情請參閱這篇 Apigee 社群貼文。

預設	不適用
存在必要性	選用
類型	不適用

<MapName> 元素

<MapName> 元素可讓政策在執行階段動態識別要使用的 KVM。 動態選取 KVM 的功能可讓您彈性設計一項KeyValueMapOperations政策，根據政策執行的情境存取不同的 KVM。

以下提供一些例子：

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

第一行會以字串常值指定 KVM 名稱。第二行會從流程變數取得名稱。在第三行中，如果流程變數解析為空值，系統會改用字串常值。

如果您在政策中使用 <MapName>，請勿指定 mapIdentifier 屬性。詳情請參閱政策屬性。

如果部署 Proxy 時地圖不存在，系統就不會建立地圖，且執行政策時 Apigee 會擲回執行階段錯誤。如果提供流程變數，則不允許使用 <InitialEntries> 元素。部署期間會發生驗證錯誤。

<Parameter> 元素

指定鍵/值組合中鍵的元件。建立、更新、擷取或刪除鍵/值組合時，這個元素會指定名稱。

你可以使用下列方式指定名稱：

• 字串常值

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• 在執行階段擷取的變數，使用 ref 屬性

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• 常值和變數參照的組合

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

如果 <Key> 元素包含多個 <Parameter> 元素，有效鍵字串就是每個參數值的串連，並以雙底線做為分隔符號。舉例來說，在上述範例中，如果 apiproxy.name 變數的值為 abc1，則有效鍵為 targeturl__abc1__weight。

無論是取得、更新或刪除鍵/值項目，鍵名都必須與 KVM 中的鍵名相符。如需相關規範，請參閱「指定及擷取金鑰名稱」。

預設	不適用
存在必要性	必填
類型	字串

屬性

下表說明 <Parameter> 元素的屬性：

屬性	說明	預設	存在必要性
ref	指定變數名稱，該變數的值包含您要建立、取得或刪除的金鑰確切名稱。	不適用	如果開頭和結尾標記之間未提供任何常值，則為必填。

<Put> 元素

將鍵/值組合寫入 KVM。如果根元素 mapIdentifier 屬性中指定的 KVM 不存在，且未使用 <MapName> 元素，系統會自動建立地圖。如果鍵值對應已存在，系統會將鍵/值新增至該對應。

如要使用 UI 或 API 建立 KVM，請參閱：

• 使用 Apigee UI 搭配 KVM，在 UI 中建立環境範圍的加密 KVM
• 機構範圍的鍵值對應 API
• 環境範圍鍵值對應 API
• API Proxy 範圍的鍵值對應 API

注意：您可以在同一項政策中使用多項作業。如果這麼做，政策會依序執行作業。如果您在同一項政策中使用相同的鍵，並依序使用 PUT 和 GET，則 PUT 在寫入時會隱含重設快取到期時間。詳情請參閱 ExpiryTimeInSecs 元素。

索引鍵大小上限為 2 KB。

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>

預設	不適用
存在必要性	如果沒有 <Get> 或 <Delete>，則為必要欄位。
類型	不適用

警告：如果政策使用 PUT 指令，透過空值鍵將鍵/值放置在 KVM 中，系統會自動建立下列鍵：__$$_EDGE_KVM_EMPTY_KEY_$$__

舉例來說，如果您使用變數參照填入鍵，但參照的變數為空值，就會發生這種情況。嘗試使用含有空值的鍵發出新 PUT 指令時，系統只會使用該鍵，因此每次執行政策時，該鍵的現有值可能會遭到覆寫。

屬性

下表說明 <Put> 元素的屬性：

屬性	說明	預設	存在必要性
覆寫	如果設為 true，則會覆寫鍵的值。 只有在 KVM 存放區中目前沒有該鍵的項目時，<Put override="false"> 才會寫入。	true	選用

<Scope> 元素

定義 KVM 的無障礙範圍。預設範圍為 environment，也就是說，根據預設，地圖項目會由環境中執行的所有 API Proxy 共用 (例如測試或正式環境)。如果將範圍設為 apiproxy，只有將值寫入地圖的 API Proxy 才能存取 KVM 中的項目。

請注意，存取對應或對應項目時，您必須指定建立對應時使用的相同範圍值。舉例來說，如果地圖是使用 apiproxy 範圍建立，您就必須使用 apiproxy 範圍擷取地圖的值、進行變更或刪除項目。

<Scope>environment</Scope>

預設	environment
存在必要性	選用
類型	字串
有效值	organization environment apiproxy policy (API Proxy 修訂版本)

如要在多個 Proxy 中使用相同的 KVM，請考慮將 KVM 政策新增至 SharedFlow，並在 Proxy 中使用 SharedFlow。

<Value> 元素

指定鍵的值。您可以將值指定為常值字串，也可以使用 ref 屬性，將值指定為要在執行階段擷取的變數：

<!-- Specify a literal value -->
<Value>literal<Value>

或：

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

您也可以加入多個 <Value> 元素，指定多部分值。值會在執行階段合併。

在下列範例中，兩個鍵會新增至 KVM：

• 鍵 k1，值 v1,v2
• 鍵 k2，值 v3,v4

<InitialEntries>
  <Entry>
    <Key>
      <Parameter>k1</Parameter>
    </Key>
    <Value>v1</Value>
    <Value>v2</Value>
  </Entry>
  <Entry>
    <Key>
      <Parameter>k2</Parameter>
    </Key>
    <Value>v3</Value>
    <Value>v4</Value>
  </Entry>
</InitialEntries>

在以下範例中，一個鍵會建立兩個值。假設機構名稱為 foo_org、API Proxy 名稱為 bar，且環境為 test：

• 鍵 foo_org，值 bar,test

<Put>
  <Key>
    <Parameter ref="organization.name"/>
  </Key>
  <Value ref="apiproxy.name"/>
  <Value ref="environment.name"/>
</Put>

預設	不適用
存在必要性	必填
類型	字串

屬性

下表說明 <Value> 元素的屬性：

屬性	說明	預設	存在必要性
ref	指定變數名稱，該變數的值包含您要設定的金鑰值。	不適用	如果開頭和結尾標記之間未提供字面值，則為必填。如果提供字面值，則禁止使用。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.keyvaluemapoperations.UnsupportedOperationException	500	This error occurs if the mapIdentifier attribute is set to empty string in the KeyValueMapOperations policy.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidIndex	If the index attribute specified in the <Get> element of KeyValueMapOperations policy is zero or a negative number, then the deployment of the API proxy fails. The index starts from 1, so an index of zero or negative integer is considered as invalid.
KeyIsMissing	This error occurs if the <Key> element is completely missing or <Parameter> element is missing within <Key> element underneath the <Entry> of the <InitialEntries> element of the KeyValueMapOperations policy.
ValueIsMissing	This error occurs if the <Value> element is missing underneath the <Entry> element of the <InitialEntries> element of the KeyValueMapOperations policy.

結構定義

範例：如要查看最新結構定義，請參閱 GitHub 存放區範例。

使用須知

如需 KVM 總覽，請參閱「使用鍵/值對應」。

使用 Apigee UI 時，您只能在環境範圍內定義 KVM，如「透過 Apigee UI 使用 KVM」一文所述。您可以使用 Apigee API，在機構、環境或 API Proxy 範圍內定義 KVM，詳情請參閱下列章節：

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

KVM 儲存空間提供輕量型資料持續性機制，可儲存格式為鍵/值組合的資料。您可以在執行階段透過政策或程式碼存取這些項目。地圖包含 key=value 格式的任意資料。

注意：金鑰大小上限為 2 KB。

例如 localhost=127.0.0.1、zip_code=94110 或 first_name=felix。在第一個範例中，localhost 是鍵，而 127.0.0.1 是值。每個鍵/值組合都會儲存在鍵值對應表中的項目。KVM 可以儲存多個項目。

舉例來說，假設您需要儲存與各種後端環境相關聯的 IP 位址清單。您可以建立名為 ipAddresses 的 KVM，其中包含鍵/值組合清單做為項目。舉例來說，這個 JSON 可以代表這類對應：

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

您可以使用這個結構建立 IP 位址商店，供政策在執行階段強制執行 IP 允許/拒絕清單，動態選取後端目標位址等。KeyValueMapOperations 政策通常用於儲存或擷取長期資訊，這些資訊需要在多個要求/回應交易中重複使用。

您可以透過 KeyValueMapOperations 政策或 Apigee API 直接操作 KVM。舉例來說，您可以使用 API 將大型資料集上傳至鍵/值儲存空間，或建立指令碼來管理鍵值對應項目。您必須先使用 API 建立 KVM，才能透過 KeyValueMapOperations 政策存取 KVM。

指定及擷取金鑰名稱

使用 <Parameter> 和 <Value> 元素時，您可以指定常值 (值位於開頭和結尾標記之間)，也可以使用 ref 屬性指定變數名稱，該變數的值應在執行階段使用。

<Parameter> 元素值得特別一提，因為它會決定建立的金鑰名稱，以及您要擷取或刪除的金鑰名稱。以下提供兩個範例。 第一個是直接指定鍵名，第二個則是使用變數指定鍵名。 假設您使用下列項目在 KVM 中建立金鑰：

<Parameter>KEY_NAME_LITERAL</Parameter>
<Parameter ref="key.name.variable"/>

在第一個執行個體中，KEY_NAME_LITERAL 的字面值會以鍵名形式儲存在 KVM 中。在第二個例項中，key.name.variable 中的任何值都會成為 KVM 中鍵的名稱。舉例來說，如果 key.name.variable 包含值 foo，則鍵會命名為 foo。

如要使用 GET 作業擷取金鑰和金鑰值 (或使用 DELETE 作業移除)，<Parameter> 元素的值必須與 KVM 中的金鑰名稱相符。舉例來說，如果 KVM 中的鍵名為 my_key，您可以指定 <Parameter>my_key</Parameter> 的字面值，也可以指定包含確切值 mny_key 的變數，如下所示：<Parameter ref="variable.containing.foo"/>。

注意：名稱「ratelimit」為保留名稱，詳情請參閱配額政策 - 擲回 NullPointerException。

相關主題

如要進一步瞭解 KVM，請參閱下列主題：

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