本頁面由 Cloud Translation API 翻譯而成。

如何建立 Java 呼叫

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。資訊

什麼是 Java 呼叫？

Apigee Edge 提供一系列政策，可因應常見的 API 管理需求，例如安全性、資料轉換、流量管理等。

然而，在某些情況下，您的 API 會需要在標準政策中實作的自訂行為。在這些情況下，Apigee 提供多種選項，讓您依據自訂 API 行為編寫指令碼或編寫程式碼。其中一種方法是在 Java 中實作所需行為。

如要瞭解支援的 Java 版本，請參閱「支援的軟體和支援的版本」。

如何在 Proxy 中使用 Java 程式碼？

Java 呼叫政策可讓您在執行中的 Proxy 流程中呼叫 Java 程式碼。您的 Java 程式碼必須實作特定 Edge 專用的 Java 介面，讓程式碼能與執行中的 Proxy 互動。舉例來說，Java 方法可在 Proxy 的目前流程環境中取得及設定標頭、查詢參數、流程變數和其他實體。

何時該使用 Java 呼叫？

我們來看看 Java 呼叫在哪些情況下相當實用，以及應該考慮採用其他方法的情況。

首先，考慮替代方法

使用 Java 呼叫之前，請注意您或許可以改用替代方法。例如：

如果是輕量級作業，例如向遠端服務發出 HTTP API 呼叫，請考慮採用 Service Call 政策。請參閱服務呼叫政策。
如要與郵件內容進行相對簡單的互動，例如修改或擷取 HTTP 標頭、參數或訊息內容，您可以使用 JavaScript 或 Python 語言。

Java 程式碼的用途

Java 呼叫支援下列基本作業：

檢查或操控要求或回應訊息
取得及設定流程變數。您可以使用 Java 方法存取 Edge 流程變數。如要存取鍵/值對應 (KVM) 資訊，請使用 KVM 政策，為流程變數指派 KVM 值，然後您就可以透過 Java 呼叫存取流程變數。
呼叫外部服務
抬起故障
操控錯誤訊息和狀態碼

Java 程式碼不支援的功能

大多數的系統呼叫都不允許。您不得：

將內部檔案系統讀取或寫入。這表示您無法使用任何 Java 套件讀取/寫入內部檔案系統，但可以進行外部遠端呼叫。
取得機器當前程序、程序清單或 CPU/記憶體使用率的相關資訊。
存取「expressions-1.0.0.jar」和「message-flow-1.0.0.jar」中的原始碼。

雖然部分呼叫可能有效，但目前仍不支援這些呼叫，且必須隨時主動停用。請避免在程式碼中進行這類呼叫。

請勿使用或仰賴 Apigee Edge 隨附的 Java 程式庫。這些程式庫僅供 Edge 產品功能使用，不保證程式庫在發布到發布期間皆可使用。如果您使用這類程式庫，請只在非實際工作環境的示範中使用。

Hello Java 摘要

以下逐步說明基本的 Hello World Java 呼叫範例。在這個範例中，我們會建立包含 Java 呼叫的簡易 Proxy，藉此傳回「hello world」回應。Proxy 可能會傳回以下兩種可能的回應：

如果您傳入含有「name」值的「username」標頭，Proxy 會傳回以下內容：
```
Hello, <name>!
```
如果省略標頭，Proxy 只會傳回：
```
"Hello, Guest!"
```

下載範例專案

為協助您輕鬆完成，我們在 Apigee api-platform-samples 存放區中為您準備了適用於 GitHub 的基本專案。

將 api-platform-samples 下載或複製到您的系統。
使用您選擇的終端機或程式碼編輯器，前往 api-platform-samples/doc-samples/java-hello 專案。

編寫 Java 程式碼

開啟 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;
                }
        }

}

將註解行 // 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 物件可讓您存取執行 Java 呼叫政策的流程中的實體。假設 Java 呼叫政策已附加至 Proxy 端點回應流程。上述程式碼會取得該流程內容的 HTTP 訊息物件。Message 物件也可以讓您存取標頭、查詢參數、內文和流程變數。
儲存檔案。

使用 Maven 編譯程式碼

專案設定完畢，方便您使用 Maven 進行編譯。如要使用 javac，我們會在 Maven 範例中加入範例。

確認已安裝 Maven：
```
mvn -version
```
執行 java-hello/buildsetup.sh 指令碼。這個指令碼會在本機 Maven 存放區中安裝必要的 JAR 依附元件。
cd 寫入 java-hello/callout 目錄。
執行 Maven：
```
mvn clean package
```
注意：如果系統顯示 Maven 錯誤，請確認您位於 java-hello/callout 目錄中。
如要確認 JAR 檔案 edge-custom-policy-java-hello.jar 是否已複製到 java-hello/apiproxy/resources/java，這是您要透過 Proxy 部署的 JAR 檔案必要位置。

透過 Javac 編譯 (選用)

在上一節中，您使用 Maven 指令自動產生必要的 Java JAR 檔案。或者，如果您想使用 javac 編譯程式碼，可以執行類似下方的操作 (從 java-hello 目錄)。java-hello/lib 目錄中會提供所需的 JAR 檔案。

cd 重新命名為 api-platform-samples/doc-samples/java-hello。
請確認路徑中有 Javac。
```
javac -version
```

執行下列 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。

在 apiproxy/resources/java 目錄中建立包含已編譯類別的 JAR 檔案。這是您要透過 Proxy 部署的 JAR 檔案必要位置。如要這麼做，請在 java-hello 目錄中執行下列指令 (不要忘記結尾的半形句號)。
```
jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
```

部署及呼叫 Proxy

./java-hello 目錄中會提供部署指令碼。但在執行前，您必須先快速設定。

CD 至 api-platform-samples/doc-samples/java-hello
如果尚未開啟檔案 ../../setup/setenv.sh，請先開啟檔案，然後依照 Apigee 帳戶資訊 (與帳戶相關聯的電子郵件地址)、貴機構的名稱，以及用於執行 API 管理呼叫的網域來編輯該檔案。舉例來說，若為 Edge Cloud，網域為 https://api.enterprise.apigee.com；不過，如果您使用的是 Edge Private Cloud，網域可能會不同。
儲存 setenv.sh 檔案。
執行部署指令碼：
```
./deploy.sh
```
如果部署成功，請執行叫用指令碼：
```
./invoke.sh
```
叫用指令碼呼叫的 cURL 指令如下所示：
```
curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
```
這會回傳「Hello, Will!

您可以透過編輯 invoke.sh 指令碼來變更名稱，或是將 cURL 呼叫變更為移除標頭，接著指令會傳回「Hello, Guest!」

關於 Proxy

讓我們快速檢查這個 Proxy 中使用的政策。請留意政策在 Proxy 流程中的位置和原因，

指派訊息政策

指派訊息政策會附加至 ProxyEndpoint 要求流程。它會複製要求中的使用者名稱標頭，然後指派給回應。這項作業可讓附加至回應流程的 Java 呼叫政策存取使用者名稱標頭，並使用該標頭的值建構自訂回應主體。

<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 檔案名稱，並新增至 Proxy 的 resources/java 目錄。

<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 檔案中。您可以透過管理 UI Proxy 編輯器上傳 Java JAR，也可以將其加入在本機開發的 API Proxy 的 /resources/java 目錄中。
實作執行介面。在 API Proxy 中執行的任何 Java 程式碼都必須實作執行作業。
Java 呼叫政策未包含實際程式碼。Java 呼叫政策會參照 Java「資源」，您必須將該資源封裝在 JAR 中。
應避免的套件名稱：請勿使用 io.apigee 或 com.apigee 做為 Java 呼叫中的套件名稱。這些模組會由其他 Apigee 模組保留及使用。
如果您的 Java 呼叫需要使用封裝為獨立 JAR 檔案的其他第三方程式庫，請將這些 JAR 檔案放在 /resources/java 目錄中，以確保在執行階段正確載入。
如果有多個 JAR，只要將這些 JAR 新增為額外資源即可。不需要修改政策設定即可參照其他 JAR 檔案。只要在 /resources/java 中加上這些變數就夠了。
如要進一步瞭解如何上傳 Java JAR，請參閱「資源檔案」。