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

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

Edge Microgateway v. 3.3.x

קהל

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

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

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

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

בזמן ההתקנה של 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

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

   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
   

5. שומרים את הקובץ.
6. מפעילים מחדש או טוענים מחדש את 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 בקשות כל שעתיים.
      
      

3. לוחצים על שמירה.
4. יש לוודא שהמוצר נוסף לאפליקציה למפתחים. יהיה צורך במפתחות מהאפליקציה הזו כדי לבצע קריאות ל-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
    isHTTPStatusTooManyRequestEnabled: true
...

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

הסבר על המכסות

כברירת מחדל, המיקרו-שער מסנכרן את מונה המכסות שלו עם Apigee Edge כל 5 שניות אם מרווח המכסה מוגדר ל-'minute'. אם המרווח מוגדר לרמה גבוהה יותר מ'דקה', כמו 'שבוע' או 'חודש', פרק הזמן לרענון כברירת מחדל הוא דקה אחת.

חשוב לציין את מרווחי המכסות במוצרי ה-API שמוגדרים ב-Apigee Edge. מרווחי המכסה מציינים כמה בקשות מותרות לדקה, לשעה, ליום, לשבוע או לחודש. לדוגמה, מרווח הזמן של מכסה של 100 בקשות לדקה יכול להיות 100 בקשות לדקה ולמוצר ב' יכול להיות מרווח מכסה של 10,000 בקשות לשעה.

הגדרת YAML של הפלאגין Edge Microgateway quota לא קובעת את מרווח הזמן למכסה, אלא מאפשרת להתאים את התדירות שבה מכונת Edge Microgateway מקומית מסנכרנת את ספירת המכסות שלה עם Apigee Edge.

לדוגמה, נניח שיש שלושה מוצרי API שמוגדרים ב-Apigee Edge עם מרווחי המכסות הבאים:

• למוצר א' יש מכסה של 100 בקשות לדקה
• למוצר ב' יש מכסה של 5,000 בקשות בשעה
• למוצר ג' יש מכסה של 1000,000 בקשות בחודש

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

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

ההגדרה הזו מגדירה את מרווחי הסנכרון הבאים למוצרי ה-API שתוארו קודם לכן:

• מוצר א' מוגדר למרווח הזמן "דקות". Edge Microgateway יסונכרן עם Edge אחרי כל בקשה 50 או 5 שניות, המוקדם מביניהם.
• מוצר ב' מוגדר למרווח הזמן "שעה". Edge Microgateway יסונכרן עם Edge אחרי כל בקשה 2,000 או דקה אחת, המוקדם מביניהם.
• מוצר ג' מוגדר למרווח זמן "חודש". Edge Microgateway יסונכרן עם Edge אחרי כל בקשה יחידה או דקה אחת, המוקדם מביניהם.

בכל פעם שמכונה של Microgateway מסתנכרנת עם Edge, מספר המכסות של ה-microgateway נקבע לפי מספר המכסות שאוחזר.

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

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

המכסה מוגבלת לסביבה בארגון. כדי להשיג את ההיקף הזה, Edge Microgateway יוצר מזהה מכסה שהוא שילוב של " org + env + appName + productName".

שימוש בחנות לגיבוי של Redis לצורך מכסה

כדי להשתמש בחנות לגיבוי של Redis לצורך מכסה, צריך להשתמש באותה תצורה שמשמשת לתכונת הסנכרון. אלה ההגדרות הבסיסיות שנדרשות כדי להשתמש ב-Redis לצורך מכסה של נפח אחסון:

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true

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

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

{"error": "exceeded quota"}

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

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

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

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