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

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

מה

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

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

מתי

להנחיות, ראו "מתי כדאי להשתמש בנכס יתרונות מרכזיים של Java?" במאמר כיצד ליצור הסבר של Java.

מידע כללי

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

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

טעימות

דוגמה פשוטה

איך ליצור תוסף יתרונות מרכזיים של 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, מטמיעים את הבנאי הבא בהטמעה של מחלקת הביצוע באופן הבא:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

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

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

הפניה לרכיב

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

רכיב <DisplayName>

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

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

לא רלוונטי

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

אלמנט <ClassName>

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

מאפיינים

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

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

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

<ResourceURL>

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

אפשר לאחסן את הקובץ הזה בהיקף של שרת ה-proxy של ה-API (בקטע /apiproxy/resources/java בחבילה של שרת proxy ל-API או בקטע Scripts בחלונית Navigator של עורך ה-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, קראו את המאמר איך יוצרים יתרונות מרכזיים של Java.

הגבלות

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

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

אריזה

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

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

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

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

Javadoc

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

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

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

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