خط‌مشی ResponseCache

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

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

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

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

نمونه‌ها

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>

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

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

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

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

<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 تنظیم کنید؛ اگر این عنصر درست باشد، فقط پاسخ‌های دارای کدهای وضعیت از ۲۰۰ تا ۲۰۵ ذخیره خواهند شد. این‌ها تنها کدهای وضعیت 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> را ملغی می‌کند.

زمان روز را در قالب س‌س:دد:ث‌ث وارد کنید، که در آن س‌س نشان‌دهنده ساعت در ساعت ۲۴ ساعته است. برای مثال، ۱۴:۳۰:۰۰ برای ساعت ۲:۳۰ بعدازظهر.

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

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

توجه: مقدار مهلت زمانی پیش‌فرضی ارائه دهید تا درصورتی‌که مرجع مقداری از 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>

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

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

عنصر <UseAcceptHeader>

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

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

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

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

<UseAcceptHeader>false</UseAcceptHeader>

عنصر <UseResponseCacheHeaders>

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

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

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

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

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

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

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

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

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

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

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

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

• بدون مقدار Cache-Control s-maxage
• مقدار Cache-Control max-age برابر با ۳۰۰
• تاریخ Expires سه روز دیگر است
• مقدار <ExpirySettings> TimeoutInSeconds برابر با ۶۰۰.

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

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

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

برای اطلاعات کلی درباره پیکربندی کلیدهای حافظه نهان، به کار با کلیدهای حافظه نهان مراجعه کنید. برای اطلاعات درباره استفاده از سرصفحه‌های «پذیرش»، به <UseAcceptHeader> مراجعه کنید.

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

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

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

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

کدهای خطا

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

پیشوند کد خطا

موجود نیست

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

این خط‌مشی هیچ خطای زمان اجرایی ایجاد نمی‌کند.

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

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

متغیرهای خطا

موجود نیست

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

موجود نیست

طرح‌واره

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