איך יוצרים נכס יתרונות מרכזיים ב-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?

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

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

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

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

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

הסבר Java תומך בפעולות הבסיסיות הבאות:

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

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

רוב קריאות המערכת אסורות. לא ניתן:

  • הגדרת יכולת קריאה או כתיבה למערכת הקבצים הפנימית. המשמעות היא שלא ניתן להשתמש באף אחת מחבילות ה-Java כדי לקרוא/לכתוב במערכות קבצים פנימיות, אבל אפשר לבצע קריאות חיצוניות מרחוק.
  • קבלת מידע על התהליך הנוכחי, על רשימת התהליכים או על הניצול של המעבד (CPU)/הזיכרון במכונה.
  • נכנסים לקוד המקור ב-'expressions-1.0.0.jar' וב-'message-flow-1.0.0.jar'.

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

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

שלום Java יתרונות מרכזיים

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

  • אם מעבירים את הערך בשדה 'שם משתמש' בכותרת מסוג 'שם', שרת ה-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. המחלקות האלה מספקות שיטות שמאפשרות לגשת להקשר של ביצוע שרתי 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, הדומיין הוא 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"

    ומחזירה את המשפט "שלום, ווילי!

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

מידע על שרת ה-proxy

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