JavaSummary 政策

您正在查看 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

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<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 政策期間擲回例外狀況或傳回空值時發生。

部署錯誤

部署含有政策的 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] 不適用 查看錯誤字串。

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 javacallout.JC-GetUserData.failed = true

錯誤回應範例

{  
   "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.apigeecom.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 政策。

相關主題