כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
Edge Microgateway v. 3.0.x
נושא זה עוסק באופן הניהול וההגדרה של Edge Microgateway.
שדרוג Edge Microgateway אם יש לך חיבור לאינטרנט
בסעיף הזה נסביר איך לשדרג התקנה קיימת של Edge Microgateway. אם אתם משתמשים ללא חיבור לאינטרנט, קראו את המאמר האם ניתן להתקין את Edge Microgateway בלי חיבור לאינטרנט?
ב-Apigee מומלץ לבדוק את ההגדרה הקיימת באמצעות הגרסה החדשה לפני השדרוג של סביבת הייצור.
- כדי לשדרג לגרסה האחרונה של Edge Microgateway, מריצים את הפקודה
npm
הבאה:npm upgrade edgemicro -g
כדי לשדרג לגרסה ספציפית של Edge Microgateway, צריך לציין את מספר הגרסה בפקודת השדרוג. אם לא יצוין מספר הגרסה, הגרסה האחרונה תותקן. לדוגמה, כדי לשדרג לגרסה 3.0.2, צריך להשתמש בפקודה הבאה:
npm upgrade edgemicro@3.0.2 -g
- בודקים את מספר הגרסה. לדוגמה, אם התקנתם את גרסה 3.0.2:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.0.2
- ולבסוף, משדרגים לגרסה האחרונה של שרת ה-Proxy מסוג edgemicro-auth:
edgemicro upgradeauth -o org_name -e env_name -u username
ביצוע שינויים בהגדרות
קובצי התצורה שצריך להכיר כוללים:
- קובץ ברירת המחדל של תצורת המערכת
- קובץ תצורה ברירת מחדל למכונה של Edge Microgateway שאותחלה לאחרונה
- קובץ תצורה דינמי למכונות פועלות
הקטע הזה עוסק בקבצים האלה ובדברים שצריך לדעת כדי לשנות אותם.
קובץ ברירת המחדל של תצורת המערכת
כשמתקינים את Edge Microgateway, קובץ ברירת המחדל של תצורת המערכת נמצא כאן:
prefix/lib/node_modules/edgemicro/config/default.yaml
כאשר prefix היא ספריית התחילית npm
. אם לא הצלחתם לאתר את הספרייה, עיינו בקטע
היכן מותקנת אפליקציית Edge Microgateway.
אם משנים את קובץ תצורת המערכת, צריך לאתחל מחדש, להגדיר מחדש ולהפעיל מחדש את Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
קובץ תצורה המוגדר כברירת מחדל למכונות Edge Microgateway שאותחלו לאחרונה
כאשר מריצים את edgemicro init
, קובץ תצורת המערכת (כפי שמתואר למעלה), default.yaml
, מוצב בספרייה ~/.edgemicro
.
אם משנים את קובץ התצורה ב-~/.edgemicro
, צריך להגדיר מחדש ולהפעיל מחדש את Edge Microgateway:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
קובץ תצורה דינמי למכונות פועלות
כאשר מריצים את edgemicro configure [params]
, נוצר קובץ תצורה דינמי ב-~/.edgemicro
. השם של הקובץ מבוסס על התבנית הבאה: org-env-config.yaml
, כאשר org ו-env הם שמות הארגון והסביבה שלך ב-Apigee Edge. אפשר להשתמש בקובץ הזה כדי לבצע שינויים בהגדרות ואז לטעון אותו מחדש ללא זמן השבתה. לדוגמה, אם מוסיפים ומגדירים פלאגין,
אפשר לטעון מחדש את התצורה בלי לצבור זמן השבתה, כפי שמוסבר בהמשך.
אם Edge Microgateway פועל (האפשרות של אפס זמן השבתה):
- טוענים מחדש את הגדרות Edge Microgateway:
edgemicro reload -o org_name -e env_name -k key -s secret
כאשר:
- org_name זהו שם הארגון שלך ב-Edge (עליך להיות מנהל מערכת ארגוני).
- הסביבה env_name היא בארגון שלכם (למשל test או prod).
- key הוא המפתח שהוחזר קודם על ידי פקודת ההגדרה.
- secret הוא המפתח שהוחזר קודם על ידי פקודת ההגדרה.
לדוגמה
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
אם Edge Microgateway נעצר:
- מפעילים מחדש את Edge Microgateway:
edgemicro start -o org_name -e env_name -k key -s secret
כאשר:
- org_name זהו שם הארגון שלך ב-Edge (עליך להיות מנהל מערכת ארגוני).
- env_name הוא סביבה בארגון שלכם (למשל test או prod).
- key הוא המפתח שהוחזר קודם על ידי פקודת ההגדרה.
- secret הוא המפתח שהוחזר קודם על ידי פקודת ההגדרה.
לדוגמה:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
הנה קובץ תצורה לדוגמה. לפרטים נוספים על הגדרות קובץ התצורה, אפשר לעיין בחומר עזר בנושא תצורה של 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
ההגדרה של המשתנים האלה היא אופציונלית. אם מגדירים אותן, אין צורך לציין את הערכים שלהן כשמשתמשים בממשק Command-Line Interface (CLI) כדי להגדיר ולהפעיל את Edge Microgateway.
הגדרת SSL בשרת Edge Microgateway
למידע נוסף על הגדרת TLS ב-Apigee Edge Microgateway, כדאי לצפות בסרטונים הבאים:
וידאו | תיאור |
---|---|
הגדרת TLS (אבטחת שכבת התעבורה) חד-כיוונית צפונה | מידע נוסף על הגדרת TLS ב-Apigee Edge Microgateway. הסרטון הזה מספק סקירה כללית על TLS ועל חשיבותו, מציג את TLS ב-Edge Microgateway ומדגים איך להגדיר TLS בכיוון אחד לכיוון צפון. |
הגדרת TLS דו-כיווני צפונה | זה הסרטון השני על הגדרת TLS ב-Apigee Edge Microgateway. בסרטון הזה מוסבר איך להגדיר TLS דו-כיווני לכיוון צפון. |
הגדרת TLS (אבטחת שכבת התעבורה) חד-כיוונית ודו-כיוונית לדרום (TLS) | הסרטון השלישי הזה, שמסביר איך להגדיר TLS ב-Apigee Edge Microgateway, מסביר איך להגדיר TLS (אבטחת שכבת התעבורה) חד-כיוונית ודו-כיוונית לכיוון דרום. |
באפשרותך להגדיר את שרת ה-Microgateway להשתמש ב-SSL. לדוגמה, עם הגדרת SSL, תוכלו להפעיל ממשקי API דרך Edge Microgateway באמצעות הפרוטוקול "https", באופן הבא:
https://localhost:8000/myapi
כדי להגדיר SSL בשרת Microgateway, בצע את השלבים הבאים:
- תוכלו ליצור או לקבל אישור ומפתח SSL באמצעות כלי השירות openssl או בשיטה הרצויה לכם.
- יש להוסיף את המאפיין
edgemicro:ssl
לקובץ התצורה של 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 requestCert: true
- מפעילים מחדש את 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
רשימה של כל אפשרויות השרתים הנתמכים:
אפשרות | תיאור |
---|---|
key |
נתיב לקובץ ca.key (בפורמט PEM). |
cert |
נתיב לקובץ ca.cert (בפורמט PEM). |
pfx |
נתיב לקובץ pfx שמכיל את המפתח הפרטי, האישור ואישורי ה-CA
של הלקוח בפורמט PFX. |
passphrase |
מחרוזת שמכילה את ביטוי הסיסמה למפתח הפרטי או ל-PFX. |
ca |
נתיב לקובץ שמכיל רשימה של אישורים מהימנים בפורמט PEM. |
ciphers |
מחרוזת שמתארת את הצפנים שצריך להשתמש בהם, מופרדים באמצעות ":". |
rejectUnauthorized |
אם הערך הוא True, אישור השרת מאומת מול הרשימה של רשויות האישורים שסופקו. אם האימות ייכשל, תוחזר שגיאה. |
secureProtocol |
שיטת ה-SSL שבה יש להשתמש. לדוגמה, שיטת SSLv3_method כדי לכפות את השימוש ב-SSL בגרסה 3. |
servername |
שם השרת לתוסף TLS SNI (Server Name Indication). |
requestCert |
True עבור SSL דו-כיווני; False עבור SSL חד-כיווני |
שימוש באפשרויות SSL/TLS של לקוח
אפשר להגדיר את Edge Microgateway כך שיהיה לקוח TLS או SSL במהלך התחברות לנקודות קצה (endpoint) של יעד. בקובץ התצורה של Microgateway, משתמשים ברכיב היעדים כדי להגדיר אפשרויות של SSL או TLS.
בדוגמה הבאה מופיעות הגדרות שיחולו על כל המארחים:
edgemicro: ... targets: ssl: client: key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
בדוגמה הזו, ההגדרות חלות רק על המארח שצוין:
edgemicro: ... 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:
edgemicro: ... targets: - host: 'myserver.example.com' tls: client: pfx: /Users/myname/twowayssl/ssl/client.pfx passphrase: admin123 rejectUnauthorized: true
רשימה של כל אפשרויות הלקוח הנתמכות:
אפשרות | תיאור |
---|---|
pfx |
נתיב לקובץ pfx שמכיל את המפתח הפרטי, האישור ואישורי ה-CA
של הלקוח בפורמט PFX. |
key |
נתיב לקובץ ca.key (בפורמט PEM). |
passphrase |
מחרוזת שמכילה את ביטוי הסיסמה למפתח הפרטי או ל-PFX. |
cert |
נתיב לקובץ ca.cert (בפורמט PEM). |
ca |
נתיב לקובץ שמכיל רשימה של אישורים מהימנים בפורמט PEM. |
ciphers |
מחרוזת שמתארת את הצפנים שצריך להשתמש בהם, מופרדים באמצעות ":". |
rejectUnauthorized |
אם הערך הוא True, אישור השרת מאומת מול הרשימה של רשויות האישורים שסופקו. אם האימות ייכשל, תוחזר שגיאה. |
secureProtocol |
שיטת ה-SSL שבה יש להשתמש. לדוגמה, שיטת SSLv3_method כדי לכפות את השימוש ב-SSL בגרסה 3. |
servername |
שם השרת לתוסף TLS SNI (Server Name Indication). |
התאמה אישית של שרת proxy לאימות קצה
כברירת מחדל, Edge Microgateway משתמש בשרת proxy שנפרס ב-Apigee Edge לאימות OAuth2.
שרת ה-proxy הזה נפרס כשמריצים את edgemicro configure
בפעם הראשונה. אפשר לשנות את הגדרת ברירת המחדל של שרת ה-proxy הזה כדי להוסיף תמיכה בהצהרות בהתאמה אישית לאסימון אינטרנט (JWT) של JSON, להגדיר תפוגה של אסימון וליצור אסימוני רענון. פרטים נוספים זמינים בדף edgemicro-auth ב-GitHub.
שימוש בשירות אימות מותאם אישית
כברירת מחדל, Edge Microgateway משתמש בשרת proxy שנפרס ב-Apigee Edge לאימות OAuth2.
שרת ה-proxy הזה נפרס כשמריצים את 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 וגם לקובץ יומן.
איך להגדיר את רמת הרישום ביומן
אפשר להגדיר את רמות היומן הבאות: מידע, אזהרה ושגיאה. מומלץ להשתמש ברמת המידע. היא מתעדת את כל הבקשות והתגובות של ה-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
מידע על התוכן של קובצי יומן
נוסף בגרסה 2.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 – תלוי בהקשר. הערך יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. הנתונים יכולים להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להזהיר כשיש אזהרות או שגיאה לגבי שגיאות.
- 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 – תלוי בהקשר. הערך יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. הנתונים יכולים להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להזהיר כשיש אזהרות או שגיאה לגבי שגיאות.
- treq – זיהוי האירוע. במקרה הזה, בקשת יעד.
- m - פועל ה-HTTP שבו נעשה שימוש בבקשת היעד.
- u - החלק בכתובת ה-URL שמופיע אחרי נתיב הבסיס.
- h - מספר המארח והיציאה של יעד הקצה העורפי.
- i - המזהה של הרשומה ביומן. המזהה יופיע בכל ארבע הרשומות של האירועים.
3. דגימה של התשובות הנכנסות מהיעד
1436403888672 info tres s=200, d=7, i=0
1436403888651 – חותמת תאריך של Unix
- info – תלוי בהקשר. הערך יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. הנתונים יכולים להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להזהיר כשיש אזהרות או שגיאה לגבי שגיאות.
- tres – מזהה את האירוע. במקרה הזה, יעד התגובה.
- s - הסטטוס של תגובת HTTP.
- d - משך הזמן באלפיות השנייה. הזמן שנדרש להפעלת ה-API על ידי היעד.
- i - המזהה של הרשומה ביומן. המזהה יופיע בכל ארבע הרשומות של האירועים.
4. דוגמה לתשובה יוצאת ללקוח
1436403888676 info res s=200, d=11, i=0
1436403888651 – חותמת תאריך של Unix
- info – תלוי בהקשר. הערך יכול להיות מידע, אזהרה או שגיאה, בהתאם לרמת היומן. הנתונים יכולים להיות נתונים סטטיסטיים לרשומת נתונים סטטיסטיים, להזהיר כשיש אזהרות או שגיאה לגבי שגיאות.
- res – זיהוי האירוע. במקרה הזה, תגובה ללקוח.
- s - הסטטוס של תגובת HTTP.
- d - משך הזמן באלפיות השנייה. זהו הזמן הכולל שנדרש לקריאה ל-API, כולל הזמן שנדרש ל-API לטירגוט והזמן שנדרש ל-Edge Microgateway עצמו.
- i - המזהה של הרשומה ביומן. המזהה יופיע בכל ארבע הרשומות של האירועים.
תזמון קובץ היומן
מתבצעת רוטציה של קובצי יומן במרווח הזמן שצוין באמצעות מאפיין ההגדרה rotate_interval. המערכת תמשיך להוסיף ערכים לאותו קובץ יומן עד לסיום מרווח הסבב. עם זאת, בכל הפעלה מחדש של Edge Microgateway, הוא מקבל UID חדש ויוצר קבוצה חדשה של קובצי יומן עם ה-UID הזה. למידע נוסף: שיטות מומלצות לתחזוקה של קובצי יומן.
הודעות שגיאה
חלק מהרשומות ביומן יכילו הודעות שגיאה. כדי להבין איפה ולמה השגיאות מתרחשות, אפשר לעיין בחומר העזר בנושא שגיאות Edge Microgateway.
הסבר על הגדרת Edge Microgateway
המיקום של קובץ התצורה
מאפייני ההגדרות האישיות שמתוארים בקטע הזה נמצאים בקובץ התצורה של Edge Microgateway. למידע נוסף, ראו ביצוע שינויים בהגדרות.
מאפייני edge_config
ההגדרות האלה משמשות להגדרת האינטראקציה בין מכונת Edge Microgateway לבין Apigee Edge.
- bootrap (ברירת מחדל: ללא) כתובת URL שמפנה לשירות ספציפי של Edge Microgateway שפועל ב-Apigee Edge. Edge Microgateway משתמש בשירות הזה כדי לתקשר עם Apigee Edge. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה ליצירת זוג מפתחות ציבורי/פרטי:
edgemicro genkeys
. לפרטים נוספים, אפשר לקרוא את המאמר בנושא הגדרה והגדרה של מיקרו-שער של Edge. - jwt_public_key: (ברירת מחדל: אין) כתובת URL שמפנה לשרת ה-proxy של Edge Microgateway שנפרס ב-Apigee Edge. שרת ה-proxy הזה משמש כנקודת קצה לאימות לצורך הנפקת אסימוני גישה חתומים ללקוחות. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה לפריסת שרת ה-Proxy: edgemicro configuration. לפרטים נוספים, אפשר לקרוא את המאמר בנושא הגדרה והגדרה של מיקרו-שער של Edge.
- quotaUri: צריך להגדיר את מאפיין התצורה הזה אם רוצים לנהל את המכסות באמצעות שרת ה-proxy של
edgemicro-auth
שנפרס בארגון. אם לא מגדירים את המאפיין הזה, ברירת המחדל של נקודת הקצה של המכסה היא נקודת הקצה הפנימית של Edge Microgateway.edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
כדי להשתמש בתכונה הזו, צריך קודם לפרוס בארגון את גרסה 3.0.5 ואילך של שרת ה-proxy של
edgemicro-auth
. לפרטים נוספים אפשר לעיין במאמר בנושא שדרוג של שרת ה-proxy של edgemicro-auth.
מאפייני Edgemicro
ההגדרות האלה מגדירות את תהליך המיקרו-שער של Edge.
- port: (ברירת מחדל: 8000) מספר היציאה שאליו מאזין התהליך של Edge Microgateway.
- max_connections: (ברירת מחדל: -1) מציין את המספר המקסימלי של חיבורים נכנסים בו-זמנית ש-Edge Microgateway יכול לקבל. במקרה של חריגה מהמספר הזה, מוחזר הסטטוס הבא:
res.statusCode = 429; // Too many requests
- max_connections_hard: (ברירת מחדל: -1) המספר המקסימלי של בקשות בו-זמנית ש-Edge Microgateway יכול לקבל לפני כיבוי החיבור. ההגדרה הזו נועדה למנוע התקפות של מניעת שירות (DoS). בדרך כלל, מגדירים אותו למספר גדול מ-max_ ביחדs.
-
רישום ביומן:
-
level: (ברירת מחדל: שגיאה)
- info – התיעוד של כל הבקשות והתגובות הזורמות דרך מכונת Edge Microgateway.
- warn – רישום של הודעות אזהרה בלבד.
- error – מתעדת הודעות שגיאה בלבד.
- dir: (ברירת מחדל: /var/tmp) הספרייה שבה מאוחסנים קובצי היומן.
- stats_log_interval: (ברירת מחדל: 60) מרווח בשניות, כאשר רשומת הנתונים הסטטיסטיים נכתבת בקובץ היומן של ה-API.
- rotate_interval: (ברירת מחדל: 24) מרווח, בשעות, כשמתבצעת רוטציה של קובצי יומן.
-
level: (ברירת מחדל: שגיאה)
- יישומי פלאגין: יישומי פלאגין מוסיפים פונקציונליות ל-Edge Microgateway. לפרטים על פיתוח יישומי פלאגין, מומלץ לקרוא את המאמר פיתוח יישומי פלאגין מותאמים אישית.
- dir: נתיב יחסי מספריית ./gateway לספרייה ./Plugins או מנתיב מוחלט.
- sequence: רשימה של מודולים של פלאגין להוספה למכונה של Edge Microgateway. המודולים יפעלו לפי הסדר שבו הם מצוינים כאן.
-
ניפוי באגים: הוספת ניפוי באגים מרחוק לתהליך Microgateway של Edge.
- port: מספר היציאה שצריך להאזין לו. לדוגמה, צריך להגדיר את הכלי לניפוי באגים בסביבת הפיתוח המשולבת (IDE) כך שיאזין ביציאה הזו.
- args: ארגומנטים לתהליך ניפוי הבאגים. לדוגמה:
args --nolazy
- config_change_poll_interval: (ברירת מחדל: 600 שניות) Edge Microgateway
טוען תצורה חדשה מדי פעם ומבצע טעינה מחדש אם משהו השתנה. הסקר מאפשר לזהות את כל השינויים שבוצעו ב-Edge (שינויים במוצרים, שרתי proxy שתומכים ב-microgateway וכו') וגם את השינויים שבוצעו בקובץ התצורה המקומי.
- disable_config_poll_interval: (ברירת מחדל: false) מגדירים את הערך true כדי לכבות את תשאול השינוי האוטומטי.
- request_timeout: הגדרה של זמן קצוב לתפוגה עבור בקשות ליעד. הזמן הקצוב לתפוגה מוגדר בשניות. אם הזמן הקצוב פג, Edge Microgateway מגיב עם קוד סטטוס 504. (נוסף v2.4.x)
מאפייני כותרות
ההגדרות האלה קובעות את אופן הטיפול בכותרות HTTP מסוימות.
- x-forwarded-for: (ברירת מחדל: true) יש להגדיר את הערך false כדי למנוע העברה של כותרות מסוג x-forwarded-for ליעד. הערה: אם הבקשה מכילה כותרת x-forwarded-for, הערך שלה יוגדר לערך client-ip ב-Edge Analytics.
- 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 כדי למנוע העברה של כותרות דרך ליעד.
מאפייני oauth
ההגדרות האלה קובעות את האופן שבו אימות הלקוח נאכף על ידי Edge Microgateway.
- allowNoAuthorization: (ברירת מחדל: false) אם היא מוגדרת כ-True, קריאות ל-API יכולות לעבור דרך Edge Microgateway בלי בכלל כותרת Authorization. מגדירים את הערך כ-False כדי לדרוש כותרת הרשאה (ברירת מחדל).
- allowInvalidAuthorization: (ברירת מחדל: false) אם היא מוגדרת כ-True, קריאות ל-API מורשות להעביר אם האסימון שהועבר בכותרת Authorization לא תקין או שתוקפו פג. אם מגדירים את הערך הזה כ-FALSE כדי לדרוש אסימונים תקפים (ברירת מחדל).
- authorization-header: (ברירת המחדל: Authorization: Bearer) הכותרת המשמשת לשליחת אסימון הגישה אל Edge Microgateway. כדאי לשנות את ברירת המחדל במקרים שבהם היעד צריך להשתמש בכותרת Authorization למטרה אחרת.
- api-key-header: (ברירת מחדל: x-api-key) שם הכותרת או פרמטר השאילתה שמשמש להעברת מפתח API אל Edge Microgateway. למידע נוסף, ראו שימוש במפתח API.
- keep-authorization-header: (ברירת מחדל: false) אם היא מוגדרת כ-true, כותרת ההרשאה שנשלחת בבקשה מועברת ליעד (היא נשמרת).
- allowOAuthOnly – אם המדיניות מוגדרת כ-True, לכל ממשק API חייב להיות כותרת Authorization עם אסימון גישה למוכ"ז. מאפשרת לאשר רק את מודל האבטחה של OAuth (תוך שמירה על תאימות לאחור). (נוסף 2.4.x)
- allowAPIKeyOnly -- אם היא מוגדרת כ-True, לכל ממשק API חייבת להיות כותרת x-api-key (או מיקום מותאם אישית) עם מפתח API.מאפשרת להתיר רק את מודל האבטחה של מפתח ה-API (תוך שמירה על תאימות לאחור). (נוסף 2.4.x)
- gracePeriod – הפרמטר הזה עוזר למנוע שגיאות שנגרמות עקב אי-התאמות קלות בין שעון המערכת לבין השעות מסוג 'לא לפני' (nbf) או 'הונפק בתאריך (iat)' שצוינו באסימון האימות של JWT. צריך להגדיר את הפרמטר הזה למספר השניות כדי לאפשר אי-התאמות כאלה. (נוסף 2.5.7)
מאפיינים ספציפיים לפלאגין
ראה 'שימוש ביישומי פלאגין' לקבלת פרטים על מאפיינים הניתנים להגדרה עבור כל פלאגין.
סינון שרתי proxy
אפשר לסנן אילו שרתי proxy בעלי מודעות ל-microgateway יעבד מכונת Edge Microgateway.
כש-Edge Microgateway מופעל, הוא מוריד את כל שרתי ה-proxy המותאמים ל-Microgateway בארגון שאליו הוא משויך. ניתן להשתמש בתצורה הבאה כדי להגביל את שרתי ה-proxy
שהמיקרו-שער יעבד. לדוגמה, ההגדרה הזו מגבילה את שרתי ה-proxy שהמיקרו-שער יעבד לשלושה: edgemicro_proxy-1
, edgemicro_proxy-2
ו-edgemicro_proxy-3
:
proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
הגדרת תדירות דחיפה של Analytics
פרמטרי התצורה הבאים מאפשרים לקבוע את התדירות שבה Edge Microgateway שולח נתוני ניתוח אל Apigee:
- bufferSize (אופציונלי): המספר המקסימלי של רשומות Analytics שהמאגר הזמני יכול להחזיק לפני שמתחילים לשחרר את הרשומות הישנות ביותר. ברירת מחדל: 10,000
- batchSize (אופציונלי): הגודל המקסימלי של קבוצת רשומות Analytics שנשלחה אל Apigee. ברירת מחדל: 500
- flushInterval (אופציונלי): מספר אלפיות השנייה בין כל רצף של רשומות ניתוח שנשלחו אל Apigee. ברירת מחדל: 5,000
לדוגמה:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
אנונימיזציה של נתוני ניתוח
ההגדרות הבאות מונעות הצגה של מידע על נתיב הבקשה ב-Edge Analytics. מוסיפים את הקוד הבא לתצורת המיקרו-שער כדי לבצע אנונימיזציה של ה-URI של הבקשה ו/או של נתיב הבקשה. לתשומת לבך, ה-URI מורכב משם המארח ומחלקי נתיב של הבקשה.
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
הפרדה של קריאות ל-API ב-Edge Analytics
אפשר להגדיר את הפלאגין של Analytics כך שיפריד נתיב API ספציפי, כך שהוא יופיע כשרת proxy נפרד במרכזי השליטה של Edge Analytics. לדוגמה, אפשר להפריד ממשק API לבדיקת תקינות במרכז הבקרה כדי לא לבלבל אותו עם קריאות בפועל לשרת ה-API. במרכז השליטה של Analytics, שרתי proxy נפרדים פועלים לפי תבנית השמות הבאה:
edgemicro_proxyname-health
בתמונה הבאה מוצגים שני שרתי proxy נפרדים במרכז הבקרה של Analytics: edgemicro_hello-health
ו-edgemicro_mock-health
:
תוכלו להשתמש בפרמטרים הבאים כדי להפריד בין נתיבים יחסיים ומוחלטים במרכז הבקרה של Analytics כשרתי proxy נפרדים:
- relativePath (אופציונלי): מציין נתיב יחסי להפרדה במרכז הבקרה של Analytics. לדוגמה, אם מציינים
/healthcheck
, כל הקריאות ל-API שמכילות את הנתיב/healthcheck
יופיעו במרכז הבקרה בתורedgemicro_proxyname-health
. שים לב שהסימון הזה מתעלם מנתיב הבסיס של שרת ה-proxy. כדי לבצע הפרדה על סמך נתיב מלא, כולל נתיב בסיסי, יש להשתמש בדגלproxyPath
. - proxyPath (אופציונלי): מציין נתיב מלא של שרת proxy ל-API, כולל נתיב הבסיס של שרת ה-proxy, להפרדה במרכז הבקרה של Analytics. לדוגמה, אם מציינים
/mocktarget/healthcheck
, שבו/mocktarget
הוא נתיב הבסיס של שרת ה-proxy, כל הקריאות ל-API עם הנתיב/mocktarget/healthcheck
יופיעו במרכז הבקרה בתורedgemicro_proxyname-health
.
לדוגמה, לפי התצורה הבאה, כל נתיב API שמכיל /healthcheck
יופרד על ידי הפלאגין של Analytics. כלומר, /foo/healthcheck
ו-/foo/bar/healthcheck
יופרדו כשרת proxy נפרד שנקרא edgemicro_proxyname-health
במרכז הבקרה של Analytics.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 relativePath: /healthcheck
בהגדרה הבאה, כל API עם נתיב שרת ה-proxy /mocktarget/healthcheck
יופרד כשרת proxy נפרד שנקרא edgemicro_proxyname-health
במרכז הבקרה של ניתוח נתונים.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 proxyPath: /mocktarget/healthcheck
הגדרה של Edge Microgateway מאחורי חומת אש של החברה
גרסה 2.4.x נתמכת
אם Edge Microgateway מותקן מאחורי חומת אש, יכול להיות שהשער לא יוכל לתקשר עם Apigee Edge. במקרה כזה, יש שתי אפשרויות:
אפשרות 1:
האפשרות הראשונה היא להגדיר את האפשרות edgemicro: proxy_tunnel כ-true בקובץ התצורה של ה-microgateway:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: true
כשהערך של proxy_tunnel הוא true, Edge Microgateway משתמש בשיטת HTTP CONNECT כדי לנתב בקשות HTTP בחיבור TCP יחיד. (אותו הדבר נכון אם משתני הסביבה להגדרת שרת ה-proxy מופעלים באמצעות TLS).
אפשרות 2:
האפשרות השנייה היא לציין שרת proxy ולהגדיר את proxy_tunnel כ-FALSE בקובץ התצורה של ה-microgateway. לדוגמה:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: false
במקרה כזה, תוכלו להגדיר את המשתנים הבאים כדי לשלוט במארחים לכל שרת proxy של HTTP שבו אתם רוצים להשתמש, או אילו מארחים לא יטפלו בשרתי proxy של Edge Microgateway: HTTP_PROXY, HTTPS_PROXY ו-NO_PROXY.
ניתן להגדיר את NO_PROXY כרשימה מופרדת בפסיקים של דומיינים שאליהם Microgateway לא אמור לשמש כשרת proxy. לדוגמה:
export NO_PROXY='localhost,localhost:8080'
מגדירים את HTTP_PROXY ו-HTTPS_PROXY לנקודת הקצה של שרת ה-HTTP Proxy Edge Microgateway יכולים לשלוח הודעות לשרת. לדוגמה:
export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786'
מידע נוסף על המשתנים האלה זמין בכתובת https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
כדאי לעיין גם בפרטים הבאים
איך להגדיר את Edge Microgateway מאחורי חומת אש של חברה בקהילת Apigee.
שימוש בתווים כלליים לחיפוש בשרתי proxy של Microgateway
אפשר להשתמש בתו כללי לחיפוש '*' אחד או יותר בנתיב הבסיס של שרת proxy ל-edgemicro_* (Microgateway-aware). לדוגמה, נתיב בסיסי של
/team/*/members מאפשר ללקוחות לקרוא
https://[host]/team/blue/members ו-
https://[host]/team/green/members ללא צורך ליצור שרתי proxy חדשים של API
כדי לתמוך בצוותים חדשים. לתשומת ליבך: /**/
לא נתמך.
חשוב: ב-Apigee אין תמיכה בשימוש בתו כללי לחיפוש "*" בתור
הרכיב הראשון של נתיב בסיסי. לדוגמה, ערך זה אינו נתמך: חיפוש /*/
.
סיבוב מקשי JWT
זמן מה אחרי היצירה הראשונית של JWT, יכול להיות שתצטרכו לשנות את זוג המפתחות הציבורי/הפרטי שמאוחסן ב-KVM המוצפן באמצעות Edge. התהליך הזה של יצירת זוג מפתחות חדש נקרא רוטציית מפתחות.
איך Edge Microgateway משתמש ב-JWT
אסימון אינטרנט מסוג JSON (JWT) הוא תקן אסימון שמתואר ב-RFC7519. JWT מספק דרך לחתום על סדרת תביעות, שאפשר לאמת אותן באופן מהימן על ידי המקבל של ה-JWT.
Edge Microgateway משתמש באסימוני JWT למוכ"ז לצורך אבטחת OAuth. כשיוצרים אסימון OAuth ל-Edge Microgateway, מקבלים בחזרה JWT. לאחר מכן אפשר להשתמש ב-JWT בכותרת Authorization בקריאות ל-API. לדוגמה:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
יצירת JWT חדש
אפשר ליצור JWT ל-Edge Microgateway באמצעות הפקודה edgemicro token
או API. לדוגמה:
edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
הפקודה הזו מבקשת מ-Apigee Edge ליצור JWT שאפשר להשתמש בו כדי לאמת קריאות ל-API. הפרמטרים -i
ו--s
הם מזהה הצרכן והערכים הסודיים של אפליקציה למפתחים
בארגון Apigee Edge.
לחלופין, אפשר גם ליצור JWT באמצעות ממשק ה-API לניהול:
curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "your consumer key", "client_secret": "your consumer secret", "grant_type": "client_credentials" }'
כאשר:
- org זהו שם הארגון שלך ב-Edge (עליך להיות מנהל מערכת ארגוני).
- הסביבה env היא בארגון שלך (למשל test או prod).
- client_id הוא מזהה הצרכן באפליקציה למפתחים שיצרת בעבר.
- client_secret הוא סוד הצרכן באפליקציה למפתחים שיצרת בעבר.
מה זה רוטציית מפתחות?
זמן מה אחרי היצירה הראשונית של JWT, יכול להיות שתצטרכו לשנות את זוג המפתחות הציבורי/הפרטי שמאוחסן ב-KVM המוצפן באמצעות Edge. התהליך הזה של יצירת זוג מפתחות חדש נקרא רוטציית מפתחות. כשמסובבים מפתחות, נוצר זוג מפתחות פרטי/ציבורי חדש ומאוחסן ב-KVM של "microgateway" בסביבה או בארגון של Apigee Edge. בנוסף, המפתח הציבורי הישן נשמר יחד עם הערך של מזהה המפתח המקורי.
כדי ליצור JWT, Edge משתמש במידע שמאוחסן ב-KVM המוצפן.
KVM בשם microgateway
נוצר ואכלס את המפתחות בזמן ההגדרה הראשונית (ההגדרה)
של Edge Microgateway. המפתחות ב-KVM משמשים לחתימה ולהצפנה של JWT.
מפתחות ה-KVM כוללים:
-
private_key – מפתח ה-RSA הפרטי האחרון (החדש ביותר) המשמש לחתימה על אסימוני JWT.
-
public_key – האישור האחרון (החדש ביותר) המשמש לאימות אסימוני JWT שנחתמו באמצעות ה-private_key.
-
private_key_kid – מזהה המפתח הפרטי האחרון (החדש ביותר). מזהה המפתח הזה משויך לערך Private_key ומשמש לתמיכה ברוטציית מפתחות.
-
public_key1_kid – מזהה המפתח הציבורי האחרון (החדש ביותר). המפתח הזה משויך לערך Public_key1 והוא משמש לתמיכה ברוטציית מפתחות. הערך הזה זהה לערך של הילד או הילדה של המפתח הפרטי.
-
public_key1 - המפתח הציבורי האחרון (שנוצר לאחרונה).
כשמבצעים רוטציית מפתחות, ערכי המפתחות הקיימים מוחלפים במפה ומפתחות חדשים מתווספים כדי לשמור את המפתחות הציבוריים הישנים. לדוגמה:
-
public_key2_kid - המזהה של המפתח הציבורי הישן. המפתח הזה משויך לערך Public_key2 והוא משמש לתמיכה ברוטציית מפתחות.
-
public_key2 - המפתח הציבורי הישן.
אסימוני JWT שמוצגים לאימות יאומתו באמצעות המפתח הציבורי החדש. אם האימות ייכשל, נשתמש במפתח הציבורי הישן עד שהתוקף שלו יפוג (אחרי 30 דקות). כך אפשר "לסובב" מפתחות בלי לשבש באופן מיידי את תנועת ה-API.
איך מבצעים רוטציית מפתחות
בקטע הזה מוסבר איך לבצע רוטציית מפתחות.
אם הגדרת את מכונת Edge Microgateway לפני גרסה 2.5.2
אם המכונה של Edge Microgateway נוצרה לפני גרסה 2.5.2, צריך להריץ את שתי הפקודות הבאות כדי לשדרג את ה-KVM ואת מדיניות האימות:
upgradekvm -o org -e env -u username
מידע נוסף על הפקודה הזו זמין במאמר שדרוג ה-KVM.
הפקודה הבאה משדרגת את שרת ה-Proxy מסוג edgemicro-oauth שנפרס בארגון Apigee כשהגדרת את Edge Microgateway. שרת ה-proxy הזה מספק שירותים שדרושים ליצירת אסימונים.
upgradeauth -o org -e env -u username
למידע נוסף על הפקודה הזו תוכלו לקרוא את המאמר שדרוג של שרת proxy ל-edgemicro-auth.
סיבוב המקשים
מוסיפים את השורה הבאה לקובץ ~/.edgemicro/org-env-config.yaml
, שבו צריך לציין את אותו הארגון והסביבה שבהם הגדרתם את המיקרו-גייט להשתמש:
jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'
כדי לסובב את המקשים, מריצים את הפקודה של רוטציית המפתחות. (למידע נוסף על הפקודה הזו, ראו סיבוב מקשים).
edgemicro rotatekey -o org -e env -u username -k kid_value
לדוגמה:
edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2 current nodejs version is v12.5.0 current edgemicro version is 3.0.2 password: Checking if private key exists in the KVM... Checking for certificate... Found Certificate Generating New key/cert pair... Extract new public key Key Rotation successfully completed!
הפרמטר -k
מציין מזהה מפתח (kid). המזהה הזה משמש להתאמה של מפתח ספציפי.
Edge Microgateway משתמש בערך הזה כדי לבחור מתוך קבוצת מקשים במהלך רוטציית המקשים. למידע נוסף, ראו סעיף 4.5 במפרט מפתח האינטרנט של JSON.
אחרי רוטציית המפתחות, Edge מחזירה מספר מקשים ל-Edge Microgateway. בדוגמה הבאה יש לשים לב שלכל מפתח יש ערך 'kid' (מזהה מפתח) ייחודי. לאחר מכן, המיקרו-שער משתמש במפתחות האלה כדי לאמת את אסימוני ההרשאה. אם אימות האסימון נכשל, המיקרו-גייטוויי מחפש אם יש מפתח ישן יותר בקבוצת המפתחות ומנסה את המפתח הזה. הפורמט של המפתחות שהוחזרו הוא מפתח האינטרנט JSON (JWK). אפשר לקרוא על הפורמט הזה ב-RFC 7517.
{ "keys": [ { "kty": "RSA", "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ", "e": "AQAB", "kid": "2" }, { "kty": "RSA", "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw", "e": "AQAB", "kid": "1" } ] }
סינון שרתי proxy שהורדו
כברירת מחדל, Edge Microgateway מוריד את כל שרתי ה-proxy של ארגון Edge שלך שמתחילים בקידומת השם "edgemicro_". אפשר לשנות את ברירת המחדל כדי להוריד שרתי proxy שהשמות שלהם תואמים לתבנית מסוימת.
- פותחים את קובץ התצורה של Edge Micro:
~/.edgemicro/org-env-config.yaml
- מוסיפים את הרכיב proxyPattern בקטע edge_config. לדוגמה, התבנית הבאה
תוריד שרתי proxy כמו edgemicro_foo, edgemicro_fast ו-edgemicro_first.
edge_config: … proxyPattern: edgemicro_f*
ציון מוצרים ללא שרתי proxy ל-API
ב-Apigee Edge אפשר ליצור מוצר API שלא מכיל שרתי proxy של API. ההגדרה הזו של המוצר מאפשרת למפתח API שמשויך למוצר לפעול עם כל שרת proxy שנפרס בארגון. החל מגרסה 2.5.4, Edge Microgateway תומך בהגדרת המוצר הזו.
ניפוי באגים ופתרון בעיות
התחברות לכלי לניפוי באגים
אפשר להריץ את Edge Microgateway באמצעות כלי לניפוי באגים, למשל node-inspector. הפעולה הזו שימושית לפתרון בעיות ולניפוי באגים ביישומי פלאגין מותאמים אישית.
- מפעילים מחדש את Edge Microgateway במצב ניפוי באגים. כדי לעשות את זה, צריך להוסיף את הקוד
DEBUG=*
בתחילת הפקודהstart
. לדוגמה:DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
- מפעילים את הכלי לניפוי באגים ומגדירים לו האזנה למספר היציאה לתהליך ניפוי הבאגים.
- עכשיו אפשר להתקדם בקוד Edge Microgateway, להגדיר נקודות עצירה, להציג ביטויי צפייה ועוד.
ניתן לציין דגלי Node.js רגילים שקשורים למצב ניפוי באגים. לדוגמה, התג --nolazy
עוזר לנפות באגים בקוד אסינכרוני.
קובצי היומן בבדיקה
אם נתקלתם בבעיות, כדאי לבדוק את קובצי היומן כדי לראות את פרטי הביצוע ואת פרטי השגיאות. מידע נוסף מופיע במאמר בנושא ניהול קובצי יומן.
שימוש באבטחת מפתחות API
מפתחות API מספקים מנגנון פשוט לאימות לקוחות ששולחים בקשות אל Edge Microgateway. אפשר לקבל מפתח API על ידי העתקת הערך של מפתח הצרכן (שנקרא גם Client ID) ממוצר של Apigee Edge שכולל את שרת ה-proxy לאימות של Edge Microgateway.
שמירה של מפתחות במטמון
מפתחות ה-API מועברים באסימונים למוכ"ז, והם נשמרים במטמון. אפשר להשבית את השמירה במטמון על ידי הגדרת הכותרת Cache-Control: no-cache
בבקשות נכנסות ל-Edge Microgateway.
שימוש במפתח API
אפשר להעביר את מפתח ה-API בבקשת ה-API כפרמטר של שאילתה או ככותרת. כברירת מחדל, הכותרת ושם הפרמטר של השאילתה הם x-api-key
.
דוגמה לפרמטר של שאילתה:
curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz
דוגמה לכותרת:
curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
הגדרה של שם מפתח ה-API
כברירת מחדל, x-api-key
הוא השם המשמש גם לכותרת של מפתח ה-API וגם לפרמטר השאילתה.
ניתן לשנות את ברירת המחדל בקובץ התצורה, כפי שמוסבר במאמר ביצוע שינויים בתצורה. לדוגמה, כדי לשנות את השם ל-apiKey:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false api-key-header: apiKey
בדוגמה הזו, גם פרמטר השאילתה וגם שם הכותרת משתנים ל-apiKey
. השם
x-api-key
לא יפעל יותר בשני המקרים. למידע נוסף, ראו ביצוע שינויים בהגדרות.
לדוגמה:
curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
למידע נוסף על השימוש במפתחות API עם בקשות לשרת proxy, אפשר לעיין במאמר Secure Edge Microgateway.
הפעלת קודי תגובה של upstream
כברירת מחדל, הפלאגין oauth
מחזיר רק קודי סטטוס של שגיאה 4xx, אם
התגובה אינה בסטטוס 200. אפשר לשנות את ההתנהגות הזו כך שתמיד
תחזיר את הקוד 4xx או 5xx המדויק, בהתאם לשגיאה. (פורסם בגרסה 3.0.7)
כדי להפעיל את התכונה הזו, צריך להוסיף את המאפיין oauth.useUpstreamResponse: true
להגדרה של Edge Microgateway. לדוגמה:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false gracePeriod: 10 useUpstreamResponse: true
שימוש באבטחת אסימון OAuth2
בקטע הזה מוסבר איך לקבל אסימוני גישה מסוג OAuth2 ואסימוני רענון. אסימוני הגישה משמשים לביצוע קריאות מאובטחות ל-API דרך המיקרו-שער. אסימוני רענון משמשים להשגת אסימוני גישה חדשים.
איך מקבלים אסימון גישה
בקטע הזה מוסבר איך להשתמש בשרת ה-proxy של edgemicro-auth
כדי לקבל אסימון גישה.
אפשר לקבל אסימון גישה גם באמצעות הפקודה edgemicro token
CLI.
מידע נוסף על ה-CLI זמין במאמר ניהול אסימונים.
API 1: שליחת פרטי כניסה כפרמטרים לגוף
מחליפים את שמות הארגון והסביבה בכתובת ה-URL, מחליפים את הערכים של 'מזהה הצרכן' ו'סוד הצרכן' שהתקבלו מאפליקציה למפתחים ב-Apigee Edge בפרמטרים של הגוף client_id ו-client_secret:
curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \ -d '{"grant_type": "client_credentials", "client_id": "your_client_id", \ "client_secret": "your_client_secret"}' -H "Content-Type: application/json"
API 2: שליחת פרטי כניסה בכותרת 'אימות בסיסי'
שולחים את פרטי הכניסה של הלקוח ככותרת לאימות בסיסי ואת
grant_type
כפרמטר של טופס. גם טופס הפקודה הזה מופיע במאמר RFC 6749: מסגרת ההרשאות של OAuth 2.0.
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
פלט לדוגמה
ה-API מחזיר תגובת JSON. שימו לב שאין הבדל בין הנכסtoken
לנכס access_token
. אפשר להשתמש בכל אחת מהן.
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": "108000" }
איך מקבלים אסימון רענון
כדי לקבל אסימון רענון, צריך לבצע קריאה ל-API לנקודת הקצה /token
של
שרת ה-proxy של edgemicro-auth
. חובה לבצע את הקריאה הזו ל-API עם סוג המענק password
. השלבים הבאים מפרטים את התהליך.
- קבלת אסימון גישה ורענון באמצעות ה-API של
/token
. חשוב לשים לב שסוג המענק הואpassword
:curl -X POST \ https://your_organization-your_environment.apigee.net/edgemicro-auth/token \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq", "client_secret":"bUdDcFgv3nXffnU", "grant_type":"password", "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq", "password":"bUdD2FvnMsXffnU" }'
ה-API יחזיר אסימון גישה ואסימון רענון. התשובה אמורה להיראות כך:
{ "token": "your-access-token", "access_token": "your-access-token", "token_type": "bearer", "expires_in": "108000", "refresh_token": "your-refresh-token", "refresh_token_expires_in": "431999", "refresh_token_issued_at": "1562087304302", "refresh_token_status": "approved" }
- עכשיו אפשר להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש על ידי קריאה
לנקודת הקצה
/refresh
של אותו API. לדוגמה:curl -X POST \ https://willwitman-test.apigee.net/edgemicro-auth/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq", "client_secret":"bUdDc2Fv3nMXffnU", "grant_type":"refresh_token", "refresh_token":"your-refresh-token" }'
ה-API מחזיר אסימון גישה חדש. התגובה נראית כך:
{ "token": "your-new-access-token" }
מעקב לתמיד
Forever הוא כלי Node.js שמבצע הפעלה מחדש באופן אוטומטי של אפליקציית Node.js במקרה שהתהליך מושבת או שיש בו שגיאה. Edge Microgateway כולל קובץ forever.json שאפשר להגדיר כדי לקבוע כמה פעמים ובאילו מרווחי הזמן להפעיל מחדש Edge Microgateway. בקובץ הזה מוגדר שירות Forever בשם forever-monitor, שמנהל באופן פרוגרמטי את Forever.
אפשר למצוא את הקובץ forever.json בספריית ההתקנה ברמה הבסיסית של Edge Microgateway. למידע נוסף, ראו היכן מותקנת אפליקציית Edge Microgateway. מידע נוסף על אפשרויות ההגדרה זמין במסמכי התיעוד בנושא מעקב לתמיד.
הפקודה edgemicro forever
כוללת דגלים שמאפשרים לציין את מיקום הקובץ forever.json
(הדגל -f
), ולהתחיל/להפסיק את תהליך המעקב Forever (הדגל -a
). לדוגמה:
edgemicro forever -f ~/mydir/forever.json -a start
מידע נוסף זמין במאמר Forever Monitoring בחומר העזר בנושא CLI.
ציון נקודת קצה (endpoint) של קובץ תצורה
אם אתם מפעילים כמה מכונות של Edge Microgateway, יכול להיות שתרצו לנהל את ההגדרות שלהן ממקום אחד. כדי לעשות זאת, צריך לציין נקודת קצה (endpoint) ב-HTTP שבה אפשר להוריד את קובץ התצורה של Edge Micro. אפשר לציין את נקודת הקצה הזו כשמפעילים את Edge Micro באמצעות הדגל -u.
לדוגמה:
edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key
שבה נקודת הקצה mgconfig מחזירה את התוכן של קובץ התצורה. זהו הקובץ
שהמיקום שלו, כברירת מחדל, הוא ~/.edgemicro
, עם המוסכמות למתן שמות:
org-env-config.yaml
.
השבתה של אחסון זמני של נתונים בחיבור TCP
אפשר להשתמש במאפיין ההגדרה nodelay
כדי להשבית את מאגר הנתונים הזמני עבור
חיבורי TCP שבהם נעשה שימוש ב-Edge Microgateway.
כברירת מחדל, חיבורי TCP משתמשים באלגוריתם Nagle כדי לאחסן נתונים זמניים לפני השליחה. אם מגדירים את nodelay
ל-true
,
תשבית את ההתנהגות הזו (הנתונים יופעלו באופן מיידי לאחר כל קריאה ל-socket.write()
). לפרטים נוספים, אפשר לעיין גם במשאבי העזרה
של Node.js.
כדי להפעיל את nodelay
, צריך לערוך את קובץ התצורה של Edge Micro באופן הבא:
edgemicro: nodelay: true port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
הפעלת Edge Microgateway במצב עצמאי
אפשר להריץ את Edge Microgateway כשהוא מנותק מכל תלות של Apigee Edge. התרחיש הזה, שנקרא מצב עצמאי, מאפשר להריץ ולבדוק את Edge Microgateway ללא חיבור לאינטרנט.
התכונות הבאות לא פועלות במצב עצמאי כי הן דורשות חיבור ל-Apigee Edge:
- מפתח OAuth ו-API
- מכסה
- ניתוח נתונים
מצד שני, יישומי פלאגין מותאמים אישית ומעצר חד-פעמי פועלים כרגיל, כי הם לא מחייבים חיבור ל-Apigee Edge. בנוסף, פלאגין חדש בשם extauth
מאפשר לאשר קריאות ל-API למיקרו-שער באמצעות JWT במצב עצמאי.
הגדרת השער והפעלתו
כדי להפעיל את Edge Microgateway במצב עצמאי:
- צריך לוודא שמותקנת במכשיר Edge Microgateway מגרסה 3.0.1 ואילך. אחרת, צריך להריץ את הפקודה הבאה כדי לשדרג לגרסה האחרונה:
npm install -g edgemicro
אם אתם זקוקים לעזרה, קראו את המאמר התקנת Edge Microgateway.
- יוצרים קובץ תצורה בשם:
$HOME/.edgemicro/
org_name-
env_name-config.yaml
לדוגמה:
vi $HOME/.edgemicro/foo-bar-config.yaml
- מדביקים את הקוד הבא בקובץ:
edgemicro: port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - extauth - spikearrest headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true extauth: publickey_url: https://www.googleapis.com/oauth2/v1/certs spikearrest: timeUnit: second allow: 10 buffersize: 0
- מייצאים את משתנה הסביבה הבא עם הערך '1':
export EDGEMICRO_LOCAL=1
- מריצים את הפקודה
start
הבאה, שבה מספקים ערכים ליצירת שרת ה-Proxy המקומי:edgemicro start -o org_name -e environment_name -a local_proxy_name \ -v local_proxy_version -t target_url -b base_path
כאשר:
- your_org הוא שם ה-"org" שבו השתמשת בשם קובץ התצורה.
- your_environment הוא שם ה-env שבו השתמשתם בשם קובץ התצורה.
- local_proxy_name הוא השם של שרת ה-proxy המקומי שייווצר. אפשר להשתמש בכל שם שרוצים.
- local_proxy_version הוא מספר הגרסה של שרת ה-proxy.
- target_url היא כתובת ה-URL של היעד של שרת ה-proxy. (ה-target הוא השירות ששרת ה-proxy קורא).
- base_path הוא הנתיב הבסיסי של שרת ה-proxy. הערך צריך להתחיל בקו נטוי קדימה. לנתיב בסיס של הבסיס, יש לציין רק קו נטוי לפנים. לדוגמה, '/'.
לדוגמה:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- בודקים את ההגדרה.
curl http://localhost:8000/echo { "error" : "missing_authorization" }
מאחר שהפלאגין
extauth
נמצא בקובץfoo-bar-config.yaml
, מופיעה השגיאה "missing_authorization". הפלאגין הזה מאמת JWT שחייב להופיע בכותרת Authorization של הקריאה ל-API. בקטע הבא מתקבל JWT שיאפשר קריאות ל-API ללא השגיאה.
דוגמה: קבלת אסימון הרשאה
הדוגמה הבאה מראה איך לקבל JWT מנקודת הקצה של Edge Microgateway JWT ב-Apigee Edge (edgemicro-auth/jwkPublicKeys
).
נקודת הקצה הזו נפרסת כשמבצעים הגדרה והגדרה רגילה של Edge Microgateway.
כדי לקבל את ה-JWT מנקודת הקצה של Apigee, קודם צריך לבצע את ההגדרה הרגילה של Edge Microgateway ולהיות מחוברים לאינטרנט. נקודת הקצה של Apigee משמשת כאן למטרות לדוגמה בלבד
ואינה נדרשת. אם רוצים, אפשר להשתמש בנקודת קצה אחרת של אסימון JWT. אם תעשו זאת, תצטרכו להשיג את ה-JWT באמצעות
ה-API שסופק עבור נקודת הקצה הזו.
בשלבים הבאים מוסבר איך לקבל אסימון באמצעות נקודת הקצה edgemicro-auth/jwkPublicKeys
:
- כדי לפרוס את שרת ה-Proxy של
edgemicro-auth
בארגון או בסביבה ב-Apigee Edge צריך לבצע הגדרה והגדרה סטנדרטיות של Edge Microgateway. אם כבר ביצעת את השלב הזה, אין צורך לחזור עליו. - אם פרסתם את Edge Microgateway ל-Apigee Cloud, אתם צריכים להיות מחוברים לאינטרנט כדי לקבל JWT מנקודת הקצה הזו.
-
עוצרים את Edge Microgateway:
edgemicro stop
- בקובץ התצורה שיצרת קודם לכן (
$HOME/.edgemicro
/org-env-config.yaml
), מכוונים את המאפייןextauth:publickey_url
לנקודת הקצה שלedgemicro-auth/jwkPublicKeys
בארגון או בסביבה של Apigee Edge. לדוגמה:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
מפעילים מחדש את Edge Microgateway כמו קודם, תוך שימוש בשמות הארגון או הסביבות שבהם השתמשתם בשם קובץ התצורה. לדוגמה:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
קבלת אסימון JWT מנקודת הקצה של ההרשאה. מאחר שאתם משתמשים בנקודת הקצה
edgemicro-auth/jwkPublicKeys
, תוכלו להשתמש בפקודה הבאה של ה-CLI:
אפשר ליצור JWT ל-Edge Microgateway באמצעות הפקודה edgemicro token
או API. לדוגמה:
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
כאשר:
- your_org הוא השם של ארגון Apigee שעבורו הגדרת בעבר Edge Microgateway.
- your_env היא סביבה בארגון.
- האפשרות
i
מציינת את מפתח הצרכן מאפליקציה של מפתח שמכילה מוצר שכולל את שרת ה-proxy שלedgemicro-auth
. - האפשרות
s
מציינת את סוד הצרכן מאפליקציית מפתח שמכילה מוצר שכולל את שרת ה-proxyedgemicro-auth
.
הפקודה הזו מבקשת מ-Apigee Edge ליצור JWT שאפשר להשתמש בו כדי לאמת קריאות ל-API.
כדאי לעיין גם במאמר יצירת אסימון.בדיקת התצורה העצמאית
כדי לבדוק את ההגדרות האישיות, צריך לקרוא ל-API עם האסימון שנוסף בכותרת Authorization באופן הבא:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
דוגמה:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
פלט לדוגמה:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
שימוש במצב שרת proxy מקומי
במצב שרת proxy מקומי, Edge Microgateway לא מחייב פריסה של שרת proxy תומך ב-microgateway ב-Apigee Edge. במקום זאת, מגדירים 'שרת proxy מקומי' על ידי ציון שם של שרת proxy מקומי, נתיב בסיסי וכתובת URL של היעד כשאתם מפעילים את המיקרו-שער. לאחר מכן, קריאות ל-API למיקרו-שער נשלחות לכתובת ה-URL של היעד של שרת ה-proxy המקומי. בכל שאר ההיבטים, המצב של שרת ה-proxy המקומי פועל בדיוק כמו הפעלת Edge Microgateway במצב הרגיל. האימות פועל באותו אופן, כמו גם היקף המעצרים והאכיפה של המכסות, יישומי פלאגין מותאמים אישית וכו'.
תרחיש לדוגמה ודוגמה
מצב שרת proxy מקומי שימושי כשיש צורך לשייך רק שרת proxy אחד למכונה של Edge Microgateway. לדוגמה, אתם יכולים להחדיר את Edge Microgateway ל-Kubernetes בתור שרת proxy צדדי, שבו מיקרו-שערה ושירות פועלים כל אחד ב-pod אחד, והמיקרו-שער מנהל את תעבורת הנתונים לשירות הנלווה שלו וממנו. באיור הבא מוצגת הארכיטקטורה שבה Edge Microgateway פועל כשרת proxy חיצוני באשכול Kubernetes. כל מכונה של Microgateway מתקשרת רק עם נקודת קצה אחת בשירות הנלווה שלה:
אחד היתרונות של סגנון הארכיטקטורה הזה הוא ש-Edge Microgateway מספק ניהול API לשירותים נפרדים שנפרסו בסביבת קונטיינר, כמו אשכול Kubernetes.
הגדרת מצב שרת proxy מקומי
כדי להגדיר את Edge Microgateway כך שיפעל במצב proxy מקומי, בצע את השלבים הבאים:
- צריך לוודא שמותקנת במכשיר Edge Microgateway מגרסה 3.0.1 ואילך. אחרת, צריך להריץ את הפקודה הבאה כדי לשדרג לגרסה האחרונה:
npm install -g edgemicro
אם אתם זקוקים לעזרה, קראו את המאמר התקנת Edge Microgateway.
- מריצים את
edgemicro init
כדי להגדיר את סביבת התצורה המקומית, בדיוק כמו שמגדירים בסביבה רגילה של Edge Microgateway. למידע נוסף, ראו הגדרת מיקרו-שער של Edge. - מריצים את
edgemicro configure
כמו שעושים בתהליך הגדרה טיפוסי של Edge Microgateway. לדוגמה:edgemicro configure -o your_org -e your_env -u your_apigee_username
הפקודה הזו תפרוס את המדיניות edgemicro-auth ב-Edge, ותחזיר מפתח וסוד שתצטרכו כדי להפעיל את המיקרו-שער. אם אתם זקוקים לעזרה, ראו הגדרת Edge Microgateway.
- ב-Apigee Edge, יוצרים מוצר של ממשק API ועומדים בדרישות ההגדרה הנדרשות (תוכלו לנהל את כל שאר ההגדרות כרצונך):
- חובה להוסיף למוצר את שרת ה-proxy מסוג edgemicro-auth. שרת ה-proxy הזה נפרס באופן אוטומטי כשהפעלת את
edgemicro configure
. - אתם חייבים לציין נתיב של משאב. Apigee ממליצה להוסיף את הנתיב הזה
למוצר:
/**
. מידע נוסף זמין במאמר הגדרת ההתנהגות של נתיב המשאב. למידע נוסף, ראו יצירת מוצרי API במסמכי התיעוד של Edge.
- חובה להוסיף למוצר את שרת ה-proxy מסוג edgemicro-auth. שרת ה-proxy הזה נפרס באופן אוטומטי כשהפעלת את
ב-Apigee Edge, אפשר ליצור מפתח או להשתמש במפתח קיים. למידע נוסף, אפשר לעיין בהוספת מפתחים באמצעות ממשק המשתמש לניהול Edge.
- ב-Apigee Edge, אפשר ליצור אפליקציה למפתחים. חובה להוסיף לאפליקציה את מוצר ה-API שיצרת הרגע. לקבלת עזרה, קראו את המאמר רישום אפליקציה בממשק המשתמש לניהול Edge.
- במחשב שבו מותקן Edge Microgateway, מייצאים את משתנה
הסביבה הבא עם הערך "1".
export EDGEMICRO_LOCAL_PROXY=1
- מריצים את הפקודה
start
הבאה:edgemicro start -o your_org -e your_environment -k your_key -s your_secret \ -a local_proxy_name -v local_proxy_version -t target_url -b base_path
כאשר:
- your_org הוא הארגון שלך ב-Apigee.
- your_environment היא סביבה בארגון שלך.
- your_key הוא המפתח שהוחזר כשהפעלת את
edgemicro configure
. - your_secret הוא הסוד שהוחזר כשהפעלת את
edgemicro configure
. - local_proxy_name הוא השם של שרת ה-proxy המקומי שייווצר.
- local_proxy_version הוא מספר הגרסה של שרת ה-proxy.
- target_url היא כתובת ה-URL של היעד של שרת ה-Proxy (השירות שאליו יתקשר שרת ה-Proxy).
- base_path הוא הנתיב הבסיסי של שרת ה-proxy. הערך צריך להתחיל בקו נטוי קדימה. לנתיב בסיס של הבסיס, יש לציין רק קו נטוי לפנים. לדוגמה, '/'.
לדוגמה:
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \ -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \ -t http://mocktarget.apigee.net -b /echo
בדיקת התצורה
אפשר לבדוק את ההגדרה המקומית של שרת ה-proxy באמצעות קריאה לנקודת הקצה של שרת ה-proxy. לדוגמה,
אם ציינתם נתיב בסיס של /echo
, תוכלו לקרוא לשרת ה-Proxy באופן הבא:
curl http://localhost:8000/echo { "error" : "missing_authorization", "error_description" : "Missing Authorization header" }
הקריאה הראשונית ל-API גרמה לשגיאה כי לא סיפקת מפתח API תקין. תוכלו למצוא את המפתח באפליקציה למפתחים שיצרתם קודם לכן. פותחים את האפליקציה בממשק המשתמש של Edge, מעתיקים את מפתח הצרכן ומשתמשים במפתח הזה באופן הבא:
curl http://localhost:8000/echo -H 'x-api-key:your_api_key'
לדוגמה:
curl http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"
פלט לדוגמה:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }