פיתוח יישומי פלאגין מותאמים אישית

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

Edge Microgateway v. 3.3.x

קהל

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

מהו פלאגין Edge Microgateway בהתאמה אישית?

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

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

איפה מציבים קוד פלאגין מותאם אישית

תיקייה עבור יישומי פלאגין מותאמים אישית כלולה בהתקנת Edge Microgateway כאן:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

כאשר [prefix] היא ספריית התחילית npm כפי שמתואר בקטע 'היכן מותקן Edge Microgateway' במאמר התקנת Edge Microgateway.

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

בדיקת יישומי הפלאגין שהוגדרו מראש

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

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

כאשר [prefix] היא ספריית התחילית npm. למידע נוסף, ראו "היכן מותקן Edge Microgateway" במאמר Installing Edge Microgateway.

לפרטים נוספים, אפשר לקרוא את המאמר בנושא יישומי פלאגין מוגדרים מראש שסופקו עם Edge Microgateway.

כתיבת פלאגין פשוט

בקטע הזה נפרט את השלבים הנדרשים ליצירת פלאגין פשוט. הפלאגין הזה מבטל את נתוני התגובה (לא משנה מהם) באמצעות המחרוזת "Hello, World!" ומדפיס אותה בטרמינל.

  1. אם Edge Microgateway פועל, צריך להפסיק אותו עכשיו:
    edgemicro stop
    
  2. cd לספריית יישומי הפלאגין המותאמים אישית:

    cd [prefix]/lib/node_modules/edgemicro/plugins

    כאשר [prefix] היא ספריית התחילית npm כפי שמתואר בקטע 'היכן מותקן Edge Microgateway' במאמר התקנת Edge Microgateway.

  3. יוצרים פרויקט פלאגין חדש בשם response-override ו-cd לפרויקט:
    mkdir response-override && cd response-override
    
  4. יוצרים פרויקט חדש ב-Node.js:
    npm init
    
    לוחצים על מקש Return כמה פעמים כדי לאשר את ברירות המחדל.
  5. יש להשתמש בעורך טקסט כדי ליצור קובץ חדש בשם index.js.
  6. מעתיקים את הקוד הבא אל index.js ושומרים את הקובץ.
    'use strict';
    var debug = require('debug')
    
    module.exports.init = function(config, logger, stats) {
    
      return {
       
        ondata_response: function(req, res, data, next) {
          debug('***** plugin ondata_response');
          next(null, null);
        },
        
        onend_response: function(req, res, data, next) {
          debug('***** plugin onend_response');
          next(null, "Hello, World!\n\n");
        }
      };
    }
    
  7. עכשיו יצרתם פלאגין וצריך להוסיף אותו לתצורה של Edge Microgateway. פותחים את הקובץ $HOME/.edgemicro/[org]-[env]-config.yaml, כאשר org ו-env הם שמות הארגון והסביבה ב-Edge.
  8. מוסיפים את הפלאגין response-override לרכיב plugins:sequence כפי שמוצג בהמשך.
          ...
          
          plugins:
            dir: ../plugins
            sequence:
              - oauth
              - response-override
              
          ...
    
  9. מפעילים מחדש את Edge Microgateway.
  10. קריאה ל-API דרך Edge Microgateway. (קריאת ה-API הזו מבוססת על ההנחה שהגדרת את אותה הגדרה כמו זו של המדריך עם אבטחת מפתחות API, כפי שמתואר בהגדרה והגדרה של Edge Microgateway:
    curl -H 'x-api-key: uAM4gBSb6YoMvTHfx5lXJizYIpr5Jd' http://localhost:8000/hello/echo
    Hello, World!
    

המבנה של פלאגין

הפלאגין לדוגמה של Edge Microgateway מדגים את הדפוס שצריך לבצע במהלך פיתוח יישומי פלאגין משלכם. קוד המקור של הפלאגין לדוגמה שנדון בקטע הזה נמצא ב-plugins/header-uppercase/index.js.

  • יישומי פלאגין הם מודולים רגילים של NPM עם package.json ו-index.js בתיקיית השורש.
  • פלאגין חייב לייצא פונקציית init().
  • הפונקציה init() מקבלת שלושה ארגומנטים: init(), init() ו-init(). הארגומנטים האלה מתוארים בארגומנטים של פונקציות init().
  • הפונקציה init() מחזירה אובייקט עם רכיבי handler של פונקציות בעלות שם, שמופעלים כשאירועים מסוימים מתרחשים במהלך משך החיים של בקשה.

הפונקציות של הגורם המטפל באירועים

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

בקשת מטפלים באירועי זרימה

הפונקציות האלה מופעלות לפי בקשות ב-Edge Microgateway.

  • onrequest
  • ondata_request
  • onend_request
  • onclose_request
  • onerror_request

onrequest פונקציה

מופעלת בתחילת בקשת הלקוח. הפונקציה הזו מופעלת כשהבייט הראשון של הבקשה מתקבל על ידי Edge Microgateway. הפונקציה הזו נותנת גישה לכותרות של הבקשות, לכתובת ה-URL, לפרמטרים של השאילתה ולשיטת ה-HTTP. אם תפעיל את הפקודה הבאה עם ארגומנט ראשון מהימן (כמו מופע של שגיאה), עיבוד הבקשה יופסק ולא תופעל בקשת יעד.

דוגמה:

onrequest: function(req, res, next) {
      debug('plugin onrequest');
      req.headers['x-foo-request-start'] = Date.now();
      next();
    }

ondata_request פונקציה

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

דוגמה:

ondata_request: function(req, res, data, next) {
      debug('plugin ondata_request ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    }

onend_request פונקציה

התקשרות לאחר שכל נתוני הבקשה התקבלו מהלקוח.

דוגמה:

onend_request: function(req, res, data, next) {
      debug('plugin onend_request');
      next(null, data);
    }

הפונקציה onclose_request

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

דוגמה:

onclose_request: function(req, res, next) {
      debug('plugin onclose_request');
      next();
    }

הפונקציה onerror_request

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

דוגמה:

onerror_request: function(req, res, err, next) {
      debug('plugin onerror_request ' + err);
      next();
    }

גורמים מטפלים באירועים של זרימת תגובה

הפונקציות האלה מופעלות באירועי תגובה ב-Edge Microgateway.

  • onresponse
  • ondata_response
  • onend_response
  • onclose_response
  • onerror_response

הפונקציה onresponse

מופעלת בתחילת תגובת היעד. הפונקציה הזו מופעלת כשהבייט הראשון של התגובה מתקבל על ידי Edge Microgateway. הפונקציה הזו נותנת גישה לכותרות של התגובות ולקוד הסטטוס.

דוגמה:

onresponse: function(req, res, next) {      
    debug('plugin onresponse');     
    res.setHeader('x-foo-response-time', Date.now() - req.headers['x-foo-request-start'])    
    next();    
}


הפונקציה ondata_response

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

דוגמה:

ondata_response: function(req, res, data, next) {
      debug('plugin ondata_response ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    }


הפונקציה onend_response

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

דוגמה:

onend_response: function(req, res, data, next) {
      debug('plugin onend_response');
      next(null, data);
    }

הפונקציה onclose_response

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

דוגמה:

onclose_response: function(req, res, next) {
      debug('plugin onclose_response');
      next();
    }


הפונקציה onerror_response

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

דוגמה:

onerror_response: function(req, res, err, next) {
      debug('plugin onerror_response ' + err);
      next();
    }

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

הפונקציות של הגורם המטפל באירועי פלאגין מופעלות בתגובה לאירועים ספציפיים שמתרחשים, בזמן ש-Edge Microgateway מעבד בקשת API נתונה.

  • כל הגורמים המטפלים בפונקציות init() (init(), init() וכו') חייבים להפעיל את הקריאה החוזרת (callback) init() בסיום העיבוד. אם לא קוראים ל-next(), העיבוד יופסק והבקשה תיתקע.
  • הארגומנט הראשון של next() עשוי להיות שגיאה שתגרום לסיום עיבוד הבקשות.
  • רכיבי ה-handler של ondata_ ו-onend_ צריכים לקרוא ל-next() עם ארגומנט שני שמכיל את הנתונים שיועברו ליעד או ללקוח. הארגומנט הזה יכול להיות null אם הפלאגין נמצא בתהליך אגירת נתונים ואין לו מספיק נתונים כדי לבצע שינוי כרגע.
  • הערה: מופע אחד של הפלאגין משמש לטיפול בכל הבקשות והתגובות. אם פלאגין רוצה לשמור את המצב לפי בקשה בין קריאות, הוא יכול לשמור את המצב הזה בנכס שנוסף לאובייקט הבקשה (req) שסופק, שמשך החיים שלו הוא משך הזמן של הקריאה ל-API.
  • הקפידו לזהות את כל השגיאות ולהפעיל את הקריאה next() עם השגיאה. אם הקריאה ל-next() לא תתבצע, הפעולה תגרום להשעיה של הקריאה ל-API.
  • חשוב להיזהר שלא ליצור דליפות זיכרון, מכיוון שהדבר עלול להשפיע על הביצועים הכוללים של Edge Microgateway ולגרום לו לקרוס אם אין בו מספיק זיכרון.
  • חשוב להקפיד לפעול לפי המודל Node.js ולא לבצע משימות אינטנסיביות מבחינת המחשוב ב-thread הראשי, כי פעולה כזו עלולה לפגוע בביצועים של Edge Microgateway.

מידע על הפונקציה init() של הפלאגין

בקטע הזה מתוארים הארגומנטים שמועברים לפונקציה init(): init(), init() ו-init().

config

נתוני ההגדרה שמתקבלים ממיזוג של קובץ התצורה של Edge Microgateway עם הנתונים שהורדו מ-Apigee Edge ממוקמים באובייקט בשם: config.

כדי להוסיף פרמטר תצורה שנקרא param עם הערך foo לפלאגין בשם response-override, צריך להוסיף אותו בקובץ default.yaml:

response-override:
    param: foo

לאחר מכן, תוכלו לגשת לפרמטר בקוד הפלאגין, באופן הבא:

// Called when response data is received
    ondata_response: function(req, res, data, next) {
      debug('***** plugin ondata_response');
      debug('***** plugin ondata_response: config.param: ' + config.param);
      next(null, data);
    },

במקרה כזה, תראו את הכיתוב foo מודפס בפלט של ניפוי הבאגים של הפלאגין:

Sun, 13 Dec 2015 21:25:08 GMT plugin:response-override ***** plugin ondata_response: config.param: foo

אפשר לגשת לתצורת המיקרו-שער שמוזגו ולנתוני Apigee Edge שהורדתם באובייקט הצאצא config.emgConfigs. לדוגמה, אפשר לגשת לנתוני ההגדרה האלה בפונקציה init באופן הבא:

module.exports.init = function(config, logger, stats) {
   let emgconfigs = config.emgConfigs;

למטה מוצגת דוגמה לנתונים ש-emgConfigs מכילים:

{
    edgemicro:
    {
        port: 8000,
        max_connections: 1000,
        config_change_poll_interval: 600,
        logging:
        {
            level: 'error',
            dir: '/var/tmp',
            stats_log_interval: 60,
            rotate_interval: 24,
            stack_trace: false
        },
        plugins: { sequence: [Array] },
        global: { org: 'Your Org', env: 'test' }
    },
    headers:
    {
        'x-forwarded-for': true,
        'x-forwarded-host': true,
        'x-request-id': true,
        'x-response-time': true,
        via: true
    },
    proxies:
    [    {
                max_connections: 1000,
                name: 'edgemicro_delayed',
                revision: '1',
                proxy_name: 'default',
                base_path: '/edgemicro_delayed',
                target_name: 'default',
                url: 'https://httpbin.org/delay/10',
                timeout: 0
            }
    ],
    product_to_proxy: { EdgeMicroTestProduct: [ 'edgemicro-auth','edgemicro_delayed',] },
    product_to_scopes: {prod4: [ 'Admin', 'Guest', 'Student' ] },
    product_to_api_resource: { EdgeMicroTestProduct: [ '/*' ] },
    _hash: 0,
    keys: { key: 'Your key', secret: 'Your key ' },
    uid: 'Internally generated uuid',
    targets: []
  }

logger

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

  • info(object, message)
  • warn(object, message)
  • error(object, message)
  • trace(object, message)
  • debug(object, message)

נתונים סטטיסטיים

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

  • treqErrors - מספר בקשות היעד עם שגיאות.
  • treqErrors - מספר תגובות היעד עם שגיאות.
  • statusCodes – אובייקט שמכיל ספירות של קודי תגובה:
{
  1: number of target responses with 1xx response codes
  2: number of target responses with 2xx response codes
  3: number of target responses with 3xx response codes
  4: number of target responses with 4xx response codes
  5: number of target responses with 5xx response codes
  }
  
  • requests - המספר הכולל של בקשות.
  • תגובות - מספר התשובות הכולל.
  • חיבורים – מספר החיבורים הפעילים לטירגוט.

מידע על הפונקציה next()

כל שיטות הפלאגין חייבות להפעיל את next() כדי להמשיך לעבד את השיטה הבאה בסדרה (אחרת תהליך הפלאגין ייתקע). במחזור החיים של הבקשה, השיטה הראשונה נקראת onrequest() . השיטה הבאה שתתבצע קריאה היא השיטה ondata_request(). עם זאת, תתבצע קריאה ל-ondata_request רק אם הבקשה כוללת נתונים, כמו במקרה של בקשת POST. השיטה הבאה שנקראה היא onend_request(), והיא מופעלת בסיום עיבוד הבקשה. הפונקציות של onerror_* מופעלות רק במקרה של שגיאה, והן מאפשרות לטפל בשגיאות באמצעות קוד בהתאמה אישית, אם רוצים.

נניח שנשלחו נתונים בבקשה ומתבצעת קריאה ל-ondata_request(). שימו לב שהפונקציה מפעילה את next() עם שני פרמטרים:

next(null, data);

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

הפרמטר השני מעביר את נתוני הבקשה לפונקציה הבאה בשרשרת. אם לא מבצעים עיבוד נוסף, נתוני הבקשה מועברים ללא שינוי ליעד של ה-API. עם זאת, יש לך אפשרות לשנות את נתוני הבקשה בשיטה הזו, ולהעביר את הבקשה ששונתה ליעד. לדוגמה, אם נתוני הבקשה הם XML והיעד מצפה ל-JSON, תוכל להוסיף קוד ל-method ondata_request() אשר (א) משנה את Content-Type של כותרת הבקשה ל-application/json וממיר את נתוני הבקשה ל-JSON בכל אמצעי רצוי (לדוגמה, ניתן להשתמש בממיר של Node.js xml2json שמתקבל מ-NPM).

בואו נראה איך זה נראה:

ondata_request: function(req, res, data, next) {
  debug('****** plugin ondata_request');
  var translated_data = parser.toJson(data);
  next(null, translated_data);
},

במקרה הזה, נתוני הבקשה (שנקבעים כ-XML) עוברים המרה ל-JSON, והנתונים שמשתנים מועברים באמצעות next() לפונקציה הבאה בשרשרת הבקשות, לפני שהם מועברים ליעד הקצה העורפי.

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

ondata_request: function(req, res, data, next) {
  debug('****** plugin ondata_request');
  var translated_data = parser.toJson(data);
  debug('****** plugin ondata_response: translated_json: ' + translated_json);
  next(null, translated_data);
},

מידע על הזמנת הביצוע של ה-handler של יישומי הפלאגין

אם כותבים יישומי פלאגין ל-Edge Microgateway, צריך להבין את הסדר שבו מופעלים הגורמים המטפלים באירועים של הפלאגין.

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

הדוגמה הבאה עוזרת להבין את רצף הביצוע.

1. יצירת שלושה יישומי פלאגין פשוטים

כדאי לשקול שימוש בפלאגין הבא. כל מה שהיא עושה הוא להדפיס פלט של המסוף כאשר הגורמים המטפלים באירועים שלו נקראים:

יישומי פלאגין/פלאגין 1/index.js

module.exports.init = function(config, logger, stats) {

  return {

    onrequest: function(req, res, next) {
      console.log('plugin-1: onrequest');
      next();
    },

    onend_request: function(req, res, data, next) {
      console.log('plugin-1: onend_request');
      next(null, data);
    },

    ondata_response: function(req, res, data, next) {
      console.log('plugin-1: ondata_response ' + data.length);
      next(null, data);
    },

    onend_response: function(req, res, data, next) {
      console.log('plugin-1: onend_response');
      next(null, data);
    }
  };
}

עכשיו כדאי ליצור שני יישומי פלאגין נוספים, plugin-2 ו-plugin-3, עם אותו קוד (אלא לשנות את ההצהרות של console.log() ל-plugin-2 ו-plugin-3 בהתאמה).

2. בדיקת הקוד של הפלאגין

הפונקציות של הפלאגין שיוצאו ב-<microgateway-root-dir>/plugins/plugin-1/index.js הן רכיבי handler של אירועים שמופעלים בזמנים מסוימים במהלך עיבוד הבקשה והתגובה. לדוגמה, onrequest מריץ את הבייט הראשון של כותרות הבקשה שהתקבלו. בעוד שהפונקציה onend_response מופעלת אחרי קבלת הבייט האחרון של נתוני התגובה.

הביטו ב-handler ondata_response -- המערכת מפעילה אותו בכל פעם שמתקבל מקטע של נתוני תגובה. חשוב לדעת שנתוני התגובות לא בהכרח מתקבלים בבת אחת. במקום זאת, הנתונים עשויים להתקבל במקטעים באורך שרירותי.

3. הוספת יישומי הפלאגין לרצף של יישומי הפלאגין

בהמשך לדוגמה הזו, נוסיף את יישומי הפלאגין לרצף של יישומי הפלאגין בקובץ התצורה של Edge Microgateway (~./edgemicro/config.yaml), באופן הבא. הרצף חשוב. היא מגדירה את הסדר שבו רכיבי ה-handler של יישומי הפלאגין מופעלים.

  plugins:
    dir: ../plugins
    sequence:
      - plugin-1
      - plugin-2
      - plugin-3
  

4. בדיקת הפלט של ניפוי הבאגים

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

  • הרצף של הפלאגין של קובץ התצורה של Edge Microgateway (~./edgemicro/config.yaml) מציין את הסדר שבו מתבצעת קריאה למטפלי האירועים.
  • הגורמים המטפלים בבקשות נקראים בסדר עולה (הסדר שבו הם מופיעים ברצף של יישומי הפלאגין -- 1, 2, 3).
  • הגורמים המטפלים בתגובות מופעלים בסדר יורד – 3, 2, 1.
  • ה-handler של ondata_response מופעל פעם אחת לכל מקטע נתונים שמגיע. בדוגמה הזו (פלט מוצג למטה), מתקבלים שני מקטעים.

הנה דוגמה לפלט של ניפוי באגים שנוצר כששלושת יישומי הפלאגין האלה נמצאים בשימוש, ובקשה נשלחת דרך Edge Microgateway. פשוט שימו לב לסדר שבו ה-handlers נקראים:

  plugin-1: onrequest
  plugin-2: onrequest
  plugin-3: onrequest

  plugin-1: onend_request
  plugin-2: onend_request
  plugin-3: onend_request

  plugin-3: ondata_response 931
  plugin-2: ondata_response 931
  plugin-1: ondata_response 931

  plugin-3: ondata_response 1808
  plugin-3: onend_response

  plugin-2: ondata_response 1808
  plugin-2: onend_response

  plugin-1: ondata_response 1808
  plugin-1: onend_response

סיכום

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

עם זאת, חשוב לזכור שה-handlers של בקשות מופעלים לפי הסדר שבו יישומי הפלאגין מצוינים בקובץ התצורה של Edge Microgateway, ושה-handler של התגובות מופעלים בסדר ההפוך.

מידע על שימוש במשתנים גלובליים ביישומי פלאגין

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

שכתוב של כתובות יעד ביישומי פלאגין

נוסף בגרסה 2.3.3

אפשר לשנות באופן דינמי את כתובת ה-URL של יעד שמוגדרת כברירת מחדל בפלאגין על ידי שינוי המשתנים הבאים בקוד הפלאגין: req.targetHostname ו-req.targetPath.

נוסף בגרסה: v2.4.x

אפשר גם לבטל את יציאת היעד של נקודת הקצה ולבחור בין HTTP ל-HTTPS. משנים את המשתנים הבאים בקוד הפלאגין: req.targetPort ו-req.targetSecure. כדי לבחור ב-HTTPS, מגדירים את req.targetSecure ל-true. עבור HTTP, הגדירו את הערך false. אם מגדירים את req.targetSecure כ-True, כדאי לעיין בשרשור הדיון הזה לקבלת מידע נוסף.

פלאגין לדוגמה בשם eurekaclient נוסף ל-Edge Microgateway. הפלאגין הזה מדגים איך להשתמש במשתנים req.targetPort ו-req.targetSecure, והוא מדגים איך Edge Microgateway יכול לבצע חיפוש דינמי של נקודת קצה באמצעות Eureka כקטלוג של נקודות קצה בשירות.


יישומי פלאגין לדוגמה

יישומי הפלאגין האלה סופקו בהתקנת Edge Microgateway שלך. אפשר למצוא אותם בהתקנת Edge Microgateway כאן:

[prefix]/lib/node_modules/edgemicro/plugins

כאשר [prefix] היא ספריית התחילית npm כפי שמתואר בקטע 'היכן מותקן Edge Microgateway' במאמר התקנת Edge Microgateway.

בקשת צבירה

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

module.exports.init = function(config, logger, stats) {

  function accumulate(req, data) {

    if (!req._chunks) req._chunks = [];
    req._chunks.push(data);

  }

  return {

    ondata_request: function(req, res, data, next) {

      if (data && data.length > 0) accumulate(req, data);

      next(null, null);

    },


    onend_request: function(req, res, data, next) {

      if (data && data.length > 0) accumulate(req, data);

      var content = null;

      if (req._chunks && req._chunks.length) {

        content = Buffer.concat(req._chunks);

      }

      delete req._chunks;

      next(null, content);

    }

  };

}

תגובה מצטברת

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

module.exports.init = function(config, logger, stats) {

  function accumulate(res, data) {
    if (!res._chunks) res._chunks = [];
    res._chunks.push(data);
  }

  return {

    ondata_response: function(req, res, data, next) {
      if (data && data.length > 0) accumulate(res, data);
      next(null, null);
    },

    onend_response: function(req, res, data, next) {
      if (data && data.length > 0) accumulate(res, data);
      var content = Buffer.concat(res._chunks);
      delete res._chunks;
      next(null, content);
    }

  };

}

פלאגין באותיות רישיות בכותרת עליונה

הפצות של Edge Microgateway כוללות פלאגין לדוגמה שנקרא <microgateway-root-dir>/plugins/header-uppercase. הדוגמה כוללת הערות שמתארות את כל רכיבי ה-handler של הפונקציות. בדוגמה הזו מתבצעת טרנספורמציה פשוטה של נתונים בתגובת היעד ומוסיפה כותרות מותאמות אישית לבקשת הלקוח ולתגובת היעד.

זה קוד המקור של <microgateway-root-dir>/plugins/header-uppercase/index.js:

'use strict';

var debug = require('debug')('plugin:header-uppercase');

// required
module.exports.init = function(config, logger, stats) {

  var counter = 0;

  return {

    // indicates start of client request
    // request headers, url, query params, method should be available at this time
    // request processing stops (and a target request is not initiated) if
    // next is called with a truthy first argument (an instance of Error, for example)
    onrequest: function(req, res, next) {
      debug('plugin onrequest');
      req.headers['x-foo-request-id'] = counter++;
      req.headers['x-foo-request-start'] = Date.now();
      next();
    },

    // indicates start of target response
    // response headers and status code should be available at this time
    onresponse: function(req, res, next) {
      debug('plugin onresponse');
      res.setHeader('x-foo-response-id', req.headers['x-foo-request-id']);
      res.setHeader('x-foo-response-time', Date.now() - req.headers['x-foo-request-start']);
      next();
    },

    // chunk of request body data received from client
    // should return (potentially) transformed data for next plugin in chain
    // the returned value from the last plugin in the chain is written to the target
    ondata_request: function(req, res, data, next) {
      debug('plugin ondata_request ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    },

    // chunk of response body data received from target
    // should return (potentially) transformed data for next plugin in chain
    // the returned value from the last plugin in the chain is written to the client
    ondata_response: function(req, res, data, next) {
      debug('plugin ondata_response ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    },

    // indicates end of client request
    onend_request: function(req, res, data, next) {
      debug('plugin onend_request');
      next(null, data);
    },

    // indicates end of target response
    onend_response: function(req, res, data, next) {
      debug('plugin onend_response');
      next(null, data);
    },

    // error receiving client request
    onerror_request: function(req, res, err, next) {
      debug('plugin onerror_request ' + err);
      next();
    },

    // error receiving target response
    onerror_response: function(req, res, err, next) {
      debug('plugin onerror_response ' + err);
      next();
    },

    // indicates client connection closed
    onclose_request: function(req, res, next) {
      debug('plugin onclose_request');
      next();
    },

    // indicates target connection closed
    onclose_response: function(req, res, next) {
      debug('plugin onclose_response');
      next();
    }

  };

}


טרנספורמציה של אותיות רישיות

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

 */
module.exports.init = function(config, logger, stats) {

  // perform content transformation here
  // the result of the transformation must be another Buffer
  function transform(data) {
    return new Buffer(data.toString().toUpperCase());
  }

  return {

    ondata_response: function(req, res, data, next) {
      // transform each chunk as it is received
      next(null, data ? transform(data) : null);
    },

    onend_response: function(req, res, data, next) {
      // transform accumulated data, if any
      next(null, data ? transform(data) : null);
    },

    ondata_request: function(req, res, data, next) {
      // transform each chunk as it is received
      next(null, data ? transform(data) : null);
    },

    onend_request: function(req, res, data, next) {
      // transform accumulated data, if any
      next(null, data ? transform(data) : null);
    }

  };

}