מדיניות JavaScript

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

מה

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

מידע כללי

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

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

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

קובצי מקור של JavaScript תמיד צריכים לכלול את הסיומת .js.

כאן אפשר לראות את הגרסה הנתמכת הנוכחית של JavaScript.

וידאו

כדאי לצפות בסרטון קצר כדי ללמוד איך ליצור מדיניות מותאמת אישית באמצעות מדיניות JavaScript.

דוגמאות

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

<?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.

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

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

המאפיינים הבאים ספציפיים למדיניות הזו.

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

אלמנט <IncludeURL>

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

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

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

דוגמה

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

אלמנט <Property>

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

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

מאפיינים

דוגמה

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

אלמנט <ResourceURL>

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

<ResourceURL>jsc://my-javascript.js</ResourceURL>

דוגמה

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

אלמנט <Source>

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

דוגמה

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

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

הערות שימוש

מדיניות JavaScript לא מכילה קוד בפועל. במקום זאת, מדיניות JavaScript מפנה ל 'משאב' JavaScript ומגדירה את השלב בתהליך של ה-API שבו ה-JavaScript מופעל. אפשר להעלות את הסקריפט דרך עורך ה-proxy בממשק המשתמש לניהול, או לכלול אותו בספרייה /resources/jsc ב-API proxies שאתם מפתחים באופן מקומי.

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

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

כדי לראות את הצהרות ההדפסה ב-Trace:

1. פותחים את כלי המעקב ומתחילים סשן מעקב לשרת proxy שמכיל את מדיניות JavaScript.
2. מתקשרים לשרת ה-proxy.
3. בכלי למעקב, לוחצים על Output from all Transactions (פלט מכל העסקאות) כדי לפתוח את חלונית הפלט.

   

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

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

משתני זרימה

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

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

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

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

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.

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.

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

• מודל אובייקטים של JavaScript
• הוראות, דוגמאות למדיניות ודוגמאות ל-JavaScript זמינות במאמר Programming API proxies with JavaScript.

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

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

• How to handle multi-value headers in Javascript?