המדיניות בנושא JavaScript

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

המדיניות JavaScript מאפשרת לציין קובץ מקור של JavaScript להפעלה, או לכלול קוד JavaScript ישירות בהגדרת המדיניות באמצעות רכיב <Source>. בכל מקרה, קוד ה-JavaScript מופעל כשהשלב שאליו מצורפת המדיניות מופעל.

באפשרות של קובץ המקור, קוד המקור תמיד מאוחסן במיקום סטנדרטי בחבילת ה-proxy: ‏ apiproxy/resources/jsc. אפשר גם לאחסן את קוד המקור בקובץ משאבים ברמת הסביבה או הארגון. הוראות מפורטות מופיעות במאמר בנושא קבצי משאבים. אפשר גם להעלות JavaScript באמצעות כלי העריכה של ה-proxy בממשק המשתמש של Apigee.

קבצי מקור של JavaScript חייבים להסתיים בסיומת .js. ‫Apigee תומך ב-JavaScript שפועל במנוע JavaScript‏ Rhino 1.7.13.

ב-Apigee לא מומלץ להשתמש במדיניות JavaScript במקרים הבאים:

  • רישום ביומן. המדיניות בנושא רישום נתונים של הודעות מתאימה יותר לרישום נתונים בפלטפורמות רישום נתונים של צד שלישי, כמו Splunk, ‏ Sumo ו-Loggly. המדיניות הזו גם משפרת את הביצועים של proxy ל-API, כי היא מופעלת ב-PostClientFlow אחרי שהתגובה חוזרת ללקוח.
  • החלפת מדיניות Apigee. מדיניות JavaScript לא מחליפה את היכולות של מדיניות Apigee. אם היכולות שאתם צריכים זמינות במדיניות של Apigee, עדיף להשתמש במדיניות הזו במקום להטמיע פתרון JavaScript בהתאמה אישית. יכול להיות שקוד JavaScript מותאם אישית לא יתאים לביצועים ולאופטימיזציה של מדיניות Apigee.
  • כדי לבצע קריאות למערכת. מודל האבטחה לא מאפשר קריאות למערכת ממדיניות JavaScript. לדוגמה, אסור לבצע קריאות או כתיבות במערכת קבצים פנימית, לקבל מידע על המשתמש הנוכחי, לקבל רשימות של תהליכים או לקבל נתונים על השימוש במעבד או בזיכרון. יכול להיות שחלק מהשיחות יפעלו, אבל הן לא נתמכות ואנחנו עשויים להשבית אותן בכל שלב. כדי לשמור על תאימות קדימה, מומלץ להימנע מהפעלת הפונקציות האלה בקוד.

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

דוגמאות

לשכתב את כתובת ה-URL ליעד

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

  1. בממשק המשתמש של Apigee, פותחים את ה-proxy שיצרתם בכלי לעריכת proxy.
  2. בוחרים בכרטיסייה פיתוח.
  3. בתפריט 'חדש', בוחרים באפשרות סקריפט חדש.
  4. בתיבת הדו-שיח, בוחרים באפשרות JavaScript ונותנים לסקריפט את השם js-example.
  5. מדביקים את הקוד הבא בעורך הקוד ושומרים את ה-proxy. האובייקט context זמין לקוד JavaScript בכל מקום בתהליך של ה-proxy. היא מקבלת קבועים ספציפיים לזרימה, קוראת ל-methods שימושיות של get/set ומבצעת פעולות אחרות. האובייקט הזה הוא חלק ממודל האובייקטים של JavaScript ב-Apigee. המשתנה target.url של Flow הוא משתנה מובנה עם גישת קריאה/כתיבה שאפשר לגשת אליו בתהליך Target Request. כשמגדירים את המשתנה הזה עם כתובת ה-URL של ה-API, ‏ Apigee קורא לכתובת ה-URL של ה-backend. הפעולה הזו משכתבת את כתובת ה-URL המקורית של היעד, שהיא כתובת ה-URL שציינתם כשנוצר ה-Proxy (לדוגמה, http://www.example.com). 
    if (context.flow=="PROXY_REQ_FLOW") {
     var username = context.getVariable("request.formparam.user");
     context.setVariable("info.username", username);
}


if (context.flow=="TARGET_REQ_FLOW") {
     context.setVariable("request.verb", "GET");
     var name = context.getVariable("info.username");
     var url = "http://mocktarget.apigee.net/"
     context.setVariable("target.url", url + "?user=" + name);
}
  6. בתפריט New Policy (מדיניות חדשה), בוחרים באפשרות JavaScript.
  7. נותנים למדיניות את השם target-rewrite. מאשרים את ברירות המחדל ושומרים את המדיניות.
  8. אחרי שבוחרים באפשרות Proxy Endpoint Preflow (זרימת נתונים לפני נקודת הקצה של ה-Proxy) בNavigator (חלונית הניווט), המדיניות מתווספת לזרימת הנתונים הזו.
  9. בחלונית הניווט, בוחרים באפשרות Target Endpoint PreFlow (זרימת נתונים לפני נקודת קצה של יעד).
  10. בNavigator, גוררים את מדיניות JavaScript לצד Request של Target Endpoint בכלי לעריכת זרימת הנתונים.
  11. שמירה.
  12. כשמתקשרים ל-API, מחליפים את שם הארגון ואת שם ה-proxy: 
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

בודקים את הגדרת ה-XML של מדיניות JavaScript שמשמשת בדוגמה הזו. האלמנט <ResourceURL> מציין את קובץ המקור של JavaScript להרצה. התבנית הזו חלה על כל קובץ מקור של JavaScript: ‏ jsc://filename.js. אם קוד ה-JavaScript שלכם דורש הכללות, צריך להשתמש באלמנט אחד או יותר של <IncludeURL>, כמו שמתואר בהמשך המאמר הזה.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

אחזור ערך מאפיין מ-JavaScript

אפשר להוסיף רכיב <Property> להגדרה ואז לאחזר את הערך שלו באמצעות JavaScript בזמן ריצה.

משתמשים במאפיין name של הרכיב כדי לציין את השם לגישה למאפיין מקוד JavaScript. הערך של רכיב <Property> (הערך שבין התג הפותח לתג הסוגר) הוא הערך המילולי שמתקבל ב-JavaScript.

ב-JavaScript, כדי לאחזר את ערך מאפיין המדיניות, ניגשים אליו כמאפיין של האובייקט Properties, באופן הבא:

  • מגדירים את הנכס. ערך המאפיין הוא שם המשתנה response.status.code. 
    <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite">
    <DisplayName>JavascriptURLRewrite</DisplayName>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
    <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL>
</Javascript>
  • מאחזרים את המאפיין באמצעות JavaScript. הפונקציה getVariable משתמשת בשם המשתנה שאוחזר כדי לאחזר את ערך המשתנה. 
    var responseCode = properties.source; // Returns "response.status.code"
var value = context.getVariable(responseCode); // Get the value of response.status.code
context.setVariable("response.header.x-target-response-code", value);

הפניה לרכיב

ההפניה לרכיב מתארת את הרכיבים והמאפיינים של מדיניות JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false"
        continueOnError="false" enabled="true" timeLimit="200"
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>
</Javascript>

מאפיינים של <Javascript>

< languageVersion="VERSION_1_3" Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
מאפיין תיאור ברירת מחדל נוכחות
languageVersion

מציין את הגרסה של שפת JavaScript שבה הקוד כתוב. הערכים האפשריים הם VERSION_DEFAULT, VERSION_1_0, VERSION_1_1, VERSION_1_2, VERSION_1_3, VERSION_1_4, VERSION_1_5, VERSION_1_6, VERSION_1_7, VERSION_1_8 ו-VERSION_ES6.

 VERSION_DEFAULT אופציונלי
timeLimit

מציין את משך הזמן המרבי (באלפיות השנייה) שסקריפט יכול לפעול. לדוגמה, אם חורגים ממגבלה של 200 אלפיות השנייה, המדיניות מחזירה את השגיאה הבאה: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms.

 לא רלוונטי חובה

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

מאפיין תיאור ברירת מחדל נוכחות
name

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

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

 לא רלוונטי חובה
continueOnError

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

הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף:

 FALSE אופציונלי
enabled

מגדירים את המדיניות למצב true כדי לאכוף אותה.

מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

 TRUE אופציונלי
async

המאפיין הזה הוצא משימוש.

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל

לא רלוונטי

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

אלמנט <IncludeURL>

מציין קובץ של ספריית JavaScript לטעינה כתלות בקובץ ה-JavaScript הראשי שצוין באמצעות הרכיב <ResourceURL> או <Source>. המדיניות מעריכה את הסקריפטים לפי הסדר שבו הם מופיעים במדיניות. הקוד יכול להשתמש באובייקטים, בשיטות ובמאפיינים של מודל האובייקטים של JavaScript.

אפשר לכלול יותר ממשאב תלות אחד ב-JavaScript באמצעות עוד רכיבי <IncludeURL>.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
ברירת מחדל: ללא
נוכחות: אופציונלי
סוג: String

אלמנט <Property>

מציין מאפיין שאפשר לגשת אליו מקוד JavaScript בזמן ריצה.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
ברירת מחדל: ללא
נוכחות: אופציונלי
סוג: String

מאפיינים

מאפיין תיאור ברירת מחדל נוכחות
name

מציין את שם הנכס.

 לא רלוונטי חובה

דוגמה

אפשר לראות דוגמה בקטע דוגמאות.

אלמנט <ResourceURL>

המדיניות קובעת את קובץ ה-JavaScript הראשי שמופעל בתהליך העבודה של ה-API. אפשר לאחסן את הקובץ הזה בהיקף של proxy ל-API (בקטע /apiproxy/resources/jsc בחבילת proxy ל-API או בקטע Scripts בחלונית Navigator של עורך proxy ל-API). אפשרות אחרת היא לאחסן אותו בהיקף הארגון או הסביבה כדי שאפשר יהיה לעשות בו שימוש חוזר בכמה שרתי proxy של API, כמו שמתואר במאמר בנושא ניהול משאבים. הקוד יכול להשתמש באובייקטים, בשיטות ובמאפיינים של מודל האובייקטים של JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>
ברירת מחדל: ללא
נוכחות: צריך לציין <ResourceURL> או <Source>. אם גם <ResourceURL> וגם <Source> קיימים, המדיניות מתעלמת מ-<ResourceURL>.
סוג: String

דוגמה

אפשר לראות דוגמה בקטע דוגמאות.

רכיב <Source>

אפשר להוסיף JavaScript ישירות להגדרת ה-XML של המדיניות. קוד ה-JavaScript שמוסיפים מופעל כשהמדיניות מופעלת בתהליך של ה-API.

ברירת מחדל: ללא
נוכחות: צריך לציין <ResourceURL> או <Source>. אם גם <ResourceURL> וגם <Source> קיימים, המדיניות מתעלמת מ-<ResourceURL>.
סוג: String

דוגמה

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

אלמנט <SSLInfo>

מציינת את המאפיינים שמשמשים להגדרת TLS לכל המופעים של לקוח HTTP שנוצרו על ידי מדיניות JavaScript. 

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
ברירת מחדל: ללא
נוכחות: אופציונלי
סוג: String

תהליך ההגדרה של TLS ללקוח HTTP זהה לתהליך ההגדרה של TLS ל-TargetEndpoint או ל-TargetServer. מידע נוסף מופיע במאמר בנושא אפשרויות להגדרת TLS.

שימוש ב-JavaScript לטיפול בשגיאות

אפשר להשתמש במדיניות JavaScript כדי לטפל בשגיאות ולהחזיר אותן. דיון בנושא הזה זמין ב Correct way to return an error from a JavaScript policy בקהילת Apigee. הערה: הפוסטים והתגובות בקהילה לא בהכרח מייצגים את השיטות המומלצות של Apigee.

ניפוי באגים בקוד מדיניות JavaScript

אפשר להשתמש בפונקציה print() כדי להציג מידע לניפוי באגים בחלונית הפלט של העסקה בכלי לניפוי באגים. לפרטים נוספים ולדוגמאות, אפשר לעיין במאמר בנושא ניפוי באגים ב-JavaScript באמצעות הצהרות print()‎.

כדי לראות את הצהרות ההדפסה בכלי לניפוי באגים:

  1. פותחים את כלי ניפוי הבאגים ומתחילים סשן מעקב לשרת proxy שמכיל את מדיניות JavaScript.
  2. מתקשרים לשרת ה-proxy.
  3. בכלי לניפוי באגים, לוחצים על מדיניות JavaScript ואז על הכרטיסייה מאפיינים כדי לראות את המאפיין stepExecution-stdout שמציג את הפלט של הצהרת ההדפסה.

    פלט מהכרטיסייה 'מאפיינים' בכלי לניפוי באגים, שבו מוצגות הצהרות הדפסה.

  4. הדוחות של ההדפסות יופיעו בחלונית הזו.

משתני זרימה

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

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

האובייקט context הוא חלק ממודל האובייקטים של JavaScript ב-Apigee.

הפניה לשגיאה

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

שגיאות זמן ריצה

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

קוד תקלה סטטוס HTTP מטרה תיקון
steps.javascript.ScriptExecutionFailed 500 מדיניות JavaScript יכולה להחזיר סוגים שונים של שגיאות ScriptExecutionFailed. סוגי השגיאות הנפוצים כוללים את: RangeError, ReferenceError, SyntaxError, TypeError, ו- URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 אירעה שגיאה בקוד JavaScript. פרטים נוספים מופיעים במחרוזת השגיאה. לא רלוונטי
steps.javascript.ScriptSecurityError 500 אירעה שגיאת אבטחה במהלך ההפעלה של JavaScript. פרטים נוספים מופיעים במחרוזת השגיאה. לא רלוונטי

שגיאות בהטמעה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שמכיל את המדיניות הזו.

שם השגיאה מטרה תיקון
InvalidResourceUrlFormat אם הפורמט של כתובת ה-URL של המשאב שצוינה ברכיב <ResourceURL> או ברכיב <IncludeURL> של מדיניות JavaScript לא תקין, הפריסה של ה-proxy ל-API תיכשל.
InvalidResourceUrlReference אם הרכיבים <ResourceURL> או <IncludeURL> מפנים לקובץ JavaScript שלא קיים, הפריסה של proxy ל-API תיכשל. קובץ המקור שאליו יש הפניה צריך להיות קיים ברמת proxy ל-API, הסביבה או הארגון.
WrongResourceType השגיאה הזו מתרחשת במהלך הפריסה אם הרכיבים <ResourceURL> או <IncludeURL> של המדיניות JavaScript מתייחסים לסוג משאב כלשהו שאינו jsc (קובץ JavaScript).
NoResourceURLOrSource פריסת המדיניות JavaScript עלולה להיכשל עם השגיאה הזו אם הרכיב <ResourceURL> לא מוצהר או אם כתובת ה-URL של המשאב לא מוגדרת ברכיב הזה. האלמנט <ResourceURL> הוא אלמנט חובה. או, הרכיב <IncludeURL> מוצהר אבל כתובת ה-URL של המשאב לא מוגדרת בתוך הרכיב הזה. הרכיב <IncludeURL> הוא אופציונלי, אבל אם הוא מוצהר, צריך לציין את כתובת ה-URL של המשאב בתוך הרכיב <IncludeURL>.

משתני תקלות

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

משתנים כאשר: דוגמה
fault.name="fault_name" ‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed ‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. javascript.JavaScript-1.failed = true

דוגמה לתגובת שגיאה

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

דוגמה לכלל שגיאה

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

סכימה

כל סוג מדיניות מוגדר על ידי סכימת XML ‏ (.xsd). סכימות מדיניות זמינות ב-GitHub.

נושאים קשורים

מאמרים בקהילת Apigee

אפשר למצוא מאמרים קשורים בקהילת Apigee: