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 政策傳回的錯誤格式與「錯誤代碼參考資料」中的說明一致。

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

結構定義

使用須知

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

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