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

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

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

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

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

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

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

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

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

לשרת ה-Proxy ל-API:

  • מארח וירטואלי של proxy ל-API: 'default'
  • הדומיין שמוגדר על ידי המארח הווירטואלי: "http://myOrg-prod.apigee.net"
  • נתיב הבסיס של שרת ה-proxy: ‎"/v1/weather"‎
  • TargetEndpoint שצוין לפי כלל המסלול: '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

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

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

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

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

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

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

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

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

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

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

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

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

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

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