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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

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

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

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

עבור proxy ל-API זה:

• מארח וירטואלי של שרת proxy ל-API: default
• הדומיין מוגדר על ידי שמות המארחים בקבוצת הסביבות: http://www.example.com
• נתיב בסיסי של שרת proxy: /v1/weather
• TargetEndpoint שצוין על ידי כלל הניתוב: default
• כתובת ה-URL של היעד: http://weather.yahooapis.com

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

curl -X GET http://www.example.com/v1/weather/forecastrss?w=12797282

שימו לב שהבקשה הזו מכילה את המשאב forecastrss ופרמטר שאילתה אחד, w. ‫Apigee מנתח את הבקשה כמו שמוצג בהמשך ומקצה חלקים מהבקשה למשתני flow:

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

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

• request.verb: GET
• proxy.basepath: ‏/v1/weather
• proxy.pathsuffix: ‏forecastrss
• request.querystring: w=12797282

הערה: יש הרבה משתני זרימה שונים שנוצרים במהלך העיבוד של בקשה ותגובה. מידע נוסף זמין במאמר Flow variables reference.

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

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

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

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

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

curl -X GET -H 'Content-type:application/xml' http://www.example.com/v1/weather/forecastrss?w=12797282

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

curl -X POST -H "Content-type:application/json" -d \
  '{"email" : "[e-mail]",
    "firstName" : "Jane",
    "lastName" : "Tutorial",
    "userName" : "jtutorialxml"
  }' \
  http://www.example.com/v1/register/user

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

איך מוחזרים נתוני התגובות?

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

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

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

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

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

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

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

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

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

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

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

var req_verb = context.getVariable('request.verb');
var req_scheme = context.getVariable('client.scheme');
var req_host = context.getVariable('request.header.host');
var req_request_uri = context.getVariable('request.uri');
var req_url = req_scheme + "://" + req_host + req_request_uri;

התוצאה של השרשור עשויה להיראות כך:

https://www.example.com/sample

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

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

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

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

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

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

• מדיניות AssignMessage: יוצרת או משנה הודעות של בקשות או תגובות HTTP במהלך זרימת הנתונים של proxy ל-API. בנוסף, הפעולה יוצרת משתני זרימה חדשים ומאכלסת אותם.
• מדיניות ExtractVariables: חילוץ תוכן מהודעות, כולל כותרות, נתיבי URI, מטענים ופרמטרים של שאילתות, לשימוש בהצהרת תנאי. לאחר מכן המדיניות מחילה דפוס טקסט על תוכן ההודעה, ואם נמצאת התאמה, היא מגדירה משתנה ייעודי.
• ‫JSONtoXML policy ו-XMLtoJSON policy: המרת הודעות מפורמט אובייקט ב-JavaScript ‏ (JSON) לפורמט extensible markup language ‏(XML) או להיפך.
• ‫JavaCallout policy, ‏ JavaScript policy, ‏ PythonScript policy,‏ RegularExpressionProtection policy: המדיניות הזו מאפשרת לכתוב סקריפט כדי לגשת למשתני זרימה שמכילים נתוני בקשות ותגובות.