המדיניות בנושא יתרונות מרכזיים של Java

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

מה

מאפשר לכם להשתמש ב-Java כדי להטמיע התנהגות מותאמת אישית שלא כלולה מחוץ לקופסה במדיניות של Apigee. בקוד Java, אפשר לגשת למאפייני ההודעה (כותרות, פרמטרים של שאילתות, תוכן) ולמשתני הזרימה בזרימת ה-proxy. אם אתם רק מתחילים לעבוד עם המדיניות הזו, כדאי לעיין במאמר איך יוצרים קריאה ל-Java.

במאמר תוכנות נתמכות וגרסאות נתמכות מפורטות הגרסאות הנתמכות של Java.

מתי

הנחיות מפורטות במאמר איך יוצרים קריאה ל-Java, בקטע 'מתי כדאי להשתמש בקריאה ל-Java?'.

מידע כללי

מדיניות Java Callout מאפשרת לקבל ולהגדיר משתני זרימה, להפעיל לוגיקה מותאמת אישית ולבצע טיפול בשגיאות, לחלץ נתונים מבקשות או מתגובות ועוד. המדיניות הזו מאפשרת לכם להטמיע התנהגות מותאמת אישית שלא נכללת באף מדיניות סטנדרטית אחרת של Edge.

אתם יכולים לארוז את אפליקציית Java עם כל קובץ JAR של חבילה שאתם צריכים. הערה יש כמה הגבלות על הפעולות שאפשר לבצע באמצעות Java Callout. ההגבלות מפורטות בהמשך בקטע הגבלות.

דוגמאות

דוגמה פשוטה

איך יוצרים קריאה ל-Java

אחזור מאפיינים בקוד Java

האלמנט <Property> של המדיניות מאפשר לציין צמד של שם/ערך שאפשר לאחזר בזמן הריצה בקוד Java. דוגמה לשימוש במאפיינים מופיעה במאמר איך משתמשים במאפיינים בקריאה ל-Java.

משתמשים במאפיין name של רכיב Property כדי לציין את השם שדרכו ניגשים למאפיין מקוד Java. הערך של רכיב <Property> (הערך שבין התג הפותח לתג הסוגר) הוא הערך שיתקבל על ידי קוד ה-Java. הערך חייב להיות מחרוזת. אי אפשר להפנות למשתנה של זרימת נתונים כדי לקבל את הערך.

  • מגדירים את הנכס. במקרה הזה, ערך המאפיין הוא שם המשתנה response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • בקוד Java, מטמיעים את הבונה הבא בהטמעה של המחלקה Execution באופן הבא:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

הגדרת משתני זרימה בקוד Java

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

הפניה לרכיב

הפניה לרכיב מתארת את הרכיבים והמאפיינים של מדיניות JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

מאפיינים של <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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

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

אלמנט <ClassName>

מציין את השם של מחלקת Java שמופעלת כשמופעלת מדיניות Java Callout. המחלקות חייבות להיכלל בקובץ ה-JAR שצוין על ידי <ResourceURL>. אפשר גם לעיין במאמר איך יוצרים קריאה חיצונית ב-Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
ברירת מחדל: לא רלוונטי
נוכחות: חובה
סוג: מחרוזת

אלמנט <Property>

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

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

מאפיינים

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

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

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

אלמנט<ResourceURL>

הרכיב הזה מציין את קובץ ה-JAR של Java שיופעל כשמדיניות ה-Java callout תפעל.

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

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
ברירת מחדל: ללא
נוכחות: חובה
סוג: מחרוזת

הפניה לשגיאה

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

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

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

קוד תקלה סטטוס HTTP סיבה תיקון
steps.javacallout.ExecutionError 500 קורה כשקוד Java גורם לחריגה או מחזיר ערך null במהלך ביצוע מדיניות JavaCallout.

שגיאות פריסה

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

שם השגיאה מחרוזת שגיאה סטטוס HTTP מתרחשת כאשר
ResourceDoesNotExist Resource with name [name] and type [type] does not exist לא רלוונטי הקובץ שצוין ברכיב <ResourceURL> לא קיים.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] לא רלוונטי קובץ המחלקה שצוין ברכיב <ClassName> לא נמצא ב צנצנת.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] לא רלוונטי הצגת מחרוזת השגיאה. כדאי לעיין גם בקטע נתמכים והגרסאות הנתמכות.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] לא רלוונטי הצגת מחרוזת השגיאה.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] לא רלוונטי הצגת מחרוזת השגיאה.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] לא רלוונטי הצגת מחרוזת השגיאה.
NoResourceForURL Could not locate a resource with URL [string] לא רלוונטי הצגת מחרוזת השגיאה.

משתני כשל

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

משתנים איפה דוגמה
fault.name="fault_name" fault_name הוא שם השגיאה, כפי שמצוין בטבלה שגיאות זמן ריצה שלמעלה. שם השגיאה הוא החלק האחרון בקוד השגיאה. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לבעיה. javacallout.JC-GetUserData.failed = true

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

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

דוגמה לכלל שגוי

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

סכימות

קומפילציה ופריסה

פרטים על קומפילציה של קוד Java בהתאמה אישית ופריסה שלו באמצעות שרת proxy מופיעים במאמר איך יוצרים קריאה (callout) של Java.

הגבלות

בהמשך מפורטות ההגבלות שצריך להביא בחשבון כשכותבים Java Callouts:

  • רוב קריאות המערכת אסורות. לדוגמה, אי אפשר לבצע קריאות או כתיבות במערכת קבצים פנימית.
  • גישה לרשת דרך שקעים. ‫Apigee מגביל את הגישה לכתובות sitelocal,‏ anylocal,‏ loopback ו-linklocal.
  • ההפניה לא יכולה לקבל מידע על התהליך הנוכחי, על רשימת התהליכים או על השימוש ב-CPU או בזיכרון במכונה. יכול להיות שחלק מהשיחות האלה יפעלו, אבל הן לא נתמכות ויכול להיות שהן יושבתו בכל שלב. כדי לשמור על תאימות קדימה, מומלץ להימנע מביצוע קריאות כאלה בקוד.
  • אין תמיכה בהסתמכות על ספריות Java שכלולות ב-Apigee Edge. הספריות האלה מיועדות רק לפונקציונליות של מוצרי Edge, ואין ערובה לכך שספרייה מסוימת תהיה זמינה מגרסה לגרסה.
  • אל תשתמשו ב-io.apigee או ב-com.apigee כשמות של חבילות ב-Java Callouts. השמות האלה שמורים ומשמשים מודולים אחרים של Apigee.

אריזה

ממקמים את קובץ ה-JAR ב-API Proxy בתיקייה /resources/java. אם ה-Java Callout שלכם מסתמך על ספריות נוספות של צד שלישי שנארזו כקבצי JAR עצמאיים, צריך למקם את קובצי ה-JAR האלה בספרייה /resources/java גם כדי לוודא שהם נטענים בצורה נכונה בזמן הריצה.

אם אתם משתמשים בממשק המשתמש לניהול כדי ליצור או לשנות את ה-proxy, תוכלו להוסיף משאב חדש ולציין קובץ JAR נוסף שתלוי בו. אם יש כמה קובצי JAR, פשוט מוסיפים אותם כמשאבים נוספים. אין צורך לשנות את הגדרות המדיניות כדי להפנות לקובצי JAR נוספים. מספיק להוסיף אותם ל/resources/java.

מידע על העלאת קובצי JAR של Java זמין במאמר בנושא קובצי משאבים.

דוגמה מפורטת שמראה איך לארוז ולפרוס Java Callout באמצעות Maven או javac מופיעה במאמר איך ליצור Java Callout.

Javadoc

‫Javadoc לכתיבת קוד Java Callout כלול כאן ב-GitHub. תצטרכו לשכפל או להוריד את קובץ ה-HTML למערכת שלכם, ואז פשוט לפתוח את הקובץ index.html בדפדפן.

הערות שימוש

  • מדיניות Java Callout לא מכילה קוד בפועל. במקום זאת, מדיניות Java Callout מפנה ל 'משאב' Java ומגדירה את השלב בתהליך של ה-API שבו קוד ה-Java מופעל. אפשר להעלות את קובץ ה-JAR של Java דרך הכלי לעריכת proxy בממשק ניהול, או לכלול אותו בספרייה /resources/java ב-API proxies שאתם מפתחים באופן מקומי.
  • לפעולות קלות משקל, כמו קריאות ל-API לשירותים מרוחקים, מומלץ להשתמש במדיניות ServiceCallout. המדיניות בנושא יתרונות מרכזיים של שירותים
  • לפעולות פשוטות יחסית עם תוכן ההודעה, כמו שינוי או חילוץ של כותרות HTTP, פרמטרים או תוכן ההודעה, מומלץ להשתמש במדיניות JavaScript.

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