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

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

Java コールアウトとは

Apigee には、セキュリティ、データ変換、トラフィック管理など、一般的な API 管理要件に対応するさまざまなポリシーがあります。

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

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

注: 重要: Java コールアウト ポリシーを作成する際は、Apigee JVM で有効となる権限ポリシーと、それらが作成するコードに及ぼす影響を知っておく必要があります。Java 権限のリファレンスをご覧ください。

プロキシで Java コードを使用する方法

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

Java コールアウトを使用するタイミング

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

最初に別のアプローチを検討する

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

• リモート サービスへの HTTP API 呼び出しなどの軽量オペレーションの場合は、ServiceCallout ポリシーの使用を検討してください。ServiceCallout ポリシーをご覧ください。
• HTTP ヘッダー、パラメータ、メッセージ コンテンツの変更や抽出など、比較的単純なメッセージ コンテンツの操作には、JavaScript や PythonScript ポリシーを使用できます。

Java コードでできること

Java コールアウトは、次の基本操作をサポートします。

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

Java コードでできないこと

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

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

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

Apigee に含まれる Java ライブラリを使用または依存しないでください。こうしたライブラリは Apigee プロダクトの機能専用であり、ライブラリがリリース間で使用できることが保証されているわけではありません。このようなライブラリは非本番環境のデモでのみ使用してください。

Hello Java コールアウト

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

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

  Hello, <name>!
  

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

  "Hello, Guest!"
  

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

簡便化のため、GitHub にある Apigee api-platform-samples リポジトリに基本プロジェクトが用意されています。

1. api-platform-samples をシステムにダウンロードするか、クローンを作成します。システムに api-platform-samples がすでにインストールされている場合は、pull を実行して、最新バージョンであることを確認します。
2. ターミナルまたは任意のコードエディタで api-platform-samples/doc-samples/java-hello プロジェクトに移動します。

Java コードを作成する

1. Java ソースファイル java-hello/callout/src/main/java/HelloJava.java を開きます。このファイルは、実装するメインの Java クラスのスケルトン バージョンです。インポートしたパッケージは Apigee Java コールアウト コードに必要です。これらのクラスには、プロキシ実行コンテキストにアクセスできるメソッドがあります。このコードをコンパイルしてデプロイする手順を説明します。
   

   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!");
   }
   

   注: MessageContext オブジェクトを使用すると、Java Callout ポリシーが実行されるフロー内のエンティティにアクセスできます。Java Callout ポリシーが Proxy Endpoint Response フローに接続されているとします。上記のコードは、このフロー コンテキストの HTTP Message オブジェクトを取得します。この Message オブジェクトを使用して、ヘッダー、クエリ パラメータ、本文コンテンツ、フロー変数にアクセスできます。
3. ファイルを保存します。

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

注: Git リポジトリにある POM ファイルと構成はサンプルです。Maven でコンパイルできますが、環境に合わせて調整が必要な場合があります。サンプルコードを変更する場合、Maven の構成も調整が必要になる可能性があります。

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

   mvn -version
   

2. 次のいずれかの方法で、必要な JAR 依存関係をローカルの Maven リポジトリにインストールします。
   • 次のスニペットを pom.xml ファイルに追加して、Artifact Registry から必要な JAR 依存関係をダウンロードします。

     <repositories>
       <repository>
         <id>artifact-registry</id>
         <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
       </repository>
     </repositories>
     
     <dependencies>
       <dependency>
         <groupId>com.apigee.gateway.libraries</groupId>
         <artifactId>message-flow</artifactId>
         <version>1.0.0</version>
         <scope>compile</scope>
         <type>jar</type>
       </dependency>
       <dependency>
         <groupId>com.apigee.infra.libraries</groupId>
         <artifactId>expressions</artifactId>
         <version>1.0.0</version>
         <scope>compile</scope>
         <type>jar</type>
       </dependency>
     </dependencies>

   • 次の curl 呼び出しを使用して、Artifact Registry から必要な JAR 依存関係をダウンロードします。

     curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar
             

     curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar
             

   • java-hello/buildsetup.sh スクリプトを実行します。このスクリプトにより、必要な JAR 依存関係が Apigee GitHub リポジトリからダウンロードされます。
3. cd で java-hello/callout ディレクトリに移動します。
4. Maven を実行します。
   
   

   mvn clean package
   

   注: Maven エラーが発生した場合は、現在のディレクトリが java-hello/callout ディレクトリであることを確認してください。
5. 必要であれば、JAR ファイル edge-custom-policy-java-hello.jar が java-hello/apiproxy/resources/java にコピーされていることも確認してください。これは、プロキシでデプロイする JAR ファイルに必要な場所です。

プロキシをデプロイして呼び出す

API プロキシをデプロイしてテストする手順は次のとおりです。

1. java-hello ディレクトリに移動します。
2. API プロキシ バンドルを ZIP ファイルにまとめます。

   zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
   

3. プロキシをデプロイする最も簡単な方法は、ZIP ファイルにバンドルし、Apigee 組織内の環境にプロキシ バンドルをアップロードすることです。API プロキシの作成をご覧ください。必ず [Upload Proxy Bundle] オプションを使用してください。Apigee コミュニティでプロキシ バンドルに API プロキシをアップロードするためのヒントもご覧ください。
4. プロキシがデプロイされたら、次のように呼び出してみてください。
   

   curl  https://$HOSTNAME/java-hello -H "username:Will"
   

   「Hello, Will!」と返されます。

プロキシについて

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

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 コールアウトについて知っておくべきこと

Java コールアウトの実装について注意が必要な事項は次のとおりです。

• 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 コールアウトのパッケージ名として io.apigee や com.apigee を使用しないでください。これらの名前は予約されており、他の Apigee モジュールで使用されています。
• Java コールアウトが、独立した JAR ファイルとしてパッケージされた追加のライブラリに依存している場合は、実行時に正しく読み込まれるように /resources/java ディレクトリに配置します。
• 複数の JAR がある場合は、追加リソースとして追加するだけで済みます。追加の JAR ファイルを参照するようにポリシー構成を変更する必要はありません。/resources/java で指定するだけで十分です。
• Java JAR のアップロードの詳細については、リソース ファイルをご覧ください。