JavaCallout ポリシー

概要

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

サポートされる Java のバージョンは、サポート対象のソフトウェアおよびサポート対象のバージョンをご覧ください。

時期

ガイドラインについては、Java Callout の作成方法の「Java Callout を使用すべき状況」をご覧ください。

説明

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

必要な 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>
デフォルト: なし
要否: 必須
型: String

<Property> 要素

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

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

属性

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

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

 なし 必須。

<ResourceURL> 要素

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

このファイルを API プロキシ スコープ（API プロキシ バンドルの /apiproxy/resources/java の下、あるいは API プロキシ エディタのナビゲーション パネルの [スクリプト] セクション）で、あるいは組織または環境スコープで格納して、複数の API プロキシ間で再使用できます。詳しくは、リソース ファイルの説明をご覧ください。

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

エラー リファレンス

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

ランタイム エラー

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

障害コード HTTP ステータス 原因 修正
steps.javacallout.ExecutionError 500 JavaCallout ポリシーの実行中に 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] 該当なし 障害文字列をご覧ください。サポートされている ソフトウェアとサポート対象バージョン。
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 Edge と一緒に含まれている Java ライブラリには依存できません。これらのライブラリは Edge プロダクトの機能のみを対象としています。また、すべてのリソースで利用できるとは限りません。
  • 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 ポリシーに実際のコードは含まれていません。代わりに、Java Callout ポリシーは Java のリソースを参照し、Java コードが実行される API フローにステップを定義します。Management UI のプロキシ エディタで Java JAR をアップロードするか、ローカルで開発している API プロキシの /resources/java ディレクトリにスクリプトを含めることができます。
  • リモート サービスに対する API 呼び出しなど、単純な操作には ServiceCallout ポリシーの使用をおすすめします。Service Callout ポリシーをご覧ください。
  • HTTP ヘッダー、パラメータ、メッセージ コンテンツの変更や抽出など、比較的単純なメッセージ コンテンツの操作には、JavaScript ポリシーの使用をおすすめします。

関連トピック