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

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

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

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

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

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

בוחרים באפשרות נקודות קצה של שרת proxy > ברירת מחדל > PostFlow ב-Navigator .

תצורת ה-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>

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

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

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

JavaScript (כגון סקריפטים של Python, קובצי Java JAR, קובצי XLS וכו') מאוחסנים בתור משאבים. כשאתם רק מתחילים לעבוד עם JavaScript, הכי קל לאחסן את קובצי JavaScript בשרת ה-proxy ל-API. ככל שמתקדמים, צריך להפוך את 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 ולאמת את תוצאות על ידי שליחת אותה בקשה. חשוב תמיד להקפיד לפרוס את שרת ה-proxy ל-API שמכיל כדי שהשינויים ייכנסו לתוקף.

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

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

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

סיכום

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