Flex Gateway新着情報
Governance新着情報
Monitoring API ManagerDevKit は、Studio 6 および Mule 3 とのみ互換性があります。Mule 4 Connector を作成するには、 「Mule SDK」ドキュメントを参照してください。 |
この例では、Java SDK を介して公開される API の Anypoint Connector の実装について説明します。このドキュメントのプロセスに従って、サービスの Java SDK ベースのコネクタをビルドします。
多くの場合、リモートサービスと統合するための最適なオプションは Java クライアントライブラリになります。クライアントライブラリがアプリケーションプロバイダで正式にサポートされている場合、または非公式でも広く使用されている場合、一般的なユースケースでアプリケーションと統合するベストプラクティスを実装できる可能性が高くなります。
このドキュメントは、読者が「Anypoint Connector DevKit」で説明されている Anypoint Connector のアーキテクチャに精通していることを前提としています。また、読者が「Anypoint Connector プロジェクトの作成」の手順に従って新しいコネクタプロジェクトを作成していることも前提としています。
SDK ベースのコネクタの全体的なアーキテクチャは次のようになります。
コネクタには、以下のコンポーネントがあります。
SDK - 認証方法とサポートされている操作を公開する Java SDK。「コネクタプロジェクトへの SDK の追加」を参照してください。
エンティティクラス - 通常、Java SDK で定義されているサポート対象データモデルエンティティクラス。
@Connector - DevKit で生成されるスケルトンに基づいて実装する @Connector
クラス
Java SDK は、一般的に RESTful または SOAP ベースの Web サービスと通信しますが、実際には必要なすべてのクライアントロジック (Java)、およびコネクタのクライアントレイヤをビルドする追加の作業や複雑さをカプセル化します。また、SDK は、管理しやすい Java ファサードの背後にある不適切な設計の Web サービスの標準以外の動作を隠すこともできます。
この説明のサンプルは、非公式だが広く使用されている twitter4j クライアントライブラリに基づく MuleSoft Twitter Connector です。 GitHub の Twitter Connector のソースコードは、説明セクションで使用および参照されます。
Twitter Connector は、DevKit 機能の多くの側面を示します。この説明の焦点は、SDK と 認証について、Twitter Connector は、
|
SDK の配信方法によっては、SDK をプロジェクトの Maven POM ファイルに追加できます。
たとえば、次のように Maven 中央リポジトリから Twitter4J を Maven 連動関係として追加できます。
<dependency>
<groupId>org.twitter4j</groupId>
<artifactId>twitter4j-core</artifactId>
<version>3.0.3</version>
</dependency>
認証は、@Connector
クラスと SDK の両方に実装されます。@Connector
クラスの認証の実装の詳細は、選択した認証スキームと SDK 認証サポートによって異なります。
「コネクタ属性の定義」の説明に従って @Connector
クラスの @Configurable
プロパティを追加したり、「コネクタ設定戦略」の説明に従って接続戦略を利用したりします。
たとえば、コネクタの接続ライフサイクルを SDK の接続メカニズムにバインドする必要があります。
ネイティブにサポートされている接続メカニズムを使用する場合、DevKit サポートを利用する必要があります。そうでない場合、Twitter と同様にハイブリッドアプローチを使用できます。Twitter Connector は、GitHub の TwitterConnector.java で定義されている興味深いハイブリッドアプローチを実装します。
Twitter4J クライアントライブラリは、Mule Connector が利用するその独自の OAuth サポートを実装します。
コネクタは、DevKit の OAuth サポートを使用しないため、DevKit の接続管理フレームワークを使用できます。
そのため、@OAuth
アノテーションのないクラス定義があります。
@Connector(name = "twitter", schemaVersion = "3.1", description = "Twitter Integration",
friendlyName = "Twitter", minMuleVersion = "3.6", connectivityTesting = ConnectivityTesting.DISABLED)
public class TwitterConnector implements MuleContextAware {
...
また、@ConnectionKey
が OAuth accessKey
に設定された @Connect
メソッド、および関連付けられている通常の @Disconnect
、@ValidateConnection
、@ConnectionIdentifier
メソッドもあります。
@Connect
public void connect(@ConnectionKey String accessKey, String accessSecret) throws ConnectionException{
ConfigurationBuilder cb = new ConfigurationBuilder();
cb.setUseSSL(useSSL);
cb.setHttpProxyHost(proxyHost);
cb.setHttpProxyPort(proxyPort);
cb.setHttpProxyUser(proxyUsername);
cb.setHttpProxyPassword(proxyPassword);
HttpClientHiddenConstructionArgument.setUseMule(true);
twitter = new TwitterFactory(cb.build()).getInstance();
twitter.setOAuthConsumer(consumerKey, consumerSecret);
if (accessKey != null) {
twitter.setOAuthAccessToken(new AccessToken(accessKey, accessSecret));
setAccessToken(accessKey);
setAccessTokenSecret(accessSecret);
}
}
...
@Disconnect
public void disconnect() {
twitter = null;
}
@ValidateConnection
public boolean validateConnection() {
return twitter != null;
}
@ConnectionIdentifier
public String getConnectionIdentifier() {
return getAccessToken() + "-" + getAccessTokenSecret();
}
一方、クラス twitter4j.Twitter
で公開される機能をコールしてアクセストークンの取得や管理などを行う OAuth 関連の機能を実装する一連の @Processor
メソッドもあります。
/**
* Set the OAuth verifier after it has been retrieved via requestAuthorization.
* The resulting access tokens log to the INFO level so the user can
* reuse them as part of the configuration in the future if desired.
* <p/>
* {@sample.xml ../../../doc/twitter-connector.xml.sample twitter:setOauthVerifier}
*
*
* @param requestToken request token from Twitter
* @param oauthVerifier The OAuth verifier code from Twitter.
* @return Twitter AccessToken info.
* @throws TwitterException when Twitter service or network is unavailable
*/
@Processor
public AccessToken setOauthVerifier(@Optional RequestToken requestToken, String oauthVerifier) throws TwitterException {
AccessToken accessToken;
if (requestToken != null) {
accessToken = twitter.getOAuthAccessToken(requestToken, oauthVerifier);
}
else {
accessToken = twitter.getOAuthAccessToken(oauthVerifier);
}
logger.info("Got OAuth access tokens. Access token:" + accessToken.getToken()
+ " Access token secret:" + accessToken.getTokenSecret());
return accessToken;
}
/**
* Start the OAuth request authorization process.
*/
@Processor
public RequestToken requestAuthorization(@Optional String callbackUrl) throws TwitterException {
RequestToken token = twitter.getOAuthRequestToken(callbackUrl);
return token;
}
...
public String getAccessToken() {
return accessToken;
}
public void setAccessToken(String accessToken) {
this.accessToken = accessToken;
}
public String getAccessTokenSecret() {
return accessTokenSecret;
}
public void setAccessTokenSecret(String accessTokenSecret) {
this.accessTokenSecret = accessTokenSecret;
}
実際に Twitter 操作をコールする @Processor メソッドは、@OAuthProtected アノテーションを使用しません。
@Processor
public User showUser() throws TwitterException {
return twitter.showUser(twitter.getId());
}
独自の OAuth サポートを提供するクライアントライブラリを使用する場合、このコードを掘り下げて、同じような実装パターンを使用することもできます。
この時点で、コネクタへの操作の追加を開始できます。
SDK では、次のような手順を実行して操作を追加します。
操作でパラメータまたは戻り値として使用される Java エンティティ SDK クラスやクライアントライブラリで発生する可能性のある例外をインポートする
クライアントインスタンスの操作をコールする @Connector
クラスの @Processor
メソッドを追加する
特定のクライアントクラスに応じて、認証を処理するために操作メソッドに認証機能を追加することが必要になる場合もあります。
テスト駆動型アプローチの適用 MuleSoft 環境では、コネクタの操作をビルドするときのテスト駆動型開発に似たサイクルに従うコネクタ実装プロジェクトが最も成功しています。
指定された操作の要件のすべてのシナリオをカバーするまで繰り返します。次に、コネクタの機能が完成するまで同じサイクルを使用して各操作を実装します。 SDK が適切に文書化されていると、操作の想定される動作が明確になり、対処するエッジケースや特定の例外的な状況の単体テストを削減できます。ただし、コネクタの信頼性は、ベースとなる SDK によって決まることに留意してください。 「いつ Studio でコネクタを試すのか?」と疑問に思うかもしれません。自動化された JUnit テストに加えて、進捗に従って手動で各操作をテストすることは効果的で好ましいことです。各操作をテストすると、以下を実現できます。
手動でテストすることで、コネクタの外観を仕上げたり、妥当なデフォルトで環境を改善したりする機会を得られます。 ただし、これによってテスト駆動型アプローチの価値が損なわれることはありません。多くのコネクタ開発プロジェクトでは、操作を定義するときにテストを定義する (事前作業は増える (ように見える) が、それだけの価値があり、より良い結果を迅速に得られる) ことができずに、行き詰まったり、使いにくいコネクタが生成されたりしてきました。 |
Twitter Connector は豊富な操作を実装します。次に、比較的単純な操作をいくつか示します。
/**
* Returns a single status, specified by the id parameter below. The status's
* author returns inline. <br>
* This method calls http://api.twitter.com/1.1/statuses/show
* <p/>
* {@sample.xml ../../../doc/twitter-connector.xml.sample twitter:showStatus}
*
* @param id the numerical ID of the status you're trying to retrieve
* @return a single {@link Status}
* @throws twitter4j.TwitterException when Twitter service or network is unavailable
* @see <a href="http://dev.twitter.com/doc/get/statuses/show/:id">GET
* statuses/show/:id | dev.twitter.com</a>
*/
@Processor
public Status showStatus(long id) throws TwitterException {
return twitter.showStatus(id);
}
/**
* Answers user information for the authenticated user
* <p/>
* {@sample.xml ../../../doc/twitter-connector.xml.sample twitter:showUser}
*
* @return a {@link User} object
* @throws TwitterException when Twitter service or network is unavailable
*/
@Processor
public User showUser() throws TwitterException {
return twitter.showUser(twitter.getId());
}
/**
* Search for places that can be attached to a statuses/update. Given a latitude
* and a longitude pair, or an IP address, this request returns a list of
* all valid places that can be used as the place_id when updating a status.
* <p/>
* {@sample.xml ../../../doc/twitter-connector.xml.sample twitter:searchPlaces}
*
* @param latitude latitude coordinate. Mandatory if no IP address is specified.
* @param longitude longitude coordinate.
* @param ip the IP. Mandatory if no coordinates are specified.
* @return a {@link ResponseList} of {@link Place}
* @throws TwitterException when Twitter service or network is unavailable
*/
@Processor
public ResponseList<Place>
searchPlaces(@Placement(group = "Coordinates") @Optional Double latitude,
@Placement(group = "Coordinates") @Optional Double longitude,
@Optional String ip) throws TwitterException {
return twitter.searchPlaces(createQuery(latitude, longitude, ip));
}
private GeoQuery createQuery(Double latitude, Double longitude, String ip) {
if (ip == null) {
return new GeoQuery(new GeoLocation(latitude, longitude));
}
return new GeoQuery(ip);
}
注意:
これらのすべての操作は、twitter
プロパティに保存されているクライアントインスタンスのメソッドをコールします。
@Optional、@Default、@Placement などのアノテーションは、コネクタの設定動作や Studio での外観を改善するために広く使用されています。
認証はすべて上記の Java クライアントと @Connector クラスのいくつかのメソッドで処理されるため、認証関連のコードは @Processor メソッドに含まれません。
各操作の JavaDoc には、サンプルコードファイルへのポインタが含まれます。
../../../doc/twitter-connector.xml.sample
DevKit では、通常の @param
および @return
コメントの他に、これらのコードサンプルを含める必要があります。提供するサンプルは、それらの操作に定義されているパラメータに対してチェックされます。各操作で必要なドキュメントの作成についての詳細は「コネクタリファレンスドキュメント」を参照してください。
各操作を定義するときに、それを利用する単体テストを作成する必要があります。DevKit Maven アーキタイプで作成されるプロジェクトスケルトンの場合、./src/test
に単体テストスイートディレクトリが含まれます。DevKit は、JUnit に基づいて単体テストフレームワークを定義します。
単体テストの作成についての詳細は、「DevKit Connector テストの開発」を参照してください。
さまざまなコネクタ実装種別を確認するだけであれば、「コネクタの属性と操作」や「データモデル」に戻り、事前ビルドされた SDK を使用せずに SOAP および RESTful Web サービスと直接通信するコネクタ実装を確認できます。
操作が含まれるコネクタの実装、ドキュメントの作成、スイートのテストが完了したら、次の作業を行うことができます。
「コネクタの開発」に戻り、そこに記載されている開発プロセスを続行する
「DevKit Connector テストの開発」の情報に基づいてテストスイートをビルドし、カバー率を改善する
「コネクタリファレンスドキュメント」の情報に基づいてドキュメントサンプルをビルドし、表示されるサンプルを増やす