JavaSummary 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

可讓您使用 Java 實作 Apigee 政策。在 Java 程式碼中，您可以存取訊息屬性 (標頭、查詢參數、 內容) 和流程變數。如果您剛開始使用這項政策 請參閱如何建立 Java 摘要。

如需支援的 Java 版本，請參閱支援 軟體和支援的版本。

時間

如需相關指南，請參閱「何時該使用 Java 呼叫？」「如何建立 Java 摘要。

關於

Java 呼叫政策可讓您取得及設定流程變數、執行自訂邏輯，並執行 以及從要求或回應中擷取資料等等。這項政策可讓你 實作其他標準 Edge 政策未涵蓋的自訂行為。

您可以將 Java 應用程式與所需的任何套件 JAR 檔案封裝。注意事項 Java 呼叫會有一些限制。如下所列： 。

範例

簡易範例

如何建立 Java 摘要

擷取 Java 程式碼中的屬性

政策的 <Property> 元素可讓您指定名稱/值 的 YAML 格式組合，可在執行階段使用 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>

&lt;JavaCallout&gt;屬性

<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 屬性值會是

存在必要性 選用
類型 字串

&lt;ClassName&gt;元素

指定在執行 Java 呼叫政策時執行的 Java 類別名稱。 類別必須包含在 <ResourceURL> 指定的 JAR 檔案中。詳情請見 另外，如何建立 Java 摘要。

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
預設： 不適用
所在地： 必填
類型： 字串

&lt;Property&gt;元素

指定您可以在執行階段中存取 Java 程式碼的屬性。您必須指定常值 每個屬性的字串值；您無法在這個元素中參照流程變數。換 請參閱如何使用屬性中的屬性 Java 呼叫。

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
預設： 無
所在地： 選用
類型： 字串

屬性

屬性 說明 預設 存在必要性
名稱

指定屬性的名稱。

 不適用 必填。

&lt;ResourceURL&gt; 元素

這個元素會指定在 Java 呼叫原則時執行的 Java JAR 檔案 或任何可執行 Knative 的環境中

您可以將這個檔案儲存在 API Proxy 範圍 (位於 /apiproxy/resources/java， 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 摘要時需要考量的限制：

  • 大部分的系統呼叫都遭到禁止。例如，您無法讓內部檔案系統讀取 寫入或寫入
  • 透過通訊端存取網路。Apigee 會限制存取 Sitelocal、alllocal 回送以及連結本機位址
  • 呼叫無法取得目前程序、程序清單或 電腦的 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 檔案只要輸入 /resources/java 即可。

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

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

Javadoc

想要編寫 Java 呼叫程式碼的 Javadoc，請參閱這裡 GitHub。您需要將 HTML 複製或下載到系統中，然後開啟 index.html 檔案。

使用須知

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

相關主題