מדיניות 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>
    <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> בהגדרת המדיניות הזו.

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

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

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

מאפיין תיאור ברירת מחדל נוכחות
name

השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

 לא רלוונטי חובה
continueOnError

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

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

 FALSE אופציונלי
enabled

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

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

 TRUE אופציונלי
async

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

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

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

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין 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>.

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

אלמנט <Scope>

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

<Scope>scope_enumeration</Scope>

ברירת מחדל:

‫"Exclusive"‏ (בלעדי)

נוכחות:

 אופציונלי

סוג:

String

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

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

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

ערכים קבילים

Global

מפתח המטמון משותף לכל שרתי ה-API הפרוקסי שנפרסו בסביבה. מפתח המטמון מתווסף בתחילת השורה בפורמט orgName __ envName __.

אם מגדירים רשומה <CacheKey> עם <KeyFragment> apiAccessToken ועם היקף <Global>, כל רשומה מאוחסנת כ-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>.

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

משתנים בתהליך

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

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

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

קודי שגיאה

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

N/A

Runtime errors

This policy does not throw any runtime errors.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidCacheResourceReference This error occurs if the <CacheResource> element is set to a name which does not exist in the environment where the API proxy is being deployed.
InvalidTimeout If the <CacheLookupTimeoutInSeconds> element is set to a negative number, then the deployment of the API proxy fails.
CacheNotFound This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component.

Fault variables

N/A

Example error response

N/A