המדיניות בנושא תגובות במטמון

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

סביר להניח ש-ResponseCache יהיה השימושי ביותר כאשר נתוני הקצה העורפי שמשמשים את ה-API שלך יתעדכנו רק מדי פעם. לדוגמה, נניח שיש לך 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 כדי להוסיף תווית למדיניות עורך 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> רכיב

מציינת את התאריך שבו יפוג תוקף רשומת מטמון. משתמשים בטופס 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> רכיב

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

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

מהדוגמה הבאה, אם המשתנה override-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 כדי שמפתח המטמון של רשומת מטמון התגובות יצורף לערכים מ- 'אישור'.

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

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

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

<UseAcceptHeader>false</UseAcceptHeader>

<UseResponseCacheHeaders> רכיב

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

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

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

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

הערות שימוש

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

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

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

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

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

כדי להשתמש בכותרות תגובה, צריך להגדיר את ערך הרכיב <UseResponseCacheHeaders> כ- נכון. ההגדרה הזו גורמת ל-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).

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

בדומה למדיניות מטמון לשימוש כללי, כמו המדיניות בנושא אכלוס המטמון, וגם מטמון התגובה שבו אתם משתמשים ברכיבים <CacheKey> ו-<Scope> להגדיר יצירת מפתחות מטמון לרשומות של המטמון. עם ResponseCache ניתן גם ליצור מפתחות מטמון באמצעות הוספת כותרות 'אישור' לערכי המפתח, להיות בעלי משמעות רבה יותר.

למידע כללי על הגדרת מפתחות מטמון, ראו עבודה עם מפתחות מטמון. עבור למידע על השימוש בכותרות, ראו <UseAcceptHeader>.

מידע על הצפנת המטמון

שוליים לענן ציבורי: המטמון מוצפן רק ב- PCI– וגם HIPAA ארגונים. ההצפנה של הארגונים האלה מוגדרת במהלך הארגון הקצאה.

משתני זרימה

משתני ה-flow המוגדרים מראש הבאים מאוכלסים כשמתבצעת מדיניות ResponseCache. מידע נוסף על משתני זרימה זמין במאמר הפניית משתנים.

קודי שגיאה

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

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

לא רלוונטי

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

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

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

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

משתני שבר

לא רלוונטי

דוגמה לשגיאה

לא רלוונטי

סכימה

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