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 リポジトリに基本的なプロジェクトが用意されています。
- システムに api-platform-samples をダウンロードするか、クローンを作成します。
- ターミナルまたは任意のコードエディタで
api-platform-samples/doc-samples/java-helloプロジェクトに移動します。
Java コードを作成する
- 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; } } } - コメント行
// 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!"); } - ファイルを保存します。
Maven でコードをコンパイルする
このプロジェクトは Maven でコンパイルできるように設定されています。javac を使用する方法については、Maven の例の後に説明します。
- Maven がインストールされていることを確認します。
mvn -version
java-hello/buildsetup.shスクリプトを実行します。このスクリプトにより、必要な JAR 依存関係がローカルの Maven リポジトリにインストールされます。- cd で
java-hello/calloutディレクトリに移動します。 - Maven を実行します。
mvn clean package
- 必要であれば、JAR ファイル
edge-custom-policy-java-hello.jarがjava-hello/apiproxy/resources/javaにコピーされていることも確認してください。これは、プロキシでデプロイする JAR ファイルに必要な場所です。
javac でコンパイルする（任意）
前のセクションでは、Maven のコマンドを使用して、必要な Java JAR ファイルを自動的に生成しました。javac でコードをコンパイルする場合は、java-hello ディレクトリから次の操作を行います。必要な JAR ファイルは、java-hello/lib ディレクトリに用意されています。
- cd で
api-platform-samples/doc-samples/java-helloに移動します。 - javac がパスに含まれていることを確認します。
javac -version
- 次の 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が作成されます。 - コンパイル済みのクラスを含む JAR ファイルを
apiproxy/resources/javaディレクトリにコピーします。プロキシでデプロイする JAR ファイルは必ずこの場所に置く必要があります。次のコマンドをjava-helloディレクトリで実行することでコピーできます。最後のピリオドまで忘れずに入力してください。
jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
プロキシをデプロイして呼び出す
デプロイ スクリプトは ./java-hello ディレクトリにあります。ただし、スクリプトを実行する前に、クイック設定を行う必要があります。
- cd で
api-platform-samples/doc-samples/java-helloに移動します。 ../../setup/setenv.shファイルをまだ編集していない場合は、このファイルを開いて、Apigee アカウント情報に合わせてユーザー名（アカウントに関連付けられたメールアドレス）、組織名、API 管理呼び出しを行うために使用するドメインを編集します。たとえば、Edge Cloud の場合、ドメインはhttps://api.enterprise.apigee.comですが、Edge Private Cloud を使用している場合はドメインが異なる可能性があります。setenv.shファイルを保存します。- deploy スクリプトを実行します。
./deploy.sh
- デプロイが成功したら、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 メッセージ ポリシーは、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 ファイルに含める必要があります。Management UI のプロキシ エディタで Java JAR をアップロードするか、ローカルで開発している API プロキシの/resources/javaディレクトリにスクリプトを含めることができます。- Execution インターフェースを実装します。API プロキシ内で実行される Java コードはすべて、Execution を実装する必要があります。
- Java Callout ポリシーに実際のコードは含まれていません。代わりに、Java Callout ポリシーは Java「リソース」を参照します。このリソースは JAR にパッケージ化する必要があります。
- 避けるべきパッケージ名: Java Callout のパッケージ名として io.apigee や com.apigee を使用しないでください。これらの名前は予約されており、他の Apigee モジュールで使用されています。
- Java Callout が、独立した JAR ファイルとしてパッケージされた追加のライブラリに依存している場合は、実行時に正しく読み込まれるように
/resources/javaディレクトリに配置します。 - 複数の JAR がある場合は、追加リソースとして追加するだけで済みます。追加の JAR ファイルを参照するようにポリシー構成を変更する必要はありません。
/resources/javaに配置するだけで十分です。 - Java JAR のアップロードの詳細については、リソース ファイルをご覧ください。