‫JavaCallout policy

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

גרסאות Java נתמכות: Oracle JDK 11 ו-OpenJDK 11.

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

דוגמאות

דוגמאות כלליות

דוגמה פשוטה לשימוש ב-Java callout מופיעה במאמר איך יוצרים Java callout.

כדי ללמוד איך להגדיר משתני זרימה בקוד Java, אפשר לעיין בפוסט לקהילה הזה ב-Apigee בנושא ניפוי באגים של קריאות ל-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>
</JavaCallout>
  • בקוד Java, מטמיעים את הבונה הבא במחלקה Execution:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

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

הפניה לרכיב

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

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

לא רלוונטי

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

אלמנט <ClassName>

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

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

אלמנט <Properties>

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

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

אלמנט <Property>

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

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

מאפיינים

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

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

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

אלמנט<ResourceURL>

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

אפשר לאחסן את הקובץ הזה בהיקף של שרת ה-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>
ברירת מחדל: ללא
נוכחות: חובה
סוג: String

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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. Supported Java versions include: Oracle JDK 7/8 and OpenJDK 7/8
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 מופיעים במאמר איך יוצרים קריאה (callout) של Java.

הגבלות

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

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

אריזה

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

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

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

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

Javadoc

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

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

  • כשעובדים עם כמה כללי מדיניות של JavaCallout, כדאי להעלות קובצי JAR נפוצים כמשאבים בהיקף הסביבה. השיטה הזו יעילה יותר בהשוואה לאריזת אותם קובצי JAR עם כמה חבילות של שרת proxy כשמבצעים פריסה לאותה סביבה.
  • לא מומלץ לארוז ולפרוס כמה עותקים או גרסאות של אותו קובץ JAR בסביבה. לדוגמה, Apigee ממליצה להימנע מהפעולות הבאות:
    • פריסת אותו קובץ JAR כחלק מחבילת proxy וכמשאב סביבה.
    • פריסה של גרסה אחת של קובץ JAR כמשאב סביבה וגרסה אחרת כחלק מחבילת proxy.

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

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