JavaSummary 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

您可以使用 JavaCallout 政策，透過 Java 實作 Apigee 政策未提供的自訂行為。在 Java 程式碼中，您可以存取訊息屬性 (標頭、查詢參數、內容)、取得及設定流程變數、執行自訂邏輯和執行錯誤處理、從要求或回應中擷取資料等。如果您剛開始使用這項政策，請參閱如何建立 Java 呼叫。

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

支援的 Java 版本包括：Oracle JDK 11 和 OpenJDK 11。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

範例

一般樣本

如需使用 Java 呼叫的簡單範例，請參閱「如何建立 Java 呼叫」。

如要瞭解如何在 Java 程式碼中設定流程變數，請參閱這篇Apigee 社群貼文，瞭解如何偵錯 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>
</JavaCallout>

在 Java 程式碼中，於 Execution 類別實作下列建構函式：

public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

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

元素參考資料

元素參考資料說明 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>` 元素，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。	不適用	必填
`continueOnError`	設為 `false`，在政策失敗時傳回錯誤。這是大多數政策的預期行為。設為 `true`，即使政策失敗，流程執行作業仍會繼續。另請參閱：只有在錯誤狀態下才會觸發錯誤規則 (關於 continueOnError) 處理目前流程中的錯誤提示：如果 Java 程式碼擲回例外狀況，即使 `continueOnError` 屬性設為 true，Apigee 代理程式流程仍會移至錯誤狀態。如果您不希望擲回的例外狀況導致 Proxy 發生錯誤狀態，請設計 Java 呼叫程式碼，確保不會擲回錯誤。請改為擷取例外狀況，並設定內容變數來擷取例外狀況資訊。詳情請參閱這篇 Apigee 社群貼文。	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉這項政策。即使政策仍附加至流程，系統也不會強制執行。	true	選用
`async`	這項屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以使用這個屬性，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
狀態	選用
類型	字串

不適用

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

狀態選用

類型字串

<ClassName> 元素

指定 JavaCallout 政策執行時執行的 Java 類別名稱。類別必須包含在 <ResourceURL> 指定的 JAR 檔案中。另請參閱如何建立 Java 呼叫。

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

預設值：	不適用
外觀狀態：	必填
類型：	字串

<Properties> 元素

新增可在執行階段從 Java 程式碼存取的新屬性。

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

預設值：	無
外觀狀態：	選用
類型：	字串

<Property> 元素

指定可在執行階段透過 Java 程式碼存取的屬性。您必須為每個屬性指定字串值，且無法在這個元素中參照流程變數。如需使用屬性的運作範例，請參閱「如何在 JavaCallout 政策中使用屬性」。

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

預設值：	無
外觀狀態：	選用
類型：	字串

屬性

屬性	說明	預設	狀態
名稱	指定屬性的名稱。	不適用	必填。

<ResourceURL> 元素

這個元素會指定 Java JAR 檔案，在 JavaCallout 政策執行時執行。

您可以將這個檔案儲存在 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 Apigee 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. Supported Java versions include: Oracle JDK 7/8 and OpenJDK 7/8
`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>

結構定義

範例：每個政策類型都是由 XML 結構定義 (.xsd) 所定義。如需參考，請前往 GitHub 查看政策結構定義。

編譯及部署

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

限制

撰寫 Java 呼叫程式碼時，請注意下列限制：

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

包裝

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

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

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

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

Javadoc

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

使用注意事項和最佳做法

使用多個 JavaCallout 政策時，請考慮將常見的 JAR 做為環境範圍資源上傳。與在部署至相同環境時，使用多個 Proxy 組合封裝相同 JAR 相比，這種做法的效率更高。
請避免將同一 JAR 檔案的多個副本或版本封裝及部署至環境。舉例來說，Apigee 建議您避免：
- 將同一個 JAR 部署為 Proxy 套件的一部分，以及環境資源。
- 將一個版本的 JAR 檔案部署為環境資源，另一個版本則部署為 Proxy 組合的一部分。
如果部署多個相同 JAR 的副本，可能會因 ClassLoader 衝突而導致執行階段出現非決定性行為。
JavaCallout 政策不含實際程式碼。而是參照 Java「資源」，並定義 Java 程式碼執行的 API 流程步驟。您可以透過管理 UI Proxy 編輯器上傳 Java JAR，也可以將其納入您在本機開發的 API Proxy 的 /resources/java 目錄中。
如果是輕量型作業 (例如呼叫遠端服務的 API)，建議使用 ServiceCallout 政策。請參閱服務呼叫政策。
如果與訊息內容的互動相對簡單，例如修改或擷取 HTTP 標頭、參數或訊息內容，Apigee 建議使用 JavaScript 政策。