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

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

כתיבת קוד Java

פותחים את קובץ המקור של 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;
                }
        }

}

מחליפים את השורה עם ההערה // 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!");
}
```
הערה: הערה: האובייקט MessageContext מאפשר לכם לגשת לישויות בתוך התהליך שבו מופעלת מדיניות JavaCallout. נניח שמדיניות JavaCallout מצורפת לזרימת התגובה של נקודת הקצה של ה-Proxy. הקוד שמופיע למעלה מאחזר את אובייקט ההודעה של HTTP עבור הקשר של אותו תהליך. אובייקט ההודעה, בתורו, נותן לכם גישה לכותרות, לפרמטרים של שאילתות, לתוכן הגוף ולמשתני הזרימה.
שומרים את הקובץ.

הידור הקוד באמצעות Maven

מוודאים ש-Maven מותקן:
```
mvn -version
```

מתקינים את יחסי התלות הנדרשים ב-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.

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

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

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

עוברים לספרייה java-hello.

מכווצים את חבילת ה-proxy ל-API:

zip apiproxy-bundle.zip -r apiproxy -x \*.\*~

הדרך הכי פשוטה לפרוס את ה-proxy היא לארוז אותו בקובץ ZIP ולהעלות את חבילת ה-proxy לסביבה בארגון Apigee. מידע נוסף זמין במאמר בנושא יצירת proxy ל-API. חשוב להשתמש באפשרות העלאת חבילת שרת proxy. אפשר לעיין גם ב טיפים וטריקים להעלאת proxy ל-API בחבילת proxy בקהילת Apigee.
אחרי שפורסים את ה-proxy, מנסים להתקשר אליו:
```
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 זמין במאמר קובצי משאבים.