‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

המסמך הזה עוסק ב-Apigee Edge.
למעבר אל מסמכי התיעוד של Apigee X. info

גרסה 3.0.x של Edge Microgateway

במאמר הזה נסביר איך לנהל ולהגדיר את Edge Microgateway.

שדרוג Edge Microgateway אם יש חיבור לאינטרנט

בקטע הזה מוסבר איך לשדרג התקנה קיימת של Edge Microgateway. אם אתם פועלים בלי חיבור לאינטרנט, קראו את המאמר Can I install Edge Microgateway without an internet connection?‎.

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

מריצים את הפקודה הבאה של npm כדי לשדרג לגרסה העדכנית של Edge Microgateway:
```
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. אם אתם לא מוצאים את הספרייה הזו, עיינו במאמר Where is Edge Microgateway installed.

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

edgemicro init
edgemicro configure [params]
edgemicro start [params]

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

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

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

edgemicro stop
edgemicro 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

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

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

בסרטונים הבאים מוסבר איך להגדיר TLS ב-Apigee Edge Microgateway:

וידאו	תיאור
הגדרת TLS חד-כיווני לכיוון צפון	מידע על הגדרת TLS ב-Apigee Edge Microgateway. בסרטון הזה יש סקירה כללית של TLS והחשיבות שלו, הסבר על TLS ב-Edge Microgateway והדגמה של הגדרת Northbound One-Way TLS.
הגדרת TLS דו-כיווני לכיוון צפון	זהו הסרטון השני בנושא הגדרת TLS ב-Apigee Edge Microgateway. בסרטון הזה מוסבר איך להגדיר 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
```
המפתח שצוין בקובץ המפתח של ה-SSL שאליו מפנים לא יכול להיות מוצפן.
מפעילים מחדש את 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 (ציון שם השרת).
`requestCert`	true ל-SSL דו-כיווני; false ל-SSL חד-כיווני

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

אפשר להגדיר את Edge Microgateway כלקוח TLS או SSL כשמתחברים לנקודות קצה (endpoints) לטירגוט. בקובץ התצורה של Microgateway, משתמשים ברכיב targets כדי להגדיר את אפשרויות ה-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 (ציון שם השרת).

התאמה אישית של שרת ה-proxy ‏edgemicro-auth

כברירת מחדל, Edge Microgateway משתמש בשרת proxy שנפרס ב-Apigee Edge לצורך אימות OAuth2. השרת הזה נפרס כשמריצים את edgemicro configure בפעם הראשונה. אפשר לשנות את הגדרת ברירת המחדל של שרת ה-proxy הזה כדי להוסיף תמיכה בהצהרות מותאמות אישית ל-JSON Web Token ‏(JWT), להגדיר את תפוגת התוקף של הטוקן וליצור טוקני רענון. פרטים נוספים זמינים בדף edgemicro-auth ב-GitHub.

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

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

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

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

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

‫edgeconfig:verify_api_key_url – מגדירים את כתובת ה-URL הזו כך שתצביע על נקודת הקצה של מפתח ה-API בשירות האימות בהתאמה אישית. בשרת ה-proxy שמוגדר כברירת מחדל, edgemicro-auth, כתובת ה-URL היא: https://myorg-myenv.apigee.net/edgemicro-auth/publicKey.
‫edgeconfig:products – מגדירים את כתובת ה-URL הזו כך שתפנה לנקודת הקצה של המוצרים בשירות האימות המותאם אישית. בשרת ה-proxy שמוגדר כברירת מחדל, edgemicro-auth, כתובת ה-URL היא: https://myorg-myenv.apigee.net/edgemicro-auth/products.

חשוב: אם משנים את שרת ה-proxy שמוגדר כברירת מחדל לאימות, שרת ה-proxy או השירות החדש חייבים להחזיר פורמט תגובה שזהה לשרת ה-proxy שמוגדר כברירת מחדל ב-edgemicro-auth.

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

‫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.

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

אפשר להגדיר את הרישום ביומן כך שמידע מהיומן יישלח לפלט סטנדרטי (stdout) במקום לקובץ יומן. מגדירים את הדגל 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

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

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

קובצי יומן יכולים להיות גדולים מאוד, לכן חשוב לוודא שיש מספיק מקום בספרייה של קובצי היומן. אפשר לעיין בקטעים הבאים: איפה קובצי היומן מאוחסנים ואיך משנים את ספריית ברירת המחדל של קובצי היומן.
למחוק או להעביר קובצי יומן לספריית ארכיון נפרדת לפחות פעם בשבוע.
אם המדיניות שלכם היא למחוק יומנים, אתם יכולים להשתמש בפקודת ה-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 ‏(JWT) שהורדו. אם רוצים להוציא את האובייקטים האלה לקובצי היומן, צריך להגדיר את DEBUG=* כשמפעילים את Edge Microgateway. לדוגמה:

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

ב-Windows, משתמשים ב-SET DEBUG=*

התוכן של קובץ היומן "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, בהתאם לרמת היומן. הערך יכול להיות stats לרשומת נתונים סטטיסטיים, 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, בהתאם לרמת היומן. הערך יכול להיות stats לרשומת נתונים סטטיסטיים, warn לאזהרות או error לשגיאות.
‫treq – מזהה את האירוע. במקרה הזה, בקשת היעד.
‫m – פועל ה-HTTP שמשמש בבקשת היעד.
u – החלק בכתובת ה-URL שאחרי נתיב הבסיס.
‫h – המארח ומספר היציאה של יעד הקצה העורפי.
‫i – המזהה של הרשומה ביומן. כל ארבעת רשומות האירועים ישתפו את המזהה הזה.

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

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

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

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

4. דוגמה לתגובה שנשלחת ללקוח

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

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

‫info – תלוי בהקשר. יכול להיות info,‏ warn או error, בהתאם לרמת היומן. הערך יכול להיות stats לרשומת נתונים סטטיסטיים, warn לאזהרות או error לשגיאות.
‫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.

‫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.
‫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 Microgateway.

‫port: (ברירת מחדל: 8000) מספר היציאה שבה תהליך Edge Microgateway מאזין.
‫max_connections: (ברירת מחדל: ‎-1) מציין את המספר המקסימלי של חיבורים נכנסים בו-זמניים ש-Edge Microgateway יכול לקבל. אם חורגים מהמספר הזה, מוחזר הסטטוס הבא:

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

‫plugins: יישומי פלאגין מוסיפים פונקציונליות ל-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 כדי להשבית את הסקר האוטומטי של השינויים.
‫request_timeout: מגדיר זמן קצוב לתפוגה של בקשות יעד. הזמן הקצוב לתפוגה מוגדר בשניות. אם מתרחש זמן קצוב לתפוגה, Edge Microgateway מגיב עם קוד סטטוס 504. (נוסף בגרסה 2.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 כדי למנוע העברה של כותרות via ליעד.

מאפייני OAuth

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

‫allowNoAuthorization: (ברירת המחדל: false) אם הערך הוא true, קריאות ל-API יכולות לעבור דרך Edge Microgateway בלי כותרת Authorization בכלל. צריך להגדיר את הערך false כדי לדרוש כותרת Authorization (ברירת המחדל).
‫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, הכותרת Authorization שנשלחת בבקשה מועברת ליעד (היא נשמרת).
‫allowOAuthOnly – אם הערך הוא true, כל API חייב לכלול כותרת Authorization עם Bearer טוקן גישה. מאפשרת לכם לאשר רק את מודל האבטחה של OAuth (תוך שמירה על תאימות לדורות קודמים). (נוסף בגרסה 2.4.x)
‫allowAPIKeyOnly – אם הערך הוא true, כל API חייב לכלול כותרת x-api-key (או מיקום מותאם אישית) עם מפתח API.מאפשר להגדיר רק את מודל האבטחה של מפתח ה-API (תוך שמירה על תאימות לדורות קודמים). (נוסף בגרסה 2.4.x)
אל תגדירו את allowOAuthOnly ואת allowAPIKeyOnly כ-true. כברירת מחדל, שני הדגלים מוגדרים כ-false (כדי לשמור על תאימות לדורות קודמים).
‫gracePeriod – הפרמטר הזה עוזר למנוע שגיאות שנגרמות בגלל הבדלים קלים בין שעון המערכת לבין הזמנים Not Before (nbf)‎ או Issued At (iat)‎ שצוינו באסימון ההרשאה של JWT. מגדירים את הפרמטר הזה למספר השניות שמאפשרים לפערים כאלה. (נוסף בגרסה 2.5.7)

מאפיינים ספציפיים לפלאגין

במאמר "שימוש בפלאגינים" מפורטים המאפיינים שאפשר להגדיר בכל פלאגין.

שרתי proxy לסינון

אתם יכולים לסנן את שרתי ה-proxy שמודעים ל-microgateway, שמופע של Edge Microgateway יעבד. כשהשירות Edge Microgateway מתחיל לפעול, הוא מוריד את כל שרתי ה-proxy שמזהים את microgateway בארגון שאליו הוא משויך. כדי להגביל את שרתי ה-proxy ששער ה-microgateway יעבד, משתמשים בהגדרות הבאות: לדוגמה, ההגדרה הזו מגבילה את שרתי ה-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 (אופציונלי): המספר המקסימלי של רשומות ניתוח נתונים שהמאגר יכול להכיל לפני שהוא מתחיל להשמיט את הרשומות הישנות ביותר. ברירת המחדל: 10,000
‫batchSize (אופציונלי): הגודל המקסימלי של קבוצת רשומות ניתוח שנשלחות ל-Apigee. ברירת המחדל: 500
‫flushInterval (אופציונלי): מספר האלפיות של השנייה בין כל ניקוי של קבוצת רשומות ניתוח שנשלחות ל-Apigee. ברירת המחדל: 5,000

לדוגמה:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

הסתרת נתונים ב-Analytics

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

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

הפרדת קריאות ל-API ב-Edge Analytics

אתם יכולים להגדיר את הפלאגין של ניתוח הנתונים כך שיפריד נתיב API ספציפי, כדי שהוא יופיע כשרת proxy נפרד בלוחות הבקרה של Edge Analytics. לדוגמה, אתם יכולים להפריד את ה-API של בדיקת התקינות בלוח הבקרה כדי לא לבלבל אותו עם קריאות בפועל ל-proxy ל-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. כדי להפריד על סמך נתיב מלא, כולל basepath, משתמשים בדגל proxyPath.
‫proxyPath (אופציונלי): מציין נתיב מלא של שרת proxy ל-API, כולל נתיב הבסיס של שרת ה-proxy, כדי להפריד אותו בלוח הבקרה של ניתוח הנתונים. לדוגמה, אם מציינים את /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 משתמש ב-method‏ CONNECT של HTTP כדי להעביר בקשות 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 כרשימה מופרדת בפסיקים של דומיינים ש-Edge Microgateway לא צריך להעביר אליהם דרך שרת proxy. לדוגמה:

export NO_PROXY='localhost,localhost:8080'

מגדירים את HTTP_PROXY ואת HTTPS_PROXY לנקודת הקצה של ה-Proxy ל-HTTP, כדי ש-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

ראה גם

How to set up Edge Microgateway behind a company firewall בקהילת Apigee.

שימוש בתווים כלליים לחיפוש בשרתי proxy שמזהים את Microgateway

אפשר להשתמש בתו כללי לחיפוש אחד או יותר, "*", בנתיב הבסיס של שרת proxy מסוג edgemicro_*‎ (עם תמיכה ב-Microgateway). לדוגמה, נתיב בסיס של ‎/team/*/members מאפשר ללקוחות לקרוא ל-‎https://[host]/team/blue/members ול-‎https://[host]/team/green/members בלי שתצטרכו ליצור שרתי proxy ל-API חדשים כדי לתמוך בצוותים חדשים. חשוב לזכור שאין תמיכה ב-/**/.

חשוב: Apigee לא תומך בשימוש בתו הכללי לחיפוש "*" כרכיב הראשון של נתיב בסיס. לדוגמה, אין תמיכה בחיפוש /*/.

רוטציה של מפתחות JWT

בשלב כלשהו אחרי שיוצרים JWT, יכול להיות שתצטרכו לשנות את זוג המפתחות הציבוריים/הפרטיים שמאוחסנים ב-KVM המוצפן של Edge. התהליך הזה של יצירת זוג מפתחות חדש נקרא רוטציית מפתחות.

איך Edge Microgateway משתמש ב-JWT

‫JSON Web Token ‏(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 באמצעות Management 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 המוצפן. כשמגדירים את Edge Microgateway בפעם הראשונה, נוצר KVM בשם microgateway והוא מאוכלס במפתחות. המפתחות ב-KVM משמשים לחתימה על JWT ולהצפנה שלו.

מפתחות ה-KVM כוללים:

‫private_key – המפתח הפרטי העדכני ביותר (שנוצר לאחרונה) של RSA, שמשמש לחתימה על אסימוני JWT.
‫public_key – האישור האחרון (שנוצר הכי לאחרונה) שמשמש לאימות אסימוני JWT שנחתמו באמצעות private_key.
‫private_key_kid – המזהה של המפתח הפרטי האחרון (שנוצר הכי לאחרונה). מזהה המפתח הזה משויך לערך private_key ומשמש לתמיכה ברוטציית מפתחות.
‫public_key1_kid – המזהה של המפתח הציבורי האחרון (שנוצר הכי לאחרונה). המפתח הזה משויך לערך public_key1 ומשמש לתמיכה ברוטציית מפתחות. הערך הזה זהה ל-kid של המפתח הפרטי.
‫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, שבו צריך לציין את אותו ארגון ואותה סביבה שהגדרתם לשימוש ב-microgateway:

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 Web Key.

אחרי רוטציית המפתחות, Edge מחזיר כמה מפתחות ל-Edge Microgateway. שימו לב שבדוגמה הבאה, לכל מפתח יש ערך "kid" (מזהה מפתח) ייחודי. לאחר מכן, ה-microgateway משתמש במפתחות האלה כדי לאמת אסימוני הרשאה. אם אימות הטוקן נכשל, ה-microgateway בודק אם יש מפתח ישן יותר בקבוצת המפתחות ומנסה להשתמש בו. הפורמט של המפתחות שמוחזרים הוא JSON Web Key‏ (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
```
ב-Windows, משתמשים ב-SET DEBUG=*
מפעילים את מנפה הבאגים ומגדירים אותו להאזין למספר היציאה של תהליך ניפוי הבאגים.
עכשיו אפשר לעבור על הקוד של 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 עם בקשות פרוקסי זמין במאמר אבטחת Edge Microgateway.

הפעלת קודי תגובה במעלה הזרם

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

איך מקבלים טוקן גישה

בקטע הזה מוסבר איך משתמשים בשרת ה-proxy של edgemicro-auth כדי לקבל טוקן גישה.

אפשר גם לקבל טוקן גישה באמצעות פקודת ה-CLI‏ edgemicro token. פרטים נוספים על ה-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: שליחת פרטי כניסה בכותרת Basic Auth

שולחים את פרטי הכניסה של הלקוח ככותרת Basic Authentication ואת grant_type כפרמטר של טופס. הפורמט הזה של הפקודה מופיע גם ב-RFC 6749: The OAuth 2.0 Authorization Framework.

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 עם סוג ה-grant‏ 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 נמצא בתיקיית ההתקנה ברמה הבסיסית (root) של Edge Microgateway. איפה מתקינים את Edge Microgateway. לפרטים על אפשרויות ההגדרה, עיינו במסמכי התיעוד של forever-monitor.

הפקודה edgemicro forever כוללת דגלים שמאפשרים לציין את המיקום של הקובץ forever.json (הדגל -f), ולהתחיל או להפסיק את תהליך המעקב של Forever (הדגל -a). לדוגמה:

edgemicro forever -f ~/mydir/forever.json -a start

מידע נוסף זמין בקטע Forever monitoring במדריך העזר ל-CLI.

ציון נקודת קצה של קובץ תצורה

אם אתם מפעילים כמה מכונות של 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
מכסה
Analytics

מצד שני, פלאגינים בהתאמה אישית ו-spike arrest פועלים כרגיל, כי הם לא דורשים חיבור ל-Apigee Edge. בנוסף, פלאגין חדש בשם extauth מאפשר לאשר קריאות ל-API ל-microgateway באמצעות JWT במצב עצמאי.

הגדרה והפעלה של השער

כדי להריץ את Edge Microgateway במצב עצמאי:

חשוב לוודא שמותקנת גרסה 3.0.1 או גרסה חדשה יותר של Edge Microgateway. אם לא, צריך להריץ את הפקודה הבאה כדי לשדרג לגרסה העדכנית:
```
npm install -g edgemicro
```
אם אתם צריכים עזרה, תוכלו להיעזר במאמר התקנת Edge Microgateway.
יוצרים קובץ תצורה עם השם הבא: $HOME/.edgemicro/org_name-env_name-config.yaml
אפשר להשתמש בכל ערך שרוצים בשביל org_name ו-env_name בשם הקובץ. השילוב של הארגון והסביבה הוא פשוט מוסכמה שמאפשרת ל-Edge Microgateway למצוא את הקובץ כשהוא מופעל.

לדוגמה:
```
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
```
קובץ התצורה מכיל פלאגין מיוחד ואופציונלי שנקרא extauth. הפלאגין הזה מאמת אסימון JWT תקין שמועבר ל-microgateway. בשלב מאוחר יותר נסביר איך לקבל את האסימון ולהשתמש בו. בנוסף, שימו לב שהפלאגין spikearrest כלול כי הוא לא מסתמך על קישוריות עם Edge. התוספים quota, oauth ו-analytics לא נכללים, כי הם מסתמכים על קישוריות עם Edge ולא יפעלו במצב מנותק. אפשר להשתמש בפלאגינים בהתאמה אישית, והם יפעלו כצפוי.
מייצאים את משתנה הסביבה הבא עם הערך "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 הוא שם הארגון שבו השתמשתם בשם של קובץ התצורה.
- ‫your_environment הוא השם של "env" שבו השתמשתם בשם של קובץ התצורה.
- ‫local_proxy_name הוא השם של שרת ה-Proxy המקומי שייווצר. אפשר להשתמש בכל שם שרוצים.
- ‫local_proxy_version הוא מספר הגרסה של שרת ה-proxy.
- ‫target_url היא כתובת ה-URL של היעד של שרת ה-proxy. (היעד הוא השירות שאליו שרת ה-proxy שולח קריאה).
- ‫base_path הוא נתיב הבסיס של שרת ה-Proxy. הערך הזה חייב להתחיל בלוכסן. לנתיב בסיס ברמה הבסיסית (root), מציינים רק לוכסן, לדוגמה "/".
לדוגמה:
```
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 שסופק לנקודת הקצה הזו.

הוספת הפלאגין extauth להגדרות של ה-microgateway היא אופציונלית, אבל אם מוסיפים אותו, צריך לספק אסימון JWT תקין בכותרת Authorization בקריאות ל-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 הזו:
בשלב הזה תצטרכו חיבור לאינטרנט. הפקודה הבאה מאחזרת אסימון מ-Apigee Edge. כדי לבצע את השלב הזה, צריך ארגון ב-Apigee שבו ביצעתם הגדרה וקביעת תצורה רגילות של Edge Microgateway. אחרי שמבצעים את השלב הזה, לא צריך להיות מחוברים לאינטרנט. האסימון ימשיך לפעול במצב עצמאי עד שיפוג תוקפו.

אפשר ליצור 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 מציינת את סוד הלקוח מאפליקציית מפתח שיש לה מוצר שכולל את שרת ה-proxy של edgemicro-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 לטירגוט כשאתם מפעילים את ה-microgateway. לאחר מכן, קריאות ל-API אל ה-microgateway נשלחות לכתובת ה-URL המטורגטת של שרת ה-proxy המקומי. בכל שאר ההיבטים, מצב שרת proxy מקומי פועל בדיוק כמו הפעלת Edge Microgateway במצב הרגיל שלו. האימות פועל באותו אופן, וכך גם עצירת הזינוקים ואכיפת המכסות, הפלאגינים בהתאמה אישית וכו'.

שני ההבדלים החשובים בין מצב מקומי לבין הגדרה רגילה של Edge Microgateway הם: (1) במצב מקומי, לא צריך ליצור שרת proxy שמזהה את Microgateway ב-Apigee Edge, ו-(2) כשיוצרים מוצר API ב-Edge, צריך להוסיף לו רק שרת proxy אחד, שרת ה-proxy edgemicro-auth. אין צורך להוסיף עוד שרתי proxy למוצר.

תרחיש לדוגמה

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

Edgemicro כ-Sidecar

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

הגדרת מצב שרת proxy מקומי

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

חשוב לוודא שמותקנת גרסה 3.0.1 או גרסה חדשה יותר של Edge Microgateway. אם לא, צריך להריץ את הפקודה הבאה כדי לשדרג לגרסה העדכנית:
```
npm install -g edgemicro
```
אם אתם צריכים עזרה, תוכלו להיעזר במאמר התקנת Edge Microgateway.
מריצים את הפקודה edgemicro init כדי להגדיר את סביבת התצורה המקומית, בדיוק כמו בהגדרה רגילה של Edge Microgateway. אפשר לעיין גם במאמר הגדרת Edge Microgateway.
מריצים את edgemicro configure, כמו בהליך הגדרה רגיל של Edge Microgateway. לדוגמה:
```
edgemicro configure -o your_org -e your_env -u your_apigee_username
```
הפקודה הזו פורסת את המדיניות edgemicro-auth ב-Edge ומחזירה מפתח וסוד שתצטרכו כדי להפעיל את ה-microgateway. אם אתם צריכים עזרה, תוכלו להיעזר במאמר הגדרת Edge Microgateway.
ב-Apigee Edge, יוצרים מוצר API עם דרישות ההגדרה הבאות (אפשר לנהל את כל שאר ההגדרות כרצונכם):
- חובה להוסיף למוצר את שרת ה-proxy‏ edgemicro-auth. שרת ה-proxy הזה נפרס באופן אוטומטי כשהרצת את edgemicro configure.
- חובה לציין נתיב למשאב. ‫Apigee ממליצה להוסיף את הנתיב הזה למוצר: /**. מידע נוסף זמין במאמר הגדרת ההתנהגות של נתיב המשאב. אפשר גם לעיין במאמר יצירת מוצרי API במסמכי התיעוד של Edge.
ב-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. הערך הזה חייב להתחיל בלוכסן. לנתיב בסיס ברמה הבסיסית (root), מציינים רק לוכסן, לדוגמה "/".
לדוגמה:
```
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":""
}