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

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

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

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

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

שיטות

(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 שבו מאוחסנים נתוני המטמון. משאבי מטמון משמשים לשיפור ההקצאה של הזיכרון ולפרמטרים אחרים של המטמון. אם לא מציינים משאב, המערכת תשתמש במשאב ברירת המחדל. אם המשאב של המטמון לא קיים, ה-method יקפיץ הודעת שגיאה.

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

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

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

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

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

  • defaultTtl: מציין את משך הזמן המוגדר כברירת מחדל להזנה של רשומת מטמון, בשניות. אם לא מציינים ערך, המערכת תשתמש בערך ברירת המחדל של 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: (חובה) מחרוזת, מאגר נתונים זמני או אובייקט שמייצגים את הנתונים לשמירה במטמון. כל סוג נתונים אחר יוביל לשגיאה. מטעמי נוחות, האובייקטים יומרו למחרוזת באמצעות '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
});

get

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

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

פרמטרים:

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

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

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

    • error – אובייקט שגיאה. אם תהיה שגיאה במהלך האחזור מהמטמון, יוגדר כאן אובייקט 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
});

remove

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

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

פרמטרים:

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

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

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

דוגמה:

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