本頁適用於 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中的原始碼。
雖然部分這類呼叫可能會運作，但 Google 不支援這類呼叫，且可能隨時主動停用。請避免在程式碼中進行這類呼叫。
請勿使用或仰賴 Apigee 隨附的 Java 程式庫。這些程式庫僅供 Apigee 產品功能使用，且無法保證每個版本都會提供程式庫。如果您使用這類程式庫，請僅在非正式環境的示範中使用。
您好，JavaCallout
讓我們來看看基本的 hello world JavaCallout 政策範例。在本例中，我們會使用 JavaCallout 建立簡單的 Proxy，傳回「hello world」回應。代理程式可傳回下列兩種可能的回應：
- 如果您傳入含有「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」。請務必使用「Upload Proxy Bundle」選項。另請參閱 Apigee 社群的 有關在 Proxy 套件中上傳 API 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 檔案中。您可以透過管理介面 Proxy 編輯器上傳 Java JAR，也可以在本機開發的 API Proxy 的/resources/java目錄中加入 JAR。 - 實作執行介面。在 API 代理程式中執行的任何 Java 程式碼都必須實作 Execution。
- JavaCallout 政策不包含實際程式碼。相反地，政策會參照 Java 的「資源」，您必須將這類資源封裝在 JAR 中。
- 應避免的套件名稱：請勿在 JavaCallout 政策中使用 io.apigee 或 com.apigee 做為套件名稱。這些名稱已保留，並由其他 Apigee 模組使用。
- 如果 JavaCallout 政策會使用其他以獨立 JAR 檔案封裝的第三方程式庫，請將這些 JAR 檔案也放在
/resources/java目錄中，確保這些檔案在執行階段正確載入。 - 如果有多個 JAR，只要將這些 JAR 新增為額外資源即可。您不需要修改政策設定，即可參照其他 JAR 檔案。將這些元素放入
/resources/java即可。 - 如要進一步瞭解如何上傳 Java JAR，請參閱「資源檔案」。