הפניה לפעולה ולהגדרה של Edge Microgateway

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

סקירה כללית

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

ביצוע שינויים בהגדרות

קובצי התצורה שחשוב להכיר כוללים:

• קובץ ברירת המחדל של הגדרות המערכת
• קובץ תצורה שמוגדר כברירת מחדל למופע חדש של Edge Microgateway
• קובץ תצורה דינמי להרצת מופעים

בקטע הזה נסביר על הקבצים האלה ומה צריך לדעת כדי לשנות אותם. פרטים על ההגדרות של קובץ ההגדרות זמינים במאמר הפניה להגדרות של Edge Microgateway.

קובץ ברירת המחדל של הגדרות המערכת

כשמתקינים את Edge Microgateway, קובץ תצורת מערכת שמוגדר כברירת מחדל ממוקם כאן:

[prefix]/lib/node_modules/edgemicro/config/default.yaml

כאשר [prefix] הוא ספריית התחילית npm. איפה מותקן Edge Microgateway

אם משנים את קובץ ההגדרה של המערכת, צריך לאתחל מחדש, להגדיר מחדש ולהפעיל מחדש את Edge Microgateway:

1. התקשרות אל edgemicro init
2. התקשרות אל edgemicro configure [params]
3. התקשרות אל edgemicro start [params]

קובץ תצורה שמוגדר כברירת מחדל למופעים חדשים של Edge Microgateway

כשמריצים את הפקודה edgemicro init, קובץ התצורה של המערכת (שמתואר למעלה), default.yaml, ממוקם בספרייה הזו: /.edgemicro~

אם משנים את קובץ התצורה ב-‎~/.edgemicro, צריך להגדיר מחדש ולהפעיל מחדש את Edge Microgateway:

1. edgemicro stop
2. edgemicro configure [params]
3. edgemicro start [params]

קובץ תצורה דינמי להרצת מופעים

כשמריצים את הפקודה edgemicro configure [params], נוצר קובץ תצורה דינמי בתיקייה ‎~/.edgemicro. שם הקובץ נקבע לפי התבנית הבאה: [org]-[env]-config.yaml, כאשר org ו-env הם השם של הארגון והסביבה ב-Apigee Edge. אפשר להשתמש בקובץ הזה כדי לבצע שינויים בהגדרות, ואז לטעון אותם מחדש ללא השבתה. לדוגמה, אם מוסיפים ומגדירים פלאגין, אפשר לטעון מחדש את ההגדרה בלי לגרום להשבתה, כמו שמוסבר בהמשך.

אם Edge Microgateway פועל (אפשרות ללא השבתה):

1. טוענים מחדש את ההגדרות של Edge Microgateway:

   edgemicro reload -o [org] -e [env] -k [key] -s [secret]

   כאשר:

   • ‫org הוא שם הארגון שלכם ב-Edge (אתם צריכים להיות אדמינים של הארגון).
   • ‫env היא סביבה בארגון (למשל בדיקה או ייצור).
   • ‫key הוא המפתח שהוחזר קודם על ידי הפקודה configure.
   • ‫secret הוא המפתח שהוחזר קודם על ידי הפקודה configure.

   דוגמה

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188016b3c39177d64a88754d615c74e1f78b6181d000723 -s 05c14356e42ed136b8dd35cf8a18531ff52d7299134677e30ef4e34ab0cc824

אם Edge Microgateway מושבת:

1. מפעילים מחדש את Edge Microgateway:

   edgemicro start -o [org] -e [env] -k [key] -s [secret]

   כאשר:

   • ‫org הוא שם הארגון שלכם ב-Edge (אתם צריכים להיות אדמינים של הארגון).
   • ‫env היא סביבה בארגון (למשל בדיקה או ייצור).
   • ‫key הוא המפתח שהוחזר קודם על ידי הפקודה configure.
   • ‫secret הוא המפתח שהוחזר קודם על ידי הפקודה configure.

   דוגמה

   edgemicro start -o docs -e test -k 701e70ee718ce6dc188016b3c39177d64a88754d615c74e1f78b6181d000723 -s 05c14356e42ed136b8dd35cf8a18531ff52d7299134677e30ef4e34ab0cc824

זו דוגמה לקובץ הגדרה. פרטים על ההגדרות בקובץ ההגדרות זמינים במאמר הפניה להגדרות של Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

הגדרת משתני סביבה

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

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

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

הגדרת SSL בשרת Edge Microgateway

אפשר להגדיר את שרת ה-Microgateway לשימוש ב-SSL. לדוגמה, אם SSL מוגדר, אפשר להפעיל ממשקי API דרך Edge Microgateway באמצעות הפרוטוקול https, כך:

https://localhost:8000/myapi

כדי להגדיר SSL בשרת Microgateway, פועלים לפי השלבים הבאים:

1. יוצרים או מקבלים אישור ומפתח SSL באמצעות כלי השירות openssl או בכל שיטה אחרת שרוצים.
2. מוסיפים את המאפיין edgemicro:ssl לקובץ התצורה של Edge Microgateway. רשימת האפשרויות המלאה מופיעה בטבלה שלמטה. פרטים על שינוי ההגדרה של Edge Microgateway מופיעים במאמר ביצוע שינויים בהגדרה. לדוגמה:
   

    edgemicro:
        ssl:
            key: <absolute path to the SSL key file>
            cert: <absolute path to the SSL cert file>
            passphrase: admin123 #option added in v2.2.2
            rejectUnauthorized: true #option added in v2.2.2

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

דוגמה לקטע edgemicro בקובץ התצורה, עם SSL מוגדר:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

זו רשימה של כל אפשרויות השרת הנתמכות:

שימוש באפשרויות של לקוח SSL/TLS

אתם יכולים להגדיר את Edge Microgateway כלקוח TLS או SSL כשמתחברים לנקודות קצה של יעד. בקובץ ההגדרות של Microgateway, משתמשים ברכיב targets כדי להגדיר אפשרויות SSL/TLS.

בדוגמה הזו מופיעות הגדרות שיחולו על כל המארחים:

targets:
   ssl:
     client:
       key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
       cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true

בדוגמה הזו, ההגדרות חלות רק על המארח שצוין:

targets:
   host: 'myserver.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true

דוגמה ל-TLS:

targets:
   host: 'myserver.example.com'
   tls:
     client:
       pfx: /Users/myname/twowayssl/ssl/client.pfx
       passphrase: admin123
       rejectUnauthorized: true

זו רשימה של כל האפשרויות הנתמכות של לקוחות:

שימוש בשירות אימות מותאם אישית

כברירת מחדל, Edge Microgateway משתמש ב-proxy שנפרס ב-Apigee Edge לאימות OAuth2. הפרוקסי הזה נפרס כשמריצים את edgemicro configure בפעם הראשונה. כברירת מחדל, כתובת ה-URL של שרת ה-proxy הזה מצוינת בקובץ ההגדרות של Edge Microgateway באופן הבא:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

אם אתם רוצים להשתמש בשירות מותאם אישית משלכם כדי לטפל באימות, אתם צריכים לשנות את הערך authUri בקובץ ההגדרות כך שיצביע על השירות שלכם. לדוגמה, יכול להיות שיש לכם שירות שמשתמש ב-LDAP כדי לאמת את הזהות.

ניהול קובצי יומן

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

איפה קובצי היומן מאוחסנים

כברירת מחדל, קובצי היומן מאוחסנים ב-/var/tmp.

איך משנים את ספריית ברירת המחדל של קובץ היומן

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

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

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

שליחת יומנים למסוף

אפשר להגדיר את הרישום ביומן כך שפרטי היומן יישלחו לפלט רגיל במקום לקובץ יומן. מגדירים את הדגל to_console לערך true באופן הבא:

edgemicro:
  logging:
    to_console: true  

אם בוחרים בהגדרה הזו, היומנים יישלחו לפלט רגיל. בשלב הזה, אי אפשר לשלוח יומנים גם ל-stdout וגם לקובץ יומן.

איך מגדירים את רמת הרישום ביומן

אפשר להגדיר את רמות היומן הבאות: info,‏ warn ו-error. מומלץ להשתמש ברמת המידע. הוא מתעד את כל בקשות ה-API והתגובות לבקשות, והוא ברירת המחדל.

איך משנים את מרווחי הזמן של יומן השינויים

אפשר להגדיר את המרווחים האלה בקובץ ההגדרות של Edge Microgateway. פרטים על ביצוע שינויים בהגדרות מופיעים במאמר ביצוע שינויים בהגדרות.

אלה המאפיינים שניתן להגדיר:

• ‫stats_log_interval: (ברירת מחדל: 60) מרווח הזמן בשניות שבו רשומת הנתונים הסטטיסטיים נכתבת בקובץ היומן של ה-API.
• ‫rotate_interval: (ברירת מחדל: 24) מרווח הזמן בשעות שבו מתבצעת רוטציה של קובצי היומן. לדוגמה:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

הערה: קבצי יומן שהועברו לארכיון לא נדחסים. כשמתחיל מרווח הזמן, נוצר קובץ יומן חדש עם חותמת זמן חדשה.

שיטות מומלצות לניהול קובצי יומן

ככל שנתוני קובץ היומן מצטברים לאורך זמן, Apigee ממליצה לאמץ את השיטות הבאות:

• קובצי יומן יכולים להיות גדולים מאוד, לכן חשוב לוודא שיש מספיק מקום בספרייה של קובץ היומן. בקטעים הבאים מוסבר איפה קובצי היומן מאוחסנים ואיך משנים את ספריית ברירת המחדל של קובצי היומן.
• מומלץ למחוק את קובצי היומן או להעביר אותם לספריית ארכיון נפרדת לפחות פעם בשבוע.
• אם המדיניות שלכם היא למחוק יומנים, אתם יכולים להשתמש בפקודת ה-CLI‏ edgemicro log -c כדי להסיר (לנקות) יומנים ישנים יותר.

מוסכמה למתן שמות לקובצי יומן

כל מופע של Edge Microgateway יוצר שלושה סוגים של קובצי יומן:

• ‫api – מתעד את כל הבקשות והתגובות שעוברות דרך Edge Microgateway. גם מוני ה-API (נתונים סטטיסטיים) ושגיאות מתועדים בקובץ הזה.
• ‫err – מתעד כל מה שנשלח אל stderr.
• ‫out – מתעד כל מה שנשלח ל-stdout.

זוהי מוסכמת מתן השמות:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

לדוגמה:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

מידע על התוכן של קובץ יומן

נוסף בגרסה: v2.3.3

כברירת מחדל, שירות הרישום ביומן משמיט את ה-JSON של שרתי proxy, מוצרים ו-JSON Web Token ‏ (JWT) שהורדו. אם רוצים להוציא את האובייקטים האלה לקובצי היומן, צריך להגדיר את DEBUG=* כשמפעילים את Edge Microgateway. לדוגמה:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

התוכן של קובץ היומן api

קובץ היומן api מכיל מידע מפורט על זרימת הבקשות והתגובות דרך Edge Microgateway. שמות קובצי היומן של ה-API הם כאלה:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

עבור כל בקשה שנשלחת אל Edge Microgateway, ארבעה אירועים נרשמים בקובץ היומן api:

• בקשה נכנסת מהלקוח
• נשלחה בקשה יוצאת ליעד
• תגובה נכנסת מהיעד
• תגובה יוצאת ללקוח

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

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

בואו נבחן אותם אחד אחד:

1. דוגמה לבקשה נכנסת מלקוח:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• ‫1436403888651 – חותמת תאריך של Unix
• info – תלוי בהקשר. יכול להיות info,‏ warn או error,‏ בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים של רשומה סטטיסטית, אזהרה לגבי אזהרות או שגיאה לגבי שגיאות.
• ‫req – מזהה את האירוע. במקרה הזה, הבקשה היא מהלקוח.
• ‫m – פועל ה-HTTP שבו נעשה שימוש בבקשה.
• ‫u – החלק של כתובת ה-URL שאחרי נתיב הבסיס.
• ‫h – המארח ומספר היציאה שבהם Edge Microgateway מאזין.
• ‫r – המארח והיציאה המרוחקים שממנה הגיעה בקשת הלקוח.
• ‫i – מזהה הבקשה. כל ארבעת רשומות האירועים ישתמשו באותו מזהה. לכל בקשה מוקצה מזהה בקשה ייחודי. הצלבת רשומות ביומן לפי מזהה בקשה יכולה לספק תובנות חשובות לגבי זמן האחזור של היעד.
• ‫d – משך הזמן במילי-שניות מאז שהבקשה התקבלה על ידי Edge Microgateway. בדוגמה שלמעלה, התגובה של היעד לבקשה 0 התקבלה אחרי 7 אלפיות השנייה (שורה 3), והתגובה נשלחה ללקוח אחרי 4 אלפיות השנייה נוספות (שורה 4). במילים אחרות, זמן האחזור הכולל של הבקשה היה 11 אלפיות השנייה, מתוכן 7 אלפיות השנייה נלקחו על ידי היעד ו-4 אלפיות השנייה על ידי Edge Microgateway עצמו.

2. דוגמה לבקשה יוצאת שנשלחה ליעד:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• ‫1436403888651 – חותמת תאריך של Unix
• info – תלוי בהקשר. יכול להיות info,‏ warn או error,‏ בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים של רשומה סטטיסטית, אזהרה לגבי אזהרות או שגיאה לגבי שגיאות.
• ‫treq – מזהה את האירוע. במקרה הזה, בקשת היעד.
• ‫m – פועל ה-HTTP שבו נעשה שימוש בבקשת היעד.
• ‫u – החלק של כתובת ה-URL שאחרי נתיב הבסיס.
• ‫h – המארח ומספר היציאה של יעד ה-backend.
• ‫i – המזהה של רשומת היומן. כל ארבעת רשומות האירועים יכללו את המזהה הזה.

3. דוגמה לתגובה נכנסת מהיעד

1436403888672 info tres s=200, d=7, i=0

‫1436403888651 – חותמת תאריך של Unix

• info – תלוי בהקשר. יכול להיות info,‏ warn או error,‏ בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים של רשומה סטטיסטית, אזהרה לגבי אזהרות או שגיאה לגבי שגיאות.
• ‫tres – מזהה את האירוע. במקרה הזה, התשובה היא היעד.
• ‫s – סטטוס תגובת ה-HTTP.
• ‫d – משך הזמן באלפיות השנייה. הזמן שנדרש לקריאה ל-API על ידי היעד.
• ‫i – המזהה של רשומת היומן. כל ארבעת רשומות האירועים יכללו את המזהה הזה.

4. דוגמה לתשובה יוצאת ללקוח

1436403888676 info res s=200, d=11, i=0

‫1436403888651 – חותמת תאריך של Unix

• info – תלוי בהקשר. יכול להיות info,‏ warn או error,‏ בהתאם לרמת היומן. יכול להיות נתונים סטטיסטיים של רשומה סטטיסטית, אזהרה לגבי אזהרות או שגיאה לגבי שגיאות.
• ‫res – מזהה את האירוע. במקרה הזה, התשובה ללקוח.
• ‫s – סטטוס תגובת ה-HTTP.
• ‫d – משך הזמן באלפיות השנייה. זהו הזמן הכולל שלקח לקריאה ל-API, כולל הזמן שלקח ל-API של היעד והזמן שלקח ל-Edge Microgateway עצמו.
• ‫i – המזהה של רשומת היומן. כל ארבעת רשומות האירועים יכללו את המזהה הזה.

לוח זמנים של קובץ היומן

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

הפניה להגדרות של Edge Microgateway

המיקום של קובץ התצורה

מאפייני ההגדרות שמתוארים בקטע הזה נמצאים בקובץ ההגדרות של Edge Microgateway. פרטים על ביצוע שינויים בהגדרות מופיעים במאמר ביצוע שינויים בהגדרות.

מאפיינים של edge_config

ההגדרות האלה משמשות להגדרת האינטראקציה בין מופע Edge Microgateway לבין Apigee Edge.

• ‫bootstrap: (ברירת מחדל: none) כתובת URL שמפנה לשירות ספציפי של Edge Microgateway שפועל ב-Apigee Edge. ‫Edge Microgateway משתמש בשירות הזה כדי לתקשר עם Apigee Edge. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה ליצירת זוג מפתחות ציבורי/פרטי: edgemicro genkeys. פרטים נוספים זמינים במאמר הגדרה וקביעת הגדרות של Edge Microgateway.
• ‫jwt_public_key: (ברירת מחדל: none) כתובת URL שמפנה לשרת proxy של Edge Microgateway שנפרס ב-Apigee Edge. שרת ה-proxy הזה משמש כנקודת קצה לאימות לצורך הנפקת אסימוני גישה חתומים ללקוחות. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה לפריסת שרת ה-proxy: edgemicro configure. פרטים נוספים זמינים במאמר הגדרה וקביעת הגדרות של Edge Microgateway.

מאפיינים של edgemicro

ההגדרות האלה קובעות את התהליך של Edge Microgateway.

• ‫port: (ברירת מחדל: 8000) מספר היציאה שבה תהליך Edge Microgateway מאזין.
• ‫max_connections: (ברירת מחדל: ‎-1) מציינת את המספר המקסימלי של חיבורים נכנסים בו-זמנית ש-Edge Microgateway יכול לקבל. אם המספר הזה חורג מהמגבלה, מוחזר הסטטוס הבא:
  
  res.statusCode = 429; // Too many requests
  
• ‫max_connections_hard: (ברירת מחדל: ‎-1) המספר המקסימלי של בקשות בו-זמניות ש-Edge Microgateway יכול לקבל לפני שהוא סוגר את החיבור. ההגדרה הזו נועדה למנוע התקפות מניעת שירות. בדרך כלל, צריך להגדיר מספר גדול יותר מ-max_connections.
• logging:
  • level: (ברירת מחדל: error)
    • ‫info – רישום ביומן של כל הבקשות והתגובות שעוברות דרך מופע של Edge Microgateway.
    • ‫warn – רישום רק של הודעות אזהרה.
    • ‫error – רישום הודעות שגיאה בלבד.
  • ‫dir: (ברירת מחדל: /var/tmp) התיקייה שבה מאוחסנים קובצי היומן.
  • ‫stats_log_interval: (ברירת מחדל: 60) מרווח הזמן בשניות שבו הרשומה של הנתונים הסטטיסטיים נכתבת בקובץ היומן של ה-API.
  • ‫rotate_interval: (ברירת מחדל: 24) מרווח הזמן בשעות שבו מתבצעת רוטציה של קובצי היומן.

• פלאגינים: פלאגינים מוסיפים פונקציונליות ל-Edge Microgateway. פרטים נוספים על פיתוח פלאגינים מופיעים במאמר פיתוח פלאגינים בהתאמה אישית.

• ‫dir: נתיב יחסי מהספרייה ‎ ./gateway לספרייה ‎./plugins, או נתיב מוחלט.
• ‫sequence: רשימה של מודולים של תוספים שרוצים להוסיף למופע של Edge Microgateway. המודולים יופעלו לפי הסדר שבו הם מופיעים כאן.

• ‫debug: מוסיף ניפוי באגים מרחוק לתהליך של Edge Microgateway.
  • ‫port: מספר היציאה להאזנה. לדוגמה, אפשר להגדיר את מאתר הבאגים של סביבת הפיתוח המשולבת (IDE) כך שיאזין ליציאה הזו.
  • ‫args: ארגומנטים לתהליך הניפוי. לדוגמה: args --nolazy
    
• ‫config_change_poll_interval: (ברירת מחדל: 600 שניות) Edge Microgateway טוען הגדרה חדשה באופן תקופתי ומבצע טעינה מחדש אם משהו השתנה. הסקר מזהה שינויים שבוצעו ב-Edge (שינויים במוצרים, בשרתי proxy עם מודעות ל-microgateway וכו') וגם שינויים שבוצעו בקובץ ההגדרות המקומי.
  
• ‫disable_config_poll_interval: (ברירת מחדל: false) מגדירים את הערך true כדי להשבית את הבדיקה האוטומטית של שינויים.

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

ההגדרות האלה קובעות איך כותרות HTTP מסוימות מטופלות.

• ‫x-forwarded-for: (ברירת מחדל: true) מגדירים את הערך false כדי למנוע העברה של כותרות x-forwarded-for ליעד.
• ‫x-forwarded-host: (ברירת מחדל: true) מגדירים את הערך false כדי למנוע העברה של כותרות x-forwarded-host ליעד.
• ‫x-request-id: (ברירת מחדל: true) מגדירים את הערך כ-false כדי למנוע העברה של כותרות x-request-id ליעד.
• ‫x-response-time: (ברירת מחדל: true) מגדירים את הערך false כדי למנוע העברה של כותרות x-response-time ליעד.
• ‫via: (ברירת מחדל: true) מגדירים את הערך false כדי למנוע העברה של כותרות via ליעד.

מאפייני OAuth

ההגדרות האלה קובעות איך Edge Microgateway אוכף את אימות הלקוח.

• ‫allowNoAuthorization: (ברירת מחדל: false) אם המדיניות מוגדרת כ-true, קריאות ה-API יכולות לעבור דרך Edge Microgateway בלי כותרת הרשאה בכלל. מגדירים את הערך הזה ל-false כדי לדרוש כותרת Authorization (ברירת מחדל).
• ‫allowInvalidAuthorization: (ברירת מחדל: false) אם הערך מוגדר כ-true, קריאות ל-API מורשות לעבור אם הטוקן שמועבר בכותרת ההרשאה לא תקין או שתוקפו פג. כדי לדרוש אסימונים תקפים (ברירת מחדל), צריך להגדיר את המדיניות הזו כ-False.
• ‫authorization-header: (ברירת מחדל: Authorization: Bearer) הכותרת שמשמשת לשליחת טוקן הגישה ל-Edge Microgateway. יכול להיות שתרצו לשנות את ברירת המחדל במקרים שבהם היעד צריך להשתמש בכותרת Authorization למטרה אחרת.
• ‫api-key-header: (ברירת מחדל: x-api-key) השם של הכותרת או של פרמטר השאילתה שמשמשים להעברת מפתח API ל-Edge Microgateway. אפשר לקרוא גם את המאמר שימוש במפתח API.
• ‫keepAuthHeader: (ברירת מחדל: false) אם ההגדרה היא true, כותרת ההרשאה שנשלחת בבקשה מועברת ליעד (היא נשמרת).

מאפיינים ספציפיים לתוסף

במאמר בנושא שימוש בתוספים מפורטים המאפיינים שאפשר להגדיר לכל תוסף.

סינון שרתי proxy

אתם יכולים לסנן את הפרוקסי שמודעים ל-Microgateway שמופע Edge Microgateway יעבד. כשמפעילים את Edge Microgateway, הוא מוריד את כל ה-proxies שמודעים ל-microgateway בארגון שאליו הוא משויך. כדי להגביל את הפרוקסי ששער המיקרו יעבד, משתמשים בהגדרה הבאה. לדוגמה, ההגדרה הזו מגבילה את מספר שרתי ה-proxy ששער המיקרו יעבד לשלושה: edgemicro_proxy-1, edgemicro_proxy-2 ו-edgemicro_proxy-3:

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

אנונימיזציה של נתוני ניתוח

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

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

ניפוי באגים ופתרון בעיות

חיבור למאגר באגים

אפשר להריץ את Edge Microgateway עם מאתר באגים, כמו node-inspector. האפשרות הזו שימושית לפתרון בעיות ולניפוי באגים בתוספים מותאמים אישית.

1. מפעילים מחדש את Edge Microgateway במצב ניפוי באגים. כדי לעשות את זה, מוסיפים DEBUG=* לתחילת פקודת ההתחלה. לדוגמה:
   
   DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
   
2. מפעילים את הכלי לניפוי באגים ומגדירים אותו להאזנה למספר היציאה של תהליך ניפוי הבאגים.
3. עכשיו אפשר לעבור שלב אחר שלב בקוד של Edge Microgateway, להגדיר נקודות עצירה, לצפות בביטויים וכו'.

אפשר לציין דגלים רגילים של Node.js שקשורים למצב ניפוי באגים. לדוגמה, ‫--nolazy עוזר בניפוי באגים בקוד אסינכרוני.

בדיקת קובצי יומן

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

שימוש באבטחה של מפתח API

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

שמירה במטמון של מפתחות

מפתחות API מוחלפים באסימוני Bearer, שנשמרים במטמון. כדי להשבית את השמירה במטמון, צריך להגדיר את הכותרת Cache-Control: no-cache בבקשות נכנסות ל-Edge Microgateway.

פתרון עקיף נדרש אם אתם משתמשים בגרסה 15.07 של Apigee Edge Private Cloud

כדי להשתמש באבטחת מפתח API ב-Edge Private Cloud 15.07, צריך להטמיע את הפתרון העקיף שמתואר כאן. הפתרון העקיף מחייב שינוי של שורה אחת בקובץ Node.js בשרת ה-proxy של edgemicro-auth והפעלה מחדש של Edge Microgateway.

הטמעת הפתרון העקיף בממשק המשתמש של Edge

בסיום התהליך, צריך להריץ מחדש את הפקודה edgemicro start.

1. בממשק המשתמש של Edge, פותחים את ה-proxy של edgemicro-auth בכלי לעריכת proxy.
2. בוחרים בכרטיסייה 'פיתוח'.
3. בחלונית הניווט, בקטע Scripts, פותחים את קובץ ה-JavaScript בשם verify-api-key.js.
4. מעבר לשורה 109:
   
   
   api_product_list: apigeeToken.app && apigeeToken.app.apiproducts ? apigeeToken.app.apiproducts : []

5. מחליפים את החלק שאחרי api_product_list:‎ במערך 'מקודד' של שמות המוצרים שמשויכים למפתחות ה-API שרוצים להשתמש בהם. לדוגמה, אם רוצים להשתמש במפתח מאפליקציית מפתח שכוללת את המוצרים Product-1 ו-Product-2, צריך לקודד את השורה כך:
   
   api_product_list: ["Product-1", "Product-2"]
   
6. לוחצים על 'שמירה'.
7. מריצים את הפקודה edgemicro start.

הטמעה בבסיס הקוד המקומי של Edge Microgateway

במקרה כזה, צריך להריץ מחדש את הפקודה configure של edgemicro ואחריה את הפקודה edgemicro start.

1. פותחים את הקובץ <microgateway-root-dir>/edge/auth/api/controllers/verify-api-key.js, כאשר <microgateway-root-dir> היא הספרייה שבה Edge Microgateway הותקן כשמריצים את הפקודה npm install.
2. מעבר לשורה 109:
   
   
   api_product_list: apigeeToken.app && apigeeToken.app.apiproducts ? apigeeToken.app.apiproducts : []

3. מחליפים את החלק שאחרי api_product_list:‎ במערך 'מקודד' של שמות המוצרים שמשויכים למפתחות ה-API שרוצים להשתמש בהם. לדוגמה, אם רוצים להשתמש במפתח מאפליקציית מפתח שכוללת את המוצרים Product-1 ו-Product-2, צריך לקודד את השורה כך:
   
   api_product_list: ["Product-1", "Product-2"]
   
4. שומרים את הקובץ.
5. מריצים את הפקודה edgemicro configure. (או edgemicro private configure אם אתם משתמשים ב-Edge Private Cloud). הפקודה הזו פורסת מחדש את שרת ה-proxy של edgemicro-auth.
6. מריצים את הפקודה edgemicro start.

שימוש באבטחת טוקנים של OAuth2

לפרטים על שימוש בטוקן OAuth עם בקשות לשרת proxy, אפשר לעיין במאמר Secure Edge Microgateway.

שימוש במפתח API

פרטים על שימוש במפתחות API עם בקשות פרוקסי זמינים במאמר אבטחת Edge Microgateway.

הגדרת השם של מפתח ה-API

כברירת מחדל, x-api-key הוא השם שמשמש לכותרת של מפתח ה-API או לפרמטר של השאילתה. אפשר לשנות את ברירת המחדל הזו בקובץ ההגדרות, כמו שמוסבר במאמר ביצוע שינויים בהגדרות. לדוגמה, כדי לשנות את השם ל-apiKey:

oauth:
 allowNoAuthorization: false
 allowInvalidAuthorization: false
 api-key-header: apiKey