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

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

קהל

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

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

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

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

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

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

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

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

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

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

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

  1. עוצרים את Microgateway של Edge.
  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 הגדרות למעצר שיא. לסיכום, כלל האצבע הוא להגדיר את ההגדרה allow לערך 'מספר ההשהיות הרצויות של עצירה חדה / מספר תהליכים'.

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

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

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

למידע נוסף, ראו הוספה והגדרה של יישומי פלאגין.

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

אתם מגדירים מכסות בממשק המשתמש של 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
...
אפשרות תיאור
bufferSize

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

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

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

משך הזמן המותר היחידות כוללות: minute, hour, day, week, month וגם default.

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

כדי להפעיל את המכסה 'fail 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 למכסה.

איך המכסות נספרות

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

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

YAML של הפלאגין quota Edge Microgateway לא קובעת את המכסה interval; במקום זאת, הוא מאפשר לשנות את התדר של Microsoft 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 שמתוארים בעבר:

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

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

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

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

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

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

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