خط‌مشی LookupCache

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

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

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

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

مرجع عنصر

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

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <CacheLookupTimeoutInSeconds/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

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

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

ویژگی‌های <LookupCache>

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

صفت توضیحات پیش فرض حضور
name

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

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

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

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

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

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

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

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

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

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

عنصر <DisplayName>

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

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

N/A

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

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

عنصر <AssignTo>

متغیری را مشخص می‌کند که ورودی حافظه نهان پس‌از بازیابی از حافظه نهان به آن اختصاص داده می‌شود. متغیر باید نوشتنی باشد. اگر جستجوی حافظه نهان مقداری را بازیابی نکند، متغیر تنظیم نخواهد شد.

<AssignTo>variable_to_receive_cached_value</AssignTo>

پیش‌فرض:

موجود نیست

حضور:

 الزامی

نوع:

رشته

عنصر <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> استفاده می‌کنید. برای اطلاعات بیشتر، کار با کلیدهای حافظه نهان را ببینید.

عنصر <CacheLookupTimeoutInSeconds>

تعداد ثانیه‌هایی را مشخص می‌کند که پس‌از آن جستجوی ناموفق حافظه نهان به‌عنوان عدم وجود در حافظه نهان درنظر گرفته می‌شود. اگر این اتفاق بیفتد، جریان در مسیر عدم وجود در حافظه نهان ازسر گرفته می‌شود.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

پیش‌فرض:

30

حضور:

 اختیاری

نوع:

عدد صحیح

عنصر <CacheResource>

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

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

<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> استفاده می‌کنید. برای اطلاعات بیشتر، کار با کلیدهای حافظه نهان را ببینید.

عنصر <Scope>

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

<Scope>scope_enumeration</Scope>

پیش‌فرض:

«انحصاری»

حضور:

 اختیاری

نوع:

رشته

تنظیم <Scope> کلید حافظه نهانی را تعیین می‌کند که براساس مقدار <Scope> به آن اضافه می‌شود. برای مثال، کلید حافظه نهان وقتی که محدوده روی Exclusive تنظیم شده باشد، شکل زیر را خواهد داشت: orgName__envName__applicationName__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__applicationName پیش‌رونوشت می‌شود.
Proxy

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

کلید حافظه نهان در قالب orgName__envName__applicationName__proxyEndpointName به‌کار می‌رود.
Target

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

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

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

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

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

کلید حافظه نهان در فرم پیش‌افزوده شده است orgName__envName__applicationName__proxyNameITargetName

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

apifactory__test__weatherapi__16__default__apiAccessToken
.

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

از این خط‌مشی برای ذخیره کردن در حافظه نهان با هدف کلی استفاده کنید. در زمان اجرا، خط‌مشی LookupCache مقداری را از حافظه نهان بازیابی می‌کند و آن مقدار را به متغیری که با عنصر AssignTo مشخص کرده‌اید اختصاص می‌دهد (اگر مقداری بازیابی نشود، متغیر تنظیم نخواهد شد). این ویژگی براساس کلید حافظه نهانی که ازطریق پیکربندی ایجاد شده است و عناصر CacheKey و Scope را ترکیب می‌کند، مقدار را جستجو می‌کند. به‌عبارت دیگر، برای بازیابی مقدار خاصی که توسط خط‌مشی PopulateCache به حافظه نهان اضافه شده است، خط‌مشی LookupCache شما باید عناصر مربوط به کلید حافظه نهان را به همان روش خط‌مشی PopulateCache پیکربندی کند.

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

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

متغیرهای جریان

از متغیرهای جریان می‌توان برای پیکربندی رفتار زمان اجرای پویا برای خط‌مشی‌ها و جریان‌ها براساس سرایندهای HTTP یا محتوای پیام، یا زمینه دردسترس در «جریان» استفاده کرد. برای اطلاعات بیشتر درباره متغیرهای جاری، به مرجع متغیرها مراجعه کنید.

متغیرهای «جریان» ازپیش‌تعریف‌شده زیر پس‌از سفارشی‌سازی رفتار حافظه نهانه‌ای که در خط‌مشی LookupCache تعریف می‌کنید دردسترس هستند.

متغیر نوع اجازه شرح
lookupcache.{policy-name}.cachename رشته فقط خواندنی نام حافظه نهان استفاده‌شده در خط‌مشی را برمی‌گرداند.
lookupcache.{policy-name}.cachekey رشته فقط خواندنی کلید استفاده‌شده را برمی‌گرداند.
lookupcache.{policy-name}.cachehit بولی فقط خواندنی اگر خط‌مشی مقداری برای کلید حافظه نهان مشخص‌شده پیدا کند درست است.
lookupcache.{policy-name}.assignto رشته فقط خواندنی متغیری را که حافظه نهان به آن اختصاص داده شده است برمی‌گرداند.

کدهای خطا

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

پیشوند کد خطا

N/A

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

این سیاست هیچ گونه خطای زمان اجرا ایجاد نمی کند.

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

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

نام خطا علت ثابت
InvalidCacheResourceReference اگر عنصر <CacheResource> روی نامی تنظیم شود که در محیطی که پراکسی API در آن مستقر می شود وجود نداشته باشد، این خطا رخ می دهد.
InvalidTimeout اگر عنصر <CacheLookupTimeoutInSeconds> روی یک عدد منفی تنظیم شود، آنگاه استقرار پراکسی API با شکست مواجه می شود.
CacheNotFound این خطا در صورتی رخ می دهد که حافظه پنهان ذکر شده در پیام خطا روی یک جزء خاص Message Processor ایجاد نشده باشد.

متغیرهای خطا

N/A

نمونه پاسخ خطا

N/A