‫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` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי טיפ: במקרים שבהם קוד ה-Java שלכם יוצר חריגה, הזרימה של ה-proxy ב-Apigee עוברת לסטטוס שגיאה גם אם המאפיין `continueOnError` מוגדר כ-true. אם אינכם רוצים שחריג שנוצר יגרום למצב שגיאה בשרת ה-proxy, תכננו את קוד קריאה ל-Java כך שלא יקפיץ הודעות שגיאה. במקום זאת, כדאי לטפל בחריגים ולהגדיר משתנה הקשר כדי לתעד את פרטי החריג. מידע נוסף זמין בפוסט הזה בקהילת Apigee.	FALSE	אופציונלי
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
`async`	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל

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

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין 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

הפניה לשגיאה

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

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

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

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

שגיאות פריסה

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

שם השגיאה	מחרוזת שגיאה	סטטוס HTTP	מתרחש כאשר
`ResourceDoesNotExist`	`Resource with name [name] and type [type] does not exist`	לא רלוונטי	הקובץ שצוין ברכיב `<ResourceURL>` לא קיים.
`JavaCalloutInstantiationFailed`	`Failed to instantiate the JavaCallout Class [classname]`	לא רלוונטי	קובץ המחלקה שצוין ברכיב `<ClassName>` לא נמצא בקובץ ה-JAR.
`IncompatibleJavaVersion`	`Failed to load java class [classname] definition due to - [reason]`	לא רלוונטי	לצפייה במחרוזת השגיאה. גרסאות Java נתמכות: Oracle JDK 7/8 ו-OpenJDK 7/8
`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>

סכימות

דוגמה: כל סוג מדיניות מוגדר על ידי סכימת XML (.xsd). סכימות מדיניות זמינות ב-GitHub.

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

פרטים על קומפילציה של קוד 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.