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>
預設值： 無
外觀狀態： 必填
類型： 字串

錯誤參考資料

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤程式碼 HTTP 狀態 原因 修正
steps.javacallout.ExecutionError 500 在 Java 呼叫政策執行期間，Java 程式碼擲回例外狀況或傳回空值時會發生。

部署錯誤

部署包含政策的 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.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 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 政策。

相關主題