KeyValueMapOperations 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

為 Apigee 提供可用鍵/值對應 (KVM) 儲存庫的政策存取權。您可以分別設定 PUT、GET 或 DELETE 作業的 KeyValueMapOperations 政策，藉此儲存、擷取及刪除現有命名地圖中的鍵/值組合。(政策必須執行至少一項操作)。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

範例

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

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

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

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

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

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

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

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

子元素

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

<Delete> 元素

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

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

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

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

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

您可以使用 <ExpiryTimeInSecs> 元素，控制政策中使用的鍵/值在快取中儲存多久，然後再從 KVM 重新整理。不過，GET 和 PUT 作業對快取過期時間的影響方式有些許差異。

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

• <ExpiryTimeInSecs> 中指定的秒數到期。
  or
• 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 的值。

<Get> 元素

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

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

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

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

屬性

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

從 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 鍵相關聯的值包含多個電影名稱，並以半形逗號分隔。

在這個範例設定中，政策會擷取目前最熱門的電影和導演名稱：

<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 的名稱。

例如：

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

<MapName> 元素

<MapName> 元素可讓政策在執行階段，識別要動態使用的 KVM。您可以根據政策執行的內容，動態選取 KVM，靈活設計可存取不同 KVM 的 KeyValueMapOperations 政策。

以下提供一些例子：

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

<Put> 元素

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

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

• 使用 KVM 與 Apigee UI，在 UI 中建立加密的環境範圍 KVM
• 組織層級的鍵值對應 API
• 環境範圍的鍵值對應 API
• API Proxy 範圍的鍵值對應 API

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

屬性

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

<Scope> 元素

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

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

<Scope>environment</Scope>

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

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則來處理錯誤，就必須瞭解這項資訊。如需更多資訊，請參閱「 政策錯誤的相關資訊」和「 處理錯誤」。

執行階段錯誤

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

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

結構定義

使用須知

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

您可以使用 Apigee UI，僅在環境範圍內定義 KVM，如使用 Apigee UI 的 KVM 一文所述。您可以使用 Apigee API，在組織、環境或 API Proxy 範圍內定義 KVM，詳情請參閱下列各節：

• 組織層級的鍵值對應 API
• 環境範圍的鍵值對應 API
• API Proxy 範圍的鍵值對應 API

KVM 儲存庫會為以鍵/值組合格式編寫的資料提供輕量級持久性機制。您可以在執行階段透過政策或程式碼存取這些值。地圖包含 key=value 格式的任意資料。

例如 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"/>。

相關主題

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

• 使用鍵/值對應
• 組織層級的鍵值對應 API
• 環境範圍的鍵值對應 API
• API Proxy 範圍的鍵值對應 API