KeyValueMapOperations 政策

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

Edge UI 中的鍵/值對應作業圖示

優勢

提供依據政策存取 Apigee Edge 中金鑰值對應 (KVM) 存放區的政策。您可以設定指定 PUT、GET 或 DELETE 作業的 KeyValueMapOperations 政策,藉此儲存、擷取及刪除已命名現有地圖上的鍵/值組合。(至少有一項作業必須由政策執行)。

影片

請觀看下列影片,進一步瞭解 KVM。

影片 說明
為什麼關鍵價值對應? 瞭解您需要 KVM 的原因及運作方式。
使用 UI 建立 KVM,並在執行階段擷取 KVM 建立 KVM、使用 KVM 政策擷取其值,並使用流程變數將值插入 API 要求。
在 API 執行階段建立及更新 KVM 在 API 執行階段使用 KVM 政策建立 KVM。
快取 KVM 可提高效能 快取資料,改善 KVM 政策的效能。
儲存已加密的 KVM 以加密格式將機密資訊儲存在 KVM,並在執行階段使用 KVM 政策和私人變數擷取值。
使用 KVM 範圍管理存取權 使用 KVM 政策範圍屬性,以機構、環境、API Proxy 或 API Proxy 修訂版本限制 KVM。
在 API 執行階段刪除 KVM 項目 在 API 執行階段使用 KVM 政策 DELETE 作業刪除 KVM 項目。

範例

具有常值的 PUT KVM

執行以下政策時,系統會建立名為 FooKVM 的加密 KVM,接著建立名為 FooKey_1 的金鑰,其中包含兩個值,均設為常值字串 foobar (未設定從變數中擷取的值)。當您對下一個範例中的鍵執行 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>

請注意,範圍是「環境」。也就是說,您可以在管理 UI 中的「API」>「Environment Configuration」>「Key Value Map」下看到 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>

PUT KVM (含變數)

一個實用的鍵/值對應的簡單範例就是網址縮短服務。您可以設定鍵/值對應,以便儲存短網址與對應的完整網址。

這個政策範例會建立鍵/值對應關係。這項政策會將含有兩個關聯值的鍵插入名為「urlMapper」的鍵/值對應。

<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

下列鍵/值對應和項目會在 Edge 的鍵/值儲存庫中產生,並範圍於附加政策的 API Proxy:

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

項目會保留到刪除為止。鍵/值儲存庫項目會分散在執行雲端的 Edge 執行個體中。

透過變數取得 KVM

網址「縮短」服務就是一個實用的鍵/值對應的簡單範例。您可以設定鍵/值對應,以便儲存短網址與對應的完整網址。

如要擷取鍵/值對應項目的值 (例如 KeyValueMapOperations PUT 分頁中涵蓋的值),請設定政策來 GET 鍵/值對應:

<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 取得加密值

如果鍵/值對應已加密,請在 assignTo 屬性值中使用「private.」前置字元擷取值。在這個範例中,變數 private.encryptedVar 會保留金鑰值對應 foo 金鑰的解密值。如要瞭解如何建立加密的鍵/值對應關係,請參閱 Key/Value Maps Management API 的「建立」主題。

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

系統擷取完資料後,其他政策和程式碼就能從該變數中擷取值來存取資料。


元素參照

元素參考資料說明 KeyValueMapOperations 政策的元素和屬性:

<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>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </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

指定存取這項政策或管理 UI 中建立的地圖時要使用的 ID。

KVM 名稱在對公有雲的 Apigee Edge 中有大小寫之分。例如,foobarFooBar 不同。

如果排除這個屬性,系統會使用名為 kvmap 的 KVM。

在機構/Environment/apiproxy 的範圍內,您可以使用 mapIdentifier 屬性指定自己的地圖名稱。

不適用 選用

下表說明所有政策父項元素的通用屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<Delete> 元素

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

請務必使用父項元素上的 mapIdentifier 屬性指定 KVM 名稱。例如:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>
預設 不適用
存在必要性 如果沒有 <Get><Put>,則為必要欄位。
類型 不適用

<Entry> 元素

鍵/值對應的種子值,初始化時會在鍵/值對應中填入這個值。

在 Edge for Public Cloud 中,金鑰大小不得超過 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>
預設 不適用
存在必要性 選用
類型 不適用

<uniqueCache> 元素

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

<ExpiryTimeInSecs> 元素

指定邊緣從指定 KVM 重新整理快取值的時間長度 (以秒為單位)。

值為 0 或 -1 或排除此元素時,系統會使用 300 秒的預設值。例如:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
預設 300 (5 分鐘)
存在必要性 選用
類型 整數

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

<ExpiryTimeInSecs> 元素可讓您控制政策中使用的鍵/值要保留多久,才會透過 KVM 再次重新整理。不過,GET 和 PUT 作業對快取到期時間的影響稍有不同。

GET - 首次執行 KVM GET 作業時,來自 KVM 要求的鍵/值 (名稱在政策的根 mapIdentifier 屬性中指定) 會載入到快取中,直到發生下列其中一個 GET 作業為止:

  • <ExpiryTimeInSecs> 中指定的秒數過期。
  • KVM 政策中的 PUT 作業會覆寫現有的值 (如下所述)。

PUT:PUT 作業會將鍵/值寫入指定的 KVM。如果 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」的值。

<Get> 元素

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

請務必使用父項元素的 mapIdentifier 屬性指定 KVM 名稱。

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

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

從 KVM 取得單一項目

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

從 KVM 取得多個項目

在以下範例中,假設 KVM 具有下列鍵與值。除了儲存歷來最受歡迎電影的跑步清單之外,KVM 也會儲存所有大型電影的導演姓名。

top_movies 教父、國教凱恩
公民凱恩 奧森.威爾斯 (Orson Welles)
公主新娘 羅伯雷納
教父 Francis Ford Coppola

以下 KVM 政策設定可以擷取目前最受歡迎的電影及其導演名稱:

<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 Proxy 時,Edge 會建立下列可用於 API Proxy 流程中的變數:

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

屬性

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

屬性 說明 預設 存在必要性
assignTo

擷取值的變數。

如果鍵/值對應已加密,請在 assignTo 名稱開頭加上「private.」,例如:

<Get assignTo="private.myvar">

如果您在未使用前置字串的情況下嘗試擷取加密的金鑰值對應,這項政策會擲回錯誤。基於基本安全性目的在偵錯期間必須使用前置字串,API Proxy 追蹤記錄和偵錯工作階段皆會隱藏已加密的值。

如要瞭解如何建立加密的鍵/值對應關係,請參閱 Key/Value Maps Management API建立及編輯環境金鑰值對應關係的「建立」主題。

不適用 需要
index

要從多值鍵擷取的項目索引號碼 (位於 1 開始的索引中)。 舉例來說,指定 index=1 會傳回第一個值,並指派給 assignTo 變數。如未指定索引值,系統會將該項目的所有值指派為 java.util.List 做為變數。

如需範例,請參閱範例中的「從 KVM 取得加密值」分頁。

不適用 選用

<InitialEntries> 元素

鍵/值對應的種子值,當您初始化鍵/值對應時,系統就會填入這些值。請務必使用父項元素的 mapIdentifier 屬性指定 KVM 名稱,例如:

<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>

使用這個元素時,當您在部署的 Proxy 管理 UI 中儲存政策,或部署含有這個元素的政策的 API Proxy 組合時,系統會在 KVM 中自動建立金鑰 (未加密)。如果政策中的值與 KVM 中的值不同,系統會在部署 Proxy 時覆寫 KVM 中的值。系統會將任何新的鍵/值連同現有的鍵/值一起加入現有的 KVM。

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

公用雲端邊緣和私人雲端邊緣的金鑰大小限制為 2 KB。KVM 值的大小上限為 2 KB。

如要建立加密的 KVM,請使用 Key/Value Maps Management API

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

<Key> 元素

在鍵/值對應項目中指定鍵。金鑰可以是複合型,代表可附加多個參數以建立金鑰。舉例來說,userIDrole 可能會合併以建立 key。例如:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

請務必查看 <Parameter> 元素,即可進一步瞭解如何設定金鑰名稱。

使用 Edge for Public Cloud,金鑰大小上限為 2 KB。詳情請參閱「Public Cloud API 邊緣與 Private Cloud API 之間的差異」一節。

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

<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 元素包含多個參數元素時,有效的鍵字串是每個參數值的串連,並以雙底線連結。舉例來說,在上述範例中,如果 apiproxy.name 變數的值為「abc1」,則有效鍵為 targeturl__abc1__weight

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

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

屬性

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

屬性 說明 預設 存在必要性
參考資料 指定變數名稱,該變數的值包含您要建立、取得或刪除的鍵的確切名稱。 不適用 如果開頭和結尾標記之間沒有常值值,則為必要屬性。如果提供常值,則禁用此屬性。

<Put> 元素

將鍵/值組合寫入鍵/值組合 (金鑰值對應已加密或未加密)。如果父項元素的 mapIdentifier 屬性中指定的鍵/值對應不存在,系統會自動建立地圖 (未加密)。如果鍵/值對應已存在,則須加入鍵/值。

如要建立加密的鍵/值對應,請使用 Key/Value Maps Management API;或是參閱「建立及編輯環境鍵/值對應關係」,在使用者介面中建立以環境為範圍的加密 KVM。

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>
預設 不適用
存在必要性 如果沒有 <Get><Delete>,則為必要欄位。
類型 不適用

屬性

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

屬性 說明 預設 存在必要性
覆寫

如果設為 true,則會覆寫鍵的值。

false 選用

<Scope> 元素

定義鍵/值對應的無障礙功能邊界。預設範圍為 environment,表示根據預設,在環境 (例如測試或正式版) 中執行的所有 API Proxy 都會共用地圖項目。如果將範圍設為 apiproxy,則只有將值寫入地圖的 API Proxy 才能存取鍵/值對應中的項目。

請注意,存取地圖或地圖項目時,您必須指定建立地圖時使用的範圍值。舉例來說,如果地圖是以 apiproxy 的範圍建立,則必須在擷取其值、修改或刪除項目時使用 apiproxy 範圍。

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

<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> 元素的屬性:

屬性 說明 預設 存在必要性
參考資料 指定變數名稱,該變數的值包含您要設定的鍵值。 不適用 如果開頭和結尾標記之間沒有常值值,則為必要屬性。如果提供常值,則禁用此屬性。

錯誤參考資料

Edge 政策傳回的錯誤遵循一致的格式,詳情請參閱錯誤代碼參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時,可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 修正
steps.keyvaluemapoperations.SetVariableFailed 500

如果您嘗試從加密的金鑰值對應擷取值,並將值設為名稱不含前置字串 private 的變數,就會發生這個錯誤。基於基本安全性用途在偵錯期間必須使用前置字串,API Proxy 追蹤和偵錯工作階段皆會隱藏已加密的值。

steps.keyvaluemapoperations.UnsupportedOperationException 500

如果鍵/值對應作業政策中的 mapIdentifier 屬性設為空白字串,就會發生這個錯誤。

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

錯誤名稱 原因 修正
InvalidIndex 如果鍵值對應作業政策的 <Get> 元素中指定的 index 屬性為零或負數,API Proxy 部署就會失敗。索引從 1 開始,因此系統會將零或負整數的索引視為無效。
KeyIsMissing 如果金鑰值對應作業政策的 <InitialEntries> 元素 <Entry> 下方缺少 <Key> 元素,或是缺少 <Parameter> 元素,就會發生這個錯誤。<Key>
ValueIsMissing 在鍵/值對應作業政策的 <InitialEntries> 元素的 <Entry> 元素下方,缺少 <Value> 元素,就會發生這個錯誤。

結構定義

使用須知

如需鍵/值對應關係的總覽,請參閱使用鍵/值對應一文。

「鍵/值對應儲存庫」提供輕量的持續性機制,適用於採用鍵/值組合格式的資料。您可以在執行階段透過政策或程式碼存取這些內容。地圖包含任何格式為 key=value 的任意資料。

例如 localhost=127.0.0.1zip_code=94110first_name=felix。在第一個範例中,localhost,而 127.0.0.1。每個鍵/值組合都會儲存為鍵/值對應中的一個項目。鍵/值對應可儲存多個項目。

以下為使用鍵/值對應的範例。假設您需要儲存與不同後端環境相關聯的 IP 位址清單,您可以建立一個名為 ipAddresses 的鍵/值對應,其中包含一個鍵/值組合的清單做為項目。舉例來說,以下 JSON 可代表這類地圖:

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

您可以透過這個結構建立 IP 位址儲存庫,供政策在執行階段使用,以便強制執行 IP 許可清單或拒絕清單、動態選取後端目標位址等。一般而言,KeyValueMapOperations 政策用於儲存或擷取需要在多個要求/回應交易中重複使用的長期資訊。

您可以透過 KeyValueMapOperations 政策,或直接透過 Apigee Edge Management API 來控管鍵/值對應。如要進一步瞭解機構鍵/值對應 API API,請參閱管理 API 參考資料。舉例來說,您可以使用這個 API 將大型資料集上傳至鍵/值儲存庫,或是建立指令碼來管理鍵/值對應項目。您必須先使用 API 建立鍵/值對應,才能透過 KeyValueMapOperations 政策存取它。

指定並擷取金鑰名稱

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

參數元素會決定系統建立的金鑰名稱,以及要擷取或刪除的鍵名,因此應特別提及。以下是兩個範例。 第一個函式會依字面指定金鑰名稱,第二個則使用變數指定金鑰名稱。假設下列項目用於在 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 中的鍵名是「foo」,您可以使用 <Parameter>foo</Parameter> 指定常值值,或指定包含確切值的「foo」變數,例如:<Parameter ref="variable.containing.foo"/>

相關主題