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

אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.

Edge Microgateway v. 3.3.x

Audience

הנושא הזה מיועד למפתחים שרוצים להרחיב את התכונות של 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, כמתואר בקטע "Where is Edge Microgateway installed" ב-Installing Edge Microgateway.

אפשר לשנות את ספריית ברירת המחדל של הפלאגין. איפה נמצאים יישומי פלאגין?

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

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

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

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

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

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

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

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

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

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

  3. יוצרים פרויקט פלאגין חדש בשם response-override ו-cd אליו:
    mkdir response-override && cd response-override
  4. יוצרים פרויקט חדש ב-Node.js:
    npm init
    חוזרים על הפעולה כמה פעמים כדי לאשר את ברירות המחדל.
  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() מקבלת שלושה ארגומנטים: config, logger ו-stats. הארגומנטים האלה מתוארים בארגומנטים של הפונקציה init() של פלאגין.
  • init() מחזירה אובייקט עם גורמי handler של פונקציות בעלות שם, שנקראים כשאירועים מסוימים מתרחשים במהלך משך החיים של בקשה.

פונקציות handler של אירוע

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

בקשת גורמי handler לאירועי זרימה

הפונקציות האלה נקראות באירועי בקשה ב-Microsoft 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

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

דוגמה:

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();
    }

רכיבי handler של אירועים בתהליך התגובה

הפונקציות האלה מופעלות באירועי תגובה ב-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

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

דוגמה:

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();
    }

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

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

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

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

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

הגדרה

נתוני התצורה שהתקבלו על ידי מיזוג קובץ התצורה של 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: []
  }

יומן רישום

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

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

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

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

next(null, data);

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

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

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

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

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

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

plugins/plugin-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 מופעלת אחרי שמקבלים את הבייטים האחרונים של נתוני התגובה.

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

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

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

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

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

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

  • רצף הפלאגין של קובץ התצורה של Edge Microgateway (~./edgemicro/config.yaml) מציין את הסדר שבו מתבצעת ה-handlers של האירועים.
  • ה-handlers של הבקשות נקראים בסדר עולה (הסדר שבו הם מופיעים ברצף של יישומי הפלאגין - 1, 2 או 3).
  • ה-handlers של התשובות נקראים בסדר יורד – 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 של יישומי פלאגין, כדי להטמיע פונקציונליות של פלאגין מותאם אישית, כמו צבירת נתונים וטרנספורמציה של נתוני בקשות או תגובות.

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

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

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

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

תאריך הוספה: v2.3.3

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

תאריך הוספה: v2.4.x

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

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


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

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

[prefix]/lib/node_modules/edgemicro/plugins

כאשר [prefix] היא ספריית הקידומות npm, כמתואר בקטע "Where is Edge Microgateway installed" ב-Installing 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);
    }

  };

}