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

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

Edge Microgateway גרסה 3.2.x

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

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

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

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

  1. כדי לשדרג לגרסה האחרונה של Edge Microgateway, מריצים את הפקודה הבאה npm: 
    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 הוא המפתח שהוחזר קודם על ידי הפקודה configure.
    • $SECRET הוא המפתח שהוחזר קודם על ידי הפקודה configure.

    לדוגמה

    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 הוא המפתח שהוחזר קודם על ידי הפקודה configure.
    • $SECRET הוא המפתח שהוחזר קודם על ידי הפקודה configure.

    לדוגמה:

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

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

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

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

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

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

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

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

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

איפה נשמרים קובצי היומנים

כברירת מחדל, קובצי יומנים מאוחסנים ב-/var/tmp.

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

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

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

משנים את הערך של dir כדי לציין ספרייה אחרת של קובצי יומנים.

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

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

edgemicro:
  logging:
    to_console: true

בהגדרה הזו, היומנים יישלחו ל-standard out. נכון לעכשיו, אי אפשר לשלוח יומנים גם ל-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:

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

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

edgemicro-HOST_NAME-INSTANCE_ID-api.log

לדוגמה:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

מידע על תוכן קובצי יומן

נוסף בגרסה: 2.3.3

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

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

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

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

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

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

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

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

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

נבחן אותם אחד אחרי השני:

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

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • 1436403888651 – חותמת תאריך של Unix
  • info – רמת הרישום ביומן. הערך הזה תלוי בהקשר של העסקה וברמת הרישום ביומן שמוגדרת בתצורה של 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 חדש ויוצר קבוצה חדשה של קובצי יומן עם המזהה הזה. מומלץ גם לעיין במאמר שיטות מומלצות לתחזוקת קובצי יומן.

הודעות שגיאה

חלק מהרשומות ביומן יכללו הודעות שגיאה. כדי לזהות איפה מתרחשות השגיאות ולמה הן מתרחשות, תוכלו לעיין בחומר העזר בנושא שגיאות ב-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 יכול לקבל בו-זמנית לפני שהוא סוגר את החיבור. ההגדרה הזו נועדה למנוע התקפות מניעת שירות (DoS). בדרך כלל, מגדירים אותו למספר גדול יותר מ-max_connections.
  • רישום ביומן:
    • 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 (נוסף בגרסה 3.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 עם אסימון גישה למוכ"ז. מאפשרת לאפשר רק את מודל האבטחה של OAuth (תוך שמירה על תאימות לאחור). (נוסף בגרסה 2.4.x)
  • allowAPIKeyOnly – אם הערך מוגדר כ-true, כל ממשק API חייב לכלול את הכותרת x-api-key (או מיקום מותאם אישית) עם מפתח API.ההגדרה הזו מאפשרת לאפשר רק את מודל האבטחה של מפתח ה-API (תוך שמירה על תאימות לאחור). (נוסף בגרסה 2.4.x)
  • gracePeriod – הפרמטר הזה עוזר למנוע שגיאות שנובעות מחוסר התאמה קל בין שעון המערכת לבין התאריכים 'לא לפני' (nbf) או 'תאריך הנפקה' (iat) שצוינו באסימון ההרשאה מסוג JWT. מגדירים את הפרמטר הזה למספר השניות שאפשר לאפשר להם לחול. (נוסף ב-2.5.7)

מאפיינים ספציפיים ל-Plugin

במאמר 'שימוש ב-plugins' מפורט מידע על מאפיינים שניתן להגדיר בכל פלאגין.

סינון שרתי 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. לדוגמה, ביטוי ה-regex ^[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. בהקשה על 'פיתוח', פותחים את המדיניות של JavaCallout בעורך.
  3. מוסיפים מאפיין מותאם אישית עם המפתח products.filter.attributes עם רשימה של שמות המאפיינים המופרדים בפסיקים. רק מוצרים שמכילים אחד משמות המאפיינים המותאמים אישית יחזרו אל Edge Microgateway.
  4. אם רוצים להשבית את הבדיקה כדי לבדוק אם המוצר מופעל בסביבה הנוכחית, אפשר להגדיר את המאפיין המותאם אישית products.filter.env.enable לערך false. (ברירת המחדל היא true).
  5. (ענן פרטי בלבד) אם אתם משתמשים ב-Edge לענן פרטי, צריך להגדיר את המאפיין 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 ומציינים רשימה של קודי סטטוס מופרדים בפסיקים לסינון. לדוגמה, כדי לסנן לפי הסטטוסים Pending ו-Revoked: 
    <?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 (אופציונלי): המספר המקסימלי של רשומות ניתוח נתונים שאפשר לאחסן במאגר לפני שמתחילים למחוק את הרשומות הישנות ביותר. ברירת המחדל: 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

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

edgemicro_proxyname-health

בתמונה הבאה מוצגים שני שרתים אנונימיים נפרדים בלוח הבקרה של Analytics: edgemicro_hello-health ו-edgemicro_mock-health:

אפשר להשתמש בפרמטרים האלה כדי להפריד בין נתיבים יחסיים ומוחלטים בלוח הבקרה של Analytics כשרתי proxy נפרדים:

  • relativePath (אופציונלי): מציין נתיב יחסי לצורך הפרדה בלוח הבקרה של Analytics. לדוגמה, אם מציינים את הערך /healthcheck, כל הקריאות ל-API שמכילות את הנתיב /healthcheck יופיעו במרכז הבקרה בתור edgemicro_proxyname-health. חשוב לשים לב שהדגל הזה מתעלם מנתיב הבסיס של שרת ה-proxy. כדי לבצע הפרדה על סמך נתיב מלא, כולל basepath, משתמשים בדגל 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 מאחורי חומת אש ארגונית

שימוש ב-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. מוסיפים את ההגדרות הבאות לקובץ התצורה של המיקרו-שער: 
    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 שצוינו במשתני הסביבה של שרת ה-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 אין תמיכה בשימוש בתווים כלליים לחיפוש (wildcard) מסוג '*' כרכיב הראשון בנתיב בסיס. לדוגמה, אין תמיכה באפשרות הבאה: חיפוש /*/.

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

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

  • private_key – המפתח הפרטי העדכני ביותר (האחרון שנוצר) של RSA, שמשמש לחתימה על אסימוני JWT.

  • public_key – האישור האחרון (הנוצר לאחרונה) שמשמש לאימות אסימוני JWT שנחתמו באמצעות private_key.

  • private_key_kid – מזהה המפתח הפרטי האחרון (הנוצר לאחרונה). מזהה המפתח הזה משויך לערך private_key ומשמש לתמיכה ברוטציית מפתחות.

  • public_key1_kid – מזהה המפתח הציבורי האחרון (הנוצר לאחרונה). המפתח הזה משויך לערך public_key1 ומשמש לתמיכה ברוטציית מפתחות. הערך הזה זהה ל-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, וצריך לציין את אותו ארגון ואותה סביבה שבהם הגדרתם את המיקרו-שער לשימוש: 
    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' (מזהה מפתח) ייחודי. לאחר מכן, המיקרו-שער משתמש במפתחות האלה כדי לאמת אסימוני הרשאה. אם אימות האסימון נכשל, המיקרו-שער נבדק אם יש מפתח ישן יותר בקבוצת המפתחות ומנסה את המפתח הזה. הפורמט של המפתחות המוחזרים הוא 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 דקות (כברירת מחדל) כשהתרחשה רענון של הגדרות המיקרו-שער. בגלל הזמן שחולף בין החתימה על הטוקן לבין הרענון של המכונה של שער המיקרו, טוקנים שנחתמו באמצעות המפתח העדכני ביותר יידחו עד שכל המכונות יקבלו את המפתח הציבורי העדכני ביותר.

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

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

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

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

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

סינון שרתים אנונימיים שהורדתם

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

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

מפתחות API מוחלפים באסימוני בעלים, שמאוחסנים במטמון. כדי להשבית את האחסון במטמון, מגדירים את הכותרת Cache-Control: no-cache בבקשות נכנסות ל-Edge Microgateway.

שימוש במפתח API

אפשר להעביר את מפתח ה-API בבקשת API כפרמטר של שאילתה או בכותרת. כברירת מחדל, השם של הכותרת ושל פרמטר השאילתה הוא x-api-key.

דוגמה לפרמטר של שאילתה:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

דוגמה לכותרת:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

הגדרת השם של מפתח ה-API

כברירת מחדל, השם x-api-key משמש גם לכותרת של מפתח ה-API וגם לפרמטר השאילתה. אפשר לשנות את ברירת המחדל הזו בקובץ התצורה, כפי שמוסבר בקטע ביצוע שינויים בתצורה. לדוגמה, כדי לשנות את השם ל-apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

בדוגמה הזו, גם פרמטר השאילתה וגם שם הכותרת משתנים ל-apiKey. השם x-api-key לא יפעל יותר בשני המקרים. אפשר לעיין גם במאמר ביצוע שינויים בהגדרות.

לדוגמה:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

מידע נוסף על שימוש במפתחות API עם בקשות שרת proxy זמין במאמר Secure Edge Microgateway.

הפעלת קודי תגובה ב-upstream

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

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

שולחים את פרטי הכניסה של הלקוח ככותרת של אימות בסיסי ואת הערך grant_type כפרמטר של טופס. פורמט הפקודה הזה מתואר גם במאמר RFC 6749: 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. קבלת טוקן גישה וטוקן רענון באמצעות ה-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 נמצא בספריית השורש של התקנת 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 ל-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 הוא שם הסביבה שבו השתמשתם בשם של קובץ התצורה.
    • $LOCAL_PROXY_NAME הוא השם של שרת ה-proxy המקומי שייווצר. אפשר להשתמש בכל שם שרוצים.
    • $LOCAL_PROXY_VERSION הוא מספר הגרסה של שרת ה-proxy.
    • $TARGET_URL היא כתובת ה-URL של היעד של שרת ה-proxy. (היעד הוא השירות ששרת ה-proxy קורא אליו).
    • $BASE_PATH הוא נתיב הבסיס של שרת ה-proxy. הערך הזה חייב להתחיל בקו נטוי קדימה. בנתיב בסיס ברמה הבסיסית (root), מציינים רק קו נטוי קדימה (slash). לדוגמה, '/'.

    לדוגמה:

    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 שחייב להופיע בכותרת ההרשאה של קריאת ה-API. בקטע הבא תקבלו JWT שיאפשר לשיחות API לעבור בלי השגיאה.

דוגמה: אחזור של אסימון הרשאה

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

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

מצב שרת proxy מקומי שימושי כשצריך לשייך רק שרת proxy אחד למכונה של Edge Microgateway. לדוגמה, אפשר להחדיר את Edge Microgateway ל-Kubernetes כשרת proxy בצד, שבו מיקרו-שער ושירות מריצים כל אחד ב-pod יחיד, והמיקרו-שער מנהל את התנועה אל השירות הנלווה וממנו. בתרשים הבא מוצגת הארכיטקטורה הזו, שבה Edge Microgateway פועל כשרתי proxy בצד (sidecar) באשכול 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 ומחזירה מפתח וסוד שדרושים כדי להפעיל את המיקרו-שער. אם דרושה לכם עזרה, תוכלו לעיין במאמר הגדרת 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), מציינים רק קו נטוי קדימה (slash). לדוגמה, '/'.

    לדוגמה:

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

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

מהו הסנכרוניזטור?

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

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

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