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

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

מה

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

לרשימת הגרסאות הנתמכות של Java, ראה נתמכות והגרסאות הנתמכות.

מתי

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

מידע כללי

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

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

דוגמאות

דוגמה פשוטה

איך יוצרים Java יתרונות מרכזיים

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

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

משתמשים ב<נכס> המאפיין name של הרכיב כדי לציין את השם שאיתו שבעזרתו אפשר לגשת למאפיין מקוד Java. של הרכיב <Property> value (הערך בין התג הפותח לתג הסוגר) הוא הערך שיקבל בקוד 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 שלכם, מטמיעים את ה-constructor הבא במחלקה הביצוע באופן הבא:
    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>

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

<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 של המדיניות הוא בשימוש.

נוכחות אופציונלי
סוג מחרוזת

&lt;ClassName&gt; רכיב

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

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

&lt;Property&gt; רכיב

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

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

מאפיינים

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

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

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

&lt;ResourceURL&gt; רכיב

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

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

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

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

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

סכימות

הידור ופריסה

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

הגבלות

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

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

אריזה

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

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

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

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

Javadoc

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

הערות שימוש

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

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