מדיניות LookupCache

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

המדיניות LookupCache מגדירה איך לאחזר ערכים ששמורים במטמון בזמן הריצה.

המדיניות הזו מיועדת לשימוש במטמון לטווח קצר למטרות כלליות. היא משמשת בשילוב עם המדיניות PopulateCache (לכתיבת רשומות) ועם המדיניות InvalidateCache (לביטול רשומות).

המדיניות הזו היא מדיניות ניתנת להרחבה, והשימוש בה עשוי להשפיע על העלויות או על ניצול המשאבים, בהתאם לרישיון Apigee שלכם. מידע על סוגי המדיניות וההשלכות של השימוש בהם זמין במאמר סוגי מדיניות.

למידע על שמירת תשובות של משאבי קצה עורפי במטמון, אפשר לעיין במאמר בנושא ResponseCache policy.

הפניה לרכיב

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

<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>` כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
`continueOnError`	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
`async`	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל

ברירת מחדל	לא רלוונטי אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין `name` של המדיניות.
נוכחות	אופציונלי
סוג	String

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין name של המדיניות.

נוכחות אופציונלי

סוג String

אלמנט <AssignTo>

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

<AssignTo>variable_to_receive_cached_value</AssignTo>

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	String

אלמנט <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>12</CacheLookupTimeoutInSeconds>

ברירת מחדל:	12
נוכחות:	אופציונלי
סוג:	מספר שלם

אלמנט <CacheResource>

מציין את המטמון שבו יש לאחסן את ההודעות.

אם המדיניות הזו (והמדיניות התואמת PopulateCache ו-InvalidateCache) משתמשת במטמון המשותף הכלול, צריך להשמיט את הרכיב הזה לחלוטין.

<CacheResource>cache_to_use</CacheResource>

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

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

אלמנט <CacheKey>/<KeyFragment>

מציין ערך שצריך לכלול במפתח המטמון. מציינים משתנה לביטול ההפניה באמצעות המאפיין ref, או ערך קבוע.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	לא רלוונטי

בזמן הריצה, Apigee יוצר את מפתח המטמון על ידי הוספת הערך שמתקבל מהרכיב <Scope> או מהרכיב <Prefix>, לשרשור של הערכים שפוענחו של כל אחד מהרכיבים <KeyFragment>. מידע נוסף זמין במאמר בנושא עבודה עם מפתחות מטמון.

מאפיינים

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

אלמנט <CacheKey>/<Prefix>

מציינת ערך לשימוש כקידומת של מפתח מטמון.

<Prefix>prefix_string</Prefix>

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

רכיב <Prefix> מבטל את ההגדרה של כל רכיב <Scope>.

אלמנט <Scope>

ספירה שמשמשת ליצירת תחילית למפתח מטמון כשלא מספקים רכיב <Prefix> ברכיב <CacheKey>.

<Scope>scope_enumeration</Scope>

ברירת מחדל:	‫"Exclusive"‏ (בלעדי)
נוכחות:	אופציונלי
סוג:	String

ההגדרה <Scope> קובעת מפתח מטמון שמוסף לפני הערך של <Scope>. לדוגמה, מפתח מטמון יקבל את הפורמט הבא אם ההיקף מוגדר ל-Exclusive: orgName__envName__applicationName__proxy|TargetName__ [ serializedCacheKey ].

אם רכיב <Prefix> מופיע ב-<CacheKey>, הוא מחליף את הערך של רכיב <Scope>. הערכים החוקיים כוללים את הערכים המפורטים בהמשך.

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

ערכים קבילים

`Global`	מפתח המטמון משותף לכל שרתי ה-API proxy שנפרסו בסביבה. מפתח המטמון מתווסף בתחילת השורה בפורמט orgName __ envName __. אם מגדירים רשומה של `<CacheKey>` עם `<KeyFragment>` apiAccessToken ועם `<Global>` scope, כל רשומה מאוחסנת כ-`orgName__envName__apiAccessToken`, ואחריה הערך הסדרתי של אסימון הגישה. לדוגמה, אם יש proxy ל-API שפריסתו בוצעה בסביבה בשם test בארגון בשם apifactory, טוקני הגישה יאוחסנו במפתח המטמון הבא: `apifactory__test__apiAccessToken`.
`Application`	שם ה-proxy ל-API משמש כקידומת. מפתח המטמון מופיע בתחילת השורה בפורמט orgName__envName__applicationName.
`Proxy`	ההגדרה ProxyEndpoint משמשת כקידומת. מפתח המטמון מתווסף בתחילת השם בפורמט orgName__envName__applicationName__proxyEndpointName .
`Target`	ההגדרה TargetEndpoint משמשת כקידומת. מפתח המטמון מופיע בתחילת השורה בפורמט הבא: orgName__envName__applicationName__targetEndpointName .
`Exclusive`	ברירת מחדל. זהו הערך הספציפי ביותר, ולכן הסיכון להתנגשויות במרחב השמות במטמון נתון הוא מינימלי. התחילית יכולה להיות אחת משתי צורות: אם המדיניות מצורפת לתהליך `ProxyEndpoint`, הקידומת היא בפורמט ApiProxyName_ProxyEndpointName. אם המדיניות מצורפת ב-`TargetEndpoint`, הקידומת היא מהצורה ApiProxyName_TargetName. מפתח המטמון מופיע בתחילת השורה בפורמט orgName__envName__applicationName__proxyNameITargetName לדוגמה, המחרוזת המלאה יכולה להיראות כך: apifactory__test__weatherapi__default__apiAccessToken .

הערות שימוש

משתמשים במדיניות הזו לשמירה במטמון למטרות כלליות. בזמן הריצה, מדיניות LookupCache מאחזרת ערך מהמטמון ומקצה את הערך למשתנה שצוין באמצעות הרכיב AssignTo (אם לא מאוחזר ערך, המשתנה לא יוגדר). היא מחפשת את הערך על סמך מפתח מטמון שנוצר באמצעות הגדרה שמשלבת את הרכיבים CacheKey ו-Scope. במילים אחרות, כדי לאחזר ערך מסוים שנוסף למטמון על ידי מדיניות PopulateCache, צריך להגדיר את הרכיבים שקשורים למפתח המטמון במדיניות LookupCache באותו אופן כמו במדיניות PopulateCache.

שמירת נתונים במטמון לשימוש כללי באמצעות המדיניות PopulateCache,‏ המדיניות LookupCache והמדיניות InvalidateCache משתמשת במטמון שאתם מגדירים או במטמון משותף שכלול כברירת מחדל. ברוב המקרים, המטמון המשותף הבסיסי אמור לענות על הצרכים שלכם. כדי להשתמש במטמון שמוגדר כברירת מחדל, פשוט משמיטים את הרכיב <CacheResource>.

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

משתני Flow

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

אחרי שמתאימים אישית את ההתנהגות של מטמון שהוגדר במדיניות LookupCache, המשתנים המוגדרים מראש הבאים של Flow זמינים:

משתנים	סוג	הרשאה	תיאור
lookupcache.{policy-name}.cachename	String	קריאה בלבד	מחזירה את שם המטמון שמשמש במדיניות.
lookupcache.{policy-name}.cachekey	String	קריאה בלבד	הפונקציה מחזירה את המפתח שבו נעשה שימוש.
lookupcache.{policy-name}.cachehit	בוליאני	קריאה בלבד	הערך True אם המדיניות מצאה ערך למפתח המטמון שצוין.
lookupcache.{policy-name}.assignto	String	קריאה בלבד	הפונקציה מחזירה את המשתנה שהמטמון הוקצה לו.

קודי שגיאה

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

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

לא רלוונטי

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

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

שגיאות פריסה

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

שם השגיאה	מטרה	תיקון
`InvalidCacheResourceReference`	השגיאה הזו מתרחשת אם הרכיב `<CacheResource>` מוגדר לשם שלא קיים בסביבה שבה מתבצעת הפריסה של ה-proxy ל-API.
`InvalidTimeout`	אם הרכיב `<CacheLookupTimeoutInSeconds>` מוגדר למספר שלילי, פריסת ה-proxy ל-API נכשלת.
`CacheNotFound`	השגיאה הזו מתרחשת אם מטמון ספציפי שמוזכר בהודעת השגיאה לא נוצר ברכיב ספציפי של מעבד ההודעות.

משתני תקלות

לא רלוונטי

דוגמה לתגובת שגיאה

לא רלוונטי

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

הפניה לרכיב

מאפיינים של <LookupCache>

אלמנט <DisplayName>

אלמנט <AssignTo>

אלמנט <CacheKey>

אלמנט <CacheLookupTimeoutInSeconds>

אלמנט <CacheResource>

אלמנט <CacheKey>/<KeyFragment>

מאפיינים

אלמנט <CacheKey>/<Prefix>

אלמנט <Scope>

ערכים קבילים

הערות שימוש

משתני Flow

קודי שגיאה

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

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

שגיאות פריסה

משתני תקלות

דוגמה לתגובת שגיאה

מדיניות LookupCache