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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

מהי קריאה ל-Java?

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

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

במאמר תוכנות נתמכות וגרסאות נתמכות מפורטות הגרסאות הנתמכות של Java.

איך משתמשים בקוד Java ב-proxy?

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

מתי כדאי להשתמש ב-Java callout?

נבחן מצבים שבהם כדאי להשתמש ב-Java callouts ומצבים שבהם כדאי לשקול גישות אחרות.

קודם כדאי לשקול גישות חלופיות

לפני שמשתמשים ב-Java callout, חשוב לדעת שיש גישות חלופיות שאפשר להשתמש בהן במקום זאת. לדוגמה:

  • לפעולות קלות משקל, כמו קריאות ל-API של HTTP לשירותים מרוחקים, כדאי להשתמש במדיניות ServiceCallout. המדיניות בנושא יתרונות מרכזיים של שירותים
  • כדי לבצע אינטראקציות פשוטות יחסית עם תוכן ההודעה, כמו שינוי או חילוץ של כותרות HTTP, פרמטרים או תוכן ההודעה, אפשר להשתמש בשפות JavaScript או Python.

מה אפשר לעשות בקוד Java

קריאה ל-Java תומכת בפעולות הבסיסיות הבאות:

  • בדיקה או שינוי של הודעות בקשה או תגובה
  • קבלת משתני זרימה והגדרתם. אפשר להשתמש ב-methods של Java כדי לגשת למשתני Edge flow. אם רוצים לגשת למידע של Key Value Map (KVM), צריך להשתמש במדיניות KVM, להקצות ערכי KVM למשתני זרימה ואז אפשר לגשת למשתני הזרימה מתוך קריאה ל-Java.
  • התקשרות לשירותים חיצוניים
  • דיווח על תקלות
  • שינוי הודעות שגיאה וקודי סטטוס

מה אי אפשר לעשות בקוד Java

רוב קריאות המערכת אסורות. אי אפשר:

  • לבצע קריאות או כתיבות פנימיות במערכת הקבצים. המשמעות היא שאי אפשר להשתמש בחבילות Java כדי לקרוא ולכתוב במערכות קבצים פנימיות, אבל אפשר לבצע קריאות חיצוניות מרחוק.
  • קבלת מידע על התהליך הנוכחי, על רשימת התהליכים או על השימוש במעבד או בזיכרון במכונה.
  • אפשר לגשת לקוד המקור בקובץ `expressions-1.0.0.jar` ובקובץ `message-flow-1.0.0.jar`.

יכול להיות שחלק מהשיחות האלה יפעלו, אבל הן לא נתמכות ויכול להיות שהן יושבתו באופן פעיל בכל שלב. מומלץ להימנע מביצוע שיחות כאלה בקוד.

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

Hello Java callout

נסביר בעזרת דוגמה בסיסית של קריאה ל-Java. בדוגמה הזו, אנחנו יוצרים Proxy פשוט עם קריאה ל-Java שמחזיר תגובה של 'hello world'. ה-proxy יכול להחזיר אחת משתי תשובות אפשריות:

  • אם מעבירים כותרת username עם ערך name, ה-proxy מחזיר:

    Hello, <name>!
  • אם לא מציינים את הכותרת, ה-Proxy מחזיר רק:

    "Hello, Guest!"

הורדת פרויקט ההתחלה

כדי לפשט את התהליך, הכנו בשבילכם פרויקט בסיסי ב-GitHub במאגר api-platform-samples של Apigee.

  1. מורידים או משכפלים את api-platform-samples למערכת.
  2. במסוף או בכלי לעריכת קוד לפי בחירתכם, עוברים לפרויקט api-platform-samples/doc-samples/java-hello.

כתיבת קוד Java

  1. פותחים את קובץ המקור של Java: java-hello/callout/src/main/java/HelloJava.java. הקובץ הזה הוא גרסת שלד של מחלקת ה-Java הראשית שנבצע בה הטמעה. החבילות שיובאו נדרשות לקוד של Edge Java Callout. המחלקות האלה מספקות methods שמאפשרות לכם לגשת להקשר הביצוע של ה-proxy. בהמשך נסביר איך לקמפל ולפרוס את הקוד הזה.
    package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
                
                try {

                        // Your code here.
            
            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}
  2. מחליפים את השורה עם ההערה // Your code here בקוד הבא:

    String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
  3. שומרים את הקובץ.


קומפילציה של הקוד באמצעות Maven

הפרויקט מוגדר כך שאפשר לבצע קומפילציה באמצעות Maven. אם רוצים להשתמש ב-javac, נציג דוגמה אחרי הדוגמה של Maven.

  1. מוודאים ש-Maven מותקן:

    mvn -version
  2. מריצים את הסקריפט java-hello/buildsetup.sh. הסקריפט הזה מתקין את יחסי התלות הנדרשים ב-JAR במאגר Maven המקומי.
  3. משתמשים בפקודה cd כדי לעבור לספרייה java-hello/callout.
  4. מריצים את Maven:

    mvn clean package
  5. אם רוצים, אפשר לוודא שקובץ ה-JAR‏ edge-custom-policy-java-hello.jar הועתק אל java-hello/apiproxy/resources/java. זה המיקום הנדרש לקובצי JAR שרוצים לפרוס באמצעות שרת proxy.

קומפילציה באמצעות javac (אופציונלי)

בקטע הקודם, יצרתם באופן אוטומטי את קובץ ה-Java JAR הנדרש באמצעות פקודת Maven. לחלופין, אם רוצים להשתמש ב-javac כדי לקמפל את הקוד, אפשר לעשות משהו דומה לזה (מהספרייה java-hello). קובצי ה-JAR הנדרשים מסופקים לכם בספרייה java-hello/lib.

  1. ‫cd אל api-platform-samples/doc-samples/java-hello.
  2. חשוב לוודא ש-javac נמצא בנתיב.

    javac -version
  3. מריצים את פקודת ה-javac הבאה:

    ‫
    javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
     הפעולה הזו יוצרת com/apigeesample/HelloJava.class.
  4. יוצרים קובץ JAR שמכיל את המחלקה שעברה קומפילציה בספרייה apiproxy/resources/java. זה המיקום הנדרש לקובצי JAR שרוצים לפרוס באמצעות שרת proxy. כדי לעשות את זה, מריצים את הפקודה הבאה בספרייה של java-hello (אל תשכחו את הנקודה בסוף).

    jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .

פריסה של ה-proxy והתקשרות אליו

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

  1. ‫cd אל api-platform-samples/doc-samples/java-hello
  2. אם עוד לא עשיתם את זה, פותחים את הקובץ ../../setup/setenv.sh ועורכים אותו לפי ההוראות עם פרטי החשבון שלכם ב-Apigee: שם המשתמש (כתובת האימייל שמשויכת לחשבון), שם הארגון והדומיין שבו אתם משתמשים כדי לבצע קריאות לניהול API. לדוגמה, בדומיין Edge cloud, הדומיין הוא https://api.enterprise.apigee.com, אבל יכול להיות שהדומיין שלכם יהיה שונה אם אתם משתמשים ב-Edge Private Cloud.
  3. שומרים את קובץ ה-setenv.sh.
  4. מריצים את סקריפט הפריסה:

    ./deploy.sh
  5. אם הפריסה מצליחה, מריצים את סקריפט ההפעלה:

    ./invoke.sh

    סקריפט ההפעלה קורא לפקודת cURL שנראית כך:

    curl  http://$org-$env.$api_domain/java-hello -H "username:Will"

    הפונקציה מחזירה את הערך Hello, Will!‎

    אפשר לערוך את הסקריפט invoke.sh כדי לשנות את השם, או שאם משנים את קריאת ה-cURL כדי להסיר את הכותרת, הפקודה מחזירה את הערך Hello, Guest!‎.

מידע על ה-Proxy

נעבור במהירות על כללי המדיניות שמשמשים בשרת הפרוקסי הזה. חשוב לשים לב למיקום של כללי המדיניות בתהליך של ה-proxy ולסיבה לכך.

המדיניות בנושא הקצאת הודעות

מדיניות של הקצאת הודעה מצורפת לבקשת הזרימה של ProxyEndpoint. הוא מעתיק את כותרת שם המשתמש מהבקשה ומקצה אותה לתגובה. הפעולה הזו מאפשרת למדיניות Java Callout, שמצורפת לזרימת התגובה, לגשת לכותרת של שם המשתמש וליצור גוף תגובה מותאם אישית באמצעות הערך של הכותרת הזו.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">     
    <DisplayName>CopyHeader</DisplayName>     
    <Copy source="request">         
        <Headers>             
          <Header name="username"/>         
        </Headers>     
    </Copy>     
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>     
    <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

המדיניות בנושא קריאה ל-Java

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

<JavaCallout name="hello-java">         
    <ClassName>com.apigeesample.HelloJava</ClassName>         
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL> 
</JavaCallout>

מה צריך לדעת על קריאה ל-Java

נקודות חשובות לגבי הטמעה של קריאה ל-Java:

  • מייבא כיתות מחבילות com.apigee.flow.execution ו-com.apigee.flow.message. החבילות האלה צריכות להיכלל בקובץ ה-JAR שנארז ונפרס. אפשר להעלות את קובץ ה-JAR של Java דרך כלי העריכה של ה-proxy בממשק ניהול המשתמש, או לכלול אותו בספרייה /resources/java ב-API proxies שאתם מפתחים באופן מקומי.
  • מטמיע את ממשק ההרצה. כל קוד Java שמופעל ב-proxy ל-API חייב להטמיע Execution.
  • מדיניות Java Callout לא מכילה קוד בפועל. במקום זאת, מדיניות Java Callout מפנה אל Java 'resource', שאותה צריך לארוז ב-JAR.
  • שמות חבילות שאסור להשתמש בהם: אל תשתמשו ב-io.apigee או ב-com.apigee כשמות חבילות ב-Java Callouts. הם שמורים לשימוש של מודולים אחרים של Apigee.
  • אם ה-Java Callout שלכם מסתמך על ספריות נוספות של צד שלישי שנארזו כקבצי JAR עצמאיים, צריך למקם את קובצי ה-JAR האלה גם בספרייה /resources/java כדי לוודא שהם נטענים בצורה תקינה בזמן הריצה.
  • אם יש כמה קובצי JAR, פשוט מוסיפים אותם כמשאבים נוספים. אין צורך לשנות את הגדרות המדיניות כדי להפנות לקובצי JAR נוספים. מספיק להוסיף אותם ל-/resources/java.
  • מידע נוסף על העלאת קובצי JAR של Java זמין במאמר בנושא קובצי משאבים.