سیاست LookupCache

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

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

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

برای ذخیره پاسخ‌های منابع backend، به سیاست ذخیره پاسخ (Response Cache) مراجعه کنید.

مرجع عنصر

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

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

پیش‌فرض:

۳۰

حضور:

 اختیاری

نوع:

عدد صحیح

عنصر <CacheResource>

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

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

<CacheResource>cache_to_use</CacheResource>

پیش‌فرض:

ناموجود

حضور:

 اختیاری

نوع:

رشته

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

عنصر <CacheKey>/<KeyFragment>

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

<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> مقدار کلید cache را برای ورودی‌های نوشته شده در cache به ابتدای آن اضافه می‌کند. مقدار عنصر <Prefix> مقدار عنصر <Scope> را لغو می‌کند.

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

عنصر <scope>

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

<Scope>scope_enumeration</Scope>

پیش‌فرض:

«اختصاصی»

حضور:

 اختیاری

نوع:

رشته

تنظیم <Scope> یک کلید کش تعیین می‌کند که مطابق با مقدار <Scope> اضافه می‌شود. برای مثال، اگر دامنه روی Exclusive تنظیم شده باشد، یک کلید کش به شکل زیر خواهد بود: orgName__envName__ application Name__proxy|TargetName__ [ serializedCacheKey ].

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

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

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

Global

کلید کش (cache key) بین تمام پروکسی‌های API مستقر در محیط به اشتراک گذاشته می‌شود. کلید کش به شکل orgName __ envName __ اضافه می‌شود.

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

Application

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

کلید حافظه پنهان به شکل orgName__envName__ application Name اضافه شده است.

Proxy

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

کلید حافظه پنهان به شکل orgName__envName__ application Name__proxyEndpointName اضافه شده است.

Target

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

کلید حافظه پنهان به شکل orgName__envName__ application Name__targetEndpointName به ابتدای آن اضافه شده است.

Exclusive

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

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

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

کلید حافظه پنهان به شکل orgName__envName__ application Name__proxyNameITargetName اضافه شده است.

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

apifactory__test__weatherapi__16__default__apiAccessToken
 .

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

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

ذخیره‌سازی عمومی با استفاده از سیاست Populate Cache ، سیاست 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