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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

‫Edge Microgateway מגרסה 3.1.5 ואילך

קהל

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

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

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

פלאגינים קיימים שמצורפים ל-Edge Microgateway

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

פלאגין מופעל כברירת מחדל תיאור
analytics כן שליחת נתוני ניתוח מ-Edge Microgateway אל Apigee Edge.
oauth כן הוספת אימות של טוקן OAuth ומפתח API ל-Edge Microgateway. מידע נוסף זמין במאמר בנושא הגדרה של Edge Microgateway.
quota לא מכסה מוגדרת לבקשות ל-Edge Microgateway. משתמש ב-Apigee Edge כדי לאחסן ולנהל את המכסות. איך משתמשים בפלאגין של המכסה
spikearrest לא הגנה מפני עליות חדות בתנועה והתקפות מניעת שירות (DoS). אפשר לעיין במאמר בנושא שימוש בפלאגין למניעת עליות פתאומיות.
header-uppercase לא דוגמה לשרת proxy עם הערות, שנועדה לשמש כמדריך שיעזור למפתחים לכתוב תוספים בהתאמה אישית. דוגמה לתוסף Edge Microgateway
accumulate-request לא הוא צובר את נתוני הבקשה באובייקט יחיד לפני שהוא מעביר את הנתונים ל-handler הבא בשרשרת התוספים. האפשרות הזו שימושית לכתיבת פלאגינים של טרנספורמציה שצריכים לפעול על אובייקט יחיד של תוכן בקשה מצטבר.
accumulate-response לא מצטבר נתוני התגובה לאובייקט יחיד לפני העברת הנתונים לטיפול הבא בשרשרת התוספים. התכונה הזו שימושית לכתיבת תוספים לשינוי טקסט שצריכים לפעול על אובייקט תוכן של תשובה מצטברת יחידה.
transform-uppercase לא טרנספורמציה של נתוני בקשה או תגובה. התוסף הזה מייצג הטמעה של תוסף טרנספורמציה בהתאם לשיטה מומלצת. תוסף לדוגמה מבצע טרנספורמציה פשוטה (ממיר נתוני בקשה או תגובה לאותיות רישיות), אבל אפשר להתאים אותו בקלות לביצוע טרנספורמציות מסוגים אחרים, כמו המרה מ-XML ל-JSON.
json2xml לא הופך נתוני בקשה או תגובה על סמך כותרות מסוג accept או content-type. פרטים נוספים זמינים במאמרי העזרה של הפלאגין ב-GitHub.
quota-memory לא מכסה מוגדרת לבקשות ל-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. מגדירים את הפלאגין. לחלק מהתוספים יש פרמטרים אופציונליים שאפשר להגדיר בקובץ config. לדוגמה, אפשר להוסיף את ה-stanza הבא כדי להגדיר את הפלאגין spike arrest. מידע נוסף מופיע במאמר בנושא שימוש בתוסף לזיהוי עליות פתאומיות. 
    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

שימוש בתוסף למניעת קפיצות פתאומיות

התוסף Spike Arrest מגן מפני עליות פתאומיות בתנועה. הוא מגביל את מספר הבקשות שמעובדות על ידי מופע Edge Microgateway.

הוספת הפלאגין Spike Arrest

הוספה והגדרה של פלאגינים

דוגמה להגדרה של מנגנון להגנה מפני עלייה חדה בתנועה

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

אפשרויות הגדרה של spike arrest

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

איך פועלת התכונה 'מניעת עלייה חדה בתנועה'?

הגנה מפני עליות חדות בתעבורה היא דרך להגן באופן כללי מפני עליות חדות בתעבורה, ולא דרך להגביל את התעבורה למספר מסוים של בקשות. ממשקי ה-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 שפועלים. התכונה 'מניעת עליות פתאומיות' מחשבת את מספר הבקשות המותר לכל תהליך worker. כברירת מחדל, מספר התהליכים של Edge Micro שווה למספר המעבדים במכונה שבה Edge Micro מותקן. עם זאת, אפשר להגדיר את מספר תהליכי העובד כשמפעילים את Edge Micro באמצעות האפשרות --processes בפקודה start. לדוגמה, אם רוצים שההגנה מפני עליות פתאומיות בתנועה תופעל כשמגיעות 100 בקשות בפרק זמן מסוים, ואם מפעילים את Edge Microgateway עם האפשרות --processes 4, צריך להגדיר את allow: 25 בהגדרות של ההגנה מפני עליות פתאומיות בתנועה. לסיכום, כלל האצבע הוא להגדיר את הפרמטר allow config לערך 'מספר התהליכים / מספר התהליכים הרצויים לעצירת עלייה חדה'.

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

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

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

הוספה והגדרה של פלאגינים

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

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

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

‫(Integer) הגדרת bufferSize מאפשרת לכם לשנות את התדירות שבה Edge Microgateway מסנכרן את מכסת השימוש שלו עם Apigee Edge. כדי להבין את bufferSize, כדאי לעיין בהגדרת הדוגמה הבאה: 

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

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

יחידות הזמן המותרות כוללות: minute,‏ hour,‏ day,‏ week,‏ month ו-default.

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

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

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

כדי להשתמש בתכונה הזו, צריך להגדיר את ההגדרות הבאות: 

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

הסבר על אופן החישוב של המכסות

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

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

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

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

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

בהתחשב בהגדרות המכסות האלה, איך צריך להגדיר את התוסף quota Edge Microgateway? השיטה המומלצת היא להגדיר את 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
פרטים על הפרמטרים של edgemicro.redis* מופיעים במאמר שימוש בכלי הסנכרון.

בדיקת תוסף המכסה

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

{"error": "exceeded quota"}

מה ההבדל בין הגנה מפני קפיצות פתאומיות בשימוש לבין מכסת שימוש?

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

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

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