本頁面由 Cloud Translation API 翻譯而成。

JavaSummary 政策

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

查看 Apigee Edge 說明文件。

政策圖示

結果

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

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

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

時間

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

關於

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

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

範例

簡單範例

如何建立 Java 呼叫

在 Java 程式碼中擷取屬性

您可以使用政策的 <Property> 元素指定名稱/值配對，並在 Java 程式碼中於執行階段擷取。如需使用屬性的運作範例，請參閱「如何在 JavaCallout 政策中使用屬性」。

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

預設值：	無
外觀狀態：	必填
類型：	字串

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因	修正
`steps.javacallout.ExecutionError`	`500`	發生於 Java 程式碼在執行 `JavaCallout policy` 時擲回例外狀況或傳回空值。

部署錯誤

部署含有政策的 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]`	不適用	請參閱錯誤字串。支援的 Java 版本包括：Oracle JDK 7/8 和 OpenJDK 7/8
`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>

結構定義

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

編譯及部署

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

限制

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

大多數系統呼叫都不允許。舉例來說，您無法讀取或寫入內部檔案系統。
透過通訊端存取網路。Apigee 會限制存取 sitelocal、anylocal、迴路和連結本機位址。
無法取得目前程序、程序清單或機器上 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 政策。