Java コールアウトの作成方法

Java Callout とは

Apigee Edge は、セキュリティ、データ変換、トラフィック管理などの一般的な API 管理要件に対応するさまざまなポリシーを提供しています。

ただし、標準のポリシーでは実装されないカスタムの動作が API で必要になる場合もあります。このような場合、Apigee には、カスタマイズされた API の動作のスクリプトやコードの作成を可能にするオプションが備わっています。アプローチの 1 つは、Java で必要な動作を実装することです。

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

プロキシで Java コードを使用するには

Java Callout ポリシーを使用すると、実行中のプロキシフロー内から Java コードを呼び出すことができます。Java コードには、コードと実行中のプロキシとのインタラクションを可能にする特定の Edge 固有の Java インターフェースを実装する必要があります。たとえば、プロキシの現在のフロー コンテキスト内でヘッダー、クエリ パラメータ、フロー変数、その他のエンティティを取得して設定するための Java メソッドなどがあります。

Java Callout を使用すべき状況

Java Callout が有益である状況と他のアプローチを検討すべき状況を考えてみましょう。

まず、代替アプローチを検討する

Java Callout を使用する前に、その代わりに使用できる代替アプローチが存在する可能性があることに注意します。次に例を示します。

  • リモート サービスに対する HTTP API 呼び出しなどの単純な操作には、ServiceCallout ポリシーの使用を検討します。Service Callout ポリシーをご覧ください。
  • HTTP ヘッダー、パラメータ、メッセージ コンテンツの変更や抽出など、比較的単純なメッセージ コンテンツの操作には、JavaScript や Python 言語を使用できます。

Java コードで実行できること

Java Callout は、次の基本操作をサポートします。

  • リクエスト メッセージやレスポンス メッセージの調査や操作。
  • フロー変数の取得と設定。Java メソッドを使用して Edge フロー変数にアクセスできます。Key-Value マップ(KVM)情報へのアクセスが必要な場合は、KVM ポリシーを使用し、KVM 値をフロー変数に割り当てることで Java Callout 内からフロー変数にアクセスできます。
  • 外部サービスの呼び出し。
  • 障害発生。
  • エラー メッセージとステータス コードの操作。

Java コードで実行できないこと

システムコールの大部分は許可されません。以下の操作を行うことはできません

  • 内部ファイル システムの読み取りや書き込みの実行。つまり、Java パッケージを使用して内部ファイル システムの読み取り / 書き込みを行うことはできません。ただし、外部のリモート呼び出しは可能です。
  • マシン上の現在のプロセス、プロセスリスト、CPU / メモリ使用率に関する情報の取得。
  • 「expressions-1.0.0.jar」と「message-flow-1.0.0.jar」内のソースコードへのアクセス。

このような呼び出しには機能するものもありますが、サポート対象外のため、常に無効にしておく必要があります。コード内でこのような呼び出しを行わないでください。

Apigee Edge に付属する Java ライブラリを使用したり、それに依存したりしないでください。これらのライブラリは Edge プロダクトの機能のみを対象としており、すべてのリリースで利用できるという保証はありません。この種のライブラリを使用する場合は、非本番のデモ環境でのみ使用してください。

Java Callout の例

Java Callout の基本使用例を見てみましょう。この例では、「hello world」レスポンスを返す Java Callout を含む単純なプロキシを作成します。このプロキシでは、使用可能な 2 つのレスポンスからいずれか 1 つを返します。

  • 「username」ヘッダーで「name」値を渡した場合は、プロキシから以下が返されます。

        Hello, <name>!
        
  • ヘッダーを省略すると、プロキシから以下のように返されます。

        "Hello, Guest!"
        

スターター プロジェクトをダウンロードする

気軽にご使用いただくため、GitHub にある Apigee api-platform-samples リポジトリに基本的なプロジェクトを用意しています。

  1. api-platform-samples をシステムにダウンロードするか、クローンを作成します。
  2. 任意のデバイスまたはコードエディタで、api-platform-samples/doc-samples/java-hello プロジェクトに移動します。

Java コードを作成する

  1. Java ソースファイル java-hello/callout/src/main/java/HelloJava.java を開きます。このファイルは、実装するメインの Java クラスのスケルトン バージョンです。Edge Java Callout コードにはインポート版のパッケージが必要です。これらのクラスでは、プロキシ実行コンテキストへのアクセスを可能にするメソッドが提供されます。このコードを簡潔にコンパイルしてデプロイする手順を説明します。
        package com.apigeesample;
    
        import com.apigee.flow.execution.ExecutionContext;
        import com.apigee.flow.execution.ExecutionResult;
        import com.apigee.flow.execution.spi.Execution;
        import com.apigee.flow.message.MessageContext;
    
        public class HelloJava implements Execution {
    
                public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
    
                        try {
    
                                // Your code here.
    
                    return ExecutionResult.SUCCESS;
    
                        } catch (Exception e) {
                                return ExecutionResult.ABORT;
                        }
                }
    
        }
        
  2. コメント行 // Your code here を次のコードに置き換えます。

        String name = messageContext.getMessage().getHeader("username");
    
        if (name != null && name.length()>0) {
                messageContext.getMessage().setContent("Hello, " + name + "!");
                messageContext.getMessage().removeHeader("username");
        } else {
                messageContext.getMessage().setContent("Hello, Guest!");
        }
        
  3. ファイルを保存します。


Maven でコードをコンパイルする

このプロジェクトは Maven でコンパイルできるように設定されています。javac の使用については、Maven のサンプルの後にそのサンプルを紹介しています。

  1. Maven がインストールされていることを確認してください。

        mvn -version
        
  2. スクリプト java-hello/buildsetup.sh を実行します。このスクリプトにより、必要な JAR 依存関係がローカルの Maven リポジトリにインストールされます。
  3. cd で java-hello/callout ディレクトリに移動します。
  4. Maven を実行します。

        mvn clean package
        
  5. 必要であれば、JAR ファイル edge-custom-policy-java-hello.jarjava-hello/apiproxy/resources/java にコピーされていることを確認します。これは、プロキシでデプロイする JAR ファイルに必要な場所です。

javac でのコンパイル(任意)

前のセクションでは、Maven のコマンドを使用して、必要な Java JAR ファイルを自動的に生成しました。一方、コードのコンパイルに javac を使用したい場合には、java-hello ディレクトリから次のような手順で行うこともできます。必要な JAR ファイルは、java-hello/lib ディレクトリに用意されています。

  1. cd で api-platform-samples/doc-samples/java-hello に移動します。
  2. javac がパスに含まれていることを確認します。

        javac -version
        
  3. 次の javac コマンドを実行します。

        javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
        
    これにより com/apigeesample/HelloJava.class が生成されます。
  4. コンパイル済みのクラスを含んだ JAR ファイルを apiproxy/resources/java ディレクトリにコピーします。プロキシでデプロイする JAR ファイルは必ずこの場所に置く必要があります。次のコマンドを java-hello ディレクトリで実行することでコピーできます。最後のピリオドまで忘れずに入力してください。

        jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
        

プロキシのデプロイと呼び出し

deploy スクリプトは ./java-hello ディレクトリにあります。ただし、スクリプトを実行する前に、クイック設定を行う必要があります。

  1. cd で api-platform-samples/doc-samples/java-hello に移動します。
  2. ../../setup/setenv.sh をまだ編集していない場合はこのファイルを開いて、ユーザー名(アカウントに関連付けられたメールアドレス)、組織名、API 管理呼び出しを行うために使用するドメインを、Apigee アカウント情報に従って編集します。たとえば、Edge クラウドの場合、ドメインは https://api.enterprise.apigee.com です。ただし、Edge Private Cloud を使用している場合は、ドメインが異なる場合があります。
  3. setenv.sh ファイルを保存します。
  4. deploy スクリプトを実行します。

        ./deploy.sh
        
  5. デプロイが正常に完了したら、invoke スクリプトを実行します。

        ./invoke.sh
        

    invoke スクリプトによって次のような cURL コマンドが呼び出されます。

        curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
        

    このコマンドでは「Hello, Will!」が返されます。

    invoke.sh スクリプトを編集して名前を変更できます。また、cURL 呼び出しを変更してヘッダーを削除した場合は、「Hello, Guest!」と返されます。

プロキシについて

このプロキシで使用されているポリシーを簡単に確認しましょう。ポリシーが配置されているプロキシフロー内の場所と、そこに配置されている理由に注意します。

Assign Message ポリシー

Assign Message ポリシーは、ProxyEndpoint のリクエスト フローに添付されます。このポリシーは、リクエストからユーザー名ヘッダーをコピーしてレスポンスに割り当てます。このオペレーションにより、レスポンス フローに添付されている Java Callout ポリシーは、ユーザー名ヘッダーにアクセスして、そのヘッダーの値を使用してカスタムのレスポンス本文を構築できます。

    <AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
        <DisplayName>CopyHeader</DisplayName>
        <Copy source="request">
            <Headers>
              <Header name="username"/>
            </Headers>
        </Copy>
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
        <AssignTo createNew="false" transport="http" type="response"/>
    </AssignMessage>
    

Java Callout ポリシー

Java Callout ポリシーはレスポンス フローに添付されます。これは、カスタムの Java コードがレスポンスのヘッダーとメッセージを変更するためです。このポリシーの ClassName 要素によって、ポリシーで実行されるメインクラスが指定されます。ResourceURL 要素は、構築してプロキシの resources/java ディレクトリに追加された JAR ファイルの名前です。

    <JavaCallout name="hello-java">
        <ClassName>com.apigeesample.HelloJava</ClassName>
        <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
    </JavaCallout>
    

Java Callout について知っておくべきこと

Java Callout の実装について注意が必要な事項は次のとおりです。

  • クラスは、com.apigee.flow.execution パッケージと com.apigee.flow.message パッケージからインポートします。これらのパッケージは、パッケージしてデプロイする JAR ファイルに含める必要があります。Java JAR は、管理 UI プロキシ エディタからアップロードすることも、ローカルで開発する API プロキシの /resources/java ディレクトリに含めることもできます。
  • Execution インターフェースを実装します。API プロキシ内で実行される Java コードはすべて、Execution を実装する必要があります。
  • Java Callout ポリシーに実際のコードは含まれていません。代わりに、Java Callout ポリシーは Java「リソース」を参照します。このリソースは JAR にパッケージ化する必要があります。
  • 回避すべきパッケージ名: io.apigeecom.apigee を、Java Callout のパッケージ名として使用しないでください。これらの名前は予約されており、他の Apigee モジュールで使用されています。
  • Java Callout が独立した JAR ファイルとしてパッケージ化された追加のサードパーティ ライブラリに依存している場合は、それらの JAR ファイルも /resources/java ディレクトリに配置して、ランタイムに正しく読み込まれるように保証します。
  • 複数の JAR がある場合は、追加リソースとして追加するだけで済みます。追加の JAR ファイルを参照するようにポリシー構成を変更する必要はありません。対象のファイルを /resources/java に配置するだけで十分です。
  • Java JAR のアップロードの詳細については、リソース ファイルをご覧ください。