您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
可讓您使用 Java 實作 Apigee 政策未立即提供的自訂行為。您可以在 Java 程式碼中存取 Proxy 流程中的訊息屬性 (標頭、查詢參數、內容) 和流程變數。如果您剛開始使用這項政策,請參閱如何建立 Java 呼叫。
如要瞭解支援的 Java 版本,請參閱「支援的軟體和支援的版本」。
時程
如需相關規範,請參閱「如何建立 Java 呼叫」中的「何時該使用 Java 呼叫?」一節。
About
Java 呼叫政策可讓您取得並設定流程變數、執行自訂邏輯並執行錯誤處理、從要求或回應擷取資料等。這項政策可讓您實作其他標準 Edge 政策未涵蓋的自訂行為。
您可以將 Java 應用程式與任何需要的套件 JAR 檔案封裝。請注意,您可以對 Java 呼叫執行的操作有些限制。以下列出限制中的相關條件。範例
簡易範例
如何建立 Java 呼叫擷取 Java 程式碼中的屬性
你可以透過政策的 <Property>
元素指定名稱/值組合,在執行階段中透過 Java 程式碼擷取。如需使用屬性的實際範例,請參閱「如何在 Java 呼叫中使用屬性」。
使用 <Property> 元素的 name
屬性,指定用於從 Java 程式碼存取屬性的名稱。<Property>
元素的值 (開頭與結尾標記之間的值) 是 Java 程式碼接收的值。此值必須是字串;您無法參照流程變數來取得值。
- 設定屬性。這裡的屬性值是變數名稱
response.status.code
。<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout"> <DisplayName>JavaCallout</DisplayName> <ClassName>com.example.mypolicy.MyJavaCallout</ClassName> <ResourceURL>java://MyJavaCallout.jar</ResourceURL> <Properties> <Property name="source">response.status.code</Property> </Properties> </Javascript>
- 在 Java 程式碼中,對執行類別實作方式實作下列建構函式,如下所示:
public class MyJavaCallout implements Execution{ public MyJavaCallout(Map<string, string> props){ // Extract property values from map. } ... }
在 Java 程式碼中設定流程變數
如需有關如何在 Java 程式碼中的訊息結構定義 (流程變數) 中設定變數的清楚說明,請參閱這篇 Apigee 社群貼文。
元素參照
元素參考資料說明 Javacall 政策的元素和屬性。
<JavaCallout name="MyJavaCalloutPolicy"> <ClassName>com.example.mypolicy.MyJavaCallout</ClassName> <ResourceURL>java://MyJavaCallout.jar</ResourceURL> </JavaCallout>
<Java callout> 屬性
<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >
下表說明所有政策父項元素的通用屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<ClassName> 元素
指定執行 Java 呼叫政策時執行的 Java 類別名稱。該類別必須包含在 <ResourceURL>
指定的 JAR 檔案中。另請參閱「如何建立 Java 呼叫」一文。
<JavaCallout name="MyJavaCalloutPolicy"> <ResourceURL>java://MyJavaCallout.jar</ResourceURL> <ClassName>com.example.mypolicy.MyJavaCallout</ClassName> </JavaCallout>
預設: | 不適用 |
所在地: | 需要 |
類型: | 字串 |
<Property> 元素
指定您可以在執行階段從 Java 程式碼存取的屬性。您必須為每個屬性指定常值字串值;您無法在這個元素中參照流程變數。如需使用屬性的實際範例,請參閱「如何在 Java 呼叫中使用屬性」。
<Properties> <Property name="propName">propertyValue</Property> </Properties>
預設: | 無 |
所在地: | 選用 |
類型: | 字串 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
名稱 |
指定屬性名稱。 |
不適用 | 這是必填欄位。 |
<ResourceURL> 元素
這個元素會指定執行 Java 呼叫政策時執行的 Java JAR 檔案。
您可以將這個檔案儲存在 API Proxy 範圍 (在 API Proxy 套件的 /apiproxy/resources/java
之下或 API Proxy 編輯器「Navigator」窗格的「Scripts」區段內),或者儲存在機構或環境範圍中,在多個 API Proxy 中重複使用,如資源檔案中所述。
<JavaCallout name="MyJavaCalloutPolicy"> <ResourceURL>java://MyJavaCallout.jar</ResourceURL> <ClassName>com.example.mypolicy.MyJavaCallout</ClassName> </JavaCallout>
預設: | 無 |
所在地: | 需要 |
類型: | 字串 |
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.javacallout.ExecutionError |
500 | 發生於 Java 程式碼在執行 Java Call 政策期間擲回例外狀況或傳回空值時發生。 | build |
部署錯誤
部署含有政策的 Proxy 時,就可能會發生這類錯誤。
錯誤名稱 | 錯誤字串 | HTTP 狀態 | 發生時機 |
---|---|---|---|
ResourceDoesNotExist |
Resource with name
[name] and type [type] does not exist |
不適用 | <ResourceURL> 元素中指定的檔案不存在。 |
JavaCalloutInstantiationFailed |
Failed to instantiate the JavaCallout Class [classname] |
不適用 | <ClassName> 元素中指定的類別檔案不在 jar 中。 |
IncompatibleJavaVersion |
Failed to load java class [classname] definition due to - [reason] |
不適用 | 查看錯誤字串。另請參閱支援的軟體和支援的版本。 |
JavaClassNotFoundInJavaResource |
Failed to find the ClassName in java resource [jar_name] -
[class_name] |
不適用 | 查看錯誤字串。 |
JavaClassDefinitionNotFound |
Failed to load java class [class_name] definition due to - [reason] |
不適用 | 查看錯誤字串。 |
NoAppropriateConstructor |
No appropriate constructor found in JavaCallout class [class_name] |
不適用 | 查看錯誤字串。 |
NoResourceForURL |
Could not locate a resource with URL [string] |
不適用 | 查看錯誤字串。 |
錯誤變數
系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "fault":{ "faultstring":"Failed to execute JavaCallout. [policy_name]", "detail":{ "errorcode":"javacallout.ExecutionError" } } }
故障規則示例
<FaultRule name="JavaCalloutFailed"> <Step> <Name>AM-JavaCalloutError</Name> </Step> <Condition>(fault.name Matches "ExecutionError") </Condition> </FaultRule>
結構定義
編譯及部署
如要進一步瞭解如何編譯自訂 Java 程式碼,並使用 Proxy 進行部署,請參閱「如何建立 Java 呼叫」一文。
限制
編寫 Java 呼叫時,需要考慮的限制如下:
- 大多數的系統呼叫都不允許。例如,您無法將內部檔案系統讀取或寫入。
- 透過通訊端存取網路。Apigee 會限制對 sitelocal、任何本機、回送和連結本機位址的存取權。
- 呼叫無法取得目前程序、程序清單或機器的 CPU/記憶體使用率的相關資訊。雖然部分這類呼叫可能可以正常運作,但系統不支援且必須隨時主動停用。為達成前瞻相容性,請避免在程式碼中進行這類呼叫。
- 不支援使用 Apigee Edge 隨附的 Java 程式庫。這些程式庫僅供 Edge 產品功能使用,不保證程式庫在發布到發布期間皆可使用。
- 請勿在 Java 呼叫中使用
io.apigee
或com.apigee
做為套件名稱。這些名稱會由其他 Apigee 模組保留及使用。
包裝
將 JAR 放入 API Proxy 的 /resources/java
下。如果您的 Java 呼叫需要另行封裝為獨立 JAR 檔案的第三方程式庫,請將這些 JAR 檔案放在 /resources/java
目錄中,以確保在執行階段正確載入。
如果您使用管理 UI 建立或修改 Proxy,請新增資源並指定其他相依的 JAR 檔案。如果有多個 JAR,只要將這些 JAR 新增為額外資源即可。不需要修改政策設定即可參照其他 JAR 檔案。將他們放在 /resources/java
中就夠了。
如要瞭解如何上傳 Java JAR,請參閱「資源檔案」。
如需使用 Maven 或 javac 封裝及部署 Java 呼叫的詳細範例,請參閱「如何建立 Java 呼叫」一文。
Javadoc
用於編寫 Java 呼叫程式碼的 Javadoc 已納入 GitHub。您需要複製 HTML 或下載至您的系統,然後在瀏覽器中開啟 index.html 檔案。
使用須知
- Java 呼叫政策未包含實際程式碼。Java 的呼叫政策會參照 Java 的「資源」,並在執行 Java 程式碼的 API 流程中定義步驟。您可以透過管理 UI Proxy 編輯器上傳 Java JAR,也可以將其加入您在本機開發的 API Proxy 的
/resources/java
目錄中。 - 如果是輕量作業 (例如向遠端服務發出 API 呼叫),建議使用 Service Call 政策。請參閱服務呼叫政策。
- 針對相對簡單的訊息內容互動,例如修改或擷取 HTTP 標頭、參數或訊息內容,Apigee 建議使用 JavaScript 政策。
相關主題
- 如需相關範例,請參閱 java-cookbook 存放區。