איך יוצרים Java Callout

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

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

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

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

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

גרסאות Java נתמכות: Oracle JDK 11 ו-OpenJDK 11.

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

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

מתי כדאי להשתמש במדיניות JavaCallout?

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

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

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

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

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

מדיניות JavaCallout תומכת בפעולות הבסיסיות הבאות:

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

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

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

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

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

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

Hello JavaCallout

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

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

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

    "Hello, Guest!"

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

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

  1. מורידים או משכפלים את api-platform-samples למערכת. אם api-platform-samples כבר מותקן במערכת, צריך להריץ pull כדי לוודא שמותקנת הגרסה העדכנית.
  2. במסוף או בכלי לעריכת קוד לפי בחירתכם, עוברים לפרויקט api-platform-samples/doc-samples/java-hello.

כתיבת קוד Java

  1. פותחים את קובץ המקור של Java: java-hello/callout/src/main/java/HelloJava.java. הקובץ הזה הוא גרסת שלד של מחלקת ה-Java הראשית שנבצע בה הטמעה. החבילות המיובאות נדרשות לקוד JavaCallout של Apigee. המחלקות האלה מספקות 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

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

    mvn -version
  2. מתקינים את יחסי התלות הנדרשים של JAR במאגר Maven המקומי באחת מהשיטות הבאות:
    • מוסיפים את קטע הקוד הבא לקובץ pom.xml כדי להוריד את יחסי התלות הנדרשים של JAR מ- Artifact Registry: 
      <repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>
    • משתמשים בקריאות הבאות ל-curl כדי להוריד את יחסי התלות הנדרשים ב-JAR מ- Artifact Registry: 
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar
        
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar
    • מריצים את הסקריפט java-hello/buildsetup.sh. הסקריפט הזה מוריד את קשרי התלות הנדרשים של JAR ממאגר Apigee GitHub.
  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.

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

כדי לפרוס ולבדוק את proxy ל-API:

  1. עוברים לספרייה java-hello:
  2. מכווצים את חבילת ה-API proxy: 
    zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
  3. הדרך הכי פשוטה לפרוס את ה-proxy היא לארוז אותו בקובץ ZIP ולהעלות את חבילת ה-proxy לסביבה בארגון Apigee. מידע נוסף זמין במאמר בנושא יצירת proxy ל-API. חשוב להשתמש באפשרות העלאת חבילת שרת proxy. אפשר לעיין גם ב טיפים וטריקים להעלאת proxy ל-API בחבילת proxy בקהילת Apigee.
  4. אחרי שפורסים את השרת הפרוקסי, מנסים להתקשר אליו:
    curl  https://$HOSTNAME/java-hello -H "username:Will"

    הפונקציה מחזירה 'Hello, Will!‎'

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

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

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

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

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

המדיניות JavaCallout

מדיניות JavaCallout מצורפת ל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>

מה צריך לדעת על מדיניות JavaCallout

חשוב לדעת על הטמעה של מדיניות JavaCallout:

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