JavaSummary 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

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

時間

如需相關指南，請參閱「如何建立 Java 呼叫」一文中的「何時應使用 Java 呼叫？」。

關於

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

您可以將 Java 應用程式與所需的任何套件 JAR 檔案封裝在一起。請注意，Java Callout 的功能有一些限制。這些限制列於下方的「限制」一節。

範例

簡單範例

如何建立 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 程式碼中，於 Execution 類別實作項目中實作下列建構函式：
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

在 Java 程式碼中設定流程變數

如要清楚瞭解如何在 Java 程式碼中設定訊息環境中的變數 (流程變數)，請參閱這篇 Apigee 社群貼文。

元素參考資料

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

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

<JavaCallout> 屬性

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

下表說明所有政策父項元素的共同屬性：

屬性 說明 預設 存在必要性
name

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

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

<ClassName> 元素

指定 Java Callout 政策執行時執行的 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 JAR 檔案，在 Java 呼叫政策執行時執行。

您可以將這個檔案儲存在 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>
預設值： 無
外觀狀態： 必填
類型： 字串

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Example fault rule

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

結構定義

編譯及部署

如要進一步瞭解如何編譯自訂 Java 程式碼，並透過 Proxy 部署，請參閱「如何建立 Java 呼叫」。

限制

撰寫 Java Callout 時，請注意下列限制：

  • 大多數系統呼叫都不允許。舉例來說，您無法讀取或寫入內部檔案系統。
  • 透過通訊端存取網路。Apigee 會限制存取 sitelocal、anylocal、迴路和連結本機位址。
  • 無法取得機器上的目前程序、程序清單或 CPU/記憶體使用率資訊。雖然部分這類通話可能可以運作，但我們不支援這類通話，且隨時可能主動停用。為確保向前相容性，請避免在程式碼中進行這類呼叫。
  • 不支援使用 Apigee Edge 隨附的 Java 程式庫。這些程式庫僅適用於 Edge 產品功能，且無法保證每個版本都會提供程式庫。
  • 請勿在 Java Callout 中使用 io.apigee 或 com.apigee 做為套件名稱。這些名稱已保留，供其他 Apigee 模組使用。

包裝

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

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

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

如需詳細範例，瞭解如何使用 Maven 或 javac 封裝及部署 Java 呼叫，請參閱「如何建立 Java 呼叫」。

Javadoc

如需編寫 Java Callout 程式碼的 Javadoc，請參閱 GitHub 上的這篇文章。您需要將 HTML 複製或下載到系統，然後在瀏覽器中開啟 index.html 檔案。

使用須知

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

相關主題