本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
什麼是 Java 呼叫？
Apigee 提供一系列政策，可滿足常見的 API 管理需求，例如安全性、資料轉換、流量管理等。
不過，在某些情況下，您的 API 需要自訂行為，但標準政策並未實作這類行為。在這些情況下，Apigee 提供多種選項，讓您編寫指令碼或程式碼，自訂 API 行為。其中一種做法是在 Java 中實作所需行為。
支援的 Java 版本包括：Oracle JDK 11 和 OpenJDK 11。
如何在 Proxy 中使用 Java 程式碼？
JavaCallout 政策可讓您在執行中的 Proxy 流程中呼叫 Java 程式碼。您的 Java 程式碼必須實作特定的 Apigee Java 介面，才能與執行的 Proxy 互動。舉例來說，Java 方法可用於在 Proxy 的目前流程情境中取得及設定標頭、查詢參數、流程變數和其他實體。
何時該使用 JavaCallout 政策？
我們來看看 JavaCallout 政策的適用情況，以及您應考慮其他做法的情況。
首先，請考慮其他方法
使用 JavaCallout 政策前，請注意您可能可以改用其他方法。例如：
- 如果是輕量型作業 (例如對遠端服務發出 HTTP API 呼叫)，建議使用 ServiceCallout 政策。請參閱服務說明政策。
- 如要與郵件內容進行相對簡單的互動，例如修改或擷取 HTTP 標頭、參數或郵件內容，可以使用 JavaScript 或 PythonScript 政策。
Java 程式碼可執行的操作
JavaCallout 政策支援下列基本作業：
- 檢查或操控要求或回應訊息
- 取得及設定流程變數。您可以使用 Java 方法存取 Apigee 流程變數。 如要存取鍵/值對應 (KVM) 資訊，請使用 KVM 政策，將 KVM 值指派給流程變數，然後從 JavaCallout 政策中存取流程變數。
- 呼叫外部服務
- 提出錯誤
- 操控錯誤訊息和狀態碼
Java 程式碼無法執行的操作
大多數系統呼叫都不允許。您無法：
- 讀取或寫入內部檔案系統。也就是說，您無法使用任何 Java 套件讀取/寫入內部檔案系統，但可以進行外部遠端呼叫。
- 取得機器上目前程序、程序清單或 CPU/記憶體使用率的相關資訊。
- 在
expressions-1.0.0.jar和message-flow-1.0.0.jar中存取原始碼。
雖然部分這類通話可能可以運作，但我們不支援這類通話，且隨時可能主動停用。請避免在程式碼中發出這類呼叫。
請勿使用或依賴 Apigee 隨附的 Java 程式庫。這些程式庫僅適用於 Apigee 產品功能，且無法保證每個版本都會提供程式庫。如果您使用這類程式庫，請僅在非正式環境的示範中使用。
Hello JavaCallout
我們來看看 JavaCallout 政策的基本 Hello World 範例。在本範例中，我們使用 JavaCallout 建立簡單的 Proxy，傳回「hello world」回應。Proxy 可能會傳回下列其中一種回應：
- 如果您傳遞含有「name」值的「username」標頭，Proxy 會傳回：
Hello, <name>!
- 如果省略標頭，Proxy 只會傳回：
"Hello, Guest!"
下載範例專案
為簡化作業，我們在 GitHub 的 Apigee api-platform-samples 存放區中，為您準備了基本專案。
- 將 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 類別的架構版本。Apigee JavaCallout 程式碼必須匯入這些套件。這些類別提供的方法可讓您存取 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!"); }
- 儲存檔案。
使用 Maven 編譯程式碼
- 請確認已安裝 Maven：
mvn -version
- 使用下列任一方法，在本機 Maven 存放區中安裝必要的 JAR 依附元件：
- 在
pom.xml檔案中新增下列程式碼片段，從 Artifact Registry 下載必要的 JAR 依附元件：<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呼叫，從 Artifact Registry 下載必要的 JAR 依附元件：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。這項指令碼會從 Apigee GitHub 存放區下載必要的 JAR 依附元件。
- 在
- cd 至
java-hello/callout目錄。 - 執行 Maven：
mvn clean package
- 如要確認 JAR 檔案
edge-custom-policy-java-hello.jar是否已複製到java-hello/apiproxy/resources/java，這是您要透過 Proxy 部署的 JAR 檔案必要位置。
部署及呼叫 Proxy
請按照下列步驟部署及測試 API Proxy：
- 切換至
java-hello目錄。 - 將 API Proxy 組合壓縮為 ZIP 檔案：
zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
- 如要部署 Proxy，最簡單的方法是將 Proxy 封裝在 ZIP 檔案中，然後將 Proxy 套件上傳至 Apigee 機構的環境。請參閱「建立 API Proxy」。 請務必使用「上傳 Proxy 組合」選項。另請參閱 Apigee 社群中的「 上傳 API Proxy 組合的訣竅」。
- 部署 Proxy 後，請嘗試呼叫：
curl https://$HOSTNAME/java-hello -H "username:Will"
這會傳回「Hello, Will!
關於 Proxy
讓我們快速檢查這個 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 政策會附加至回應流程。這是因為自訂 Java 程式碼會變更回應標頭和訊息。政策的 ClassName 元素會指定政策執行的主要類別。ResourceURL 元素是您建構並新增至 Proxy resources/java 目錄的 JAR 檔案名稱。
<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 檔案中。您可以透過管理 UI 代理編輯器上傳 Java JAR，也可以將其納入您在本機開發的 API 代理項目中的/resources/java目錄。 - 實作 Execution 介面。在 API 代理程式中執行的任何 Java 程式碼，都必須實作 Execution。
- JavaCallout 政策不含任何實際程式碼。而是參照 Java「資源」，您必須將該資源封裝在 JAR 中。
- 應避免的套件名稱：請勿在 JavaCallout 政策中使用 io.apigee 或 com.apigee 做為套件名稱。這些保留字會供其他 Apigee 模組使用。
- 如果 JavaCallout 政策依附於封裝為獨立 JAR 檔案的其他第三方程式庫，請將這些 JAR 檔案也放在
/resources/java目錄中，確保這些檔案在執行階段正確載入。 - 如有其他 JAR，只要新增為額外資源即可。您不需要修改政策設定，即可參照其他 JAR 檔案。將這些檔案放入
/resources/java即可。 - 如要進一步瞭解如何上傳 Java JAR，請參閱「資源檔案」一文。