Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

‫JavaCallout policy

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

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

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

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

אתם יכולים לארוז את אפליקציית 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 callout.

<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>

סכימות

דוגמה: כל סוג מדיניות מוגדר על ידי סכימת 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.