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

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

כדי להוסיף תכונות ויכולות חדשות ל-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" בחלק התקנת Edge Microgateway

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

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

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

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
   

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

פונקציות של Event 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

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

דוגמה:

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

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

דוגמה:

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(), ondata_response, וכו') צריך להפעיל את הקריאה החוזרת (callback) next() לאחר הסיום בעיבוד. אם לא קוראים ל-next(), העיבוד יופסק והבקשה תלוי.
• הארגומנט הראשון של next() עשוי להיות שגיאה שתגרום לבקשה לצורך סיום העיבוד.
• הגורמים המטפלים ב-ondata_ ו-onend_ חייבים להפעיל next() עם ארגומנט שני שמכיל את הנתונים שיועברו ליעד. או הלקוח. הארגומנט הזה יכול להיות null אם הפלאגין מבצע אחסון זמני ואין לו מספיק נתונים כדי להשתנות באותו רגע.
• שימו לב שמופע אחד של הפלאגין משמש לטיפול בכל הבקשות והתגובות. אם פלאגין מעוניין לשמור על מצב לכל בקשה בין קריאות, הוא יכול לשמור את המצב הזה נוסף לאובייקט request שסופק (req), Life הוא משך הזמן של הקריאה ל-API.
• חשוב לשים לב לכל השגיאות ולקרוא ל-next() עם השגיאה. הפעולה נכשלה call next() יגרום לניתוק הקריאה ל-API.
• כדאי להיזהר שלא ליצור דליפות זיכרון, כי הן עלולות להשפיע על הביצועים הכוללים של Edge. Microgateway ולגרום לקריסה אם נגמר לה הזיכרון.
• הקפידו לעקוב אחר המודל של Node.js ולא לבצע משימות עתירות מחשוב ולכן הן עלולות להשפיע לרעה על הביצועים של Edge Microgateway.

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

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

config

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

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

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

שלך יכול לגשת לתצורת microgateway הממוזגת ולנתוני 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)

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

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

• 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 – המספר הכולל של הבקשות.
• responses – המספר הכולל של התגובות.
• חיבורים – מספר החיבורים הפעילים לטירגוט.

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

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

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

next(null, data);

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

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

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

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

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

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

נוסף בגרסה: 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, ראה דיון זה thread למידע נוסף.

הוסרה בגרסה 3.3.3

הפלאגין לדוגמה שנקרא eurekaclient הוסר מ-Edge Microgateway ב- גרסה 3.3.3. פרטים נוספים זמינים בנתוני הגרסה.

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

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

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

[prefix]/lib/node_modules/edgemicro/plugins

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

accumulate-request

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

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

    }

  };

}

accumulate-response

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

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

הנה קוד המקור עבור <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);
    }

  };

}