‫JavaCallout policy

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

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

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

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

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

Javadoc

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

הערות שימוש

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

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