1. Homepage
  2. Connector DevKit (3.9)
  3. コネクタ機能の拡張

  4. DataSense の追加

DataSense の追加

DevKit は、Studio 6 および Mule 3 とのみ互換性があります。Mule 4 Connector を作成するには、 「Mule SDK」ドキュメント​を参照してください。

Mule DataSense には、サービスのエンティティのメタデータが表示されます。この機能は省略可能ですが、ユーザの実装を容易にするためにコネクタで DataSense を使用することを強くお勧めします。

devkit steps operations

前提条件

このドキュメントは、読者が ​Anypoint Connector DevKit​ によって提供されるコネクタアーキテクチャ、およびエンドユーザの観点からの ​DataSense​ に精通していることを前提としています。

DataSense を使用したコネクタ

インテグレーション開発者は多くの場合、Web サービスに渡したり Web サービスから返されたりするパラメータとデータ型を判断するためだけに多くの時間を費やします。これらのパラメータを確認するために各 API のドキュメントを調べる必要があるのは、効率が悪く、当てにならず、ストレスが溜まりがちです。DataSense を使用すれば、この情報は設計時に Anypoint Studio 内ですぐに確認できます。

DataSense はエンティティとその内部構造を Studio に提供し、Studio はコネクタを使用しているユーザにこの情報を表示します。DataSense は他の Anypoint Studio 機能と連携して次の処理も行います。

  • コネクタのメタデータにアクセスし、コンテキストが適切な場合に、Studio がコネクタから返される項目内の期待値をインテリジェントに提案できるようにする。

  • DataWeave の機能を使用して、マッピング内の入力データまたは出力データを自動的に推測する (DataSense 対応のコネクタと組み合わせて使用した場合)。

DataSense の基本的な利点​は、コネクタを介してアプリケーションによって公開されるデータモデルからメタデータを抽出できることです。​DataSense​ についての詳細を確認してください。

DataSense を実装する 2 つの重要なステップは、次のとおりです。

  1. メタデータ取得の設定​ – サービスからメタデータを取得し、この情報を提供するためのコネクタの実装を提供します。

  2. メタデータ認識の設定​ – Anypoint Studio が DataSense 実装を認識し、それに関する情報をコネクタのエンドユーザに提供するように、操作にアノテーションを付加する方法を定義します。

静的データモデル

コネクタは、そのエンティティを ​POJO​ として公開するときに、​静的データモデル​ (「強く型付けされた」データモデルとも呼ばれる) があるとみなされます。たとえば、特定のクラスのセットで SDK を使用する場合、これらが解決されてコンパイル時に認識されます。

この場合、メタデータ取得は簡単です。POJO エンティティクラス定義を参照し、イントロスペクションを使用して利用可能な Java で必要なすべてのメタデータを取得できます。認識は、プロセッサ内の強く型付けされたパラメータによってすでに暗示されています。

実例は、GitHub の Twitter Connector​ を確認してください。

静的メタデータ取得

静的メタデータを取得するには、コネクタから取得します。変更される可能性は低いため、Web サービスをコールして収集する必要はありません。代わりに、​コネクタに情報をハードコード​できます。

  1. コネクタクラス内で、​@MetaDataKeyRetriever​ のアノテーションを付加した新しいメソッドを追加します。

    @MetaDataKeyRetriever
    public List<MetaDataKey> getEntities() throws Exception {
        List<MetaDataKey> entities = new ArrayList<MetaDataKey>();
        entities.add(new DefaultMetaDataKey("Book_id","Book"));
        entities.add(new DefaultMetaDataKey("Author_id","Author"));
        entities.add(new DefaultMetaDataKey("BookList_id","BookList"));
        return entities;
    }

    このメソッドは、エンティティの名前のリストを返します。この場合、Book、Author、BookList の 3 つのキーを含むリストを取得します。

  2. @MetaDataRetriever​ メソッドを実装し、前の ​@MetaDataKeyRetriever​ メソッドによって返された各エンティティの記述を取得します。

    @MetaDataRetriever​ のアノテーションが付加された Java メソッドの戻り値のデータ型は ​MetaData ​である必要があり​、1 つの ​MetaDataKey​ パラメータを​受け取る必要があります​。

    この例では、サービスのエンティティクラスがローカルに存在することを前提としています。​Book.class​ および ​Author.class​ は、コード内で直接参照できます。DevKit によって提供されるインターフェース ​DefaultMetaDataBuilder​ をコールして、簡単に POJO を作成できます。

    @MetaDataRetriever
public MetaData describeEntity(MetaDataKey entityKey) throws Exception {
    //Here we describe the entity depending on the entity key
    if ("Author_id".equals(entityKey.getId())) {
        MetaDataModel authorModel =  new DefaultMetaDataBuilder().createPojo(Author.class).build();
        return new DefaultMetaData(authorModel);
    }
    if ("Book_id".equals(entityKey.getId())) {
        MetaDataModel bookModel =  new DefaultMetaDataBuilder().createPojo(Book.class).build();
        return new DefaultMetaData(bookModel);
    }
    if ("BookList_id".equals(entityKey.getId())) {
        MetaDataModel bookListModel =  new DefaultMetaDataBuilder().createList().ofPojo(Book.class).build();
        return new DefaultMetaData(bookListModel);
    }
    throw new RuntimeException(String.format("This entity %s is not supported",entityKey.getId()));
}

    このメソッドは、Book、BookList、および Author とそれらによって公開されるすべての公開項目を自動的に記述します。

外部サービスからメタデータを取得するには、​2 つの異なる操作​の使用が理想的です。

エンティティの取得に 1 つ、記述の取得に 1 つの、2 つの異なる操作を使用する理由は、​1 つのメソッドですべてのエンティティを記述すると、過剰な数の API コールが発生する可能性があるためです​ (おそらくエンティティごとに 1 つの API コールが必要になります)。

静的メタデータ認識

ここまでで、接続を目的とするサービス内のすべてのエンティティの記述メカニズムを実装しました。次に、この情報をメッセージプロセッサからアクセスできるようにします。

このメソッドは、​@MetaDataKeyParam​ のアノテーションが付加されたパラメータとして操作のデータ型を受け取ります。​@Default("#[payload]")​ としてアノテーションが付加されたパラメータで ​@MetaDataRetriever​ によって返されたエンティティデータも取得します。

このメソッドによって期待されるデータ型と生成されるデータ型は、メタデータが​静的​か​動的​かによって異なります。メタデータが​静的​の場合、エンティティデータは ​Object​ です。 
@Processor
public Object create(@MetaDataKeyParam(affects = MetaDataKeyParamAffectsType.BOTH) String entityType, @Default("#[payload]") Object entityData) {
    if (entityData instanceof Book) {
        return createBook((Book) entityData));
    }
    if (entityData instanceof Author) {
        return createAuthor((Author) entityData));
    }
    throw new RuntimeException("Entity not recognized");
}
private Object createAuthor(Author entityData) {
    //CODE FOR CREATING NEW AUTHOR GOES HERE
    return null;
}
private Object createBook(Book entityData) {
    //CODE FOR CREATING A NEW BOOK GOES HERE
    return null;
}
@Processor
public Object create(@MetaDataKeyParam String entityType, @Default("#[payload]") Object entityData) {
    }

出力メタデータは、Studio で選択されたエンティティ種別に応じて変わります。これは、DataMapper または DataWeave (Transform Message コンポーネント) と組み合わせて使用した場合に特に役立ちます。このメソッドにより、​@MetaDataRetriever​ によって返されるすべてのエンティティが Studio のドロップダウンに表示されます。

DSimage

また、エンティティに関するメタデータは、DataMapper または DataWeave (Transform Message コンポーネント) などの他の Mule 要素に渡すことができます。

image2

静的メタデータの使用例

次のセクションでは、静的データモデルを使用して Web サービスからデータを取得するコネクタの作成方法を示します。

この静的メタデータコネクタの完全な実例は、​ GitHub​ からダウンロードしてください。

この例では、コネクタはライブラリ Web サービスに接続します。この Web サービスには、​book​ と ​author​ の 2 種類の要素があります。

book​ 要素には次の項目があります。

  • title

  • synopsis

  • author

author​ 要素には次の項目があります。

  • firstName

  • lastName

動的データモデル

コネクタに動的データモデル (「弱く型付けされた」データモデルとも呼ばれる) がある場合、特定のメタデータ型はすぐには使用可能になりません。特定の ​MetaDataKey​ は、静的データモデルのようにコンパイル時ではなく、設計時または実行時に解決されるメタデータを表します。動的データモデルがあるコネクタの DataSense 機能をサポートするには、アプリケーションから提供されたデータに基づいてメタデータを作成する追加機能を実装する必要があります。

動的メタデータ取得

動的メタデータ取得では、コネクタによって参照される ​@MetaDataCategory​ の動的スキーマの DataSense メタデータを生成する、2 つのアノテーションが付加されたメタデータ関連メソッドを含める必要があります。

  • @MetaDataKeyRetriever​ は、接続されたサービスからすべてのエンティティ種別名のリストを取得する。

    @MetaDataKeyRetriever
public List<MetaDataKey> getMetadataKeys() {  }

  • @MetaDataRetriever​ は、メタデータのリスト (​@MetaDataKeyRetriever​ によって取得) を使用して、各エンティティ種別のエンティティ構成を取得する。

    @MetaDataRetriever
public MetaData getMetadata(MetaDataKey key) {  }

動的メタデータ認識

このステップでは、取得したメタデータをメッセージプロセッサからアクセスできるようにします。実装すると、Studio でのコネクタのプロパティエディタのドロップダウンには、​@MetaDataKeyRetriever​ によって返されたすべてのエンティティが表示され、各エンティティは ​@MetaDataRetriever​ によって返されたプロパティが結合されます。

DSimage

これを実現するには、エンティティ種別を ​@MetaDataKeyParam​ のアノテーションが付加されたパラメータとして受け取るメソッドをメッセージプロセッサに含める必要があります。このメソッドは、​@Payload​ または ​@Default ("#[payload]")​ としてアノテーションが付加されたパラメータで (​@MetaDataRetriever​ によって返された) エンティティデータを受け取る必要もあります。

メタデータが​動的​の場合、エンティティデータは ​Map<String,Object>​ です。

public Map<String,Object> create(@MetaDataKeyParam String entityType, @Default("#[payload]") Map<String,Object> entityData) {
    }

メタデータが​動的オブジェクト​の​リスト​の場合、エンティティデータは ​List<Map<String,Object>>​ です。

public List<Map<String,Object>> getList(@MetaDataKeyParam String entityType, @Default("#[payload]") List<Map<String,Object>> entityData) {
    }

動的メタデータの使用例

次のセクションでは、動的データモデルを使用して Web サービスからデータを取得するコネクタの作成方法を示します。メタデータを実装する最も実用的な方法は、常に動的に実装することです。こうすることで、接続するサービス内のエンティティの属性が経時的に変更される場合、コネクタはその変更に容易に適応します。

この動的メタデータコネクタの完全な実例は、​ GitHub​ からダウンロードしてください。

この例では、​静的モデルの例​と同様に、コネクタが接続する Web サービスは book データベースです。books と authors の 2 種類の要素があり、その両方に前の例と同じ項目があります。

コネクタの動的データモデルへの DataSense サポートの追加

コネクタに DataSense を実装するには、最初に ​@MetaDataCategory​ を作成し、​@MetaDataScope​ を使用してコネクタにバインドします。上記の動的データモデルセクションで繰り返されるこのウォークスルーに従ってください。

@MetaDataCategory および @MetaDataScope

DataSense リゾルバをグループ化するため、DevKit には Java クラスに適用できるアノテーション ​@MetaDataCategory​ が用意されています。この Java クラス内で、メタデータ取得メカニズム (​@MetaDataScope​ として ​@MetaDataKeyRetriever​ および ​@MetaDataRetriever​ のアノテーションが付加されたメソッド) を定義します。

たとえば、著者が書いた本を表す「books」という名前の Author エンティティのシークレット項目へのアクセス権を付与する追加の特別なメッセージプロセッサと共に、通常のメッセージプロセッサを提供するとします。メタデータカテゴリを使用して、複数の異なるメッセージプロセッサを 1 つのコネクタにまとめ、それぞれに異なるエンティティグループを表示できます。

下の例は、​@MetaDataKeyRetriever​ と ​@MetaDataRetriever​ の両方を含み、個別の Java ファイルに存在する ​@MetaDataCategory​ クラスを表示します。その後、アノテーションが付加されたメソッドを詳しく調べます。このクラスとコネクタモジュールの間にリンクを確立できます。これを行う最も一般的な方法は、次に示すように ​@Inject​ を使用してコネクタクラスを ​@MetaDataCategory​ クラスに挿入することです。

  1. @MetaDataCategory​ クラスを作成します。

    import org.mule.common.metadata.*;
import org.mule.common.metadata.builder.DefaultMetaDataBuilder;
import org.mule.common.metadata.builder.DynamicObjectBuilder;
import org.mule.common.metadata.datatype.DataType;

import org.mule.api.annotations.components.MetaDataCategory;
import org.mule.api.annotations.MetaDataKeyRetriever;
import org.mule.api.annotations.MetaDataRetriever;

@MetaDataCategory
public class DefaultCategory {

    @Inject
    private MyConnector myconnector;

    @MetaDataKeyRetriever
    public List<MetaDataKey> getEntities() throws Exception {
        //Here we generate the keys
    }

    @MetaDataRetriever
    public MetaData describeEntity(MetaDataKey entityKey) throws Exception {
        //Here we describe the entity depending on the entity key
    }
}

  2. インポートを確認します。

    • org.mule.common.metadata.*​ クラスには、メタデータの表現と管理を行う Mule クラスが含まれる。

    • org.mule.common.metadata.builder​ クラスは、メタデータ表現 (非常に複雑になる可能性があるオブジェクトのセット) を作成する。

    • org.mule.common.metadata.datatype.DataType​ クラスは、異なるオブジェクト項目のデータ型とそのプロパティを表す。

  3. @MetaDataScope​ を使用して、このカテゴリを ​@Connector​ または ​@Processor​ にバインドします。

    /**
 * DataSense-enabled Connector with multiple categories
 *
 * @author MuleSoft, inc.
 */
@MetaDataScope(DefaultCategory.class)
@Connector(name = "my-connector", minMuleVersion = "3.6")
public class MyConnector {
...

  @MetaDataScope(AdvancedCategory.class)
    @Processor
    public Map<String,Object> advancedOperation(@MetaDataKeyParam String entityType, @Default("#[payload]") Map<String,Object> entityData) {
       //Here you can use the books field in authors//
    }
}

動的メタデータ取得の実装

型構造を持つ POJO に直接アクセスすることはできないため、Web サービス自体からこの構造を取得する必要があります。​Map<String,Object>​ を使用して、動的エンティティを表します。

API コールを介してメタデータを動的に取得する場合、​@Connect​ メソッドは ​@MetaDataKeyRetriever​ メソッドの前に実行されます。これは、エンドユーザがメタデータへのアクセス権を取得する前に、接続の問題の解決が必要なことを意味します。

  1. コネクタクラス内で、​@MetaDataKeyRetriever​ のアノテーションが付加された新しいメソッドを追加します。(このメソッドは、静的メタデータを使用した実装と同じです。)

    @MetaDataKeyRetriever
    public List<MetaDataKey> getEntities() throws Exception {
        List<MetaDataKey> entities = new ArrayList<MetaDataKey>();
        entities.add(new DefaultMetaDataKey("Book_id","Book"));
        entities.add(new DefaultMetaDataKey("Author_id","Author"));
        entities.add(new DefaultMetaDataKey("BookList_id","BookList"));
        return entities;
    }

  2. @MetaDataRetriever​ メソッドを実装します。これは、前のメソッドによって返された各エンティティの記述を取得します。前の例と同様、このメソッドはインターフェース ​DefaultMetaDataBuilder​ を使用しますが、今回は POJO の代わりに動的オブジェクトを作成するためにコールされます。

    @MetaDataRetriever
public MetaData describeEntity(MetaDataKey entityKey) throws Exception {
    //Here we describe the entity depending on the entity key
    if ("Author_id".equals(entityKey.getId())) {
        MetaDataModel authorModel =  new DefaultMetaDataBuilder().createDynamicObject("Author")
                .addSimpleField("firstName", DataType.STRING)
                .addSimpleField("lastName", DataType.STRING)
                .build();
        return new DefaultMetaData(authorModel);
    }
    if ("Book_id".equals(entityKey.getId())) {
        MetaDataModel bookModel =  new   DefaultMetaDataBuilder().createDynamicObject("Book")
                .addSimpleField("title",DataType.STRING)
                .addSimpleField("synopsis",DataType.STRING)
                .addDynamicObjectField("author")
                .addSimpleField("firstName",DataType.STRING)
                .addSimpleField("lastName",DataType.STRING)
                .endDynamicObject()
                .build();
        return new DefaultMetaData(bookModel);
    }
    if ("BookList_id".equals(entityKey.getId())) {
        MetaDataModel bookListModel =  new DefaultMetaDataBuilder().createList().ofDynamicObject("book").build();
        return new DefaultMetaData(bookListModel);
    }
    throw new RuntimeException(String.format("This entity %s is not supported",entityKey.getId()));
}

動的メタデータ認識の実装

ここまでで、接続を目的とするサービス内のすべてのエンティティの記述メカニズムを実装しました。次に、この情報をメッセージプロセッサからアクセスできるようにする必要があります。

メッセージプロセッサは、​@MetaDataKeyParam​ のアノテーションが付加されたパラメータとして操作のデータ型を受け取る必要があります。(Studio では、​@MetaDataRetriever​ によって返されたすべてのエンティティを含む操作がドロップダウンに表示されます。)​@Default("#[payload]")​ としてアノテーションが付加された ​Map<String,Object>​ パラメータとして (​@MetaDataRetriever​ によって返された) エンティティデータを受け取る必要もあります。

@Processor
public Map<String,Object> create(@MetaDataKeyParam String entityType, @Default("#[payload]") Map<String,Object> entityData) {
    if ("Book_id".equals(entityType)) {
        return createBook(entityData);
    }
    if ("Author_id".equals(entityType)) {
        return createAuthor(entityData);
    }
    throw new RuntimeException("Entity not recognized");
}
private Map<String, Object> createAuthor(Map<String, Object> entityData) {
    //CODE TO CREATE BOOK GOES HERE
    return entityData;
}
private Map<String, Object> createBook(Map<String, Object> entityData) {
    //CODE TO CREATE AUTHOR GOES HERE
    return entityData;
}

このメソッドでは、ドロップダウンの項目として ​@MetaDataRetriever​ によって返されたすべてのエンティティが Studio に表示されます。

image3

また、エンティティに関するメタデータは、DataMapper または DataWeave (Transform Message コンポーネント) などの他の Mule 要素に渡すことができます。

image4

関連情報