מדיניות JavaScript

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

מה

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

מידע כללי

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

אחד מהתרחישים לדוגמה שאנחנו לא ממליצים עליהם במדיניות JavaScript הוא רישום ביומן. המדיניות של Message Logging מתאימה יותר להתחברות לפלטפורמות רישום ביומן של צד שלישי, כמו Splunk, Sumo ו-Loggly. בנוסף, אפשר לשפר את ביצועי ה-API של שרת proxy על ידי הפעלת המדיניות 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">

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

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

רכיב <DisplayName>

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

הערות על שימוש

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

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

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

כדי להציג דפי הדפסה ב'מעקב':

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

   

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, ראו שרתי proxy של API לתכנות עם JavaScript.

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

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

• איך מטפלים בכותרות מרובות ערכים ב-JavaScript?