שימוש ביישומי פלאגין

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

Edge Microgateway v. 3.0.x

קהל

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

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

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

יישומי פלאגין קיימים בחבילה עם Edge Microgateway

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

פלאגין מופעל כברירת מחדל התיאור
ניתוח נתונים כן שליחת ניתוח נתונים מ-Edge Microgateway אל Apigee Edge.
oauth כן הוספת אסימון OAuth ואימות מפתח API ל-Edge Microgateway. למידע נוסף, ראו הגדרה והגדרה של Edge Microgateway.
מכסה לא המדיניות הזו אוכפת מכסה על בקשות ל-Edge Microgateway. נעשה שימוש ב-Apigee Edge כדי לאחסן ולנהל את המכסות. כדאי לעיין בקטע שימוש בפלאגין המכסה.
כידון משטרה לא הגנה מפני עליות חדות בפקקים ומתקפות מניעת שירות (DoS). למידע נוסף, ניתן לעיין במאמר שימוש בפלאגין של מעצר שיא.
כותרת עליונה לא שרת proxy לדוגמה עם תגובה, שנועד כמדריך שיעזור למפתחים לכתוב יישומי פלאגין מותאמים אישית. למידע נוסף, ראו פלאגין לדוגמה של Edge Microgateway.
accumulate-request לא נתוני הבקשה נצברים לאובייקט יחיד לפני העברת הנתונים ל-handler הבא בשרשרת יישומי הפלאגין. שימושי לכתיבת יישומי פלאגין מסוג טרנספורמציה שצריכים לפעול על אובייקט תוכן בקשה יחיד שנצבר.
צבירת תשובה לא נתוני התגובה נצברים לאובייקט אחד לפני שהם מעבירים את הנתונים ל-handler הבא בשרשרת יישומי הפלאגין. שימושי לכתיבת יישומי פלאגין מסוג טרנספורמציה שצריכים לפעול על אובייקט תוכן תגובה יחיד שנצבר.
אותיות רישיות לא שינוי הנתונים של בקשות או תגובות. הפלאגין הזה מייצג שיטה מומלצת ליישום של פלאגין טרנספורמציה. הפלאגין לדוגמה מבצע טרנספורמציה טריוויאלית (ממירה את נתוני הבקשה או התגובה לאותיות רישיות). עם זאת, אפשר להתאים אותו בקלות לביצוע סוגים אחרים של טרנספורמציות, כמו XML ל-JSON.
json2xml לא הפונקציה הופכת נתוני בקשות או תגובות על סמך כותרות מסוג אישור או סוג תוכן. לפרטים נוספים, עיינו במסמכי התיעוד של הפלאגין ב-GitHub.
זיכרון מכסה לא המדיניות הזו אוכפת מכסה על בקשות ל-Edge Microgateway. אחסון וניהול של המכסות בזיכרון המקומי.
healthcheck לא הפונקציה מחזירה מידע על התהליך של Edge Microgateway – שימוש בזיכרון, שימוש במעבד וכו'. כדי להשתמש בפלאגין, צריך לקרוא לכתובת ה-URL /healthcheck במכונת Edge Microgateway. הפלאגין הזה נועד לשמש כדוגמה שאפשר להשתמש בו כדי להטמיע פלאגין משלך לבדיקת תקינות.

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

יישומי הפלאגין הקיימים הכלולים ב-Edge Microgateway נמצאים כאן, כאשר [prefix] הוא ספריית הקידומת npm. אם לא הצלחתם לאתר את הספרייה, עיינו בקטע היכן מותקנת אפליקציית Edge Microgateway.

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

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

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

  1. הפסקת השימוש ב-Edge Microgateway.
  2. פותחים קובץ תצורה של Edge Microgateway. פרטים נוספים זמינים במאמר ביצוע שינויים בהגדרות.
  3. מוסיפים את הפלאגין לרכיב plugins:sequence של קובץ התצורה, לפי השלבים הבאים. יישומי הפלאגין מופעלים לפי הסדר שבו הם מופיעים ברשימה הזו.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. מגדירים את הפלאגין. ליישומי פלאגין מסוימים יש פרמטרים אופציונליים שניתן להגדיר בקובץ התצורה. לדוגמה, אפשר להוסיף את הבית הבא כדי להגדיר את הפלאגין של מעצר שיא. למידע נוסף, אפשר לקרוא את המאמר בנושא שימוש בפלאגין של מעצר עלייה חדה.
    edgemicro:
      home: ../gateway
      port: 8000
      max_connections: -1
      max_connections_hard: -1
      logging:
        level: info
        dir: /var/tmp
        stats_log_interval: 60
      plugins:
        dir: ../plugins
        sequence:
          - oauth
          - spikearrest
    spikearrest:
       timeUnit: minute
       allow: 10
    
  1. שומרים את הקובץ.
  2. מפעילים מחדש או טוענים מחדש את Edge Microgateway, בהתאם לקובץ התצורה שערכתם.

הגדרה ספציפית לפלאגין

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

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

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

plugins/<plugin_name>/config/default.yaml. לדוגמה, אפשר להוסיף את הבלוק הזה ל-plugins/spikearrest/config/default.yaml, והוא יבטל כל הגדרה אחרת.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

שימוש בפלאגין של מעצר שיא

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

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

ראה הוספה והגדרה של יישומי פלאגין.

הגדרות לדוגמה למעצר עקב שיא

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

אפשרויות ההגדרה של מעצר חד-פעמי

  • timeUnit: התדירות שבה חלון הביצוע של מעצר השיא מתאפס. הערכים החוקיים הם שנייה או דקה.
  • allow: מספר הבקשות המקסימלי שמותר לשלוח במהלך יחידת הזמן. ראו גם אם מפעילים כמה תהליכי Edge Micro.
  • bufferSize: (אופציונלי, ברירת המחדל היא 0) אם bufferSize > 0, תבוצע שמירה של מספר הבקשות במאגר זמני. ברגע שההפעלה הבאה של "window" תתרחש, המערכת תעבד קודם את הבקשות במאגר הנתונים הזמני. למידע נוסף, ראו הוספת מאגר נתונים זמני.

איך פועל מעצר מהיר?

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

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

לדוגמה, נניח שציינתם קצב של 30 בקשות לדקה, באופן הבא:

spikearrest:
   timeUnit: minute
   allow: 30

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

אז מה קורה בפועל? כדי למנוע התנהגות שדומה לזו של שיאים חדשים, התכונה 'מעצר חד-פעמי' מאפשרת לחלק את התנועה המותרת על ידי חלוקת ההגדרות למרווחים קטנים יותר, באופן הבא:

תעריפים לדקה

התעריפים לדקה מוחלקים לפי מרווחי זמן מותרים של שניות. לדוגמה, 30 בקשות לדקה מוחלקות באופן הבא:

60 שניות (דקה אחת) / 30 = מרווחי זמן של 2 שניות, או בערך בקשה אחת מותרת כל 2 שניות. בקשה שנייה בתוך 2 שניות תיכשל. כמו כן, הבקשה ה-31 בתוך דקה תיכשל.

תעריפים לשנייה

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

1,000 אלפיות השנייה (שנייה אחת) / 10 = מרווחי זמן של 100 אלפיות השנייה, או כבקשה אחת מותרת לכל 100 אלפיות השנייה . בקשה שנייה בתוך 100 אלפיות השנייה תיכשל. כמו כן, הבקשה ה-11 בתוך שנייה תיכשל.

כשחורגים מהמגבלה

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

{"error": "spike arrest policy violated"}

הוספת מאגר נתונים זמני

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

אם מפעילים כמה תהליכי Edge Micro

מספר הבקשות המותרות תלוי במספר תהליכי העבודה של Edge Micro שפועלים. התכונה 'מעצר משניות' מחשבת את מספר הבקשות המותר לכל תהליך של עובד. כברירת מחדל, מספר תהליכי Edge Micro שווה למספר יחידות המעבד (CPU) במחשב שבו מותקן Edge Micro. עם זאת, אפשר להגדיר את מספר תהליכי העבודה כשמפעילים את Edge Micro באמצעות האפשרות --processes בפקודה start. לדוגמה, אם רוצים להפעיל מעצר חדירה כ-100 בקשות בפרק זמן נתון, ואם מפעילים את Edge Microgateway עם האפשרות --processes 4, אז מגדירים את allow: 25 בהגדרה של מעצר חדירה. בסיכום, הכלל המנחה הוא להגדיר את הפרמטר config allow לערך 'מספר רציף מעצר רצוי / מספר תהליכים'.

שימוש בפלאגין למכסה

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

הוספת פלאגין למכסה

ראה הוספה והגדרה של יישומי פלאגין.

הגדרת המוצר ב-Apigee Edge

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

  1. מתחברים לחשבון הארגוני של Apigee Edge.
  2. בממשק המשתמש של Edge, פותחים את המוצר שמשויך לשרת ה-proxy מבוסס-השערה שעליו רוצים להחיל את המכסה.
    1. בממשק המשתמש, בוחרים באפשרות מוצרים מהתפריט 'פרסום'.
    2. פותחים את המוצר שמכיל את ה-API שעליו רוצים להחיל את המכסה.
    3. לוחצים על עריכה.
    4. בשדה Quota מציינים את מרווח המכסה. לדוגמה, 100 בקשות בכל דקה. או 50,000 בקשות כל שעתיים.

  1. לוחצים על שמירה.
  2. יש לוודא שהמוצר נוסף לאפליקציה למפתחים. יהיה צורך במפתחות מהאפליקציה הזו כדי לבצע קריאות ל-API מאומתות.

תצורה לדוגמה של מכסה

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

אפשרויות הגדרה למכסה

כדי להגדיר את הפלאגין של המכסה, צריך להוסיף את הרכיב quotas לקובץ התצורה, כפי שמוצג בדוגמה הבאה:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
  bufferSize:
    hour: 20000
    minute: 500
    month: 1
    default: 10000
  useDebugMpId: true
  failOpen: true
  useRedis: true
  redisHost: localhost
  redisPort: 6379
  redisDb: 1
...
אפשרות התיאור
buffersize (מספר שלם) גודל המאגר שיש להגדיר למרווח הזמן שצוין. יחידות הזמן המותרות כוללות: hour, minute, day, week, month ו-default. (נוספה: גרסה 3.0.9)
failOpen כשהתכונה הזו פועלת, אם מתרחשת שגיאה בעיבוד מכסה או אם הבקשה ל'החלת מכסה' לא מתעדכנת ב-Edge, המערכת תעובד לפי ספירות מקומיות רק עד שסנכרון המכסה מרחוק יושלם בהצלחה. בשני המקרים האלה מוגדר דגל quota-failed-open באובייקט הבקשה. (נוספה: גרסה 3.0.9)

כדי להפעיל את התכונה 'fail open' של המכסה, מגדירים את ההגדרות הבאות:

edgemicro:
...
quotas:
  failOpen: true
useDebugMpId מגדירים את הדגל הזה לערך true כדי לאפשר רישום של מזהה ה-MP (מעבד הודעות) בתשובות למכסה. (נוספה: גרסה 3.0.9)

כדי להשתמש בתכונה הזו, עליך לעדכן את שרת ה-proxy של edgemicro-auth לגרסה 3.0.7 ואילך ולהגדיר את התצורה הבאה:

edgemicro:
...
quotas:
  useDebugMpId: true
...

כשמגדירים את useDebugMpId, תגובות המכסה מ-Edge יכילו את מזהה ה-MP ויירשמו ביומן על ידי Edge Microgateway. לדוגמה:

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis (בוליאני) צריך להגדיר את הערך true כדי להשתמש במודול מסד הנתונים של מכסת Redis. כשהיא מוגדרת, המכסה מוגבלת רק למכונות Edge Microgateway שמתחברות ל-Redis. אחרת, מונה המכסות יהיה גלובלי. ברירת מחדל: false (המודול redis-volos-apigee נמצא בשימוש) (נוספה: גרסה 3.0.10)
redisHost המארח שבו פועל מכונת Redis. ברירת מחדל: 127.0.0.1 (נוספה: גרסה 3.0.10)
redisPort היציאה של מכונת Redis. ברירת מחדל: 6379 (נוספה: גרסה 3.0.10)
redisDb ה-Redis DB לשימוש. ברירת מחדל: 0 (נוספה: גרסה 3.0.10)

הסבר על היקף המכסות

המכסה היא בהיקף של מוצר API. אם לאפליקציה למפתחים יש כמה מוצרים, המכסה חלה על כל אחד מהם בנפרד. כדי להשיג את ההיקף הזה, Edge Microgateway יוצר מזהה מכסה שהוא שילוב של " appName + productName".

בדיקת הפלאגין למכסה

במקרה של חריגה מהמכסה, סטטוס HTTP 403 מוחזר ללקוח יחד עם ההודעה הבאה:

{"error": "exceeded quota"}

מה ההבדל בין מעצר חד-פעמי למכסה?

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

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

אפשר להשתמש בתכונה 'מעצר שיא' כדי להגן מפני עליות פתאומיות בתנועת ה-API. בדרך כלל נעשה שימוש במעצר חד-פעמי כדי למנוע מתקפות DDoS אפשריות או התקפות זדוניות אחרות.