מדיניות JavaScript

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

מה

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

מידע כללי

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

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

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

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

תוכנות נתמכות וגרסאות נתמכות לגרסה הנתמכת כרגע של JavaScript.

וידאו

בסרטון קצר זה מוסבר איך יוצרים תוסף מדיניות מותאם אישית באמצעות JavaScript המדיניות בנושא

דוגמאות

שכתוב של כתובת היעד

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

הערה: אם אתם רוצים לנסות את הדוגמה הזו, אנחנו מניחים שיצרתם חשבון חדש שרת proxy בעורך ה-proxy. כשיוצרים אותו, צריך רק לתת לו את כתובת ה-URL של השירות לקצה העורפי: http://www.example.com. לצורך הדוגמה הזו, נשכתב את כתובת ה-URL של הקצה העורפי באופן דינמי. אם אתם לא יודעים איך ליצור שרת proxy חדש, אפשר לעיין במדריך לתחילת העבודה. .

  1. בממשק המשתמש של Edge, פותחים את שרת ה-proxy שיצרתם בעורך ה-Proxy.
  2. לוחצים על הכרטיסייה פיתוח.
  3. בתפריט New, בוחרים באפשרות New Script (סקריפט חדש).
  4. בתיבת הדו-שיח, בוחרים JavaScript ונותנים לסקריפט שם, למשל js-example
  5. מדביקים את הקוד הבא בעורך הקוד ושומרים את שרת ה-Proxy. הדבר שחשוב הוא האובייקט context. האובייקט הזה זמין לקוד ה-JavaScript בכל מקום בתהליך ה-Proxy. היא משמשת לקבלת קבועים ספציפיים לזרימה, כדי לקרוא למטרות get/set., ולעוד פעולות. חלק האובייקט הזה הוא חלק מ-Edge מודל אובייקט JavaScript. הערה: שמשתנה הזרימה target.url הוא משתנה מובנה של קריאה/כתיבה, זמינה בתהליך היעד של הבקשה. כשאנחנו מגדירים את המשתנה הזה באמצעות כתובת ה-URL של ה-API, דפדפן Edge מבצע קריאה לקצה העורפי לכתובת ה-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. אם בוחרים באפשרות 'תצוגה מקדימה של נקודת הקצה (endpoint)' של שרת ה-proxy ב-Navigator, רואים שהמדיניות נוסף לתהליך הזה.
  9. ב-Navigator, בוחרים את הסמל של Target Endpoint PreFlow (יעד קצה מקדים של נקודת הקצה).
  10. מסרגל הניווט, גוררים את מדיניות JavaScript לצד הבקשה של היעד נקודת הקצה בעורך התהליך
  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, ראה את הפוסט הזה בקהילת Apigee. ההצעות שמוצעות בקהילת Apigee הן עבור מידע בלבד ולא בהכרח מייצגות שיטות מומלצות שמומלצות על ידי Apigee.

הפניה לרכיב

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

&lt;Javascript&gt; מאפיינים

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

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

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

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

הערה: בחשבונות לתקופת ניסיון בחינם, זמן הביצוע מוגבל ל-200 אלפיות שנ'

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

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

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

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

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

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

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

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

 false אופציונלי
enabled

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

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

 true אופציונלי
async

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

 false הוצא משימוש

&lt;DisplayName&gt; רכיב

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

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

לא רלוונטי

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

&lt;IncludeURL&gt; רכיב

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

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

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

דוגמה

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

&lt;Property&gt; רכיב

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

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

מאפיינים

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

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

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

דוגמה

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

&lt;ResourceURL&gt; רכיב

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

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

דוגמה

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

&lt;Source&gt; רכיב

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

ברירת המחדל: ללא
נוכחות: השדה <ResourceURL> או <Source> הוא שדה חובה. אם המיקום המערכת מתעלמת מ-<ResourceURL> וגם <Source> מ-<ResourceURL>.
סוג: מחרוזת

דוגמה

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

&lt;SSLInfo&gt; רכיב

מציינת את המאפיינים שמשמשים להגדרת 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() כדי ליצור פלט של מידע על תוצאות ניפוי הבאגים לעסקה. חלונית הפלט בכלי המעקב. לפרטים נוספים ולעיון בדוגמאות, ראו 'ניפוי באגים באמצעות JavaScript' משפטי print().

כדי להציג דפי חשבון הדפסה בדוח 'מעקב':

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

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

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

משתני זרימה

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

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

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

התייחסות לשגיאות

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

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

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

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