Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Populate Cache policy

What

Configures how cached values should be written at runtime.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    レスポンス
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Element reference

The following lists the elements you can configure on this policy.

<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>
        <TimeoutInSec>300</TimeoutInSec>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

<PopulateCache> attributes

The following attributes are common to all policy parent elements.

Attribute 説明 デフォルト Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

該当なし Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

該当なし

If you omit this element, the value of the policy's name attribute is used.

Presence: Optional
Type: 文字列

 

<CacheKey> element

Configures a unique pointer to a piece of data stored in the cache.

Cache keys are limited to a size of 2 KB.

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

Default:

該当なし

Presence:

Required

Type:

該当なし

<CacheKey> constructs the name of each piece of data stored in the cache.

At runtime, <KeyFragment> values are prepended with either the <Scope> element value or <Prefix> value. For example, the following results in a cache key of UserToken__apiAccessToken__<value_of_client_id>:

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

You use the <CacheKey> element in conjunction with <Prefix> and <Scope>. For more information, see Working with cache keys.

<CacheResource> element

Specifies the cache where messages should be stored.

Omit this element completely if this policy (and your corresponding LookupCache and InvalidateCache policies) is using the included shared cache.

<CacheResource>cache_to_use</CacheResource>

Default:

該当なし

Presence:

Optional

Type:

文字列

キャッシュ構成の詳細については、「環境キャッシュの作成と編集」を参照してください。

<ExpirySettings>/<ExpiryDate> element

Specifies the date on which a cache entry should expire. Use the form mm-dd-yyyy.

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

Default:

該当なし

Presence:

Optional

Type:

文字列

属性

Attribute 説明 デフォルト Presence
ref

The variable from which to get the value. Should not be used if this element contains a literal value.

該当なし Optional 文字列

<ExpirySettings> element

Specifies when a cache entry should expire. When present, <TimeoutInSec> overrides both <TimeOfDay> and <ExpiryDate>.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

Default:

該当なし

Presence:

Required

Type:

該当なし

<CacheKey>/<KeyFragment> element

Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.

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

Default:

該当なし

Presence:

Optional

Type:

該当なし

This can be a key (a static name that you provide) or a value (a dynamic entry set by referencing a variable). All specified fragments combined (plus the prefix) are concatenated to create the cache key.

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

You use the <KeyFragment> element in conjunction with <Prefix> and <Scope>. For more information, see Working with cache keys.

属性

Attribute デフォルト Required 説明
ref string  

The variable from which to get the value. Should not be used if this element contains a literal value.

<CacheKey>/<Prefix> element

Specifies a value to use as a cache key prefix.

<Prefix>prefix_string</Prefix>

Default:

該当なし

Presence:

Optional

Type:

文字列

Use this value instead of <Scope> when you want to specify your own value rather than a <Scope> -enumerated value. If defined, <Prefix> prepends the cache key value for entries written to the cache. A <Prefix> element value overrides a <Scope> element value.

You use the <Prefix> element in conjunction with <CacheKey> and <Scope>. For more information, see Working with cache keys.

<Scope> element

Enumeration used to construct a prefix for a cache key when a <Prefix> element is not provided in the <CacheKey> element.

<Scope>scope_enumeration</Scope>

Default:

"Exclusive"

Presence:

Optional

Type:

文字列

The <Scope> setting determines a cache key that is prepended according to the <Scope> value. For example, a cache key would take the following form when scope is set to Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

If a <Prefix> element is present in <CacheKey>, it supercedes a <Scope> element value. Valid values include the enumerations below.

You use the <Scope> element in conjunction with <CacheKey> and <Prefix>. For more information, see Working with cache keys.

Acceptable values

Global

Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the form  orgName __ envName __.

If you define a <CacheKey> entry with the <KeyFragment> apiAccessToken and a <Global> scope, each entry is stored as orgName__envName__apiAccessToken, followed by the serialized value of the access token. For an API proxy deployed in an environment called 'test' in an organization called 'apifactory', access tokens would be stored under the following cache key: apifactory__test__apiAccessToken.

Application

API proxy name is used as the prefix.

Cache key is prepended in the form orgName__envName__apiProxyName.

Proxy

ProxyEndpoint configuration is used as the prefix.

Cache key is prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName .

Target

TargetEndpoint configuration is used as the prefix.

Cache key prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName .

Exclusive

Default. This is the most specific, and therefore presents minimal risk of namespace collisions within a given cache.

Prefix is one of two forms:

  • If the policy is attached to the ProxyEndpoint flow, prefix is of the form ApiProxyName_ProxyEndpointName.
  • If the policy is attached at TargetEndpoint, prefix is of the form ApiProxyName_TargetName.

Cache key prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

For example, the full string might look like this:

apifactory__test__weatherapi__16__default__apiAccessToken

<Source> element

Specifies the variable whose value should be written to the cache.

<Source>source_variable</Source>

Default:

該当なし

Presence:

Required

Type:

文字列

<ExpirySettings>/<TimeOfDay> element

The time of day at which a cache entry should expire. Use the form HH:mm:ss. When present, this element's sibling, <TimeoutInSec>, overrides <TimeOfDay>

各日付の時刻は HH:mm:ss の形式で入力します。HH は 24 時間制の時間を表します。例えば、午後 2:30 は 14:30:00 になります。

For the time of day, the default locale and time zone will vary depending on where the code is running (which isn't knowable when you configure the policy). For information on configuring your locale, see Creating and editing an environment cache.

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Default:

該当なし

Presence:

Optional

Type:

文字列

属性

Attribute 説明 デフォルト Presence
ref Variable with the expiration time value. 該当なし Optional 文字列
 

<ExpirySettings>/<TimeoutInSec> element

The number of seconds after which a cache entry should expire.

<ExpirySettings>
    <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
</ExpirySettings>

Default:

該当なし

Presence:

Optional

Type:

整数

属性

Attribute 説明 デフォルト Presence
ref Variable with the timeout value.
該当なし
Optional 文字列

Usage notes

The maximum size for each cached object is 512 kb. 

Use this policy for general purpose caching. At runtime, the <PopulateCache> policy writes data from the variable you specified in the <Source> element to the cache you specified in the <CacheResource> element. You can use the <CacheKey>, <Scope>, and <Prefix> elements to specify a key that you can use from the <LookupCache> policy to retrieve the value. Use the <ExpirySettings> element to configure when the cached value should expire.

General purpose caching with the PopulateCache policy, LookupCache policy, and InvalidateCache policy uses either a cache you configure or a shared cache that's included by default. In most cases, the underlying shared cache should meet your needs. To use this cache, simply omit the <CacheResource> element.

For more about the underlying data store, see Cache internals. For more about configuring caches, see Creating and editing an environment cache.

Error codes

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

policies.populatecache (What's this?)

Runtime errors

Error name HTTP Status Occurs when
EntryCannotBeCached 500 An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable.

Deployment errors

Error name Occurs when
InvalidCacheResourceReference The cache specified in the <CacheResource> element does not exist.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where
[prefix].[policy_name].failed [prefix]: populatecache
[policy_name]: The name of the policy to check.
populatecache.POP-CACHE-1.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "EntryCannotBeCached"

Example error response

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

Example fault rule

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

Help or comments?