خط‌مشی PopulateCache

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

نحوه نوشتن مقادیر ذخیره‌شده در حافظه نهان در زمان اجرا را پیکربندی می‌کند.

خط‌مشی «پر کردن حافظه نهان» برای نوشتن ورودی‌ها در حافظه نهان کوتاه‌مدت با هدف کلی طراحی شده است. این خط‌مشی همراه با خط‌مشی حافظه نهان «جستجو» (برای خواندن ورودی‌های حافظه نهان) و خط‌مشی «نامعتبر کردن حافظه نهان» (برای نامعتبر کردن ورودی‌ها) استفاده می‌شود.

برای ذخیره کردن پاسخ‌های منابع زیرینه در حافظه نهان، خط‌مشی «حافظه نهان پاسخ» را ببینید.

مرجع عنصر

در زیر، عناصر قابل‌پیکربندی در این خط‌مشی فهرست شده است.

<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 مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

 N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

 نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

 درست است اختیاری
async

این ویژگی منسوخ شده است.

 نادرست منسوخ شده است

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

عنصر <CacheKey>

یک اشاره‌گر یکتا را برای قطعه‌ای از داده‌های ذخیره‌شده در حافظه نهان پیکربندی می‌کند.

کلیدهای حافظه نهان به اندازه ۲ کیلوبایت محدود می‌شوند.

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

از عنصر <CacheKey> همراه با <Prefix> و <Scope> استفاده می‌کنید. برای اطلاعات بیشتر، کار با کلیدهای حافظه نهان را ببینید.

عنصر <CacheResource>

مشخص می‌کند پیام‌ها در کدام حافظه نهان ذخیره شوند.

اگر این خط‌مشی (و خط‌مشی‌های متناظر شما برای LookupCache و InvalidateCache) از حافظه نهان مشترک گنجانده‌شده استفاده می‌کند، این عنصر را به‌طور کامل حذف کنید.

<CacheResource>cache_to_use</CacheResource>

پیش‌فرض:

موجود نیست

حضور:

 اختیاری

نوع:

رشته

برای اطلاعات بیشتر درباره پیکربندی کردن حافظه‌های نهان، به ایجاد و ویرایش حافظه نهان محیط مراجعه کنید.

عنصر <CacheKey>/<KeyFragment>

مقدار مشخصی را که باید در کلید حافظه نهان گنجانده شود مشخص می‌کند و فضای نامی برای مطابقت دادن درخواست‌ها با پاسخ‌های ذخیره‌شده در حافظه نهان ایجاد می‌کند.

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

پیش‌فرض:

موجود نیست

حضور:

 اختیاری

نوع:

موجود نیست

این می‌تواند کلید (نام ثابتی که ارائه می‌کنید) یا مقدار (ورودی پویایی که با ارجاع به متغیر تنظیم می‌شود) باشد. همه تکه‌های مشخص‌شده (به‌علاوه پیشوند) با هم ترکیب می‌شوند تا کلید حافظه نهان ایجاد شود.

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

از عنصر <KeyFragment> همراه با <Prefix> و <Scope> استفاده می‌کنید. برای اطلاعات بیشتر، کار با کلیدهای حافظه نهان را ببینید.

مشخصه‌ها

مشخصه نوع پیش‌فرض الزامی شرح
مرجع رشته نه

متغیری که مقدار از آن گرفته می‌شود. اگر این عنصر حاوی مقدار حرفی است نباید استفاده شود.

عنصر <CacheKey>/<Prefix>

مقدار مشخصی را برای استفاده به‌عنوان پیشوند کلید حافظه نهان تعیین می‌کند.

<Prefix>prefix_string</Prefix>

پیش‌فرض:

موجود نیست

حضور:

 اختیاری

نوع:

رشته

وقتی می‌خواهید مقدار خودتان را به‌جای مقدار شمارشی <Scope> مشخص کنید، از این مقدار به‌جای <Scope> استفاده کنید. اگر تعریف شده باشد، <Prefix> مقدار کلید حافظه نهان را برای ورودی‌های نوشته‌شده در حافظه نهان پیش‌نویس می‌کند. مقدار عنصر <Prefix> مقدار عنصر <Scope> را ملغی می‌کند.

از عنصر <Prefix> همراه با <CacheKey> و <Scope> استفاده می‌کنید. برای اطلاعات بیشتر، کار با کلیدهای حافظه نهان را ببینید.

عنصر <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>

پیش‌فرض:

موجود نیست

حضور:

 الزامی

نوع:

موجود نیست

عناصر فرزند <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>

اگر تاریخ مشخص‌شده در گذشته باشد، خط‌مشی حداکثر زمان زنده بودن را برای ورودی ذخیره‌شده در حافظه نهان اعمال می‌کند. این حداکثر ۳۰ روز است.
<TimeOfDay>

زمان روزی را که ورودی حافظه نهان باید منقضی شود مشخص می‌کند. رشته‌ای را در قالب HH:mm:ss مشخص کنید، که در آن HH نشان‌دهنده ساعت در ساعت ۲۴ ساعته در منطقه زمانی ساعت هماهنگ جهانی است. برای مثال، ۱۴:۳۰:۰۰ یعنی ۲:۳۰ بعدازظهر.

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

فقط یکی از عناصر فرزند ممکن را باید مشخص کنید. اگر چندین عنصر را مشخص کنید، ترتیب ارجحیت این‌گونه است:TimeoutInSeconds، ExpiryDate، TimeOfDay.

با هریک از عناصر فرزند بالا در <ExpirySettings>، اگر مشخصه اختیاری ref را در عنصر فرزند مشخص کنید، خط‌مشی مقدار انقضا را از متغیر زمینه‌ای نام‌گذاری‌شده بازیابی خواهد کرد. اگر متغیر تعریف نشده باشد، خط‌مشی از مقدار نوشتاری عنصر فرزند استفاده می‌کند.

عنصر <Scope>

وقتی عنصر <Prefix> در عنصر <CacheKey> ارائه نشده باشد، از شمارش برای ساختن پیشوندی برای کلید حافظه نهان استفاده می‌شود.

<Scope>scope_enumeration</Scope>

پیش‌فرض:

«انحصاری»

حضور:

 اختیاری

نوع:

رشته

تنظیم <Scope> کلید حافظه نهانی را تعیین می‌کند که براساس مقدار <Scope> به آن اضافه می‌شود. برای مثال، وقتی محدوده روی Exclusive تنظیم شده باشد، کلید حافظه نهان به‌صورت زیر خواهد بود:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

اگر عنصر <Prefix> در <CacheKey> وجود داشته باشد، مقدار عنصر <Scope> را ملغی می‌کند. مقادیر معتبر شامل شمارش‌های زیر است.

از عنصر <Scope> همراه با <CacheKey> و <Prefix> استفاده می‌کنید. برای اطلاعات بیشتر، کار با کلیدهای حافظه نهان را ببینید.

مقادیر قابل‌قبول

Global

کلید حافظه نهان در همه پراکسی‌های API که در محیط مستقر شده‌اند هم‌رسانی می‌شود. کلید حافظه نهان به‌صورت orgName __ envName __ به ابتدای فرم اضافه می‌شود.

اگر ورودی <CacheKey> را با <KeyFragment> apiAccessToken و <Global> محدوده تعریف کنید، هر ورودی به‌صورت orgName__envName__apiAccessToken ذخیره می‌شود و پس‌از آن مقدار سریالی‌شده کلید دسترسی قرار می‌گیرد. برای پراکسی API که در محیطی به‌نام «test» در سازمانی به‌نام «apifactory» مستقر شده است، نشان‌های دسترسی تحت کلید حافظه نهان زیر ذخیره می‌شود: apifactory__test__apiAccessToken.
Application

نام پراکسی API به‌عنوان پیشوند استفاده می‌شود.

کلید حافظه نهان در قالب orgName__envName__apiProxyName پیش‌افزوده می‌شود.
Proxy

پیکربندی ProxyEndpoint به‌عنوان پیشوند استفاده می‌شود.

کلید حافظه نهان به‌صورت orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName به ابتدای نام اضافه می‌شود .
Target

پیکربندی TargetEndpoint به‌عنوان پیشوند استفاده می‌شود.

کلید حافظه نهان در قالب orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName پیش‌افزود می‌شود .
Exclusive

پیش‌فرض. این روش خاص‌ترین روش است و بنابراین کمترین خطر تصادم فضای نام را در یک حافظه نهان معین دارد.

پیشوند یکی از دو شکل زیر است:

  • اگر خط‌مشی به جریان ProxyEndpoint پیوست شده باشد، پیشوند به‌شکل ApiProxyName_ProxyEndpointName است.
  • اگر خط‌مشی در TargetEndpoint پیوست شده باشد، پیشوند به‌صورت ApiProxyName_TargetName است.

کلید حافظه نهان در قالب orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName پیش‌رونوشت می‌شود

برای مثال، رشته کامل ممکن است به این شکل باشد:

apifactory__test__weatherapi__16__default__apiAccessToken
.

عنصر <Source>

متغیری را مشخص می‌کند که مقدار آن باید در حافظه نهان نوشته شود.

<Source>source_variable</Source>

پیش‌فرض:

موجود نیست

حضور:

 الزامی

نوع:

رشته

یادداشت‌های استفاده

از این خط‌مشی برای ذخیره کردن در حافظه نهان با هدف کلی استفاده کنید. در زمان اجرا، خط‌مشی <PopulateCache> داده‌ها را از متغیری که در عنصر <Source> مشخص کرده‌اید در حافظه نهانی که در عنصر <CacheResource> مشخص کرده‌اید می‌نویسد. می‌توانید از عناصر <CacheKey>، <Scope>، و <Prefix> برای مشخص کردن کلیدی که می‌توانید از خط‌مشی <LookupCache> برای بازیابی مقدار استفاده کنید. از عنصر <ExpirySettings> برای پیکربندی زمان انقضای مقدار ذخیره‌شده در حافظه نهان استفاده کنید.

ذخیره‌سازی در حافظه نهان با هدف کلی با خط‌مشی PopulateCache، خط‌مشی LookupCache، و خط‌مشی InvalidateCache از یا حافظه نهانی که پیکربندی می‌کنید یا حافظه نهان مشترکی که به‌طور پیش‌فرض اضافه شده است استفاده می‌کند. در اکثر موارد، حافظه نهان مشترک زیرین باید نیازهای شما را برآورده کند. برای استفاده از این حافظه نهان، کافی است عنصر <CacheResource> را حذف کنید.

محدودیت‌های حافظه نهان: محدودیت‌های مختلف حافظه نهان اعمال می‌شود، مانند اندازه نام و مقدار، تعداد کل حافظه‌های نهان، تعداد عناصر در یک حافظه نهان، و انقضا.

برای اطلاعات بیشتر درباره فروشگاه داده زیربنایی، درون‌مایه‌های حافظه نهان را ببینید. برای اطلاعات بیشتر درباره پیکربندی حافظه‌های نهان، به ایجاد و ویرایش حافظه نهان محیط مراجعه کنید.

درباره رمزگذاری حافظه نهان

Edge for Public Cloud (لبه برای Cloud عمومی): حافظه نهان فقط در سازمان‌های فعال‌شده با PCI- و HIPAA رمزگذاری می‌شود. رمزگذاری برای این سازمان‌ها درطول آماده‌سازی سازمان پیکربندی می‌شود.

کدهای خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطایی را که Edge هنگام راه‌اندازی خطا در این خط‌مشی تنظیم می‌کند شرح می‌دهد. این اطلاعات برای دانستن اینکه آیا قوانین خطا را برای مدیریت خطاها توسعه می‌دهید یا نه مهم است. برای کسب اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانیدو رسیدگی به اشکالات را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای خط‌مشی رخ دهند.

کد خطا وضعیت HTTP وقتی رخ می‌دهد
policies.populatecache.EntryCannotBeCached ۵۰۰ ورودی نمی‌تواند در حافظه نهان ذخیره شود. شیء پیامی که در حافظه نهان ذخیره می‌شود نمونه‌ای از کلاسی نیست که «سریال‌شدنی» باشد.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خط‌مشی را مستقر می‌کنید.

نام خطا علت رفع اشکال
InvalidCacheResourceReference این خطا زمانی رخ می‌دهد که عنصر <CacheResource> در خط‌مشی PopulateCache روی نامی تنظیم شده باشد که در محیطی که پراکسی API در آن مستقر می‌شود وجود ندارد.
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>