המדיניות PopulateCache

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

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

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

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

המדיניות Populate Cache (אכלוס מטמון) מיועדת לכתיבת רשומות במטמון לשימוש כללי לטווח קצר. היא משמשת בשילוב עם המדיניות Lookup Cache (חיפוש במטמון) (לקריאת רשומות במטמון) ועם המדיניות Invalidate Cache (ביטול תוקף של מטמון) (לביטול תוקף של רשומות).

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

מידע על שמירת תשובות של משאבי backend במטמון זמין במאמר בנושא מדיניות שמירת תשובות במטמון.

הפניה לרכיב

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

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

מאפיינים של התג <PopulateCache>

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

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

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

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

אלמנט <CacheKey>

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

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

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

אלמנט <CacheResource>

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

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

אלמנט <ExpirySettings>

מציין מתי תוקף של רשומה במטמון יפוג.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

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

רכיבי צאצא של <ExpirySettings>

צריך להשתמש בדיוק ברכיב צאצא אחד. בטבלה הבאה מפורטים רכיבי הצאצא של <ExpirySettings>:

רכיב צאצא	תיאור
<TimeoutInSeconds>	מספר השניות שאחריהן תוקף של רשומה במטמון יפוג. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> הרכיב הזה מחליף את הרכיב TimeoutInSec שהוצא משימוש.
<ExpiryDate>	מציין את התאריך שבו רשומה במטמון אמורה לפוג. מציינים מחרוזת בפורמט mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> אם התאריך שצוין הוא תאריך בעבר, המדיניות תחול על הזמן המקסימלי שבו הרשומה במטמון פעילה. התקופה המקסימלית היא 30 ימים.
<TimeOfDay>	מציינים את השעה ביום שבה רשומה במטמון אמורה לפוג. מציינים מחרוזת בפורמט HH:mm:ss, כאשר HH מייצג את השעה בשעון של 24 שעות, באזור הזמן UTC. לדוגמה, 14:30:00 מציין 14:30 בצהריים. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> הערות: מציינים את השעות לפי אזור הזמן האוניברסלי המתואם (UTC). הפורמט של הערך Cache time הוא פורמט התאריך הבינלאומי שמוגדר בתקן הבינלאומי ISO 8601.

צריך לציין רק אחד מרכיבי הצאצא האפשריים. אם מציינים כמה רכיבים, סדר העדיפות הוא:TimeoutInSeconds, ExpiryDate, TimeOfDay.

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

אלמנט <Scope>

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

<Scope>scope_enumeration</Scope>

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

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

orgName__envName__apiProxyName__proxy|TargetName__ [ serializedCacheKey ]

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

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

ערכים קבילים

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

רכיב <Source>

מציין את המשתנה שהערך שלו צריך להיכתב במטמון.

<Source>source_variable</Source>

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

הערות:

• אובייקטים של JSON מאוחסנים באופן בלעדי במטמון בזיכרון (L1).
• אם אתם מתכוונים לשמור במטמון את האובייקטים האלה במטמון קבוע (L2), מומלץ להמיר אותם לפורמט string.
• אם תפעלו לפי השיטה הזו, תוכלו להשתמש ביעילות במטמון L2 ולמקסם את יעילות השמירה במטמון.
• מידע נוסף זמין במאמר בנושא פרטים פנימיים של המטמון.
  

הערות שימוש

משתמשים במדיניות הזו לשמירת נתונים במטמון למטרות כלליות. בזמן הריצה, המדיניות <PopulateCache> כותבת נתונים מהמשתנה שציינתם ברכיב <PopulateCache> למטמון שציינתם ברכיב <CacheResource>.<Source> אפשר להשתמש ברכיבים <CacheKey>,‏ <Scope> ו-<Prefix> כדי לציין מפתח שאפשר להשתמש בו ממדיניות <LookupCache> כדי לאחזר את הערך. משתמשים ברכיב <ExpirySettings> כדי להגדיר מתי הערך שנשמר במטמון יפוג.

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

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

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

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

‫Apigee ו-Apigee Hybrid (גרסה 1.4 ואילך): נתוני מטמון ו-KVM תמיד מוצפנים.

קודי שגיאה

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

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

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד תקלה	סטטוס HTTP	מתרחש כאשר
policies.populatecache.EntryCannotBeCached	500	אי אפשר לשמור רשומה במטמון. אובייקט ההודעה שנשמר במטמון הוא לא מופע של מחלקה שניתנת לסריאליזציה.

שגיאות בהטמעה

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

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

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

משתני תקלות

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

משתנים	כאשר:	דוגמה
fault.name="fault_name"	‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	populatecache.POP-CACHE-1.failed = true

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

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

דוגמה לכלל שגיאה

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>