המדיניות של LookupCache

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

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

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

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

הפניה לרכיב

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

<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> כדי להוסיף למדיניות בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם בשפה טבעית אחרת.

לא רלוונטי נדרש
continueOnError

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

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

false אופציונלי
enabled

צריך להגדיר את הערך true כדי לאכוף את המדיניות.

צריך להגדיר את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

true אופציונלי
async

המאפיין הזה הוצא משימוש.

false הוצא משימוש

רכיב <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל

לא רלוונטי

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

נוכחות אופציונלי
תיאור מחרוזת

הרכיב <assignTo>

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

<AssignTo>variable_to_receive_cached_value</AssignTo>

ברירת מחדל:

לא רלוונטי

נוכחות:

נדרש

סוג:

מחרוזת

רכיב <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>30</CacheLookupTimeoutInSeconds>

ברירת מחדל:

30

נוכחות:

אופציונלי

סוג:

מספר שלם

הרכיב<CacheResource>

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

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

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

רכיב <היקף>

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

<Scope>scope_enumeration</Scope>

ברירת מחדל:

'בלעדי'

נוכחות:

אופציונלי

סוג:

מחרוזת

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

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

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

ערכים קבילים

Global

מפתח המטמון משותף לכל שרתי ה-proxy של API שפרוסים בסביבה. מפתח המטמון מצורף מראש בצורה orgName __ envName __.

אם מגדירים רשומת <CacheKey> עם apiAccessToken <KeyFragment> והיקף <Global>, כל רשומה נשמרת כ-orgName__envName__apiAccessToken, ואחריה מופיע הערך הסידורי של אסימון הגישה. עבור שרת proxy של API שנפרס בסביבה שנקראת 'test' בארגון שנקרא 'apifactory', אסימוני הגישה יאוחסנו במפתח המטמון הבא: apifactory__test__apiAccessToken.

Application

שם ה-proxy של ה-API משמש כקידומת.

מפתח המטמון מצורף בהתחלה בצורה orgName__envName__applicationName.

Proxy

תצורת ProxyEndpoint משמשת כקידומת.

מפתח המטמון מצורף מראש בצורה orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName .

Target

תצורת TargetEndpoint משמשת כקידומת.

הוספנו מראש את מפתח המטמון בצורה הבאה: orgName__envName__applicationName__deployedRevisionNumber__targetEndpointName .

Exclusive

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

הקידומת היא אחת משתי צורות:

  • אם המדיניות מצורפת לתהליך ProxyEndpoint, הקידומת היא ApiProxyName_ProxyEndpointName.
  • אם המדיניות מצורפת ב-TargetEndpoint, הקידומת היא ApiProxyName_TargetName.

הוספנו מראש את מפתח המטמון לטופס orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName

לדוגמה, המחרוזת המלאה עשויה להיראות כך:

apifactory__test__weatherapi__16__default__apiAccessToken
.

הערות על שימוש

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

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

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

משתני זרימה

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

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

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

קודי שגיאה

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

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

לא רלוונטי

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

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

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

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

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

משתני שבר

לא רלוונטי

דוגמה לשגיאה

לא רלוונטי