מדיניות ResponseCache

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

הוא שומר במטמון נתונים ממשאב בקצה העורפי, וכך מצמצם את מספר הבקשות למשאב. כשאפליקציות שולחות בקשות לאותו URI, אפשר להשתמש במדיניות הזו כדי להחזיר תשובות שמאוחסנות במטמון במקום להעביר את הבקשות האלה לשרת העורפי. המדיניות ResponseCache יכולה לשפר את הביצועים של ה-API באמצעות הפחתה של זמן האחזור ותעבורת הרשת.

סביר להניח שהשימוש ב-ResponseCache יהיה הכי יעיל כשנתוני ה-Backend שמשמשים את ה-API מתעדכנים רק מעת לעת. לדוגמה, נניח שיש לכם API שחושף נתונים של דוח מזג אוויר שמתעדכנים רק כל עשר דקות. באמצעות ResponseCache להחזרת תגובות שנשמרו במטמון בין רענונים, אפשר להקטין את מספר הבקשות שמגיעות לקצה העורפי. בנוסף, היא מצמצמת את מספר הקפיצות ברשת.

לשמירת נתונים במטמון לטווח קצר למטרות כלליות, כדאי להשתמש במדיניות Populate 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">

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

&lt;DisplayName&gt; רכיב

צריך להשתמש בנוסף למאפיין name כדי להוסיף תווית למדיניות עורך proxy של ממשק משתמש לניהול עם שם אחר בשפה טבעית.

<DisplayName>Policy Display Name</DisplayName>

אלמנט <CacheKey>

הגדרת מצביע ייחודי לחלק מנתונים שמאוחסנים במטמון.

גודל מפתחות המטמון מוגבל ל-2KB.

<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 נשמרות במטמון כברירת מחדל.

מגדירים את הרכיב הזה לערך true אם לא רוצים לשמור במטמון תגובות של יעד עם קודי סטטוס של שגיאת HTTP. רק תגובות עם קודי סטטוס מ-200 עד 205 יישמרו במטמון אם הערך של הרכיב הזה הוא true. אלה קודי המצב היחידים של HTTP ש-Edge סופר כקודי 'הצלחה', ואי אפשר לשנות את השיוך הזה.

בפוסט הזה בקהילה יש דיון על דפוסי מטמון של תשובות שבהם הרכיב הזה שימושי.

הערה: בגרסה עתידית (שעדיין לא נקבעה), הגדרת ברירת המחדל של הרכיב הזה תשתנה ל-true. פרטים נוספים זמינים בהערות המוצר של 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> element

מציין את התאריך שבו רשומה במטמון אמורה לפוג. משתמשים בטופס 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 לשעה 14: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>

הערה: צריך לציין ערך ברירת מחדל של זמן קצוב לתפוגה, שישמש אם לא יתקבל ערך מההפניה אל 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>

הפונקציה מגדירה ביטוי שאם הערך שלו הוא True בזמן הריצה, מציין שצריך לדלג על חיפוש במטמון ולרענן את המטמון. אפשר גם לצפות בסרטון הזה על השימוש ב-SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

בדוגמה הבאה, אם המשתנה bypass-cache מוגדר כ-true בכותרת נכנסת, חיפוש במטמון מדלג על המטמון והמטמון מתרענן.

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

אלמנט <SkipCachePopulation>

הגדרה של ביטוי שאם הערך שלו הוא true בזמן הריצה, מציין שצריך לדלג על כתיבה למטמון. אפשר לצפות גם בסרטון הזה על השימוש ב-SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

לדוגמה, הפעולות הבאות ידלגו על כתיבת המטמון אם קוד סטטוס התגובה היה 400 או גבוה יותר:

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

רכיב <UseAcceptHeader>

הערך true גורם להוספת ערכים מכותרות Accept של התגובה למפתח המטמון של רשומה במטמון התגובות.

כשמחשבים את מפתח המטמון, משתמשים בכותרות הבקשה Accept, Accept-Encoding, Accept-Language ו-Accept-Charset. הגישה הזו מונעת מלקוח לקבל סוג מדיה שהוא לא ביקש.

לדוגמה, נניח שמתקבלות שתי בקשות מאותה כתובת URL, כאשר הבקשה הראשונה מקבלת gzip והשנייה לא. הבקשה הראשונה תישמר במטמון, והרשומה שנשמרה במטמון תהיה (כנראה) תגובה דחוסה ב-gzip. הבקשה השנייה תקרא את הערך שנשמר במטמון, ואז עשויה להחזיר רשומה בפורמט gzip ללקוח שלא יכול לקרוא gzip.

מידע נוסף מופיע במאמר הגדרת מפתח מטמון.

<UseAcceptHeader>false</UseAcceptHeader>

רכיב <UseResponseCacheHeaders>

הערך true גורם להתייחסות לכותרות של תגובות HTTP כשמגדירים את אורך החיים (TTL) של התגובה במטמון. אם הערך הוא true,‏ Edge מתייחס לערכים של כותרות התגובה הבאות ומשווה את הערכים לאלה שהוגדרו על ידי <ExpirySettings> כשמגדירים את משך החיים (TTL):

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

פרטים נוספים זמינים במאמר בנושא הגדרת תפוגה של רשומות במטמון.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

הערות שימוש

הגודל המקסימלי של כל אובייקט שנשמר במטמון הוא 256KB. (מידע מפורט על אופן העיבוד של המטמון ב-Edge זמין במאמר Cache internals).

באמצעות הגדרה במדיניות ResponseCache, אפשר לגרום ל-Edge לכלול כותרות של תגובות HTTP בהגדרת תפוגה של רשומת מטמון ומפתחות מטמון. בקטע הזה מוסבר איך להשתמש במדיניות עם כותרות כדי לנהל את תפוגת המטמון ואת מפתחות המטמון.

מידע נוסף על האופן שבו Edge מטפל בכותרות של תגובות באמצעות מדיניות ResponseCache זמין במאמר תמיכה בכותרות של תגובות HTTP.

הגדרת תפוגה של רשומה במטמון

בדומה למדיניות Populate Cache, אפשר להגדיר את אורך החיים (TTL) של רשומה במטמון התגובות באמצעות הרכיב <ExpirySettings>. במדיניות ResponseCache, אפשר גם להגדיר ש-Edge יתייחס לכותרות של תגובות כשהן קיימות.

כדי להשתמש בכותרות תגובה, מגדירים את ערך הרכיב <UseResponseCacheHeaders> ל-true. ההגדרה הזו גורמת ל-Edge להתייחס לכותרות התגובה, להשוות אותן לערך שהוגדר על ידי <ExpirySettings>, ואז להשתמש בערך הנמוך מבין השניים. כשמביאים בחשבון את כותרות התגובה, Edge בוחר את הערך שזמין כמו שמתואר בהמשך:

לדוגמה, נניח שתגובה נשמרת במטמון עם הערכים הבאים:

• אין ערך Cache-Control s-maxage
• ערך Cache-Control max-age של 300
• תאריך Expires בעוד שלושה ימים
• ערך של <ExpirySettings> TimeoutInSeconds הוא 600.

במקרה הזה, הערך של Cache-Control max-age ישמש כ-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. מידע נוסף על משתני Flow זמין במאמר חומר עזר בנושא משתנים.

קודי שגיאה

בקטע הזה מתוארות הודעות השגיאה ומשתני הזרימה שמוגדרים כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם מפתחים כללים לתקלה בשרת proxy. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.

קידומת קוד שגיאה

לא רלוונטי

שגיאות בזמן ריצה

המדיניות הזו לא גורמת לשגיאות זמן ריצה.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

משתני שבר

לא רלוונטי

דוגמה לשגיאה

לא רלוונטי

סכימה

כל סוג מדיניות מוגדר על ידי סכימת XML ‏ (.xsd). סכימות מדיניות זמינות ב-GitHub.