JavaSummary 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

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

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

時間

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

關於

您可以使用 JavaCallout 政策取得及設定流程變數、執行自訂邏輯和錯誤處理作業，以及從要求或回應中擷取資料等。這項政策可讓您導入任何其他標準 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" >

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

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

<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> 元素

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

您可以將此檔案儲存在 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 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

部署錯誤

部署含有政策的 Proxy 時，可能會發生這些錯誤。

錯誤變數

系統會在這項政策觸發錯誤時設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

錯誤回應範例

{  
   "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、anylocal、loopback 和 linklocal 位址。
• 呼叫無法取得目前程序、程序清單或機器上的 CPU/記憶體使用率相關資訊。雖然部分這類呼叫可能可運作，但系統不支援這類呼叫，且可能隨時主動停用。為確保向前相容性，請避免在程式碼中發出這類呼叫。
• 不支援依賴 Apigee 隨附的 Java 程式庫。這些程式庫僅供 Apigee 產品功能使用，且無法保證程式庫會在每個版本中提供。
• 請勿在 Java 說明文字中使用 io.apigee 或 com.apigee 做為套件名稱。這些名稱已保留，供其他 Apigee 模組使用。

包裝

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

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

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

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

Javadoc

如要編寫 Java 說明文字程式碼，請參閱 GitHub 上的說明文件。您必須將 HTML 複製或下載到系統，然後在瀏覽器中開啟 index.html 檔案即可。

使用注意事項和最佳做法

• 使用多個 JavaCallout 政策時，請考慮將常見的 JAR 上傳為環境範圍資源。與在相同環境中部署相同的 JAR 和多個 Proxy 套件相比，這種做法效率更高。
• 請勿將同一 JAR 檔案的多個副本或版本封裝並部署至環境。舉例來說，Apigee 建議您避免：
  • 將相同的 JAR 部署為 Proxy 套件的一部分，並做為環境資源。
  • 將一個版本的 JAR 檔案部署為環境資源，另一個版本則部署為 Proxy 套件的一部分。

  由於可能會發生 ClassLoader 衝突，因此部署相同 JAR 的多個副本可能會導致執行階段出現非確定性行為。

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