מדיניות 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">

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

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

&lt;DisplayName&gt; רכיב

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

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

הפניה לשגיאה

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

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

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

שגיאות פריסה

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

משתני כשל

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

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

{
  "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.

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

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

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

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

• How to handle multi-value headers in Javascript?