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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

Edge Microgateway v. 3.0.x

נושא זה עוסק באופן הניהול וההגדרה של Edge Microgateway.

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

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

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

  1. כדי לשדרג לגרסה האחרונה של Edge Microgateway, מריצים את הפקודה npm הבאה:
    npm upgrade edgemicro -g

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

    npm upgrade edgemicro@3.0.2 -g
  2. בודקים את מספר הגרסה. לדוגמה, אם התקנתם את גרסה 3.0.2:
    edgemicro --version
    current nodejs version is v12.5.0
    current edgemicro version is 3.0.2
        
  3. ולבסוף, משדרגים לגרסה האחרונה של שרת ה-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 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 פועל (האפשרות של אפס זמן השבתה):

  1. טוענים מחדש את הגדרות 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 נעצר:

  1. מפעילים מחדש את 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, בצע את השלבים הבאים:

  1. תוכלו ליצור או לקבל אישור ומפתח SSL באמצעות כלי השירות openssl או בשיטה הרצויה לכם.
  2. יש להוסיף את המאפיין 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
  3. מפעילים מחדש את Edge Microgateway. פועלים לפי השלבים המפורטים בקטע ביצוע שינויים בהגדרות בהתאם לקובץ התצורה שערכתם: קובץ ברירת המחדל או קובץ התצורה של זמן הריצה.

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

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

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

אפשרות תיאור
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) מרווח, בשעות, כשמתבצעת רוטציה של קובצי יומן.
  • 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 שהשמות שלהם תואמים לתבנית מסוימת.

  1. פותחים את קובץ התצורה של Edge Micro: ~/.edgemicro/org-env-config.yaml
  2. מוסיפים את הרכיב 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. הפעולה הזו שימושית לפתרון בעיות ולניפוי באגים ביישומי פלאגין מותאמים אישית.

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

  1. קבלת אסימון גישה ורענון באמצעות ה-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"
    }
  2. עכשיו אפשר להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש על ידי קריאה לנקודת הקצה /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 במצב עצמאי:

  1. צריך לוודא שמותקנת במכשיר Edge Microgateway מגרסה 3.0.1 ואילך. אחרת, צריך להריץ את הפקודה הבאה כדי לשדרג לגרסה האחרונה:
    npm install -g edgemicro

    אם אתם זקוקים לעזרה, קראו את המאמר התקנת Edge Microgateway.

  2. יוצרים קובץ תצורה בשם: $HOME/.edgemicro/org_name-env_name-config.yaml

    לדוגמה:

    vi $HOME/.edgemicro/foo-bar-config.yaml
  3. מדביקים את הקוד הבא בקובץ:
    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
  4. מייצאים את משתנה הסביבה הבא עם הערך '1':
    export EDGEMICRO_LOCAL=1
  5. מריצים את הפקודה 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 /
  6. בודקים את ההגדרה.
    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:

  1. כדי לפרוס את שרת ה-Proxy של edgemicro-auth בארגון או בסביבה ב-Apigee Edge צריך לבצע הגדרה והגדרה סטנדרטיות של Edge Microgateway. אם כבר ביצעת את השלב הזה, אין צורך לחזור עליו.
  2. אם פרסתם את Edge Microgateway ל-Apigee Cloud, אתם צריכים להיות מחוברים לאינטרנט כדי לקבל JWT מנקודת הקצה הזו.
  3. עוצרים את Edge Microgateway:
    edgemicro stop
  4. בקובץ התצורה שיצרת קודם לכן ($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'
  5. מפעילים מחדש את Edge Microgateway כמו קודם, תוך שימוש בשמות הארגון או הסביבות שבהם השתמשתם בשם קובץ התצורה. לדוגמה:
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. קבלת אסימון 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 מציינת את סוד הצרכן מאפליקציית מפתח שמכילה מוצר שכולל את שרת ה-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 של היעד כשאתם מפעילים את המיקרו-שער. לאחר מכן, קריאות ל-API למיקרו-שער נשלחות לכתובת ה-URL של היעד של שרת ה-proxy המקומי. בכל שאר ההיבטים, המצב של שרת ה-proxy המקומי פועל בדיוק כמו הפעלת Edge Microgateway במצב הרגיל. האימות פועל באותו אופן, כמו גם היקף המעצרים והאכיפה של המכסות, יישומי פלאגין מותאמים אישית וכו'.

תרחיש לדוגמה ודוגמה

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

Edgemicro בתור Sidecar

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

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

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

  1. צריך לוודא שמותקנת במכשיר Edge Microgateway מגרסה 3.0.1 ואילך. אחרת, צריך להריץ את הפקודה הבאה כדי לשדרג לגרסה האחרונה:
    npm install -g edgemicro

    אם אתם זקוקים לעזרה, קראו את המאמר התקנת Edge Microgateway.

  2. מריצים את edgemicro init כדי להגדיר את סביבת התצורה המקומית, בדיוק כמו שמגדירים בסביבה רגילה של Edge Microgateway. למידע נוסף, ראו הגדרת מיקרו-שער של Edge.
  3. מריצים את edgemicro configure כמו שעושים בתהליך הגדרה טיפוסי של Edge Microgateway. לדוגמה:
    edgemicro configure -o your_org -e your_env -u your_apigee_username

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

  4. ב-Apigee Edge, יוצרים מוצר של ממשק API ועומדים בדרישות ההגדרה הנדרשות (תוכלו לנהל את כל שאר ההגדרות כרצונך):
    • חובה להוסיף למוצר את שרת ה-proxy מסוג edgemicro-auth. שרת ה-proxy הזה נפרס באופן אוטומטי כשהפעלת את edgemicro configure.
    • אתם חייבים לציין נתיב של משאב. Apigee ממליצה להוסיף את הנתיב הזה למוצר: /**. מידע נוסף זמין במאמר הגדרת ההתנהגות של נתיב המשאב. למידע נוסף, ראו יצירת מוצרי API במסמכי התיעוד של Edge.
  5. ב-Apigee Edge, אפשר ליצור מפתח או להשתמש במפתח קיים. למידע נוסף, אפשר לעיין בהוספת מפתחים באמצעות ממשק המשתמש לניהול Edge.

  6. ב-Apigee Edge, אפשר ליצור אפליקציה למפתחים. חובה להוסיף לאפליקציה את מוצר ה-API שיצרת הרגע. לקבלת עזרה, קראו את המאמר רישום אפליקציה בממשק המשתמש לניהול Edge.
  7. במחשב שבו מותקן Edge Microgateway, מייצאים את משתנה הסביבה הבא עם הערך "1".
    export EDGEMICRO_LOCAL_PROXY=1
  8. מריצים את הפקודה 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":""
}