תכנות שרתי proxy של ממשק API באמצעות JavaScript

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

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

מורידים את הקוד לדוגמה ומנסים אותו

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

הדוגמה הזו של ספר המתכונים ממחישה דפוס של שרת proxy של API שבו מטמיעים התנהגות של API ב-JavaScript. הדוגמאות של JavaScript מיועדות להראות לך איך לעבוד עם משתנים פשוטים ותוכן הודעה. דוגמה אחת מראה איך לקבל ולהגדיר משתנים. בדוגמה השנייה אפשר לראות איך לנתח את קובץ JSON ולבנות הודעה מתוך התוצאה.

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

• setHeaders.js: קוד ה-JavaScript הזה מקבל את הערכים של כמה משתנים שמוגדרים כאשר מופעל שרת proxy של API. קוד ה-JavaScript מוסיף את המשתנים האלה להודעת התגובה, כדי שתוכלו לראות את הערכים שלהם לכל בקשה שאתם שולחים.
• minimize.js: קוד ה-JavaScript הזה מראה איך לעבוד עם תוכן ההודעות. הרעיון שעומד מאחורי הדוגמה הזו הוא ששירות מחזיר לעתים קרובות יותר נתונים מהנדרש. לכן, קוד ה-JavaScript מנתח את הודעת התגובה, מחלץ מספר מאפיינים מעניינים, ולאחר מכן משתמש בהם כדי לבנות את התוכן של הודעת התגובה.

הקוד עבור setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

הקוד עבור minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

אפשר לגשת למשתני זרימה ב-JavaScript דרך אובייקט ההקשר. האובייקט הזה הוא חלק ממודל האובייקטים של JavaScript ב-Edge. פרטים על מודל האובייקט זמינים במאמר מודל אובייקטים של JavaScript.

לפני שמתחילים

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

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

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

הסבר על זרימת שרת ה-proxy

כדי להפעיל את JavaScript בשרת proxy ל-API, צריך לצרף אותו לזרימה באמצעות קובץ שמצורף למדיניות, שנקרא 'שלב'. מדיניות מסוג JavaScript (שימוש באותיות רישיות בהערות) כוללת פשוט הפניה לשם של קובץ JavaScript. הפניה של המדיניות לקובץ JavaScript מתבצעת באמצעות הרכיב ResourceURL.

לדוגמה, המדיניות הבאה מפנה לקובץ ה-JavaScript שנקרא setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

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

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

בחלונית הניווט, בוחרים באפשרות Proxy Endpoints > default > PostFlow.

הגדרת ה-XML המתאימה ל-ProxyEndpoint בשם 'default' מופיעה למטה.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

הנה סיכום של מרכיבי התהליך.

• <Request> – הרכיב <Request> מורכב מכמה רכיבי <Step>. כל שלב כולל את אחד מכללי המדיניות שיצרת עד לסיום הנושא הזה. כללי המדיניות האלה מצרפים קוד JavaScript לתהליך ה-API של שרת ה-proxy, והמיקום של קובץ המדיניות המצורף קובע מתי ה-JavaScript יופעל.
• <Response> – הרכיב <Response> כולל גם <Steps>. השלבים האלה כוללים גם קריאה למדיניות שאחראית לעיבוד התשובה הסופית מהיעד (בדוגמה הזו הוא יעד שירות מדומה של Apigee – שימו לב להגדרה HTTPTargetConnection, שנמצאת תחת /apiproxy/targets/default.xml).
• <HTTPProxyConnection> - מציין את המארח ואת נתיב ה-URI שמגדירים את כתובת הרשת שאפליקציות קוראות לצרוך את ה-API הזה.
  
• <RouteRule> – הרכיב הזה מציין איזו הגדרה של TargetEndpoint מופעלת על ידי ProxyEndpoint.

הוספת קוד JavaScript לשרת proxy

JavaScript (כמו סקריפטים של Python, קובצי Java JAR, קובצי XSLT וכו') מאוחסנים כמשאבים. קל יותר לאחסן את קובצי ה-JavaScript בשרת ה-API של JavaScript כשמתחילים לעבוד עם JavaScript. בהמשך, מומלץ להפוך את JavaScript לגנרי ולשימוש חוזר, כמה שאפשר, ואז לאחסן אותו ברמת הסביבה או הארגון. הפעולה הזו מונעת את הצורך לאחסן את אותם קובצי JavaScript במספר שרתי proxy של API, שעלולים להפוך לבלתי ניתנים לניהול במהירות.

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

אני רוצה לנסות

לקבלת הוראות על פריסה והפעלה של שרת ה-proxy, אפשר לעיין בספר המתכונים של JavaScript README.

ייבוא ופריסה של שרת ה-proxy של ה-API

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

לחלופין, אתם יכולים להריץ את הפקודה הבאה בספרייה /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

בדיקת JavaScript

מריצים את הפקודה הבאה בספרייה /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

סימון ה-Curl -v משמש בסקריפט המעטפת כדי להציג כותרות HTTP בהודעת התגובה ששונתה על ידי ה-JavaScript.

אפשר לשלוח בקשה ישירות באופן הבא:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 

אם קוד ה-JavaScript יפעל כראוי, תוצג תגובה הדומה לזו:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

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

שגיאות בסקריפט

באופן בלתי נמנע יופיעו שגיאות בעת כתיבת JavaScript. הפורמט של שגיאות JavaScript שיופיעו על ידי שרת proxy של API מוצג בהמשך.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

מתי להשתמש ב-JavaScript

ב-Apigee Edge יש בדרך כלל יותר מדרך אחת להטמיע פונקציונליות ספציפית. מומלץ להשתמש בכללי מדיניות מוגדרים מראש כשהדבר אפשרי, ולהימנע מהפיתוי לתכנת את כל הלוגיקה של שרת ה-API של ה-API ב-JavaScript. למרות ש-Apigee Edge משתמש ב-JavaScript שעבר קומפילציה כדי לשפר ביצועים, לא סביר שהביצועים של JavaScript יהיו טובים כמו של כללי המדיניות. יכול להיות שיהיה קשה יותר לתחזק את JavaScript ולנפות באגים. יש לשמור את JavaScript כדי להשתמש בפונקציונליות שייחודית לדרישות שלך.

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

סיכום

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