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

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

Edge Microgateway גרסה 3.2.x

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

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

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

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

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

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

    npm install edgemicro@3.2.3 -g
  2. בודקים את מספר הגרסה. לדוגמה, אם התקנתם את גרסה 3.2.3: 
    edgemicro --version
current nodejs version is v12.5.0
current edgemicro version is 3.2.3
  3. לבסוף, משדרגים לגרסה העדכנית של שרת ה-proxy‏ edgemicro-auth: 
    edgemicro upgradeauth -o $ORG -e $ENV -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 פועל (אפשרות ללא זמן השבתה):

  1. טוענים מחדש את ההגדרות של Edge Microgateway: 
    edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

    כאשר:

    • ‫$ORG הוא שם הארגון ב-Edge (אתם צריכים להיות אדמינים ארגוניים).
    • ‫$ENV היא סביבה בארגון (למשל "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 -e $ENV -k $KEY -s $SECRET

    כאשר:

    • ‫$ORG הוא שם הארגון ב-Edge (אתם צריכים להיות אדמינים ארגוניים).
    • ‫$ENV היא סביבה בארגון (למשל "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, מבצעים את השלבים הבאים:

  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 (ציון שם השרת).
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

אם רוצים להחיל הגדרות TLS/SSL על כמה יעדים ספציפיים, צריך לציין את המארח הראשון בהגדרה כ "ריק", מה שמאפשר בקשות אוניברסליות, ואז לציין מארחים ספציפיים בכל סדר. בדוגמה הזו, ההגדרות חלות על כמה מארחים ספציפיים: 

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       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 כדי לאמת את הזהות.

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

‫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 וגם לקובץ יומן.

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

מציינים את רמת היומן שבה רוצים להשתמש בהגדרות של edgemicro. רשימה מלאה של רמות היומן והתיאורים שלהן מופיעה במאמר מאפייני edgemicro.

לדוגמה, ההגדרה הבאה קובעת את רמת הרישום ביומן ל-debug: 

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

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

אפשר להגדיר את המרווחים האלה בקובץ התצורה של 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

איך להקל על הרשאות מחמירות בקובצי יומן

כברירת מחדל, Edge Microgateway יוצר את קובץ היומן של האפליקציה (api-log.log) כשרמת ההרשאה לקובץ מוגדרת ל-0600. רמת ההרשאה הזו לא מאפשרת לאפליקציות או למשתמשים חיצוניים לקרוא את קובץ היומן. כדי להקל על רמת ההרשאה המחמירה הזו, מגדירים את logging:disableStrictLogFile לערך true. כשהמאפיין הזה הוא true, קובץ היומן נוצר עם הרשאות הקבצים שמוגדרות ל-0755. אם המאפיין לא צוין או אם צוין הערך false, ההרשאה שמוגדרת כברירת מחדל היא 0600.

נוסף בגרסה 3.2.3.

לדוגמה: 

edgemicro:
 logging:
   disableStrictLogFile: true

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

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

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

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

כל מכונה של Edge Microgateway יוצרת קובץ יומן עם הסיומת .log. השמות של קובצי היומן נקבעים לפי הכללים הבאים:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

לדוגמה:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

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

נוסף בגרסה: 2.3.3

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

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

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

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

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

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

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

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

  • ‫info – רמת הרישום ביומן. הערך הזה תלוי בהקשר של הטרנזקציה וברמת הרישום ביומן שהוגדרה ב-edgemicro. איך מגדירים את רמת הרישום ביומן ברשומות של נתונים סטטיסטיים, הרמה מוגדרת כ-stats. רשומות הנתונים הסטטיסטיים מדווחות במרווחי זמן קבועים שמוגדרים באמצעות ההגדרה stats_log_interval. אפשר גם לקרוא איך משנים את מרווחי הזמן של יומן השינויים.
  • ‫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

מאפייני 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 – רישום של הודעות שגיאה בלבד.
      • ‫debug – רישום ביומן של הודעות ניפוי באגים, בנוסף להודעות info, ‏ warn ו-error.
      • ‫trace – רישום ביומן של מידע על מעקב אחר שגיאות, יחד עם הודעות מידע, אזהרה ושגיאה.
      • none – לא ליצור קובץ יומן.
    • ‫dir: (ברירת המחדל: ‎/var/tmp) הספרייה שבה מאוחסנים קובצי היומן.
    • ‫stats_log_interval: (ברירת המחדל: 60) המרווח, בשניות, שבו רשומת הנתונים הסטטיסטיים נכתבת בקובץ היומן של ה-API.
    • ‫rotate_interval: (ברירת המחדל: 24) המרווח, בשעות, שבו מתבצעת רוטציה של קובצי היומן.
  • ‫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)
  • ‫keep_alive_timeout: המאפיין הזה מאפשר להגדיר את הזמן הקצוב לתפוגה של Edge Microgateway (באלפיות השנייה). (ברירת מחדל: 5 שניות) (נוסף בגרסה 3.0.6)
  • ‫headers_timeout: המאפיין הזה מגביל את משך הזמן (באלפיות השנייה) שמנתח ה-HTTP ימתין לקבלת כותרות ה-HTTP המלאות.

    לדוגמה:

    edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

    באופן פנימי, הפרמטר מגדיר את המאפיין Server.headersTimeout של Node.js בבקשות. (ברירת המחדל: 5 שניות יותר מהזמן שהוגדר באמצעות edgemicro.keep_alive_timeout. ‫(הגדרת ברירת המחדל הזו מונעת ממאזני עומסים או משרתי proxy לנתק את החיבור בטעות). (נוסף בגרסה 3.1.1)

  • ‫noRuleMatchAction: (מחרוזת) הפעולה שצריך לבצע (לאשר או לדחות את הגישה) אם כלל ההתאמה שצוין בפלאגין accesscontrol לא נפתר (אין התאמה). ערכים חוקיים: ALLOW או DENY ברירת מחדל: ALLOW (נוסף בגרסה: v3.1.7)
  • enableAnalytics: (ברירת מחדל: true) מגדירים את המאפיין כ-false כדי למנוע את הטעינה של הפלאגין של Analytics. במקרה כזה, לא יבוצעו קריאות לניתוח נתונים של Apigee Edge. אם הערך הוא true או אם המאפיין הזה לא צוין, הפלאגין של Analytics יפעל כרגיל. פרטים נוספים זמינים במאמר מאפייני edgemicro. (נוסף בגרסה 3.1.8).

    דוגמה: 

    edgemicro
  enableAnalytics=false|true
  • ‫on_target_response_abort: המאפיין הזה מאפשר לכם לקבוע איך Edge Microgateway יתנהג אם החיבור בין הלקוח (Edge Microgateway) לבין שרת היעד ייסגר לפני הזמן.
    ערך תיאור
    ברירת מחדל אם לא מציינים את on_target_response_abort, פעולת ברירת המחדל היא לחתוך את התגובה בלי להציג שגיאה. בקובצי היומן, הודעת אזהרה מוצגת עם targetResponse aborted וקוד תגובה 502.
    appendErrorToClientResponseBody השגיאה בהתאמה אישית TargetResponseAborted מוחזרת ללקוח. בקובצי היומן, הודעת אזהרה מוצגת עם targetResponse aborted וקוד תגובה 502. בנוסף, השגיאה TargetResponseAborted נרשמת ביומן עם ההודעה Target response ended prematurely.
    abortClientRequest ‫Edge Microgateway מבטל את הבקשה וכותב אזהרה בקובצי היומן: TargetResponseAborted עם קוד הסטטוס 502 של הבקשה.

דוגמה: 

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

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

ההגדרות האלה קובעות איך המערכת תתייחס לכותרות 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)
  • ‫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:

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

סינון מוצרים לפי שם

כדי להגביל את מספר מוצרי ה-API ש-Edge Microgateway מוריד ומעבד, משתמשים בהגדרות הבאות. כדי לסנן מוצרים שהורדו, מוסיפים את הפרמטר של השאילתה productnamefilter ל-API של /products שמופיע בקובץ *.config.yaml של Edge Microgateway. לדוגמה:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-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://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

חשוב לזכור שהערך של הפרמטרים של שאילתה צריך להיות בפורמט של ביטוי רגולרי ומקודד בכתובת ה-URL. לדוגמה, הביטוי הרגולרי ^[Ee]dgemicro.*$ תופס שמות כמו: "edgemicro-test-1" , "edgemicro_demo" ו-"Edgemicro_New_Demo". הערך המקודד של כתובת ה-URL, שמתאים לשימוש בפרמטרים של שאילתה, הוא: %5E%5BEe%5Ddgemicro.%2A%24.

פלט ניפוי הבאגים הבא מראה שרק המוצרים המסוננים הורדו: 

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

סינון מוצרים לפי מאפיינים מותאמים אישית

כדי לסנן מוצרים על סמך מאפיינים מותאמים אישית:

  1. בממשק המשתמש של Edge, בוחרים את שרת ה-proxy‏ edgemicro_auth בארגון או בסביבה שבהם הגדרתם את Edge Microgateway.
  2. בכרטיסייה Develop, פותחים את המדיניות JavaCallout בכלי העריכה.
  3. מוסיפים מאפיין מותאם אישית עם המפתח products.filter.attributes ורשימה מופרדת בפסיקים של שמות מאפיינים. רק מוצרים שמכילים את אחד משמות המאפיינים המותאמים אישית יוחזרו אל Edge Microgateway.
  4. אפשר להשבית את הבדיקה אם המוצר מופעל בסביבה הנוכחית על ידי הגדרת המאפיין המותאם אישית products.filter.env.enable לערך false. (ערך ברירת המחדל הוא true).
  5. ‫(ענן פרטי בלבד) אם אתם משתמשים ב-Edge for Private Cloud, הגדירו את המאפיין org.noncps לערך true כדי לשלוף מוצרים לסביבות שאינן CPS.

    6. לדוגמה:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

סינון מוצרים לפי סטטוס ביטול

למוצרי API יש שלושה קודי סטטוס: "בהמתנה", "אושר" ו"בוטל". מאפיין חדש בשם allowProductStatus נוסף למדיניות של הגדרת משתני JWT בשרת ה-proxy של edgemicro-auth. כדי להשתמש במאפיין הזה לסינון מוצרי API שרשומים ב-JWT:

  1. פותחים את שרת ה-proxy‏ edgemicro-auth בכלי לעריכת שרתי proxy של Apigee.
  2. מוסיפים את המאפיין allowProductStatus ל-XML של המדיניות SetJWTVariables ומציינים רשימה מופרדת בפסיקים של קודי סטטוס לסינון. לדוגמה, כדי לסנן לפי הסטטוסים בהמתנה ובוטל: 
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript timeLimit="20000" async="false" continueOnError="false"
    enabled="true" name="Set-JWT-Variables">
    <DisplayName>Set JWT Variables</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="allowProductStatus">Pending,Revoked</Property>
    </Properties>
    <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
</Javascript>

    אם רוצים שרק מוצרים מאושרים יופיעו, מגדירים את המאפיין באופן הבא:

    <Property name="allowProductStatus">Approved</Property>
  3. שומרים את שרת ה-proxy.

    אם התג Property לא קיים, מוצרים עם כל קודי הסטטוס יופיעו ב-JWT.

    כדי להשתמש במאפיין החדש הזה, צריך לשדרג את שרת ה-proxy של edgemicro-auth.

הגדרת תדירות שליחת הנתונים ל-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 מאחורי חומת אש של חברה

שימוש בשרת proxy ל-HTTP לתקשורת עם Apigee Edge

נוספה בגרסה 3.1.2.

כדי להשתמש בשרת proxy ל-HTTP לתקשורת בין Edge Microgateway לבין Apigee Edge:

  1. מגדירים את משתני הסביבה HTTP_PROXY,‏ HTTPS_PROXY ו-NO_PROXY. המשתנים האלה קובעים את המארחים של כל שרת proxy ל-HTTP שבו רוצים להשתמש לתקשורת עם Apigee Edge, או אילו מארחים לא צריכים לטפל בתקשורת עם Apigee Edge. לדוגמה: 
    export HTTP_PROXY='http://localhost:3786'
export HTTPS_PROXY='https://localhost:3786'
export NO_PROXY='localhost,localhost:8080'

    שימו לב ש-NO_PROXY יכול להיות רשימה של דומיינים מופרדים בפסיקים ש-Edge Microgateway לא אמור להעביר אליהם דרך שרת proxy.

    מידע נוסף על המשתנים האלה זמין בכתובת https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

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

שימוש בשרת proxy ל-HTTP לתקשורת עם היעד

נוספה בגרסה 3.1.2.

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

  1. מוסיפים את ההגדרות הבאות לקובץ התצורה של microgateway: 
    edgemicro:
  proxy:
    tunnel: true | false
    url: proxy_url
    bypass: target_host # target hosts to bypass the proxy.
    enabled: true | false

    כאשר:

    • ‫tunnel: (אופציונלי) אם הערך הוא true, ‏ Edge Microgateway משתמש ב-method‏ HTTP CONNECT כדי להעביר בקשות HTTP דרך חיבור TCP יחיד. (כך גם אם משתני הסביבה, כפי שמוזכר בהמשך, להגדרת שרת ה-proxy מופעלים ב-TLS). ברירת המחדל: false
    • ‫url: כתובת ה-URL של שרת ה-proxy ל-HTTP.
    • ‫bypass: (אופציונלי) כתובת URL אחת או יותר של מארח יעד שמופרדות בפסיקים, שצריכות לעקוף את ה-Proxy ל-HTTP. אם המאפיין הזה לא מוגדר, צריך להשתמש במשתנה הסביבה NO_PROXY כדי לציין את כתובות היעד שרוצים לעקוף.
    • ‫enabled: אם הערך הוא true והמדיניות proxy.url מוגדרת, המערכת משתמשת בערך של proxy.url בשביל ה-Proxy ל-HTTP. אם הערך הוא true ו-proxy.url לא מוגדר, משתמשים בשרתי ה-proxy שצוינו במשתני הסביבה של שרת ה-proxy ל-HTTP‏ HTTP_PROXY ו-HTTPS_PROXY, כפי שמתואר בקטע שימוש בשרת proxy ל-HTTP לתקשורת עם Apigee Edge.

    לדוגמה: 

    edgemicro:
  proxy:
    tunnel: true
    url: 'http://localhost:3786'
    bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
    enabled: true

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

שימוש בתווים כלליים לחיפוש בשרתי 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 יכול לאמת באופן מהימן.

אתם יכולים ליצור JWT באמצעות ה-CLI ולהשתמש בו בכותרת Authorization של קריאות ל-API במקום במפתח API. לדוגמה:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

במאמר יצירת אסימון מוסבר איך יוצרים אסימוני JWT באמצעות ה-CLI.

מהי רוטציית מפתחות?

בשלב כלשהו אחרי שיוצרים 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 שיוצגו לאימות יאומתו באמצעות המפתח הציבורי החדש. אם האימות נכשל, המערכת תשתמש במפתח הציבורי הישן עד שתוקף ה-JWT יפוג (אחרי מרווח הזמן של token_expiry*, ברירת המחדל היא 30 דקות). כך אפשר "לסובב" מפתחות בלי לשבש באופן מיידי את התנועה ב-API.

איך מבצעים רוטציית מפתחות

בקטע הזה מוסבר איך לבצע רוטציית מפתחות.

  1. כדי לשדרג את ה-KVM, משתמשים בפקודה edgemicro upgradekvm. לפרטים על הפעלת הפקודה הזו, ראו שדרוג ה-KVM. צריך לבצע את השלב הזה רק פעם אחת.
  2. כדי לשדרג את שרת ה-proxy‏ edgemicro-oauth, משתמשים בפקודה edgemicro upgradeauth. לפרטים על הרצת הפקודה הזו, ראו שדרוג שרת ה-proxy של edgemicro-auth. צריך לבצע את השלב הזה רק פעם אחת.
  3. מוסיפים את השורה הבאה לקובץ ~/.edgemicro/org-env-config.yaml, שבו צריך לציין את אותו ארגון ואותה סביבה שהגדרתם לשימוש ב-microgateway: 
    jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

  4. מריצים את הפקודה לרוטציית מפתחות כדי להחליף את המפתחות. למידע נוסף על הפקודה הזו, קראו את המאמר רוטציית מפתחות.

    edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

    לדוגמה:

    edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47

אחרי רוטציית המפתחות, 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"
    }
  ]
}

הגדרת השהיה מסוג "לא לפני"

בגרסאות 3.1.5 ומטה, המפתח הפרטי החדש שנוצר באמצעות הפקודה rotatekey נכנס לתוקף באופן מיידי, והאסימונים החדשים שנוצרו נחתמו באמצעות המפתח הפרטי החדש. עם זאת, המפתח הציבורי החדש היה זמין למכונות של Edge Microgateway רק כל 10 דקות (כברירת מחדל), כשההגדרות של ה-microgateway רועננו. בגלל העיכוב הזה בין החתימה על הטוקן לבין הרענון של המכונה של microgateway, טוקנים שנחתמו באמצעות המפתח האחרון נדחו עד שכל המכונות קיבלו את המפתח הציבורי האחרון.

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

החל מגרסה 3.1.6, דגל חדש בפקודה rotatekey מאפשר לציין עיכוב עד שהמפתח הפרטי החדש ייכנס לתוקף, כדי לאפשר לכל המופעים של microgateway להתעדכן ולקבל את המפתח הציבורי החדש. הדגל החדש הוא --nbf, שפירושו "לא לפני". הערך של הדגל הזה הוא מספר שלם, שמציין את מספר הדקות של העיכוב.

בדוגמה הבאה, ההשהיה מוגדרת ל-15 דקות: 

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

שימו לב: מומלץ להגדיר את העיכוב לזמן ארוך יותר מהגדרת התצורה של config_change_poll_internal, שמוגדרת כברירת מחדל ל-10 דקות. אפשר לעיין גם במאפייני edgemicro.

סינון שרתי 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 $ORG -e $ENV -k $KEY -s $SECRET

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

    export DEBUG=* nohup edgemicro start \
-o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

  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 עם בקשות פרוקסי זמין במאמר אבטחת Edge Microgateway.

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

כברירת מחדל, הפלאגין oauth מחזיר רק קודי סטטוס של שגיאות 4xx אם התגובה היא לא סטטוס 200. אפשר לשנות את ההתנהגות הזו כך שתמיד יוחזר קוד 4xx או 5xx מדויק, בהתאם לשגיאה.

כדי להפעיל את התכונה הזו, מוסיפים את המאפיין 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. אפשר להשתמש בכל אחת מהן. חשוב לזכור שהערך expires_in הוא מספר שלם שמצוין בשניות. 
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 1799
}

איך מקבלים טוקן רענון

כדי לקבל טוקן רענון, שולחים קריאה ל-API לנקודת הקצה /token של שרת ה-Proxy של edgemicro-auth. חובה לבצע את הקריאה הזו ל-API עם סוג ה-grant‏ 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 מחזיר טוקן גישה וטוקן רענון. התגובה אמורה להיראות כך: חשוב לזכור שהערכים של expires_in הם מספרים שלמים ומוגדרים בשניות. 

    {
    "token": "your-access-token",
    "access_token": "your-access-token",
    "token_type": "bearer",
    "expires_in": 108,
    "refresh_token": "your-refresh-token",
    "refresh_token_expires_in": 431,
    "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 נמצא בתיקיית ההתקנה ברמה הבסיסית (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 במצב עצמאי:

  1. יוצרים קובץ תצורה עם השם הבא: $HOME/.edgemicro/$ORG-$ENV-config.yaml

    לדוגמה:

    vi $HOME/.edgemicro/foo-bar-config.yaml
  2. מדביקים את הקוד הבא בקובץ: 
    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
  3. מייצאים את משתנה הסביבה הבא עם הערך "1": 
    export EDGEMICRO_LOCAL=1
  4. מריצים את הפקודה הבאה של start, שבה מספקים ערכים כדי ליצור מופע של שרת ה-proxy המקומי: 
    edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
  -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

    כאשר:

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

תרחיש לדוגמה

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

Edgemicro כ-Sidecar

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

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

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

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

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

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

  4. ב-Apigee Edge, יוצרים מפתח, או משתמשים במפתח קיים אם רוצים. לקבלת עזרה, אפשר לעיין במאמר הוספת מפתחים באמצעות ממשק המשתמש לניהול של Edge.

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

שימוש בסנכרון

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

תכונת הסנכרון נתמכת כרגע בעבודה עם Redis 5.0.x.

מהו הסנכרון?

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

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

הסנכרון של Edge Microgateway מספק מנגנון חלופי למכונות של Edge Microgateway כדי לאחזר נתוני תצורה שנדרשים להן כדי להפעיל ולעבד תנועה של שרתי proxy ל-API. נתוני ההגדרות שמאוחזרים מקריאות ל-Apigee Edge כוללים: הקריאה ל-jwk_public_keys, הקריאה ל-jwt_public_key, הקריאה ל-bootstrap והקריאה למוצרי ה-API. הסנכרון מאפשר לכל המופעים של Edge Microgateway שפועלים בצמתים שונים להתחיל לפעול כמו שצריך ולהישאר מסונכרנים, גם אם החיבור לאינטרנט בין Edge Microgateway ל-Apigee Edge משובש.

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

הגדרת מכונה של סנכרון

מוסיפים את ההגדרה הבאה לקובץ org-env/config.yaml של ההתקנה של Edge Microgateway שבה רוצים להשתמש כסנכרון: 

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

לדוגמה: 

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true
אפשרות תיאור
redisHost המארח שבו פועל מכונת Redis. ברירת המחדל: 127.0.0.1
redisPort היציאה של מכונת Redis. ברירת המחדל: 6379
redisDb מסד הנתונים של Redis שבו רוצים להשתמש. ברירת המחדל: 0
redisPassword הסיסמה למסד הנתונים.

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

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

כשהסנכרון פועל, אפשר להגדיר צומתי Edge Microgateway נוספים כדי להריץ מכונות רגילות של Microgateway שמעבדות תנועה של שרתי proxy ל-API. עם זאת, אתם מגדירים את המכונות האלה כך שיקבלו את נתוני ההגדרות שלהן ממסד הנתונים של Redis ולא מ-Apigee Edge.

מוסיפים את ההגדרות הבאות לקובץ org-env/config.yaml של כל צומת נוסף של Edge Microgateway. שימו לב שהמאפיין synchronizerMode מוגדר לערך 0. המאפיין הזה מגדיר את המכונה לפעול כמכונה רגילה של Edge Microgateway שמעבדת תנועה של שרת proxy ל-API, והמכונה תקבל את נתוני ההגדרות שלה ממסד הנתונים של Redis. 

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

לדוגמה: 

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

מאפייני ההגדרות האישיות

מאפייני ההגדרה הבאים נוספו כדי לתמוך בשימוש בסנכרון:

מאפיין ערכים תיאור
edge_config.synchronizerMode 0 או 1

אם הערך הוא 0 (ברירת המחדל), Edge Microgateway פועל במצב הרגיל שלו.

אם הערך הוא 1, מפעילים את המכונה של Edge Microgateway כדי שתפעל כסנכרון. במצב הזה, המכונה תמשוך נתוני הגדרות מ-Apigee Edge ותאחסן אותם במסד נתונים מקומי של Redis. המכונה הזו לא יכולה לעבד בקשות של שרתי proxy ל-API. המטרה היחידה שלה היא לדגום את Apigee Edge כדי לקבל נתוני הגדרות ולכתוב אותם במסד הנתונים המקומי. לאחר מכן, צריך להגדיר מכונות אחרות של microgateway לקריאה ממסד הנתונים.
edge_config.redisBasedConfigCache true or false אם הערך הוא true, המכונה של Edge Microgateway מאחזרת את נתוני ההגדרות שלה ממסד הנתונים של Redis במקום מ-Apigee Edge. מסד הנתונים של Redis חייב להיות אותו מסד נתונים שהסנכרון מוגדר לכתוב אליו. אם מסד הנתונים של Redis לא זמין או אם הוא ריק, ה-microgateway מחפש קובץ cache-config.yaml קיים בשביל ההגדרות שלו.

אם הערך הוא false (ברירת המחדל), המכונה של Edge Microgateway מאחזרת נתוני הגדרות מ-Apigee Edge כרגיל.
edgemicro.config_change_poll_interval מרווח הזמן, בשניות מציין את מרווח הזמן שבו הסנכרון שולף נתונים מ-Apigee Edge.

הגדרת כתובות URL להחרגה בפלאגינים

אתם יכולים להגדיר את ה-microgateway כך שידלג על עיבוד הפלאגינים של כתובות URL מסוימות. אתם יכולים להגדיר את כתובות ה-URL האלה ל "החרגה" באופן גלובלי (לכל הפלאגינים) או לפלאגינים ספציפיים.

לדוגמה: 

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

בדוגמה הזו, הפלאגינים לא יעבדו קריאות נכנסות לשרת proxy ל-API עם הנתיבים /hello או /proxy_one. בנוסף, הפלאגין json2xml ידלג על ממשקי API עם /hello/xml בנתיב שלהם.

הגדרת מאפייני תצורה עם ערכים של משתני סביבה

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

בדוגמה הזו, המאפיין key מוחלף בערך של משתנה הסביבה TARGETS_SSL_CLIENT_KEY, וכן הלאה. 

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

בדוגמה הזו, התג <n> משמש לציון ערך של מספר שלם. אפשר להשתמש רק במספרים שלמים חיוביים. 

edgemicro:
  port: <E><n>EMG_PORT</n></E>

בדוגמה הזו, התג <b> משמש לציון ערך בוליאני (כלומר, true או false). 

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>