משתני בקשה ותגובה

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

כששולחים בקשה לשרת proxy של API, אפשר להעביר את כל הפרטים הבאים או חלק מהם, בהתאם לאופן שבו מוגדר שרת ה-API של ה-API:

• כותרות של בקשות
• פרמטרים של שאילתה
• נתוני טופס
• מטענים ייעודיים (payloads) של XML או JSON
• מזהי URI של משאבים

כברירת מחדל, כל הנתונים בבקשה מועברים ללא שינוי מ-ProxyEndpoint ל-TargetEndpoint. לכן, כש-TargetEndpoint שולח את הבקשה לשרת הקצה העורפי, כל המידע שבבקשה המקורית מועבר לשירות הקצה העורפי.

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

איך נתוני הבקשות מועברים לשרת הקצה העורפי?

בתמונה הבאה מוצגת הגדרה של שרת proxy ל-API:

עבור שרת proxy זה של API:

• מארח וירטואלי של proxy ל-API: 'ברירת מחדל'
• הדומיין מוגדר על ידי המארח הווירטואלי: "http://myOrg-prod.apigee.net"
• נתיב הבסיס של שרת ה-proxy: '/v1/weather'
• TargetEndpoint צוין על ידי כלל נתיב: "default"
• כתובת אתר יעד: "http://weather.yahooapis.com"

אפליקציית לקוח שולחת בקשת GET לשרת ה-API של ה-API באמצעות הפקודה curl הבאה:

curl -X GET http://myOrg-prod.apigee.net/v1/weather/forecastrss?w=12797282

שימו לב שהבקשה הזו מכילה את המשאב 'חזאים' ופרמטר שאילתה אחד, w. Edge מנתח את הבקשה כפי שמוצג למטה ומקצה חלקים מהבקשה לזרימת משתנים:

{request.verb} {proxy.basepath}/{proxy.pathsuffix}?{request.querystring}

משתני הזרימה מוגדרים עם הערכים הבאים:

• request.verb: "GET"
• proxy.basepath: "/v1/weather"
• proxy.pathsuffix: "מנבאים"
• request.querystring: 'w=12797282'

בשלב הבא, TargetEndpoint שולח בקשה לשירות הקצה העורפי באמצעות מידע מהבקשה:

{request.verb} {target.basepath}/{proxy.pathsuffix}?{request.querystring}

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

curl -X GET http://weather.yahooapis.com/forecastrss?w=12797282

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

curl -X GET -H 'Content-type:application/xml' http://myOrg-prod.apigee.net/v1/weather/forecastrss?w=12797282

או בקשה בטופס למטה לכלול כותרת ונתוני טופס:

curl -X POST -H "Content-type:application/json" -d \
  '{"email" : "janetutorialxml@example.com",
    "firstName" : "Jane",
    "lastName" : "Tutorial",
    "userName" : "jtutorialxml"
  }' \
  http://myOrg-prod.apigee.net/v1/register/user

בשתי הדוגמאות, הכותרות ונתוני הטופס מועברים אל שירות הקצה העורפי ללא שינוי. הכותרות מיוצגות על ידי משתני זרימה כמו request.headers.count ו-request.headers.names. נתוני הטופס מיוצגים על ידי משתני זרימה כמו request.formparam.count ו-request.formparam.names.

איך מוצגים נתוני התשובות?

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

גישה לנתוני בקשות ותגובה בשרת proxy של API

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

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

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

הודעות של בקשות גישה

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

• כותרות
• פרמטרים של שאילתה
• פרמטרים בטופס
• כתובת IP של המקור
• גוף הודעת ה-HTTP

בתהליך רגיל, אחרי עיבוד הבקשה, שרת ה-proxy שולח את הבקשה שהשתנתה ליעד.

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

גישה להודעות תגובה

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

שרת ה-proxy מקבל הודעת תגובה, ולאחר מכן מחיל עליו סדרה של כללי מדיניות, המבוססים על התנאים שמעריכים את התגובה, שיכולים לשנות או לשנות את התגובה.

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

כללי מדיניות נפוצים לגישה למשתני זרימה

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

• המדיניות ל-assignMessage: יצירה או שינוי של בקשות HTTP או הודעות תגובה במהלך זרימה של שרת proxy ב-API. בנוסף, המערכת יוצרת ומאכלסת משתני זרימה חדשים.
• המדיניות extracts: חילוץ תוכן מהודעות, כולל כותרות, נתיבי URI, מטענים ייעודיים (payloads) ופרמטרים של שאילתות, לשימוש בהצהרת תנאים. לאחר מכן המדיניות מחילה תבנית טקסט על תוכן ההודעה, ואחרי שהיא מוצאת התאמה מגדירה משתנה ייעודי.
• מדיניות JSONtoXML ומדיניות XMLtoJSON: המרת הודעות מ-JavaScript Object Notation (JSON) לפורמט של שפת סימון ניתנת להרחבה (XML) או להפך.
• מדיניות JavaCallout, מדיניות JavaScript, מדיניות PythonScript, מדיניות רגולריExpressionProtection: כללי המדיניות האלה מאפשרים לכתוב סקריפט כדי לגשת למשתני זרימה שמכילים נתוני בקשות ותגובה.