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

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

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

    לדוגמה

    edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
  -s 05c14356e42ed1...4e34ab0cc824

אם Edge Microgateway נעצר:

  1. מפעילים מחדש את Edge Microgateway: 
    edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

    כאשר:

    • $ORG זהו שם הארגון שלך ב-Edge (עליך להיות מנהל מערכת ארגוני).
    • $ENV הוא סביבה בארגון שלכם (למשל test או prod).
    • $KEY הוא המפתח שהוחזר קודם על ידי פקודת ההגדרה.
    • $SECRET הוא המפתח שהוחזר קודם על ידי פקודת ההגדרה.

    לדוגמה:

    edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
  -s 05c1435...e34ab0cc824

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

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

הגדרת משתני סביבה

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

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

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

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

למידע נוסף על הגדרת TLS ב-Apigee Edge Microgateway, כדאי לצפות בסרטונים הבאים:

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

באפשרותך להגדיר את שרת ה-Microgateway להשתמש ב-SSL. לדוגמה, עם הגדרת SSL, תוכלו להפעיל ממשקי API דרך Edge Microgateway באמצעות הפרוטוקול "https", באופן הבא:

https://localhost:8000/myapi

כדי להגדיר SSL בשרת Microgateway, בצע את השלבים הבאים:

  1. תוכלו ליצור או לקבל אישור ומפתח SSL באמצעות כלי השירות openssl או בשיטה הרצויה לכם.
  2. יש להוסיף את המאפיין edgemicro:ssl לקובץ התצורה של Edge Microgateway. בטבלה הבאה מופיעה רשימת האפשרויות המלאה. לדוגמה:
    edgemicro:
  ssl:
   key: <absolute path to the SSL key file>
   cert: <absolute path to the SSL cert file>
   passphrase: admin123 #option added in v2.2.2
   rejectUnauthorized: true #option added in v2.2.2
   requestCert: true
  3. מפעילים מחדש את Edge Microgateway. פועלים לפי השלבים המפורטים בקטע ביצוע שינויים בהגדרות בהתאם לקובץ התצורה שערכתם: קובץ ברירת המחדל או קובץ התצורה של זמן הריצה.

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

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

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

אפשרות תיאור
key נתיב לקובץ ca.key (בפורמט PEM).
cert נתיב לקובץ ca.cert (בפורמט PEM).
pfx נתיב לקובץ pfx שמכיל את המפתח הפרטי, האישור ואישורי ה-CA של הלקוח בפורמט PFX.
passphrase מחרוזת שמכילה את ביטוי הסיסמה למפתח הפרטי או ל-PFX.
ca נתיב לקובץ שמכיל רשימה של אישורים מהימנים בפורמט PEM.
ciphers מחרוזת שמתארת את הצפנים שצריך להשתמש בהם, מופרדים באמצעות ":".
rejectUnauthorized אם הערך הוא True, אישור השרת מאומת מול הרשימה של רשויות האישורים שסופקו. אם האימות ייכשל, תוחזר שגיאה.
secureProtocol שיטת ה-SSL שבה יש להשתמש. לדוגמה, שיטת SSLv3_method כדי לכפות את השימוש ב-SSL בגרסה 3.
servername שם השרת לתוסף TLS SNI (Server Name Indication).
requestCert True עבור SSL דו-כיווני; False עבור SSL חד-כיווני

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

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

בדוגמה הבאה מופיעות הגדרות שיחולו על כל המארחים:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

בדוגמה הזו, ההגדרות חלות רק על המארח שצוין:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

הנה דוגמה ל-TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

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

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

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

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

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

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

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

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

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

כברירת מחדל, קובצי יומן נשמרים בתיקייה /var/tmp.

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

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

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

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

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

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

edgemicro:
  logging:
    to_console: true

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

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

צריך לציין את רמת היומן לשימוש בהגדרה של 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

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

נוסף בגרסה 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 חדש ויוצר קבוצה חדשה של קובצי יומן עם ה-UID הזה. למידע נוסף: שיטות מומלצות לתחזוקה של קובצי יומן.

הודעות שגיאה

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

הסבר על הגדרת Edge Microgateway

המיקום של קובץ התצורה

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

מאפייני edge_config

ההגדרות האלה משמשות להגדרת האינטראקציה בין מכונת Edge Microgateway לבין Apigee Edge.

  • bootrap (ברירת מחדל: ללא) כתובת URL שמפנה לשירות ספציפי של Edge Microgateway שפועל ב-Apigee Edge. Edge Microgateway משתמש בשירות הזה כדי לתקשר עם Apigee Edge. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה ליצירת זוג מפתחות ציבורי/פרטי: edgemicro genkeys. לפרטים נוספים, אפשר לקרוא את המאמר בנושא הגדרה והגדרה של מיקרו-שער של Edge.
  • jwt_public_key: (ברירת מחדל: אין) כתובת URL שמפנה לשרת ה-proxy של Edge Microgateway שנפרס ב-Apigee Edge. שרת ה-proxy הזה משמש כנקודת קצה לאימות לצורך הנפקת אסימוני גישה חתומים ללקוחות. כתובת ה-URL הזו מוחזרת כשמריצים את הפקודה לפריסת שרת ה-Proxy: edgemicro configuration. לפרטים נוספים, אפשר לקרוא את המאמר בנושא הגדרה והגדרה של מיקרו-שער של Edge.
  • quotaUri: צריך להגדיר את מאפיין התצורה הזה אם רוצים לנהל את המכסות באמצעות שרת ה-proxy של edgemicro-auth שנפרס בארגון. אם לא מגדירים את המאפיין הזה, ברירת המחדל של נקודת הקצה של המכסה היא נקודת הקצה הפנימית של Edge Microgateway. 
    edge_config:
  quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth

מאפייני Edgemicro

ההגדרות האלה מגדירות את תהליך המיקרו-שער של Edge.

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

    res.statusCode = 429; // Too many requests
  • max_connections_hard: (ברירת מחדל: -1) המספר המקסימלי של בקשות בו-זמנית ש-Edge Microgateway יכול לקבל לפני כיבוי החיבור. ההגדרה הזו נועדה למנוע התקפות של מניעת שירות (DoS). בדרך כלל, מגדירים אותו למספר גדול מ-max_ ביחדs.
  • רישום ביומן:
    • level: (ברירת מחדל: שגיאה)
      • info – (מומלץ) מתעד את כל הבקשות והתגובות שזורמות דרך מכונת Edge Microgateway.
      • warn – רישום של הודעות אזהרה בלבד.
      • error – מתעדת הודעות שגיאה בלבד.
      • debug (ניפוי באגים), תיעוד של הודעות ניפוי באגים ביומנים, יחד עם מידע, אזהרה והודעות שגיאה.
      • trace - יומני מעקב אחר שגיאות, יחד עם מידע, אזהרה והודעות שגיאה.
      • none – אל תיצור קובץ יומן.
    • dir: (ברירת מחדל: /var/tmp) הספרייה שבה מאוחסנים קובצי היומן.
    • stats_log_interval: (ברירת מחדל: 60) מרווח בשניות, כאשר רשומת הנתונים הסטטיסטיים נכתבת בקובץ היומן של ה-API.
    • rotate_interval: (ברירת מחדל: 24) מרווח, בשעות, כשמתבצעת רוטציה של קובצי יומן.
  • dir: נתיב יחסי מספריית ./gateway לספרייה ./Plugins או מנתיב מוחלט.
  • sequence: רשימה של מודולים של פלאגין להוספה למכונה של Edge Microgateway. המודולים יפעלו לפי הסדר שבו הם מצוינים כאן.
  • ניפוי באגים: הוספת ניפוי באגים מרחוק לתהליך Microgateway של Edge.
    • port: מספר היציאה שצריך להאזין לו. לדוגמה, צריך להגדיר את הכלי לניפוי באגים בסביבת הפיתוח המשולבת (IDE) כך שיאזין ביציאה הזו.
    • args: ארגומנטים לתהליך ניפוי הבאגים. לדוגמה: args --nolazy
  • config_change_poll_interval: (ברירת מחדל: 600 שניות) Edge Microgateway טוען תצורה חדשה מדי פעם ומבצע טעינה מחדש אם משהו השתנה. הסקר מאפשר לזהות את כל השינויים שבוצעו ב-Edge (שינויים במוצרים, שרתי proxy שתומכים ב-microgateway וכו') וגם את השינויים שבוצעו בקובץ התצורה המקומי.
  • disable_config_poll_interval: (ברירת מחדל: false) מגדירים את הערך true כדי לכבות את תשאול השינוי האוטומטי.
  • request_timeout: הגדרה של זמן קצוב לתפוגה עבור בקשות ליעד. הזמן הקצוב לתפוגה מוגדר בשניות. אם הזמן הקצוב פג, Edge Microgateway מגיב עם קוד סטטוס 504. (נוסף v2.4.x)
  • keep_alive_timeout: המאפיין הזה מאפשר להגדיר את הזמן הקצוב לתפוגה של Edge Microgateway (באלפיות השנייה). (ברירת מחדל: 5 שניות) (נוספה גרסה 3.0.6)
  • headers_timeout: המאפיין הזה מגביל את משך הזמן (באלפיות שנייה) שמנתח ה-HTTP ימתין לקבלת כותרות ה-HTTP המלאות.

    לדוגמה:

    edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

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

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

    דוגמה: 

    edgemicro
  enableAnalytics=false|true
  • on_target_response_abort: המאפיין הזה מאפשר לקבוע את אופן הפעולה של Edge Microgateway אם החיבור בין הלקוח (Edge Microgateway) לבין שרת היעד ייסגר מוקדם מדי.
    Value תיאור
    ברירת המחדל אם לא מציינים את הערך 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 כדי למנוע העברה של כותרות דרך ליעד.

מאפייני oauth

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

  • allowNoAuthorization: (ברירת מחדל: false) אם היא מוגדרת כ-True, קריאות ל-API יכולות לעבור דרך Edge Microgateway בלי בכלל כותרת Authorization. מגדירים את הערך כ-False כדי לדרוש כותרת הרשאה (ברירת מחדל).
  • allowInvalidAuthorization: (ברירת מחדל: false) אם היא מוגדרת כ-True, קריאות ל-API מורשות להעביר אם האסימון שהועבר בכותרת Authorization לא תקין או שתוקפו פג. אם מגדירים את הערך הזה כ-FALSE כדי לדרוש אסימונים תקפים (ברירת מחדל).
  • authorization-header: (ברירת המחדל: Authorization: Bearer) הכותרת המשמשת לשליחת אסימון הגישה אל Edge Microgateway. כדאי לשנות את ברירת המחדל במקרים שבהם היעד צריך להשתמש בכותרת Authorization למטרה אחרת.
  • api-key-header: (ברירת מחדל: x-api-key) שם הכותרת או פרמטר השאילתה שמשמש להעברת מפתח API אל Edge Microgateway. למידע נוסף, ראו שימוש במפתח API.
  • keep-authorization-header: (ברירת מחדל: false) אם היא מוגדרת כ-true, כותרת ההרשאה שנשלחת בבקשה מועברת ליעד (היא נשמרת).
  • allowOAuthOnly – אם המדיניות מוגדרת כ-True, לכל ממשק API חייב להיות כותרת Authorization עם אסימון גישה למוכ"ז. מאפשרת לאשר רק את מודל האבטחה של OAuth (תוך שמירה על תאימות לאחור). (נוסף 2.4.x)
  • allowAPIKeyOnly -- אם היא מוגדרת כ-True, לכל ממשק API חייבת להיות כותרת x-api-key (או מיקום מותאם אישית) עם מפתח API.מאפשרת להתיר רק את מודל האבטחה של מפתח ה-API (תוך שמירה על תאימות לאחור). (נוסף 2.4.x)
  • gracePeriod – הפרמטר הזה עוזר למנוע שגיאות שנגרמות עקב אי-התאמות קלות בין שעון המערכת לבין השעות מסוג 'לא לפני' (nbf) או 'הונפק בתאריך (iat)' שצוינו באסימון האימות של JWT. צריך להגדיר את הפרמטר הזה למספר השניות כדי לאפשר אי-התאמות כאלה. (נוסף 2.5.7)

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

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

סינון שרתי proxy

אפשר לסנן אילו שרתי proxy בעלי מודעות ל-microgateway יעבד מכונת Edge Microgateway. כש-Edge Microgateway מופעל, הוא מוריד את כל שרתי ה-proxy המותאמים ל-Microgateway בארגון שאליו הוא משויך. ניתן להשתמש בתצורה הבאה כדי להגביל את שרתי ה-proxy שהמיקרו-שער יעבד. לדוגמה, ההגדרה הזו מגבילה את שרתי ה-proxy שהמיקרו-שער יעבד לשלושה: edgemicro_proxy-1, edgemicro_proxy-2 ו-edgemicro_proxy-3:

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

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

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

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

חשוב לזכור שצריך לציין את הערך של פרמטר השאילתה בפורמט של ביטוי רגולרי ולקודד את כתובת ה-URL. לדוגמה, הביטוי הרגולרי ^[Ee]dgemicro.*$ כולל שמות כמו: "edgemicro-test-1" , "edgemicro_demo" ו-"Edgemicro_New_Demo". הערך המקודד של כתובת האתר, שמתאים לשימוש בפרמטר השאילתה, הוא %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. בהקשה על 'פיתוח', פותחים את המדיניות של 'יתרונות מרכזיים של Java' בעורך.
  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>

הגדרת תדירות דחיפה של Analytics

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

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

לדוגמה:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

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

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

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

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

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

edgemicro_proxyname-health

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

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

  • relativePath (אופציונלי): מציין נתיב יחסי להפרדה במרכז הבקרה של Analytics. לדוגמה, אם מציינים /healthcheck, כל הקריאות ל-API שמכילות את הנתיב /healthcheck יופיעו במרכז הבקרה בתור edgemicro_proxyname-health. שים לב שהסימון הזה מתעלם מנתיב הבסיס של שרת ה-proxy. כדי לבצע הפרדה על סמך נתיב מלא, כולל נתיב בסיסי, יש להשתמש בדגל proxyPath.
  • proxyPath (אופציונלי): מציין נתיב מלא של שרת proxy ל-API, כולל נתיב הבסיס של שרת ה-proxy, להפרדה במרכז הבקרה של Analytics. לדוגמה, אם מציינים /mocktarget/healthcheck, שבו /mocktarget הוא נתיב הבסיס של שרת ה-proxy, כל הקריאות ל-API עם הנתיב /mocktarget/healthcheck יופיעו במרכז הבקרה בתור edgemicro_proxyname-health.

לדוגמה, לפי התצורה הבאה, כל נתיב API שמכיל /healthcheck יופרד על ידי הפלאגין של Analytics. כלומר, /foo/healthcheck ו-/foo/bar/healthcheck יופרדו כשרת proxy נפרד שנקרא edgemicro_proxyname-health במרכז הבקרה של Analytics.

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

בהגדרה הבאה, כל API עם נתיב שרת ה-proxy /mocktarget/healthcheck יופרד כשרת proxy נפרד שנקרא edgemicro_proxyname-health במרכז הבקרה של ניתוח נתונים.

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

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

שימוש בשרת 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 לא צריך להיות שרת proxy.

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

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

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

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

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

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

    כאשר:

    • tunnel: (אופציונלי) כשהערך הוא True, Edge Microgateway משתמש בשיטת HTTP CONNECT כדי לנתב בקשות HTTP בחיבור TCP יחיד. (כך גם משתני הסביבה (המפורטים בהמשך) להגדרת שרת ה-proxy מופעלים ב-TLS (אבטחת שכבת התעבורה). ברירת המחדל: false
    • url: כתובת ה-URL של שרת ה-Proxy מסוג HTTP.
    • עקיפה: (אופציונלי) מציינת כתובת URL אחת או יותר של מארח יעד שמופרדות בפסיקים, שאמורות לעקוף את שרת ה-proxy של HTTP. אם לא הוגדר המאפיין הזה, צריך להשתמש במשתנה הסביבה NO_PROXY כדי לציין את כתובות ה-URL של היעד שרוצים לעקוף.
    • מופעל: אם True ו-proxy.url מוגדר, יש להשתמש בערך proxy.url עבור שרת ה-Proxy של HTTP. אם True ו-proxy.url לא מוגדר, יש להשתמש בשרתי ה-proxy שצוינו במשתני הסביבה HTTP_PROXY ו-HTTPS_PROXY של שרת ה-HTTP 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-aware). לדוגמה, נתיב בסיסי של /team/*/members מאפשר ללקוחות לקרוא https://[host]/team/blue/members ו- https://[host]/team/green/members ללא צורך ליצור שרתי proxy חדשים של API כדי לתמוך בצוותים חדשים. לתשומת ליבך: /**/ לא נתמך.

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

סיבוב מקשי JWT

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

איך Edge Microgateway משתמש במפתחות JWT

אסימון אינטרנט מסוג JSON (JWT) הוא תקן אסימון שמתואר ב-RFC7519. JWT מספק דרך לחתום על סדרת תביעות, שאפשר לאמת אותן באופן מהימן על ידי המקבל של ה-JWT.

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

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

מידע נוסף על יצירת אסימוני JWT באמצעות ה-CLI זמין במאמר יצירת אסימון.

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

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

כדי ליצור JWT, Edge משתמש במידע שמאוחסן ב-KVM המוצפן. KVM בשם microgateway נוצר ואכלס את המפתחות בזמן ההגדרה הראשונית (ההגדרה) של Edge Microgateway. המפתחות ב-KVM משמשים לחתימה ולהצפנה של JWT.

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

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

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

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

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

  • public_key1 - המפתח הציבורי האחרון (שנוצר לאחרונה).

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

  • public_key2_kid - המזהה של המפתח הציבורי הישן. המפתח הזה משויך לערך Public_key2 והוא משמש לתמיכה ברוטציית מפתחות.

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

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

הגדרה של עיכוב 'not לפני'

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

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

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

  1. פותחים את קובץ התצורה של Edge Micro: ~/.edgemicro/org-env-config.yaml
  2. מוסיפים את הרכיב proxyPattern בקטע edge_config. לדוגמה, התבנית הבאה תוריד שרתי proxy כמו edgemicro_foo, edgemicro_fast ו-edgemicro_first. 
    edge_config:
…
proxyPattern: edgemicro_f*

ציון מוצרים ללא שרתי proxy ל-API

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

ניפוי באגים ופתרון בעיות

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

אפשר להריץ את Edge Microgateway באמצעות כלי לניפוי באגים, למשל node-inspector. הפעולה הזו שימושית לפתרון בעיות ולניפוי באגים ביישומי פלאגין מותאמים אישית.

  1. מפעילים מחדש את Edge Microgateway במצב ניפוי באגים. כדי לעשות את זה, צריך להוסיף את הפקודה DEBUG=* לתחילת הפקודה start: 
    DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

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

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

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

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

קובצי היומן בבדיקה

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

שימוש באבטחת מפתחות API

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

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

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

שימוש במפתח API

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

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

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

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

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

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

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

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

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

לדוגמה:

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

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

אפשר לקבל אסימון גישה גם באמצעות הפקודה edgemicro token CLI. מידע נוסף על ה-CLI זמין במאמר ניהול אסימונים.

API 1: שליחת פרטי כניסה כפרמטרים לגוף

מחליפים את שמות הארגון והסביבה בכתובת ה-URL, מחליפים את הערכים של 'מזהה הצרכן' ו'סוד הצרכן' שהתקבלו מאפליקציה למפתחים ב-Apigee Edge בפרמטרים של הגוף client_id ו-client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: שליחת פרטי כניסה בכותרת 'אימות בסיסי'

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

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

פלט לדוגמה

ה-API מחזיר תגובת JSON. שימו לב שאין הבדל בין הנכס token לנכס access_token. אפשר להשתמש בכל אחת מהן. שימו לב ש-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. מידע נוסף על אפשרויות ההגדרה זמין במסמכי התיעוד בנושא מעקב לתמיד.

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

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

מידע נוסף זמין במאמר Forever Monitoring בחומר העזר בנושא CLI.

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

אם אתם מפעילים כמה מכונות של Edge Microgateway, יכול להיות שתרצו לנהל את ההגדרות שלהן ממקום אחד. כדי לעשות זאת, צריך לציין נקודת קצה (endpoint) ב-HTTP שבה אפשר להוריד את קובץ התצורה של Edge Micro. אפשר לציין את נקודת הקצה הזו כשמפעילים את Edge Micro באמצעות הדגל -u.

לדוגמה:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

שבה נקודת הקצה mgconfig מחזירה את התוכן של קובץ התצורה. זהו הקובץ שהמיקום שלו, כברירת מחדל, הוא ~/.edgemicro, עם המוסכמות למתן שמות: org-env-config.yaml.

השבתה של אחסון זמני של נתונים בחיבור TCP

אפשר להשתמש במאפיין ההגדרה nodelay כדי להשבית את מאגר הנתונים הזמני עבור חיבורי TCP שבהם נעשה שימוש ב-Edge Microgateway.

כברירת מחדל, חיבורי TCP משתמשים באלגוריתם Nagle כדי לאחסן נתונים זמניים לפני השליחה. אם מגדירים את nodelay ל-true, תשבית את ההתנהגות הזו (הנתונים יופעלו באופן מיידי לאחר כל קריאה ל-socket.write()). לפרטים נוספים, אפשר לעיין גם במשאבי העזרה של Node.js.

כדי להפעיל את nodelay, צריך לערוך את קובץ התצורה של Edge Micro באופן הבא:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

הפעלת Edge Microgateway במצב עצמאי

אפשר להריץ את Edge Microgateway כשהוא מנותק מכל תלות של Apigee Edge. התרחיש הזה, שנקרא מצב עצמאי, מאפשר להריץ ולבדוק את Edge Microgateway ללא חיבור לאינטרנט.

התכונות הבאות לא פועלות במצב עצמאי כי הן דורשות חיבור ל-Apigee Edge:

  • מפתח OAuth ו-API
  • מכסה
  • ניתוח נתונים

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

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

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

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

    לדוגמה:

    edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  5. בודקים את ההגדרה. 
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

    מאחר שהפלאגין extauth נמצא בקובץ foo-bar-config.yaml, מופיעה השגיאה "missing_authorization". הפלאגין הזה מאמת JWT שחייב להופיע בכותרת Authorization של הקריאה ל-API. בקטע הבא מתקבל JWT שיאפשר קריאות ל-API ללא השגיאה.

דוגמה: קבלת אסימון הרשאה

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

בשלבים הבאים מוסבר איך לקבל אסימון באמצעות נקודת הקצה edgemicro-auth/jwkPublicKeys:

  1. כדי לפרוס את שרת ה-Proxy של edgemicro-auth בארגון או בסביבה ב-Apigee Edge צריך לבצע הגדרה והגדרה סטנדרטיות של Edge Microgateway. אם כבר ביצעת את השלב הזה, אין צורך לחזור עליו.
  2. אם פרסתם את Edge Microgateway ל-Apigee Cloud, אתם צריכים להיות מחוברים לאינטרנט כדי לקבל JWT מנקודת הקצה הזו.
  3. עוצרים את Edge Microgateway: 
    edgemicro stop
  4. בקובץ התצורה שיצרת קודם לכן ($HOME/.edgemicro/org-env-config.yaml), מכוונים את המאפיין extauth:publickey_url לנקודת הקצה של edgemicro-auth/jwkPublicKeys בארגון או בסביבה של Apigee Edge. לדוגמה:
    extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
  5. מפעילים מחדש את Edge Microgateway כמו קודם, תוך שימוש בשמות הארגון או הסביבות שבהם השתמשתם בשם קובץ התצורה. לדוגמה: 
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. קבלת אסימון JWT מנקודת הקצה של ההרשאה. מאחר שאתם משתמשים בנקודת הקצה edgemicro-auth/jwkPublicKeys, תוכלו להשתמש בפקודה הבאה של ה-CLI:

אפשר ליצור JWT ל-Edge Microgateway באמצעות הפקודה edgemicro token או API. לדוגמה:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

כאשר:

  • your_org הוא השם של ארגון Apigee שעבורו הגדרת בעבר Edge Microgateway.
  • your_env היא סביבה בארגון.
  • האפשרות i מציינת את מפתח הצרכן מאפליקציה של מפתח שמכילה מוצר שכולל את שרת ה-proxy של edgemicro-auth.
  • האפשרות s מציינת את סוד הצרכן מאפליקציית מפתח שמכילה מוצר שכולל את שרת ה-proxy edgemicro-auth.

הפקודה הזו מבקשת מ-Apigee Edge ליצור JWT שאפשר להשתמש בו כדי לאמת קריאות ל-API.

כדאי לעיין גם במאמר יצירת אסימון.

בדיקת התצורה העצמאית

כדי לבדוק את ההגדרות האישיות, צריך לקרוא ל-API עם האסימון שנוסף בכותרת Authorization באופן הבא:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

דוגמה:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

פלט לדוגמה:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

שימוש במצב שרת proxy מקומי

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

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

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

Edgemicro בתור Sidecar

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

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

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

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

    לדוגמה:

    edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
  -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
  -t http://mocktarget.apigee.net -b /echo

בדיקת התצורה

אפשר לבדוק את ההגדרה המקומית של שרת ה-proxy באמצעות קריאה לנקודת הקצה של שרת ה-proxy. לדוגמה, אם ציינתם נתיב בסיס של /echo, תוכלו לקרוא לשרת ה-Proxy באופן הבא:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

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

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

לדוגמה:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

פלט לדוגמה:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

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

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

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

מהו הסנכרון?

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

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

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

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

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

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

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

לדוגמה: 

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

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