PopulateCache 政策

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

設定在執行階段應如何寫入快取值。

Populate Cache 政策的用途是在短期一般用途快取中寫入項目。 這項政策會與 Lookup Cache 政策 (用於讀取快取項目) 和Invalidated Cache 政策 (用於撤銷項目) 一併使用。

如要快取後端資源的回應，請參閱「回應快取政策」。

元素參考資料

以下列出您可以在這項政策中設定的元素。

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

<PopulateCache> 屬性

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

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

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

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

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

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

不適用

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

存在必要性 選用
類型 字串

<CacheKey> 元素

設定指向快取中儲存資料的專屬指標。

快取金鑰大小不得超過 2 KB。

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

預設值：

N/A

外觀狀態：

 必填

類型：

N/A

<CacheKey> 會建構儲存在快取中的每筆資料名稱。

在執行階段，系統會在 <KeyFragment> 值前面加上 <Scope> 元素值或 <Prefix> 值。舉例來說，下列程式碼會產生 UserToken__apiAccessToken__<value_of_client_id> 的快取鍵：

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

您會搭配 <Prefix> 和 <Scope> 使用 <CacheKey> 元素。詳情請參閱「處理快取金鑰」。

<CacheResource> 元素

指定郵件的儲存快取。

如果這項政策 (以及對應的 LookupCache 和 InvalidateCache 政策) 使用內含的共用快取，請完全省略這個元素。

<CacheResource>cache_to_use</CacheResource>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

如要進一步瞭解如何設定快取，請參閱「建立及編輯環境快取」。

<CacheKey> 元素

指定應納入快取鍵的值，為比對要求與快取回應建立命名空間。

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

預設值：

N/A

外觀狀態：

 選用

類型：

N/A

這可以是鍵 (您提供的靜態名稱)，也可以是值 (透過參照變數設定的動態項目)。所有指定的片段 (加上前置字串) 會串連在一起，形成快取金鑰。

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

您會搭配 <Prefix> 和 <Scope> 使用 <KeyFragment> 元素。詳情請參閱「處理快取金鑰」。

屬性

屬性 類型 預設 必填 說明
ref 字串 否

要取得值的變數。如果這個元素含有常值，則不應使用。

<CacheKey>/<Prefix> 元素

指定要用做快取鍵前置字串的值。

<Prefix>prefix_string</Prefix>

預設值：

N/A

外觀狀態：

 選用

類型：

字串

如要指定自己的值，而非 <Scope> 列舉值，請使用這個值，不要使用 <Scope>。如果已定義，<Prefix> 會在寫入快取的項目快取鍵值前面加上前置字元。<Prefix> 元素值會覆寫 <Scope> 元素值。

您會搭配 <CacheKey> 和 <Scope> 使用 <Prefix> 元素。詳情請參閱「處理快取金鑰」。

<ExpirySettings> 元素

指定快取項目的到期時間。如果存在，<TimeoutInSeconds> 會覆寫 <TimeOfDay> 和 <ExpiryDate>。

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

預設值：

N/A

外觀狀態：

 必填

類型：

N/A

<ExpirySettings> 的子元素

只能使用一個子項元素。下表說明 <ExpirySettings> 的子元素：

子元素 說明
<TimeoutInSeconds>

快取項目應在幾秒後過期。

<ExpirySettings>
  <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds>
</ExpirySettings>

這個元素會取代現已淘汰的 TimeoutInSec 元素。
<ExpiryDate>

指定快取項目的到期日期。請以 mm-dd-yyyy 格式指定字串。

<ExpirySettings>
  <ExpiryDate ref="var-containing-date">expiry</ExpiryDate>
</ExpirySettings>

如果指定的日期是過去的日期，政策會對快取項目套用最長存留時間。最長不得超過 30 天。
<TimeOfDay>

指定快取項目應過期的時間。以 HH:mm:ss 形式指定字串，其中 HH 代表 24 小時制的小時，時區為世界標準時間。例如，14:30:00 代表下午 2:30。

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

您只能指定其中一個可能的子項元素。如果指定多個元素，優先順序為：TimeoutInSeconds、ExpiryDate、TimeOfDay。

對於 <ExpirySettings> 的每個上述子項元素，如果您在子項元素上指定選用的 ref 屬性，政策會從具名內容變數擷取到期值。如果未定義變數，政策會使用子項元素的常值文字值。

<Scope> 元素

列舉用於在 <CacheKey> 元素中未提供 <Prefix> 元素時，建構快取鍵的前置字串。

<Scope>scope_enumeration</Scope>

預設值：

「Exclusive」

外觀狀態：

 選用

類型：

字串

<Scope> 設定會根據 <Scope> 值決定要預先加入的快取鍵。舉例來說，如果範圍設為 Exclusive，快取金鑰會採用下列格式：

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

如果 <CacheKey> 中有 <Prefix> 元素，系統會優先採用該元素的值，而非 <Scope> 元素的值。有效值包括下列列舉。

您會搭配 <CacheKey> 和 <Prefix> 使用 <Scope> 元素。詳情請參閱「處理快取金鑰」。

可接受的值

Global

環境中部署的所有 API Proxy 都會共用快取金鑰。快取金鑰會以 orgName __ envName __ 格式預先附加。

如果您使用 <KeyFragment> apiAccessToken 和 <Global> 範圍定義 <CacheKey> 項目，每個項目都會儲存為 orgName__envName__apiAccessToken，後面接著存取權杖的序列化值。如果 API Proxy 部署在名為「apifactory」機構的「test」環境中，存取權杖會儲存在下列快取鍵下：apifactory__test__apiAccessToken。
Application

API Proxy 名稱會做為前置字串。

快取金鑰會以 orgName__envName__apiProxyName 格式預先附加。
Proxy

ProxyEndpoint 設定會做為前置字串。

快取金鑰會以 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName 格式預先附加。
Target

TargetEndpoint 設定會做為前置字串。

快取鍵會以 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName 格式預先附加。
Exclusive

預設。這是最明確的選項，因此在特定快取中，命名空間發生衝突的風險最低。

前置字元有兩種形式：

  • 如果政策附加至 ProxyEndpoint 流程，前置字串的格式為 ApiProxyName_ProxyEndpointName。
  • 如果政策附加在 TargetEndpoint，前置字元格式為「ApiProxyName_TargetName」ApiProxyName_TargetName。

快取金鑰會以以下格式加上前置字串：orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

舉例來說，完整字串可能如下所示：

apifactory__test__weatherapi__16__default__apiAccessToken
。

<Source> 元素

指定應將值寫入快取的變數。

<Source>source_variable</Source>

預設值：

N/A

外觀狀態：

 必填

類型：

字串

使用須知

這項政策適用於一般用途的快取。在執行階段，<PopulateCache> 政策會將您在 <Source> 元素中指定的變數資料，寫入您在 <CacheResource> 元素中指定的快取。您可以使用 <CacheKey>、<Scope> 和 <Prefix> 元素指定金鑰，以便從 <LookupCache> 政策擷取值。使用 <ExpirySettings> 元素設定快取值應何時過期。

使用 PopulateCache 政策、LookupCache 政策和 InvalidateCache 政策進行一般用途快取時，會使用您設定的快取或預設內含的共用快取。在大多數情況下，底層共用快取應可滿足您的需求。如要使用這個快取，只要省略 <CacheResource> 元素即可。

快取限制：適用各種快取限制，例如名稱和值的大小、快取總數、快取中的項目數和到期時間。

如要進一步瞭解基礎資料儲存庫，請參閱「快取內部機制」。如要進一步瞭解如何設定快取，請參閱「建立及編輯環境快取」。

關於快取加密

公有雲專用 Edge：快取內容僅會在啟用 PCI 和 HIPAA 的機構中加密。系統會在機構佈建期間設定這些機構的加密功能。

錯誤代碼

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

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

錯誤程式碼 HTTP 狀態 發生時間
policies.populatecache.EntryCannotBeCached 500 無法快取項目。要快取的訊息物件並非 類別為 Serializable

部署錯誤

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

錯誤名稱 原因 修正
InvalidCacheResourceReference 如果 PopulateCache 政策中的 <CacheResource> 元素設為 沒有名稱在部署 API Proxy 的環境中。
CacheNotFound <CacheResource> 元素中指定的快取並未 個值。

錯誤變數

當這項政策觸發錯誤時，系統會設定這些變數。詳情請參閱重要須知 政策錯誤。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤程式碼的最後部分。 fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed policy_name 是使用者指定錯誤的政策名稱。 populatecache.POP-CACHE-1.failed = true

錯誤回應範例

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

錯誤規則範例

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>