גישה למטמון ב-Node.js

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

אפשר להשתמש במודול apigee-access כדי לגשת למטמון המבוזר של Edge מתוך אפליקציית Node.js. המודול כולל שיטות לקבלת מטמון ולהוספה, קבלת והסרה של נתונים.

המטמון המבוזר של Apigee Edge מאפשר לכם לאחסן מחרוזות או נתונים אחרים. בדומה לרוב מטמוני הנתונים, זהו מטמון נתונים מסוג least-recently-used (LRU) עם גודל מקסימלי. ב-Apigee Edge, המטמון מפוזר בין כל הצמתים שבהם אפליקציית Node.js פועלת. אפשר לנהל את המטמון באמצעות Apigee Edge API. באמצעות ה-API, אפשר ליצור משאבי מטמון באופן ידני, או להשתמש במשאב ברירת המחדל. במאמר כלי התמדה ב-Edge מופיע מבוא בנושא שמירת נתונים במטמון ב-Apigee Edge. מידע נוסף על מטמון מבוזר אפשר למצוא במאמר דוגמה: שמירה במטמון למטרות כלליות.

מידע נוסף על מודול apigee-access ועל התכונות האחרות שלו זמין במאמר שימוש במודול apigee-access.

Methods

‫(1) getCache

var cache = apigee.getCache(cacheName);

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

פרמטרים:

‫cacheName – מחרוזת, השם של המטמון. (לא השם של משאב המטמון).

החזרות:

אובייקט מטמון.

דוגמה:

var apigee = require('apigee-access');
var cache = apigee.getCache('cache');

‫(2) getCache

var customCache = apigee.getCache(cacheName, options );

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

פרמטרים:

‫cacheName – מחרוזת, השם של המטמון המותאם אישית. (לא השם של משאב המטמון)

‫options – אובייקט הגדרה. האובייקט יכול להיות ריק, או שהוא יכול להכיל את הפרמטרים האופציונליים הבאים:

  • ‫resource: השם של 'משאב מטמון' ב-Apigee שבו מאוחסנים נתוני המטמון. משאבי המטמון משמשים לכוונון עדין של הקצאת הזיכרון ופרמטרים אחרים של המטמון. אם לא מציינים משאב, המערכת תשתמש במשאב ברירת המחדל. אם משאב המטמון לא קיים, השיטה מעלה שגיאה.

  • ‫scope: מציין אם רשומות במטמון מקבלות קידומת כדי למנוע התנגשויות. הערכים התקפים הם global,‏ application ו-exclusive.

    • ‫global: כל רשומות המטמון יכולות להיות גלויות לכל האפליקציות של Node.js באותו 'סביבה' של Apigee.

    • ‫application: כל הרשומות במטמון יכולות להיות גלויות לכל המטמונים של Node.js שמהווים חלק מאותה אפליקציית Apigee Edge.

    • ‫exclusive: (ברירת מחדל) רשומות במטמון נראות רק במטמון של Node.js באותה אפליקציה עם אותו שם. זוהי אפשרות ברירת המחדל.

  • ‫prefix: אם שם מפתח המטמון כולל תוספת לשם, כמו שמתואר במאמרים איכלוס מדיניות המטמון ועבודה עם מפתחות מטמון, צריך להשתמש בפרמטר הזה כדי לציין אותה. ‫Edge מוסיף אוטומטית סיומת של קו תחתון כפול לשם הקידומת. לכן, אם נוצר מפתח מטמון עם הקידומת UserToken, הקידומת שצריך לציין כאן היא UserToken__.

  • ‫defaultTtl: מציין את אורך החיים (TTL) המוגדר כברירת מחדל של רשומה במטמון, בשניות. אם לא מציינים ערך, המערכת משתמשת בערך ברירת המחדל של TTL במשאב המטמון.

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

החזרות:

אובייקט מטמון מותאם אישית.

דוגמה:

var apigee = require('apigee-access');
var customCache = apigee.getCache('doesNotMatter',
  { resource: 'MyCustomResource', scope: 'global', prefix: 'UserToken'} );
customCache.put("myCacheKey", "xyz");

התכונה הזו פועלת עם מדיניות LookupCache שהוגדרה כך:

<LookupCache name="Lookup-Cache-1">
  <CacheKey>
    <Prefix>UserToken</prefix>    
    <KeyFragment>myCacheKey</KeyFragment>
  </CacheKey>
  <CacheResource>MyCustomResource</CacheResource>
  <Scope>Global</Scope>
  <AssignTo>contextVariable</AssignTo>
</LookupCache>

put

cache.put('key', data, ttl, function(error));

הכנסת נתונים למטמון.

פרמטרים:

  • ‫key: (חובה) מחרוזת שמזהה באופן ייחודי את הפריט במטמון. גודל מפתחות המטמון מוגבל ל-2KB.

  • ‫data: (חובה) מחרוזת, Buffer או אובייקט שמייצגים את הנתונים שצריך לשמור במטמון. כל סוג נתונים אחר יגרום לשגיאה. לנוחותכם, האובייקטים יומרו למחרוזת באמצעות JSON.stringify.

  • ‫ttl: (אופציונלי) משך הזמן המקסימלי לשמירת הנתונים במטמון, בשניות. אם לא מציינים ערך, המערכת משתמשת בערך ברירת המחדל של TTL.

  • ‫callback: (אופציונלי) אם מציינים פונקציה, היא תופעל ברגע שהנתונים יישמרו במטמון. הפונקציה הזו תופעל עם אובייקט Error בתור הפרמטר הראשון אם יש שגיאת הוספה, אחרת היא תופעל ללא פרמטרים.

דוגמה:

var apigee = require('apigee-access');
var cache = apigee.getCache();
// Insert a string into cache using the default TTL
cache.put('key1', 'Buenos dias, Mundo!');
// Insert a string into cache using a TTL of 120 seconds
cache.put('key2', 'Hello, World!', 120);
// Insert a string with the default TTL, and get notified when the insert is complete
cache.put('key3', 'Ciao, Mondo!', function(error) {
  // "error" will be falsy unless there was an error on insert
});
// Insert a string with a TTL of 600 seconds, and get notified when the insert is complete
cache.put('key4', 'Hallo Wereld!', 600, function(error) {
  // "error" will be falsy unless there was an error on insert
});

מקבלים

cache.get('key', function(error, data));

אחזור נתונים ממטמון.

פרמטרים:

  • ‫key (חובה): מחרוזת שמזהה באופן ייחודי את הפריט במטמון.

    כדי לאחזר רשומות במטמון שהוכנסו למטמון ממדיניות של Apigee Edge (כמו Populate Cache policy), צריך ליצור את מפתח המטמון על סמך הדרך הספציפית שבה המדיניות יוצרת מפתחות לרשומות. כדי לעשות את זה, צריך לדעת איך המדיניות מוגדרת. במאמר בנושא עבודה עם מפתחות מטמון מוסבר איך כללי מדיניות יוצרים מפתחות מטמון. עם זאת, חשוב לזכור שאסור לציין ערכי מחרוזת שקשורים להיקף. בקריאות מ-Node.js, ההיקף כבר כלול בהקשר.

  • ‫callback (נדרש): פונקציה שתופעל כשהנתונים יהיו זמינים. אם יש נתונים במטמון, הם מוחזרים בפרמטר השני.

    • ‫error – אובייקט שגיאה. אם יש שגיאה במהלך האחזור מהמטמון, יוגדר כאן אובייקט שגיאה. אחרת, הפרמטר הזה יוגדר כ-undefined.

    • ‫data – הנתונים שאוחזרו, אם יש כאלה. הערך יהיה אחד מארבעת הערכים הבאים:

      • אם הוכנסה מחרוזת, הפונקציה תחזיר מחרוזת.
      • אם הוכנס באפר, הוא יהיה באפר.
      • אם הוכנס אובייקט, הוא יהיה מחרוזת שמכילה את גרסת ה-JSON של האובייקט כפי שהופקה על ידי JSON.stringify.
      • אם לא נמצאו נתונים, הערך יהיה undefined.

דוגמה:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.get('key', function(error, data) {
  // If there was an error, then "error" will be set.
  // If error is falsy, "data" is the item that was retrieved:
  //   - undefined, in the case of cache miss, or
  //   - a Buffer, or
  //   - a String
});

הסרה

cache.remove('key', function(error));

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

פרמטרים:

  • ‫key (חובה): מחרוזת שמזהה באופן ייחודי את הפריט במטמון שצריך לבטל את התוקף שלו.

    כדי לאחזר רשומות במטמון שהוכנסו למטמון ממדיניות של Apigee Edge (כמו Populate Cache policy), צריך ליצור את מפתח המטמון על סמך הדרך הספציפית שבה המדיניות יוצרת מפתחות לרשומות. כדי לעשות את זה, צריך לדעת איך המדיניות מוגדרת. במאמר בנושא עבודה עם מפתחות מטמון מוסבר איך כללי מדיניות יוצרים מפתחות מטמון. חשוב לזכור שאסור לציין ערכי מחרוזת שקשורים להיקף. בקריאות מ-Node.js, ההיקף כבר כלול בהקשר.

  • ‫callback (חובה): פונקציית קריאה חוזרת שתופעל עם אובייקט Error כפרמטר הראשון אם יש שגיאה.

דוגמה:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.remove('key', function(error) {
});