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

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

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

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

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

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

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

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