Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

KeyValueMapOperations 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

提供以政策為準的存取權，可存取 Apigee Edge 中提供的鍵/值對應 (KVM) 儲存庫。您可以設定 KeyValueMapOperations 政策，指定 PUT、GET 或 DELETE 作業，從現有具名對應項儲存、擷取及刪除鍵/值組合。(政策必須執行至少一項這類作業)。

影片

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

影片	說明
為何要使用鍵/值對應？	瞭解為何需要 KVM，以及 KVM 的運作方式。
使用 UI 建立 KVM，並在執行階段擷取 KVM	建立 KVM、使用 KVM 政策擷取值，然後使用流程變數將值注入 API 要求。
在 API 執行階段建立及更新 KVM	使用 KVM 政策在 API 執行階段建立 KVM。
快取 KVM，提升效能	快取資料，提升 KVM 政策的效能。
儲存加密的 KVM	以加密格式將敏感資訊儲存在 KVM 中，並在執行階段使用 KVM 政策和私有變數擷取值。
使用 KVM 範圍管理存取權	使用 KVM 政策範圍屬性，將 KVM 限制在機構、環境、API Proxy 或 API Proxy 修訂版本。
在 API 執行階段刪除 KVM 項目	在 API 執行階段，使用 KVM 政策的 DELETE 作業刪除 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>

請注意，範圍是「環境」。也就是說，您可以在管理 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>

使用變數 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 鍵的解密值。如要瞭解如何建立加密鍵值對應，請參閱「鍵/值對應管理 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 屬性會指定您要互動的 KVM 名稱。

屬性說明預設存在必要性

mapIdentifier

屬性	說明	預設	存在必要性
mapIdentifier	指定存取此政策或管理 UI 所建立地圖時使用的 ID。在 Apigee Edge for Public Cloud 中，KVM 名稱會區分大小寫。舉例來說，`foobar` 與 `FooBar` 不同。如果排除這項屬性，系統會使用名為 `kvmap` 的 KVM。在機構/環境/apiproxy 的範圍內，您可以使用 `mapIdentifier` 屬性指定自己的對應名稱。	N/A	選用

指定存取此政策或管理 UI 所建立地圖時使用的 ID。

在 Apigee Edge for Public Cloud 中，KVM 名稱會區分大小寫。舉例來說，foobar 與 FooBar 不同。

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

在機構/環境/apiproxy 的範圍內，您可以使用 mapIdentifier 屬性指定自己的對應名稱。

N/A

選用

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

屬性	說明	預設	存在必要性
`name`	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。此值不能超過 255 個半形字元視需要使用 `<DisplayName>` 元素，為政策加上標籤：管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。	不適用	必填
`continueOnError`	如果設為「`false`」，系統會在政策失敗時傳回錯誤。這是可預期的情況大多數政策的行為如果設為 `true`，即使政策已發生，流程執行作業仍會繼續執行失敗。	false	選用
`enabled`	如要強制執行政策，請設為 `true`。設為 `false` 即可停用政策。這項政策不會仍會強制執行政策。	true	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName>元素

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

<DisplayName>Policy Display Name</DisplayName>

預設

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性選用

類型字串

<Delete> 元素

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

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

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

預設	N/A
存在必要性	如果沒有 `<Get>` 或 `<Put>`，則為必要欄位。
類型	N/A

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

預設	N/A
存在必要性	選用
類型	N/A

<ExclusiveCache> 元素

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

<ExpiryTimeInSecs> 元素

指定 Edge 在幾秒後從指定的 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

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

<Get> 元素

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

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

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

預設	N/A
存在必要性	如果沒有 `<Put>` 或 `<Delete>`，則為必要欄位。
類型	N/A

從 KVM 取得單一項目

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

從 KVM 取得多個項目

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

鍵	值
top_movies	《公主新娘》、《教父》、《大國民》
大國民	奧森威爾斯
公主新娘	羅勃雷納
教父	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	要指派擷取值的變數。如果鍵/值對應表經過加密，請在 assignTo 名稱開頭加上「`private.`」。例如： <Get assignTo="private.myvar"> 如果您嘗試擷取加密的金鑰值對應表，但未使用前置字元，政策就會擲回錯誤。前置字元是偵錯期間的基本安全措施，可隱藏 API Proxy 追蹤和偵錯工作階段中的加密值。如要瞭解如何建立加密鍵/值對應，請參閱「鍵/值對應管理 API」的「建立」主題，以及「建立及編輯環境鍵/值對應」。	N/A	必填
索引	要從多值鍵擷取項目的索引編號 (以 1 為基準)。舉例來說，指定 `index=1` 會傳回第一個值，並將其指派給 `assignTo` 變數。如未指定索引值，系統會將該項目的所有值指派給變數，做為 `java.util.List`。如需範例，請參閱「範例」中的「從 KVM 取得加密值」分頁。	N/A	選用

要指派擷取值的變數。

如果鍵/值對應表經過加密，請在 assignTo 名稱開頭加上「private.」。例如：

<Get assignTo="private.myvar">

如果您嘗試擷取加密的金鑰值對應表，但未使用前置字元，政策就會擲回錯誤。前置字元是偵錯期間的基本安全措施，可隱藏 API Proxy 追蹤和偵錯工作階段中的加密值。

如要瞭解如何建立加密鍵/值對應，請參閱「鍵/值對應管理 API」的「建立」主題，以及「建立及編輯環境鍵/值對應」。

N/A

必填

索引

要從多值鍵擷取項目的索引編號 (以 1 為基準)。舉例來說，指定 index=1 會傳回第一個值，並將其指派給 assignTo 變數。如未指定索引值，系統會將該項目的所有值指派給變數，做為 java.util.List。

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

N/A

選用

<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 版本中，透過管理使用者介面儲存政策，或是部署包含這個元素的政策的 API Proxy 套件，系統就會在 KVM 中自動建立金鑰 (未加密)。如果政策中的值與 KVM 中的值不同，部署 Proxy 時，系統會覆寫 KVM 中的值。任何新鍵/值都會與現有鍵/值一起新增至現有 KVM。

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

無論是公有雲 Edge 或私有雲 Edge，金鑰大小上限皆為 2 KB。KVM 值上限為 2 KB。

如要建立加密的 KVM，請使用鍵/值對應管理 API。

預設	N/A
存在必要性	選用
類型	N/A

<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 的差異」。

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

預設	N/A
存在必要性	選用
類型	N/A

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

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

預設	N/A
存在必要性	必填
類型	字串

屬性

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

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

<Put> 元素

將鍵/值組合寫入鍵/值對應，無論鍵/值對應是否經過加密。如果父項元素 mapIdentifier 屬性中指定的鍵/值對應不存在，系統會自動建立對應 (未加密)。如果鍵/值對應已存在，系統會將鍵/值新增至該對應。

如要建立加密的鍵/值對應，請使用鍵/值對應管理 API；或參閱「建立及編輯環境鍵/值對應」，在使用者介面中建立加密的環境範圍 KVM。

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

預設	N/A
存在必要性	如果沒有 `<Get>` 或 `<Delete>`，則為必要欄位。
類型	N/A

警告：如果政策使用空值鍵將鍵/值放入 KVM，系統會自動建立下列鍵：__$$_EDGE_KVM_EMPTY_KEY_$$__

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

屬性

下表說明 <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>

預設	N/A
存在必要性	必填
類型	字串

屬性

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

屬性	說明	預設	存在必要性
ref	指定變數名稱，該變數的值包含您要設定的金鑰值。	N/A	如果開始和結束標記之間未提供任何常值，則為必填。如果提供常值，則禁止使用。

錯誤參考資料

從 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.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 管理 API 操作。如要瞭解 Organization key/value maps API API 的詳細資料，請參閱管理 API 參考資料。舉例來說，您可以使用 API 將大型資料集上傳至鍵/值儲存庫，或建立指令碼來管理鍵/值對應項目。您必須先使用 API 建立鍵/值對應，才能透過 KeyValueMapOperations 政策存取該對應。

指定及擷取金鑰名稱

使用 <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 中的鍵名為「foo」，您可以指定具有 <Parameter>foo</Parameter> 的常值，也可以指定含有「foo」確切值的變數，例如：<Parameter ref="variable.containing.foo"/>。

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

KeyValueMapOperations 政策

結果

影片

範例

使用常值 PUT KVM

從常值取得 KVM

使用變數 PUT KVM

從變數取得 KVM

從 KVM 取得加密值

元素參考資料

<KeyValueMapOperations> 屬性

&lt;DisplayName&gt;元素

<Delete> 元素

<Entry> 元素

<ExclusiveCache> 元素

<ExpiryTimeInSecs> 元素

範例 - 快取 KVM

<Get> 元素

從 KVM 取得單一項目

從 KVM 取得多個項目

屬性

<InitialEntries> 元素

<Key> 元素

<Parameter> 元素

屬性

<Put> 元素

屬性

<Scope> 元素

<Value> 元素

屬性

錯誤參考資料

執行階段錯誤

部署錯誤

結構定義

使用須知

指定及擷取金鑰名稱

相關主題

<DisplayName>元素