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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

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

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

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

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

בקשה מלקוח HTTP שעוברת דרך נקודת קצה של Proxy אל נקודת היעד בקצה העורפי כדי להגיע לשירות HTTP. מוצגות דוגמאות לנקודת קצה של ה-proxy ולנקודת קצה של היעד.

עבור proxy ל-API זה:

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

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

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

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

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

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

  • request.verb: "GET"
  • proxy.basepath: ‎"/v1/weather"‎
  • ‫proxy.pathsuffix: forecastrss
  • 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 Proxy מועברים לשרת הקצה העורפי. לדוגמה, אתם שולחים את הבקשה הבאה שכוללת כותרת:

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

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

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

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

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

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

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

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

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

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

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

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

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

  • מדיניות 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: המדיניות הזו מאפשרת לכם לכתוב סקריפט כדי לגשת למשתני זרימה שמכילים נתוני בקשות ותשובות.