Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

PopulateCache 政策

可擴充的政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

PopulateCache 政策會設定在執行階段寫入快取值的方式。

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

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

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

元素參考資料

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

<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>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
`continueOnError`	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

預設

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

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。

存在必要性選用

類型字串

<CacheKey> 元素

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

快取金鑰大小上限為 2 KB。

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

預設值：	不適用
外觀狀態：	必填
類型：	不適用

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

預設值：	不適用
外觀狀態：	選用
類型：	字串

如要進一步瞭解如何設定快取，請參閱「一般用途快取」。

<CacheKey> 元素

指定應納入快取金鑰的值。使用 ref 屬性或固定值，指定要取消參照的變數。

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

預設值：	不適用
外觀狀態：	零或更多
類型：	不適用

在執行階段，Apigee 會先從 <Scope> 元素或 <Prefix> 元素取得值，然後將該值加到每個 <KeyFragment> 元素解析值的串連值前面，藉此建立快取金鑰。詳情請參閱「處理快取金鑰」。

屬性

屬性	類型	預設	必填	說明
ref	字串		否	要從中取得值的變數。如果這個元素含有字面值，則不應使用。

<CacheKey>/<Prefix> 元素

指定要用做快取金鑰前置字串的固定值。

<Prefix>prefix_string</Prefix>

預設值：	不適用
外觀狀態：	選用
類型：	字串

<Prefix> 元素會覆寫任何 <Scope> 元素。

<ExpirySettings> 元素

指定快取項目的到期時間。

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

預設值：	不適用
外觀狀態：	必填
類型：	不適用

`<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> 注意：請以世界標準時間 (UTC) 時區指定時間。填入快取時間時，請採用國際標準日期標記，如國際標準 ISO 8601 所定義。

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

預設值：	「專屬」
外觀狀態：	選用
類型：	字串

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

orgName__envName__apiProxyName__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__proxyEndpointName」orgName__envName__apiProxyName__proxyEndpointName格式加在開頭。
`Target`	TargetEndpoint 設定會做為前置字串。快取鍵會預先加上 orgName__envName__apiProxyName__targetEndpointName 格式。
`Exclusive`	預設值，這是最明確的選項，因此在特定快取中，命名空間發生衝突的風險最低。前置字元有兩種形式：如果政策附加至 `ProxyEndpoint` 流程，前置字串的格式為 ApiProxyName_ProxyEndpointName。如果政策附加在 `TargetEndpoint`，前置字串的格式為 ApiProxyName_TargetName。快取金鑰會預先加上以下格式： orgName__envName__apiProxyName__proxyNameITargetName 舉例來說，完整字串可能如下所示： apifactory__test__weatherapi__default__apiAccessToken 。

<Source> 元素

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

<Source>source_variable</Source>

預設值：	不適用
外觀狀態：	必填
類型：	字串

使用須知

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

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

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

如要進一步瞭解基礎資料存放區，請參閱快取內部機制。

關於快取加密

Apigee 和 Apigee Hybrid (1.4 以上版本)：快取和 KVM 資料一律會加密。

錯誤代碼

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

執行階段錯誤

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

錯誤代碼	HTTP 狀態	發生時機
`policies.populatecache.EntryCannotBeCached`	`500`	無法快取項目。快取的訊息物件並非可序列化的類別例項。

部署錯誤

部署含有這項政策的 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>

PopulateCache 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

元素參考資料

<PopulateCache> 屬性

<DisplayName> 元素

<CacheKey> 元素

<CacheResource> 元素

<CacheKey> 元素

屬性

<CacheKey>/<Prefix> 元素

<ExpirySettings> 元素

<ExpirySettings> 的子元素

<Scope> 元素

可接受的值

<Source> 元素

使用須知

關於快取加密

錯誤代碼

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

PopulateCache 政策

`<ExpirySettings>` 的子元素