JavaCallout ポリシー

概要

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

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

使用するタイミング

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

説明

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

必要な JAR パッケージ ファイルと Java アプリケーションをパッケージ化できます。ただし、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> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

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

属性

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

エラー リファレンス

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

ランタイム エラー

以下のエラーは、ポリシー実行時に発生する可能性があるものです。

障害コード 障害文字列 HTTP ステータス 発生する状況
javacallout.ExecutionError Failed to execute JavaCallout. [policy_name] 500 障害文字列をご覧ください。

デプロイエラー

以下のエラーは、ポリシーを含んだプロキシがデプロイされた場合に発生する可能性があります。

エラー名 障害文字列 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 Callouts でパッケージ名として io.apigee または com.apigee を使用しないでください。これらの名前は予約されており、他の Apigee モジュールで使用されています。

パッケージ化

API プロキシの JAR を /resources/java に配置します。Java Callout が独立した JAR ファイルとしてパッケージ化された追加のサードパーティ ライブラリに依存している場合は、それらの 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 フローにステップを定義します。Java JAR は、管理 UI プロキシ エディタからアップロードすることも、ローカルで開発する API プロキシの /resources/java ディレクトリに配置することもできます。
  • リモート サービスに対する API 呼び出しなど、単純な操作には ServiceCallout ポリシーの使用をおすすめします。Service Callout ポリシーをご覧ください。
  • HTTP ヘッダー、パラメータ、メッセージ コンテンツの変更や抽出など、比較的単純なメッセージ コンテンツの操作には、JavaScript ポリシーの使用をおすすめします。

関連トピック