כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
Edge Microgateway v. 3.1.5 ואילך
קהל
הנושא הזה מיועד לאופרטורים של 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
הוספה והגדרה של יישומי פלאגין
כדי להוסיף ולהגדיר יישומי פלאגין, פועלים לפי הדפוס הבא:
- הפסקת השימוש ב-Edge Microgateway.
- פותחים קובץ תצורה של Edge Microgateway. פרטים נוספים זמינים במאמר ביצוע שינויים בהגדרות.
- מוסיפים את הפלאגין לרכיב
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
- מגדירים את הפלאגין. ליישומי פלאגין מסוימים יש פרמטרים אופציונליים שניתן להגדיר בקובץ התצורה. לדוגמה, אפשר להוסיף את הבית הבא כדי להגדיר את הפלאגין של
מעצר שיא. למידע נוסף,
אפשר לקרוא את המאמר בנושא שימוש בפלאגין של מעצר עלייה חדה.
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
- שומרים את הקובץ.
- מפעילים מחדש או טוענים מחדש את 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.
- מתחברים לחשבון הארגוני של Apigee Edge.
- בממשק המשתמש של Edge, פותחים את המוצר שמשויך לשרת ה-proxy מבוסס-השערה שעליו רוצים להחיל את המכסה.
- בממשק המשתמש, בוחרים באפשרות מוצרים מהתפריט 'פרסום'.
- פותחים את המוצר שמכיל את ה-API שעליו רוצים להחיל את המכסה.
- לוחצים על עריכה.
- בשדה Quota מציינים את מרווח המכסה. לדוגמה, 100 בקשות
בכל דקה. או 50,000 בקשות כל שעתיים.
- לוחצים על שמירה.
- יש לוודא שהמוצר נוסף לאפליקציה למפתחים. יהיה צורך במפתחות מהאפליקציה הזו כדי לבצע קריאות ל-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 |
(מספר שלם) ההגדרה של quotas: bufferSize: minute: 500 default: 10000 useDebugMpId: true failOpen: true כברירת מחדל, המיקרו-שער מסנכרן את מונה המכסות שלו עם Apigee Edge כל 5 שניות אם מרווח המכסה מוגדר ל-'minute'. לפי ההגדרות שלמעלה, אם מרווח המכסה מוגדר במוצר ה-API כ-'minute', Edge Microgateway תסתנכרן עם Edge כדי לקבל את מספר המכסות הנוכחי אחרי 500 בקשות או אחרי 5 שניות, הראשון מביניהם. איך המכסות נספרות?
יחידות הזמן המותרות כוללות: |
failOpen |
כשהתכונה הזו פועלת, אם מתרחשת שגיאה בעיבוד מכסה או אם הבקשה ל'החלת מכסה' לא מתעדכנת ב-Edge, המערכת תעובד לפי ספירות מקומיות רק עד שסנכרון המכסה מרחוק יושלם בהצלחה. בשני המקרים האלה מוגדר דגל quota-failed-open באובייקט הבקשה.
כדי להפעיל את התכונה 'fail open' של המכסה, מגדירים את ההגדרות הבאות: edgemicro: ... quotas: failOpen: true |
useDebugMpId |
מגדירים את הדגל הזה לערך true כדי לאפשר רישום של מזהה ה-MP (מעבד הודעות) בתשובות למכסה.
כדי להשתמש בתכונה הזו, צריך לקבוע את ההגדרות הבאות: edgemicro: ... quotas: useDebugMpId: true ...
כשמגדירים את { "allowed": 20, "used": 3, "exceeded": 0, "available": 17, "expiryTime": 1570748640000, "timestamp": 1570748580323, "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a" } |
useRedis |
אם המדיניות מוגדרת כ-true , הפלאגין משתמש ב-Redisis במאגר של המכסה לגיבוי.
לפרטים נוספים אפשר לעיין בשימוש בחנות של Redis לגיבוי לצורך מכסה. |
הסבר על המכסות
כברירת מחדל, המיקרו-שער מסנכרן את מונה המכסות שלו עם 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לפרטים על הפרמטרים
edgemicro.redis*
, אפשר לעיין במאמר שימוש במסנכרן.
בדיקת הפלאגין למכסה
במקרה של חריגה מהמכסה, סטטוס HTTP 403 מוחזר ללקוח יחד עם ההודעה הבאה:
{"error": "exceeded quota"}
מה ההבדל בין מעצר חד-פעמי למכסה?
חשוב לבחור את הכלי המתאים למשימה שאתם רוצים לבצע. מדיניות המכסה קובעת את מספר הודעות הבקשות שאפליקציית לקוח מורשית לשלוח ל-API במשך שעה, יום, שבוע או חודש. מדיניות המכסה אוכפת את מגבלות הצריכה על אפליקציות לקוח באמצעות מונה מבוזר שסופר את הבקשות הנכנסות.
שימוש במדיניות מכסה כדי לאכוף חוזים עסקיים או הסכמי רמת שירות עם מפתחים ושותפים, ולא לצורך ניהול תעבורת נתונים תפעולית. לדוגמה, אפשר להשתמש במכסה כדי להגביל את תעבורת הנתונים של שירות חינמי, ובמקביל לאפשר גישה מלאה ללקוחות משלמים.
אפשר להשתמש בתכונה 'מעצר שיא' כדי להגן מפני עליות פתאומיות בתנועת ה-API. בדרך כלל נעשה שימוש במעצר חד-פעמי כדי למנוע מתקפות DDoS אפשריות או התקפות זדוניות אחרות.