המדיניות בנושא 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 למטרות הבאות:

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

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

דוגמאות

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

תרחיש נפוץ לשימוש ב-Flow הוא חילוץ נתונים מגוף הבקשה, אחסון שלהם במשתנה Flow ואז שימוש במשתנה Flow הזה במקום אחר ב-Flow של ה-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 הוא משתנה מובנה עם גישת קריאה/כתיבה שאפשר לגשת אליו בתהליך 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. בתפריט 'מדיניות חדשה', בוחרים באפשרות JavaScript.
  7. נותנים למדיניות את השם target-rewrite. מאשרים את ברירות המחדל ושומרים את המדיניות.
  8. אחרי שבוחרים באפשרות Proxy Endpoint Preflow (זרימת נתונים לפני נקודת קצה של שרת proxy) בNavigator (חלונית הניווט), המדיניות מתווספת לזרימת הנתונים הזו.
  9. בחלונית הניווט, בוחרים באפשרות Target Endpoint PreFlow (זרימת נתונים לפני נקודת הקצה של היעד).
  10. בחלונית הניווט, גוררים את מדיניות JavaScript לצד Request של נקודת הקצה של היעד בכלי לעריכת תהליכים.
  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 שמציג את הפלט של הצהרת ההדפסה.

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

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

משתני זרימה

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

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

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

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javascript.ScriptExecutionFailed 500 The JavaScript policy can throw many different types of ScriptExecutionFailed errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 An error occurred in the JavaScript code. See the fault string for details. N/A
steps.javascript.ScriptSecurityError 500 A security error occurred when the JavaScript executed. See the fault string for details. N/A

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidResourceUrlFormat If the format of the resource URL specified within the <ResourceURL> or the <IncludeURL> element of the JavaScript policy is invalid, then the deployment of the API proxy fails.
InvalidResourceUrlReference If the <ResourceURL> or the <IncludeURL> elements refer to a JavaScript file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
WrongResourceType This error occurs during deployment if the <ResourceURL> or the <IncludeURL> elements of the JavaScript policy refer to any resource type other than jsc (JavaScript file).
NoResourceURLOrSource The deployment of the JavaScript policy can fail with this error if the <ResourceURL> element is not declared or if the resource URL is not defined within this element. <ResourceURL> element is a mandatory element. Or, The <IncludeURL> element is declared but the resource URL is not defined within this element. The <IncludeURL> element is optional but if declared, the resource URL must be specified within the <IncludeURL> element.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javascript.JavaScript-1.failed = true

Example error response

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

Example fault rule

<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: