JavaSummary 政策

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

優勢

讓你使用 Java 導入 Java 政策未立即導入的自訂行為。在 Java 程式碼中，您可以存取 Proxy 流程中的訊息屬性 (標頭、查詢參數、內容) 和流程變數。如果您剛開始使用這項政策，請參閱如何建立 Java 摘要。

請參閱支援的軟體和支援版本。

時程

如需指南，請參閱「如何建立 Java 摘要？」中的「何時需要使用 Java 摘要？」。

簡介

Java 摘要政策可讓您取得及設定流程變數、執行自訂邏輯並執行錯誤處理、擷取要求或回應中的資料等。這項政策可讓您實作其他標準邊緣政策未涵蓋的自訂行為。

您可以將 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 社群貼文。

元素參照

元素參考資料會說明 JavaSummary 政策的元素和屬性。

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

<JavaSummary> 屬性

<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 程式碼在執行 JavaSummary 政策執行時擲回例外狀況或傳回空值時。

部署錯誤

部署含有該政策的 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 會限制存取本機網站、任何本機、回送和連結本機位址。
  • 呼叫無法取得關於目前程序、程序清單或機器上的 CPU/記憶體使用率的資訊。這類呼叫雖然可以正常運作，但實際上並非受支援，且隨時可以自行停用。為求回溯相容性，請避免在程式碼中發出這類呼叫。
  • 不支援 Apigee Edge 隨附的 Java 程式庫。這些程式庫僅適用於 Edge 產品功能，無法保證程式庫一定會發布。
  • 請勿在 Java 摘要中使用 io.apigee 或 com.apigee 做為套件名稱。這些名稱是由其他 Apigee 模組保留及使用。

包裝

將 JAR 放入 API Proxy 下的 /resources/java Proxy 中。如果 Java 摘要依附的其他第三方程式庫需要獨立的 JAR 檔案，請將這些 JAR 檔案放入 /resources/java 目錄，以確保在執行階段正確載入這些 JAR 檔案。

如果您使用管理 UI 建立或修改 Proxy，請新增資源並指定其他相依 JAR 檔案。如果有多個 JAR，只需將這些 JAR 新增為其他資源。如果不需要參照其他 JAR 檔案，則無須修改政策設定。將裝置放在 /resources/java 中即可。

如要進一步瞭解如何上傳 Java JAR，請參閱「資源檔案」。

如需使用 Maven 或 javac 封裝及部署 Java 摘要的詳細範例，請參閱如何建立 Java 摘要。

Javadoc

請參閱GitHub 程式碼，取得編寫 Java 摘要程式碼的 Javadoc。您需要複製 HTML 或下載系統至系統，然後在瀏覽器中開啟 index.html 檔案。

使用須知

  • Java 呼叫政策不含實際的程式碼。相反地，Java 摘要政策會參照 Java 的「資源」，並在 API 程式碼的 Java 程式碼中執行步驟。您可以透過管理 UI Proxy 編輯器上傳 Java JAR，也可以透過 API 的 /resources/java Proxy 目錄，在本機開發 API。
  • 如果是簡易作業，例如向遠端服務發出的 API 呼叫，建議您使用 ServiceSummary 政策。請參閱「服務摘要政策」。
  • 針對訊息訊息的相對互動 (例如修改或擷取 HTTP 標頭、參數或訊息內容)，Apigee 建議使用 JavaScript 政策。

相關主題