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

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

‫Edge Microgateway גרסה 3.2.x

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

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

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

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

  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. אם אתם לא מוצאים את הספרייה הזו, תוכלו לעיין במאמר איפה מותקן 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 -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 היא סביבה בארגון שלכם (למשל 'בדיקה' או 'ייצור').
    • ‫$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, ומוסבר איך להגדיר 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 (Server Name Indication).
requestCert ‫true ל-SSL דו-כיווני; ‏false ל-SSL חד-כיווני

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

אתם יכולים להגדיר את Edge Microgateway כלקוח TLS או SSL כשמתחברים לנקודות קצה של יעד. בקובץ ההגדרות של 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 (Server Name Indication).

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

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

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

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

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

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

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

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

edgemicro-HOST_NAME-INSTANCE_ID-api.log

לדוגמה:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

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

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

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

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

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

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

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

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

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

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

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

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

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

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • ‫1436403888651 – חותמת תאריך של Unix
  • ‫info – רמת הרישום ביומן. הערך הזה תלוי בהקשר של העסקה וברמת הרישום ביומן שהוגדרה בהגדרות של 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 – המארח ומספר היציאה של יעד ה-backend.
  • ‫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.
  • logging:
    • level: (ברירת מחדל: error)
      • ‫info – (מומלץ) מתעד את כל הבקשות והתשובות שעוברות דרך מופע של Edge Microgateway.
      • ‫warn – רישום רק של הודעות אזהרה.
      • ‫error – רישום הודעות שגיאה בלבד.
      • ‫debug – רישום ביומן של הודעות ניפוי באגים יחד עם הודעות מידע, אזהרה ושגיאה.
      • ‫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. (נוסף בגרסה v2.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, או אם המאפיין הזה לא מסופק, תוסף ניתוח הנתונים יפעל כרגיל. פרטים נוספים זמינים במאמר בנושא מאפייני 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 בלי כותרת הרשאה בכלל. מגדירים את הערך הזה ל-false כדי לדרוש כותרת Authorization (ברירת מחדל).
  • ‫allowInvalidAuthorization: (ברירת מחדל: false) אם הערך מוגדר כ-true, קריאות ל-API מורשות לעבור אם הטוקן שמועבר בכותרת ההרשאה לא תקין או שתוקפו פג. כדי לדרוש אסימונים תקפים (ברירת מחדל), צריך להגדיר את המדיניות הזו כ-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 עם אסימון גישה מסוג 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

אתם יכולים לסנן את הפרוקסי שמודעים ל-Microgateway שמופע Edge Microgateway יעבד. כשמפעילים את Edge Microgateway, הוא מוריד את כל ה-proxies שמודעים ל-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'

שימו לב שערך הפרמטר query צריך להיות בפורמט של ביטוי רגולרי ומקודד בכתובת ה-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 נוסף למדיניות Set JWT Variables בשרת ה-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. שומרים את השרת הפרוקסי.

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

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

הגדרת התדירות של שליחת נתונים ל-Analytics

פרמטרי ההגדרה האלה מאפשרים לקבוע את התדירות שבה Edge Microgateway שולח נתוני ניתוח ל-Apigee:

  • ‫bufferSize (אופציונלי): המספר המקסימלי של רשומות Analytics שמאגר הנתונים הזמני יכול להכיל לפני שהוא מתחיל להשליך את הרשומות הכי ישנות. ברירת מחדל: 10000
  • ‫batchSize (אופציונלי): הגודל המקסימלי של אצווה של רשומות ניתוח שנשלחות אל Apigee. ברירת מחדל: 500
  • ‫flushInterval (אופציונלי): מספר אלפיות השנייה בין כל פעולת ניקוי של קבוצת רשומות של ניתוח נתונים שנשלחת אל Apigee. ברירת מחדל: 5,000

לדוגמה:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

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

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

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

הגדרת Edge Microgateway מאחורי חומת אש של חברה

שימוש ב-HTTP proxy לתקשורת עם 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 לא אמור להעביר אליהם בקשות.

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

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

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

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

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

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

    כאשר:

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

שימוש בתווים כלליים לחיפוש בפרוקסי עם מודעות ל-Microgateway

אפשר להשתמש בתו כללי אחד או יותר '*' בנתיב הבסיס של פרוקסי 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 ולהשתמש בו בכותרת ההרשאות של קריאות ל-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 ומשמש לתמיכה ברוטציית מפתחות. הערך הזה זהה לערך של מזהה המפתח הפרטי.

  • ‫public_key1 – המפתח הציבורי העדכני ביותר (שנוצר לאחרונה).

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

  • ‫public_key2_kid – המזהה של המפתח הציבורי הישן. המפתח הזה משויך לערך public_key2 ומשמש לתמיכה ברוטציית מפתחות.

  • ‫public_key2 – המפתח הציבורי הישן.

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

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

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

  1. כדי לשדרג את KVM, משתמשים בפקודה edgemicro upgradekvm. פרטים על הרצת הפקודה הזו זמינים במאמר בנושא שדרוג KVM. צריך לבצע את השלב הזה רק פעם אחת.
  2. כדי לשדרג את ה-proxy‏ edgemicro-oauth, משתמשים בפקודה edgemicro upgradeauth. פרטים על הרצת הפקודה הזו זמינים במאמר בנושא שדרוג פרוקסי edgemicro-auth. צריך לבצע את השלב הזה רק פעם אחת.
  3. מוסיפים את השורה הבאה לקובץ ~/.edgemicro/org-env-config.yaml, שבו צריך לציין את אותו ארגון ואת אותה סביבה שהגדרתם לשימוש במיקרו-שער: 
    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 משתמש במפתחות האלה כדי לאמת אסימוני הרשאה. אם אימות הטוקן נכשל, המיקרו-גייטוויי מחפש מפתח ישן יותר בערכת המפתחות ומנסה להשתמש בו. הפורמט של המפתחות שמוחזרים הוא 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. בגלל העיכוב הזה בין חתימת הטוקן לבין רענון המופע של שער המיקרו, טוקנים שנחתמו באמצעות המפתח האחרון יידחו עד שכל המופעים יקבלו את המפתח הציבורי האחרון.

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

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

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

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

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

סינון של שרתי proxy שהורדו

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

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

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

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

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

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

כדי להפעיל את התכונה הזו, מוסיפים את המאפיין oauth.useUpstreamResponse: true להגדרות של Edge Microgateway. לדוגמה: 

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

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

בקטע הזה מוסבר איך מקבלים טוקנים של גישה ורענון מסוג OAuth2. אסימוני גישה משמשים לשליחת קריאות מאובטחות ל-API דרך המיקרו-שער. אסימוני רענון משמשים לקבלת אסימוני גישה חדשים.

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

בקטע הזה מוסבר איך משתמשים בשרת ה-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

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

  1. מקבלים אסימון גישה ורענון באמצעות /token API. שימו לב: סוג ההרשאה הוא 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 בספריית השורש של ההתקנה של Edge Microgateway. איפה מותקן Edge Microgateway לפרטים על אפשרויות ההגדרה, אפשר לעיין במסמכי התיעוד של forever-monitor.

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

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

מידע נוסף מופיע במאמר מעקב מתמשך במדריך העזר ל-CLI.

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

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

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

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

כדי להפעיל את Edge Microgateway במצב Standalone:

  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 הוא השם של הסביבה שבה השתמשתם בשם של קובץ התצורה.
    • ‫$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 מקומי

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

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

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

‫Edgemicro כקובץ עזר

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

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

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

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

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

בדיקת ההגדרות

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

בשלב הזה, תכונת הסנכרון נתמכת ב-Redis 5.0.x.

מהו הכלי לסנכרון?

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

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

המסנכרן של Edge Microgateway מספק מנגנון חלופי למופעים של Edge Microgateway לאחזור נתוני ההגדרה שנדרשים להם כדי להפעיל ולעבד תנועה של proxy ל-API. נתוני ההגדרה שאוחזרו מקריאות ל-Apigee Edge כוללים: הקריאה jwk_public_keys, הקריאה jwt_public_key, קריאת האתחול וקריאת מוצרי ה-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. הכלי יתחיל לשלוח בקשות (polling) ל-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 כדי לקבל נתוני הגדרה ולכתוב אותם במסד הנתונים המקומי. לאחר מכן צריך להגדיר מופעים אחרים של מיקרו-שער כדי לקרוא מהמסד הנתונים.
edge_config.redisBasedConfigCache true or false אם הערך הוא true, מופע Edge Microgateway מאחזר את נתוני ההגדרה שלו ממסד הנתונים של Redis במקום מ-Apigee Edge. מסד הנתונים של Redis חייב להיות זהה לזה שהוגדר בכלי הסנכרון לכתיבה. אם מסד הנתונים של Redis לא זמין או שהוא ריק, המיקרו-שער מחפש קובץ cache-config.yaml קיים להגדרות שלו.

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

הגדרת החרגה של כתובות URL לתוספים

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