سیاست ResponseCache

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

داده‌ها را از یک منبع باطن ذخیره می‌کند و تعداد درخواست‌ها به منبع را کاهش می‌دهد. از آنجایی که برنامه‌ها به یک URI درخواست می‌کنند، می‌توانید از این خط‌مشی برای برگرداندن پاسخ‌های ذخیره‌شده در حافظه پنهان به جای ارسال آن درخواست‌ها به سرور پشتیبان استفاده کنید. خط مشی ResponseCache می تواند عملکرد API شما را از طریق کاهش تاخیر و ترافیک شبکه بهبود بخشد.

هنگامی که داده های Backend مورد استفاده توسط API شما فقط به صورت دوره ای به روز می شوند، احتمالا ResponseCache را بسیار مفید خواهید یافت. به عنوان مثال، تصور کنید یک API دارید که داده های گزارش آب و هوا را تنها هر ده دقیقه یکبار به روز می کند. با استفاده از ResponseCache برای برگرداندن پاسخ‌های ذخیره شده در حافظه پنهان بین بازخوانی‌ها، می‌توانید تعداد درخواست‌هایی را که به پشتیبان می‌رسند کاهش دهید. این همچنین تعداد پرش های شبکه را کاهش می دهد.

برای ذخیره‌سازی پنهان کوتاه‌مدت با هدف کلی، استفاده از خط‌مشی Populate Cache را در نظر بگیرید. این خط‌مشی همراه با خط‌مشی Lookup Cache (برای خواندن ورودی‌های حافظه پنهان) و خط‌مشی Invalidate Cache (برای باطل کردن ورودی‌ها) استفاده می‌شود.

نمونه ها

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

مرجع عنصر

مرجع عنصر عناصر و ویژگی های خط مشی را توصیف می کند.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

ویژگی های <ResponseCache>

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

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

عنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

عنصر <CacheKey>

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

اندازه کلیدهای کش به 2 کیلوبایت محدود شده است.

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

<CacheKey> نام هر قطعه از داده های ذخیره شده در حافظه پنهان را می سازد. کلید اغلب با استفاده از مقداری از سرصفحه های موجودیت یا پارامترهای پرس و جو تنظیم می شود. در این موارد، شما باید ویژگی ref عنصر را مشخص کنید که حاوی مقدار کلید است.

در زمان اجرا، مقادیر <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>

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

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

عنصر <CacheResource>

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

عنصر <ExcludeErrorResponse>

در حال حاضر، به‌طور پیش‌فرض، این خط‌مشی پاسخ‌های HTTP را با هر کد وضعیت ممکن ذخیره می‌کند. این بدان معناست که هر دو پاسخ موفقیت و خطا در حافظه پنهان هستند. به عنوان مثال، پاسخ هایی با کدهای وضعیت 2xx و 3xx به طور پیش فرض ذخیره می شوند.

اگر نمی‌خواهید پاسخ‌های هدف را با کدهای وضعیت خطای HTTP ذخیره کنید، این عنصر را روی true تنظیم کنید. اگر این عنصر درست باشد، فقط پاسخ هایی با کدهای وضعیت از 200 تا 205 در حافظه پنهان ذخیره می شوند. اینها تنها کدهای وضعیت HTTP هستند که Edge آنها را به عنوان کدهای "موفقیت" به حساب می آورد و شما نمی توانید این ارتباط را تغییر دهید.

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

توجه: در نسخه بعدی (که مشخص می شود)، تنظیمات پیش فرض این عنصر به درست تغییر می کند. برای جزئیات بیشتر به یادداشت‌های انتشار Apigee مراجعه کنید.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

عنصر <ExpirySettings>

مشخص می کند که یک ورودی حافظه پنهان چه زمانی باید منقضی شود. در صورت وجود، <TimeoutInSeconds> هر دو <TimeOfDay> و <ExpiryDate> را لغو می کند.

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

عنصر <ExpirySettings> /<ExpiryDate>

تاریخ انقضای ورودی حافظه پنهان را مشخص می کند. از فرم mm-dd-yyyy استفاده کنید. در صورت وجود، خواهر و برادر این عنصر، <TimeoutInSeconds> ، <ExpiryDate> را لغو می کند.

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

ویژگی های

<ExpiryDate ref="" />

عنصر <ExpirySettings>/<TimeOfDay>

زمانی از روز که در آن ورودی حافظه پنهان باید منقضی شود. از فرم hh:mm:ss استفاده کنید. در صورت وجود، خواهر و برادر این عنصر، <TimeoutInSeconds> ، <TimeOfDay> را لغو می کند.

زمان روز را در قالب HH:mm:ss وارد کنید، جایی که HH نشان دهنده ساعت در ساعت 24 ساعته است. به عنوان مثال، 14:30:00 تا 2:30 بعد از ظهر.

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

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

ویژگی های

عنصر <ExpirySettings>/<TimeoutInSec>

تعداد ثانیه هایی که پس از آن یک ورودی کش باید منقضی شود.

عنصر <ExpirySettings>/<TimeoutInSeconds>

تعداد ثانیه هایی که پس از آن یک ورودی کش باید منقضی شود. در صورت وجود، این عنصر بر برادران خود، <TimeOfDay> و <ExpiryDate> لغو می شود.

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

توجه: در صورتی که ref مقداری از duration_variable دریافت نکرد، یک مقدار زمان پیش‌فرض برای استفاده ارائه کنید.

ویژگی های

عنصر <Scope>

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

<Scope>scope_enumeration</Scope>

تنظیم <Scope> یک کلید حافظه پنهان را تعیین می کند که با توجه به مقدار <Scope> از قبل اضافه می شود. برای مثال، هنگامی که دامنه روی Exclusive تنظیم می شود، یک کلید حافظه پنهان به شکل زیر است: orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

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

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

ارزش های قابل قبول

apifactory__test__weatherapi__16__default__apiAccessToken

عنصر <SkipCacheLookup>

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

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

از مثال زیر، اگر متغیر bypass-cache در یک هدر ورودی روی true تنظیم شود، جستجوی حافظه پنهان حذف شده و حافظه نهان تازه‌سازی می‌شود.

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

عنصر <SkipCachePopulation>

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

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

به عنوان مثال، اگر کد وضعیت پاسخ 400 یا بالاتر باشد، موارد زیر از نوشتن حافظه پنهان صرفنظر می کنند:

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

عنصر <UseAcceptHeader>

روی true تنظیم کنید تا کلید حافظه پنهان ورودی پاسخ با مقادیری از هدرهای پاسخ اضافه شود.

Edge هنگام محاسبه کلید حافظه پنهان از سرصفحه‌های Accept ، Accept-Encoding ، Accept-Language و Accept-Charset استفاده می‌کند. این رویکرد باعث می‌شود مشتری نتواند نوع رسانه‌ای را که درخواست نکرده است دریافت کند.

به عنوان مثال، در نظر بگیرید که آیا دو درخواست از یک URL وارد می شوند، که در آن درخواست اول gzip را می پذیرد و دومی نمی پذیرد. اولین درخواست ذخیره خواهد شد و ورودی ذخیره شده (احتمالاً) یک پاسخ gzip خواهد بود. درخواست دوم مقدار ذخیره شده را می خواند و ممکن است یک ورودی gzip را به کلاینتی که قادر به خواندن gzip نیست بازگرداند.

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

<UseAcceptHeader>false</UseAcceptHeader>

عنصر <UseResponseCacheHeaders>

برای در نظر گرفتن هدرهای پاسخ HTTP هنگام تنظیم «زمان زنده بودن» (TTL) پاسخ در حافظه پنهان، روی true تنظیم کنید. وقتی این درست باشد، Edge مقادیر سرصفحه‌های پاسخ زیر را در نظر می‌گیرد و مقادیر را با مقادیر تنظیم شده توسط <ExpirySettings> هنگام تنظیم زمان برای زندگی مقایسه می‌کند:

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

برای جزئیات بیشتر به تنظیم انقضای ورودی حافظه پنهان مراجعه کنید.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

نکات استفاده

حداکثر اندازه برای هر شی ذخیره شده 512 کیلوبایت است. (برای اطلاعات دقیق در مورد نحوه پردازش حافظه پنهان توسط Edge، به بخش داخلی کش مراجعه کنید.)

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

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

تنظیم انقضای ورودی حافظه پنهان

همانند خط‌مشی Populate Cache ، می‌توانید با استفاده از عنصر <ExpirySettings> انقضای ورودی حافظه پنهان پاسخ (زمان زنده شدن آن) را تنظیم کنید. در خط‌مشی ResponseCache، می‌توانید زمانی که Edge سرصفحه‌های پاسخ را در نظر می‌گیرد، در نظر بگیرید.

برای استفاده از هدرهای پاسخ، مقدار عنصر <UseResponseCacheHeaders> را روی true تنظیم می کنید. این تنظیم باعث می شود Edge سرصفحه های پاسخ را در نظر بگیرد، آنها را با مقدار تنظیم شده توسط <ExpirySettings> مقایسه کند، سپس از کمترین مقدار بین این دو استفاده کند. هنگام در نظر گرفتن هدرهای پاسخ، Edge مقدار موجود را همانطور که در زیر توضیح داده شده است انتخاب می کند:

به عنوان مثال، تصور کنید یک پاسخ با مقادیر زیر ذخیره شده است:

• مقدار Cache-Control s-maxage وجود ندارد
• مقدار Cache-Control max-age 300
• تاریخ Expires در سه روز
• مقدار <ExpirySettings> TimeoutInSeconds 600.

در این مورد، مقدار max-age Cache-Control برای TTL استفاده می شود زیرا از مقدار <ExpirySettings> کمتر است و به دلیل اینکه مقدار Cache-Control s-maxage وجود ندارد (که بر max-age اولویت دارد).

پیکربندی یک کلید حافظه پنهان

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

برای اطلاعات کلی در مورد پیکربندی کلیدهای حافظه پنهان، به کار با کلیدهای حافظه پنهان مراجعه کنید. برای اطلاعات در مورد استفاده از هدرهای Accept، به <UseAcceptHeader> مراجعه کنید.

درباره رمزگذاری کش

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

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

متغیرهای Flow از پیش تعریف شده زیر هنگام اجرای یک خط مشی ResponseCache پر می شوند. برای اطلاعات بیشتر در مورد متغیرهای جریان، به مرجع متغیرها مراجعه کنید.

کدهای خطا

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

پیشوند کد خطا

N/A

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

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

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

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

متغیرهای خطا

N/A

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

N/A

طرحواره

هر نوع خط مشی توسط یک طرح XML ( .xsd ) تعریف می شود. برای مرجع، طرح‌های خط‌مشی در GitHub در دسترس هستند.