JavaCallout ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントはこちらをご覧ください。

ポリシー アイコン

内容

Java を使用すると、デフォルトの Apigee ポリシーに含まれていないカスタム動作を実装できます。Java コードでメッセージ プロパティ（ヘッダー、クエリ パラメータ、コンテンツ）とプロキシフローのフロー変数にアクセスできます。このポリシーを初めて使用する場合は、Java Callout の作成方法をご覧ください。

サポートされる Java のバージョンは、Oracle JDK 11 と OpenJDK 11 です。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

タイミング

ガイドラインについては、Java Callout の作成方法の「Java Callout を使用するタイミング」をご覧ください。

概要

Java Callout ポリシーを使用すると、フロー変数の取得と設定、カスタム ロジックの実行とエラー処理の実施、リクエストやレスポンスからのデータ抽出などを行うことができます。また、標準の Apigee ポリシーに含まれていないカスタム動作を実装することもできます。

必要な JAR パッケージ ファイルと Java アプリケーションをパッケージ化できます。ただし、Java Callout の使用には制限があります。制限事項に Java Callout の使用の制限について示しています。

サンプル

簡単な例

Java Callout の作成方法

Java コードのプロパティを取得する

ポリシーの <Property> 要素を使用すると、Java コードでランタイム時に取得できる名前と値のペアを指定できます。プロパティを使用する実際の例については、Java Callout のプロパティの使用方法をご覧ください。

<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 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

 なし 必須
continueOnError

ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目:

 false 省略可
enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

 true 省略可
async

この属性は非推奨となりました。

 false 非推奨

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>
デフォルト

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否 省略可
タイプ 文字列

<ClassName> 要素

Java Callout ポリシーで実行される Java クラスの名前を指定します。クラスは、<ResourceURL> で指定された JAR ファイルに含める必要があります。Java Callout の作成方法もご覧ください。

<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 コードからランタイム時にアクセスできるプロパティを指定します。各プロパティにリテラル文字列値を指定する必要があります。この要素ではフロー変数を参照できません。プロパティを使用する実際の例については、Java Callout のプロパティの使用方法をご覧ください。

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
デフォルト: なし
要否: 省略可
型: 文字列

属性

属性 説明 デフォルト 要否
name

プロパティの名前を指定します。

 なし 必須。

<ResourceURL> 要素

この要素には、Java Callout ポリシーで実行される Java JAR ファイルを指定します。

このファイルを、API プロキシ スコープ（API プロキシ バンドルの /apiproxy/resources/java または API プロキシ エディタの [Navigator] ペインの [Scripts] セクション）で、もしくは組織または環境スコープで保存して、複数の API プロキシ間で再利用できます。詳しくは、リソース ファイルをご覧ください。

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
デフォルト: なし
要否: 必須
型: 文字列

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 修正
steps.javacallout.ExecutionError 500 JavaCallout policy の実行中に Java コードが例外を出力するか null を返す場合に発生します。

デプロイエラー

これらのエラーは、ポリシーを含むプロキシがデプロイされているときに発生することがあります。

エラー名 障害文字列 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>

スキーマ

コンパイルとデプロイ

カスタム Java コードをコンパイルしてプロキシと一緒にデプロイする方法については、Java Callout の作成方法をご覧ください。

制限事項

Java Callout を作成する場合は、次の制限事項に注意してください。

  • システムコールの大部分は許可されません。たとえば、内部ファイル システムの読み込み、書き込みはできません。
  • ネットワークにはソケット経由でアクセスします。Apigee では sitelocal、anylocal、loopback、linklocal の各アドレスへのアクセスが制限されます。
  • Java Callout ではマシン上の現在のプロセス、プロセスリスト、CPU / メモリ使用率に関する情報を取得できません。このような呼び出しには機能するものもありますが、サポート対象外のため、無効化される可能性があります。上位互換性を維持するため、このような呼び出しはコード内に作成しないでください。
  • Apigee に含まれる Java ライブラリへの依存はサポートされていません。こうしたライブラリは Apigee プロダクトの機能専用であり、ライブラリがリリース間で使用できることが保証されているわけではありません。
  • Java Callout でパッケージ名として io.apigee または com.apigee を使用しないでください。これらの名前は予約されており、他の Apigee モジュールで使用されています。

パッケージ化

JAR を API プロキシの /resources/java の下に配置します。Java Callout が、独立した JAR ファイルとしてパッケージされた追加のライブラリに依存している場合は、実行時に正しく読み込まれるように /resources/java ディレクトリに配置します。

管理 UI を使用してプロキシを作成または変更している場合は、新しいリソースを追加し、追加の JAR 従属ファイルを指定します。複数の JAR がある場合は、追加リソースとして追加するだけで済みます。追加の JAR ファイルを参照するようにポリシーの構成を変更する必要はありません。/resources/java で指定するだけで十分です。

Java JAR のアップロードの詳細については、リソース ファイルをご覧ください。

Maven または javac を使用して、Java Callout をパッケージ化してデプロイする方法の詳細な例については、Java Callout の作成方法をご覧ください。

Javadoc

Java Callout コードを作成するための Javadoc は GitHub のこちらにあります。HTML のクローンを作成するか、システムにダウンロードしてから、ブラウザで index.html ファイルを開く必要があります。

使用上の注意とベスト プラクティス

  • 複数の Java Callout を使用して操作する場合は、共通の JAR を環境スコープのリソースとしてアップロードすることを検討してください。この手法は、同じ環境にデプロイする場合に、同じ JAR を複数のプロキシ バンドルとともにパッケージ化するよりも効率的です。
  • 同じ JAR ファイルの複数のコピーやバージョンをパッケージ化して環境にデプロイしないでください。たとえば、以下を避けることをおすすめします。
    • プロキシ バンドルの一部として、または環境リソースとして同じ JAR をデプロイする。
    • JAR ファイルの 1 つのバージョンを環境リソースとして、もう 1 つをプロキシ バンドルの一部としてデプロイする。

    同じ JAR の複数のコピーをデプロイすると、ClassLoader が競合する可能性があるため、実行時に非決定的な動作が発生する可能性があります。

  • Java Callout ポリシーに実際のコードは含まれていません。代わりに、Java Callout ポリシーは Java のリソースを参照し、Java コードが実行される API フローにステップを定義します。Management UI のプロキシ エディタで Java JAR をアップロードするか、ローカルで開発している API プロキシの /resources/java ディレクトリにスクリプトを含めることができます。
  • リモート サービスに対する API 呼び出しなど、単純な操作には、ServiceCallout ポリシーを使用することをおすすめします。ServiceCallout ポリシーをご覧ください。
  • HTTP ヘッダー、パラメータ、メッセージ コンテンツの変更や抽出など、比較的単純なメッセージ コンテンツの操作には、JavaScript ポリシーを使用することをおすすめします。