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

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

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

הורדה של קוד לדוגמה והתנסות בו

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

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

יש שתי דוגמאות ל-JavaScript ב-proxy ל-API:

• ‫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, כפי שמוסבר במאמר בנושא הגדרת תהליכים. באמצעות Flows אפשר לציין את הרצף שבו מדיניות מופעלת על ידי proxy ל-API. בדוגמה הזו, נוצרות כמה מדיניות והן מתווספות לזרימת proxy ל-API.
• איך פרויקט של שרת proxy ל-API מאורגן במערכת הקבצים, כפי שמוסבר במאמר בנושא הפניה להגדרת שרת proxy ל-API.
• ידע בעבודה עם XML, ‏ JSON ו-JavaScript. בדוגמה הזו, יוצרים את ה-API proxy ואת כללי המדיניות שלו באמצעות קובצי XML שנמצאים במערכת הקבצים.

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

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

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

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

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

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

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

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

הוספת קוד JavaScript לפרוקסי

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

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

רוצה לנסות?

הוראות לפריסה ולהפעלת ה-proxy מפורטות בקובץ README של אוסף הפתרונות של JavaScript.

ייבוא ופריסה של 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, ולאמת את התוצאות על ידי שליחת אותה בקשה. כדי שהשינויים ייכנסו לתוקף, חשוב תמיד לוודא שפרסתם את שרת ה-proxy של ה-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, בדרך כלל יש יותר מדרך אחת להטמיע פונקציונליות ספציפית. כדאי להשתמש במדיניות מוכנה ככל האפשר, ולהימנע מהפיתוי לקודד את כל הלוגיקה של ה-proxy ל-API ב-JavaScript. למרות ש-Apigee Edge משתמש ב-JavaScript שעבר קומפילציה כדי לשפר את הביצועים, סביר להניח ש-JavaScript לא יפעל טוב כמו Policies. יכול להיות שיהיה קשה יותר לתחזק ולנפות באגים ב-JavaScript. כדאי להשתמש ב-JavaScript רק לפונקציונליות שייחודית לדרישות שלכם.

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

סיכום

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