עבודה עם מפתחות מטמון

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

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

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

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

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

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

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

PREFIX_PART__FRAGMENT_PART

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

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

שימוש בתג <CacheKey>

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

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

לדוגמה, התצורה הבאה יוצרת ערך של myprefix__hello__world לשימוש במפתח המטמון:

<CacheKey>
    <Prefix>myprefix</Prefix>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

אפשר להגדיר את Apigee כך שישתמש במפתח מטמון שנוצר באופן דינמי על ידי הפניה למשתנה ברכיב <KeyFragment>, כמו בדוגמה הבאה:

<KeyFragment ref="variable_name"/>

לדוגמה, כדי שערך מפתח המטמון ישלב את Content-Type של הודעת הבקשה, מבצעים את הפעולות הבאות:

<KeyFragment ref="request.header.Content-Type"/>

כדאי להביא בחשבון את ההגדרה הבאה:

<CacheKey>
  <Prefix>system1</Prefix>
  <KeyFragment>apiAccessToken</KeyFragment>
  <KeyFragment ref="request.header.Content-Type" />
  <KeyFragment>bar</KeyFragment>
</CacheKey>

אם למשתנה request.header.Content-Type יש את הערך application/json, מפתח המטמון יהיה system1__apiAccessToken__application/json__bar.

אפשר להשתמש במשתנים שהוגדרו על ידי הפלטפורמה או במשתנים מותאמים אישית במאפיין ref.

מפתחות מטמון שנגזרים מפרמטרים של שאילתה

באמצעות משתנים כמו request.queryparam.<queryparam_name> ו-request.querystring, אפשר להגדיר מפתח מטמון כך שהמפתח יכלול חלקים ממחרוזת השאילתה של בקשה. לדוגמה, בכתובת ה-URL הבאה נעשה שימוש בשני פרמטרים של שאילתה – param1 ו-param2 – שאפשר להשתמש בהם במפתח המטמון:

http://myaccount.apigee.net/mydata?param1=value1&param2=value2

אפשר לשלב את הערכים האלה ברכיב <CacheKey> באמצעות הגדרה כמו זו שבהמשך:

<CacheKey>
    <KeyFragment ref="request.queryparam.param1" />
    <KeyFragment ref="request.queryparam.param2" />
<CacheKey>

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

prefix_part__value1__value2

במקום לציין כמה פרמטרים שונים של שאילתה, אפשר להשתמש במשתנה request.querystring, שמכניס את כל מחרוזת הפרמטרים באופן מילולי כחלק ממפתח המטמון. חשוב לזכור ששיטה זו אמנם מתייחסת לכל הפרמטרים, אבל אם סדר הפרמטרים משתנה מבקשה לבקשה, המפתח יהיה שונה. במילים אחרות, param1=value1&param2=value2 ו-param2=value2&param1=value1 לא יוצרים את אותו ערך של מפתח מטמון.

שימוש בתגים <Scope> ו-<Prefix>

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

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

לדוגמה, הערך <Scope> Global – ההיקף הרחב ביותר – מייצג את שם הארגון והסביבה. לכן, אם ה-proxy שלכם פרוס בארגון בשם mycompany ובסביבה בשם prod, הערך שיתווסף בתחילת המחרוזת יהיה:

mycompany__prod__[FRAGMENT_PART]

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

orgName__envName__apiProxyName__deployedRevisionNumber__nameof(proxyEndpoint|targetEndpoint)__[serializedCacheKey]

בהמשך מפורטות כמה דוגמאות. ההנחה היא שהגרסה ה-16 של ה-proxy שנקרא weatherapi נפרסה בארגון שנקרא mycompany ובסביבה שנקראת prod, וששם ה-proxyEndpoint הוא default, ומדיניות ה-cache מצורפת ל-flow ב-proxyEndpoint.

הגדרות אישיות	תוצאה
<Scope>Global</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	mycompany__prod__hello__world.
<Scope>Exclusive</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	mycompany__prod__weatherapi__16__default__hello__world
<Scope>Exclusive</Scope> <CacheKey> <Prefix>system1</Prefix> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	system1__hello__world במקרה הזה, הרכיב <Prefix> מבטל את <Scope>, ולכן מרחב השמות system1 מופיע בתוצאה.