KeyValueMapOperations 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

透過政策存取 Apigee Edge 中可用的鍵/值對應 (KVM) 儲存庫。 設定可在已命名的現有地圖上儲存、擷取以及刪除鍵/值組合 用於指定 PUT、GET 或 DELETE 作業的 KeyValueMapOperations 政策。(至少一個 這些作業必須由政策執行)。

影片

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

範例

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

<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> 標記特有的屬性：

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

<DisplayName>元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

<Delete>元素

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

請務必使用 mapIdentifier 屬性指定 KVM 名稱 父元素。例如：

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

<Entry>元素

鍵/值對應的種子值，如果有，系統會在鍵/值對應中填入這些資料 初始化。

對於公有雲的 Edge，金鑰大小限制為 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>元素

指定邊緣從 指定的 KVM 執行個體

如果值為 0 或 -1，或排除此元素，則預設值為 300 秒 例如：

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

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 填入的快取在另一個 原始 60 秒造成 30 秒。
4. 15 秒後，另一個 GET 會執行並擷取「8」的值。

<Get>元素

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

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

您可以在政策中加入多個 Get 區塊，擷取多個項目 從 KVM 收到的指令

從 KVM 取得單一項目

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

從 KVM 取得多項商品

以下範例假設 KVM 具有下列鍵和值。此外， 為了儲存歷來最熱門的電影，而 KVM 儲存 所有知名電影的導演名稱

以下是我們可用來擷取目前最熱門的電影的 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> 元素的屬性：

<Get assignTo="private.myvar">

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

使用這項元素時，在已部署版本的管理 UI 中儲存政策時 或部署含有此元素政策(金鑰) 的 API Proxy 組合 系統會自動在 KVM 中建立 (未經加密)。如果政策中的值不同 而不是 KVM 中的值，那麼部署 Proxy 時就會覆寫 KVM 中的值。不限 在現有的 KVM 旁邊新增鍵/值，以及現有的鍵/值。

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

以公用雲端和 Cloud Edge 及 Cloud Edge 及，金鑰大小皆不得超過 2 KB 私刑邊緣KVM 值的上限為 2 KB。

如要建立加密的 KVM，請使用鍵/值 Maps Management API。

<Key>元素

指定鍵/值對應項目中的鍵。鍵可以組合，也就是說，超過 可以附加一個參數來建立鍵。例如 userID 和 系統可能會合併 role 來建立 key。例如：

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

請務必查看 <Parameter> 元素，即可瞭解 設定金鑰名稱

使用 Edge for Public Cloud 時，金鑰大小限制為 2 KB。 詳情請參閱 Edge for Public Cloud API 和 Private Cloud API 的 Edge 差異。

<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； 或參閱建立及編輯環境鍵/值對應關係 在 UI 中建立限定於環境範圍的加密 KVM。

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

屬性

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

<Scope>元素

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

請注意，存取地圖或對應項目時，您必須指定相同的範圍值 建立時間。例如，如果地圖的建立範圍 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 新增了兩個金鑰：

• 值為 v1,v2 的鍵 k1
• 值為 v3,v4 的鍵 k2

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

• 值為 bar,test 的鍵 foo_org

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

屬性

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

錯誤參考資料

Edge 政策傳回的錯誤格式與「錯誤代碼參考資料」中的說明一致。

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

執行階段錯誤

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

部署錯誤

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

結構定義

使用須知

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

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

例如 localhost=127.0.0.1、zip_code=94110 或 first_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。如要進一步瞭解 Organization key/value maps 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"/>。

相關主題

• 機構鍵/值對應 API