OData V2 API の構築、実装、テスト

サンプル OData MySQL は、HTTP ベースのデータサービスを使用して MySQL データベースを照会する方法を示しています。

始める前に

APIkit で OData REST API を作成および使用するには、次のソフトウェアをインストールする必要があります。

  • OData プラグイン

  • Mule Runtime Engine 4.1.1 以降

  • Anypoint Studio 7.1.4 以降

また、OData のエンティティデータモデルのサンプルをダウンロードする必要があります。

APIkit OData 拡張を使用した OData v2 API の実装

次の例では、OData 対応 REST API の実装方法を示します。

  1. Studio で、​[File (ファイル)]​ > ​[New (新規)]​ > ​[Mule Project (Mule プロジェクト)]​ を選択します。

  2. [Project Name (プロジェクト名)]​ 項目で、Mule プロジェクトの名前を入力します。

  3. [Finish (完了)]​ をクリックします。

  4. 前提条件セクションでダウンロードした ​odata.raml​ ファイルをプロジェクトの ​/src/main/resources/api​ ディレクトリにコピーします。

  5. プロジェクトエクスプローラーで、​odata.raml​ を右クリックし、​[Mule]​ > ​[Generate OData API from RAML Types (RAML 型からの OData API の生成)]​ を選択します。

    ウィンドウで [Generate OData API from RAML Types (RAML 型からの OData API の生成)] オプションへのフルパスが強調表示されています
  6. OData 拡張は、OData API 実装に必要なファイルを生成します。

    Mule フォルダーの api.xml ファイル、リソースフォルダーの api.raml および odatalibrary.raml ファイルの 3 つのファイルがツリーで強調表示されています。
1 API 実装用のフローを含む Mule 設定ファイル
2 生成された RAML 定義
3 生成された RAML ライブラリ
  1. API 実装に必要なロジックをフローに追加します。

サンプル OData MySQL

サンプル OData MySQL は、Maven プロジェクトとしてパッケージ化された、完全に機能する OData API です。このサンプルでは、データソース、アプリケーション、およびサービスはローカルです。

まず、MySQL データベースをインストールし、提供されたスクリプトを使用してテーブルを読み込みます。次に、MySQL データベースドライバーを含む圧縮プロジェクトを Studio にインポートします。フローを調べて、データにアクセスすることで必要なエンドポイントを実装する方法を確認できます。次に、プロジェクトを実行して REST サービスと OData サービスをコールします。

MySQL データベースのインストールおよび入力

  1. MySQL データベースをインストールして、MySQL を起動します。

  2. MySQL プロジェクトサンプル (apikit-odata-example-main.jar) をダウンロードします。

  3. MySQL コマンドを使用して ​src/main/resources​ にある ​example.sql​ スクリプトを実行し、データを ​apikit-odata-example​ という名前のデータベースに読み込みます。

OData API の実装

  1. Studio で、​[File (ファイル)]​ > ​[Import (インポート)]​ を選択します。

  2. [Anypoint Studio]​ > ​[Packaged mule application (.jar) (パッケージ化された Mule アプリケーション (.jar))]​ > ​[Next (次へ)]​ を選択します。

  3. apikit-odata-example-main.jar​ ファイルを参照して、​[Finish (完了)]​ をクリックします。

  4. Studio で ​src/main/resources​ フォルダー内の ​mule-configuration.properties​ ファイルを編集し、次のプロパティを設定してローカル MySQL データベースにアクセスします。

    ds.db.port=3306
    ds.db.user=<your MySQL user name>
    ds.db.host=<your MySQL host name>
    ds.db.database=apikit-odata-example
    ds.db.password=<your MySQL password>
  5. プロジェクトを右クリックし、​[Run As (別のユーザーとして実行)]​ > ​[Mule Application (Mule アプリケーション)]​ を選択して、API をローカルで実行します。

これで、REST および OData サービスにアクセスできます。

REST および OData サービスへのアクセス

API をローカルで実行する手順は、次のとおりです。

  1. プロジェクトを右クリックし、​[Run As (別のユーザーとして実行)]​ > ​[Mule Application (Mule アプリケーション)]​ を選択します。

  2. 次の URL を使用して REST および OData サービスにアクセスします。

    • REST API: /api

    • OData API: /api/odata.svc

      次の例では、使用可能な多数の REST コールと OData クエリのうちのいくつかを示します。

顧客リストを取得する

顧客リストを取得する REST API をコールします。

http://localhost:8081/api/customers

応答は次のようになります。

{
  "entries": [
    {
      "ContactName": "Maria Anders",
      "ContactTitle": "Sales Representative",
      "CompanyName": "Alfreds Futterkiste",
      "CustomerID": ""
    },
    {
      "ContactName": "Maria Anders",
      "ContactTitle": "Sales Representative",
      "CompanyName": "Alfreds Futterkiste",
      "CustomerID": "ALFKI"
    },
  ]
}

OData サービスの記述にアクセスする

このサービスの背後にあるコレクションについての情報を取得します。

http://localhost:8081/api/odata.svc

応答は次のようになります。

<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xml:base="http://localhost:8081">
  <workspace>
    <atom:title>Default</atom:title>
    <collection href="customers">
      <atom:title>customers</atom:title>
    </collection>
    <collection href="orders">
      <atom:title>orders</atom:title>
    </collection>
  </workspace>
</service>

OData サービスメタデータを取得する

サービスメタデータは、OData サービスリソースの構造、その操作、および特定のサービスの EDM を公開します。

HTTP サービスのメタデータを取得します。

http://localhost:8081/api/odata.svc/$metadata

応答は、HTTP サービス API のサンプルをビルドするために使用した ​odata.raml​ EDM と同じです。

<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" Version="1.0">
<edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="2.0">
<Schema xmlns="http://schemas.microsoft.com/ado/2008/09/edm" Namespace="odata2.namespace">
<EntityType Name="customers">
<Key>
<PropertyRef Name="CustomerID"/>
</Key>
<Property Name="CompanyName" Type="Edm.String" Nullable="true" MaxLength="40" Unicode="false"/>
<Property Name="ContactName" Type="Edm.String" Nullable="true" MaxLength="30" Unicode="false"/>
<Property Name="ContactTitle" Type="Edm.String" Nullable="true" MaxLength="30" Unicode="false"/>
<Property Name="CustomerID" Type="Edm.String" Nullable="false" MaxLength="5" Unicode="false"/>
</EntityType>
<EntityType Name="orders">
<Key>
<PropertyRef Name="OrderID"/>
<PropertyRef Name="ShipName"/>
</Key>
<Property Name="Freight" Type="Edm.Decimal" Nullable="true" Precision="3" Scale="3" Unicode="false"/>
...

データソースを照会する

顧客リストを XML および JSON 形式で取得する OData クエリを発行します。

http://localhost:8081/api/odata.svc/customers
http://localhost:8081/api/odata.svc/customers?$format=json

顧客リスト内の 10 番目の顧客を取得する OData クエリを発行します。

http://localhost:8081/api/odata.svc/customers?$format=json&$top=1&$skip=10&$inlinecount=allpages

応答は次のようになります。

{
    "d": {
        "results": [
            {
                "__metadata": {
                    "uri": "http:/localhost:8081/api/odata.svc/customers('BOTTM')",
                    "type": "odata2.namespace.customers"
                },
                "CompanyName": "Bottom-Dollar Markets",
                "ContactName": "Elizabeth Lincoln",
                "ContactTitle": "Accounting Manager",
                "CustomerID": "BOTTM"
            }
        ],
        "__count": "98"
    }
}

OData API のエンドポイントの実装

Anypoint Studio を使用して、​get:/customers:config​ や ​get:/orders:config​ フローなどの API エンドポイントを実装できます。フローの出力形式は JSON である必要があります。詳細は、​完全な機能例​を参照してください。

GET 用の入力変数の宣言

  1. 文字列のリスト (List<String>) にエンティティの項目を含む APIkit OData サービス変数用の変数を宣言します。次に例を示します。

    var entityFields = vars.odata.fields
  2. 「http.query.params」に絞り込む APIkit OData サービス変数用の変数を宣言します。次に例を示します。

    var filters = attributes.queryParams
  3. エンティティのキーを含む APIkit OData サービス変数用の変数を宣言します。次に例を示します。

    var keys = vars.odata.keyNames
  4. テーブル名を含む APIkit OData サービス変数用の変数を宣言します。次に例を示します。

    var remoteEntityName = vars.odata.remoteEntityName

POST 用の入力変数の宣言

  1. エンティティの名前を含む APIkit OData サービスインバウンドプロパティ用の変数を宣言します。

    var remoteEntityName = vars.odata.remoteEntityName
  2. ペイロードを { myKey1: 'myValue1', myKey2: 'myValue2'} などに変換するための変数を宣言します。

    var valuesFromPayload = {
      keys: payload pluck $$,
      values: payload pluck "'$'"
    }
  3. 2 つの変数を宣言し、「joinBy」を使用してキーと値をカンマ区切り値 (CSV) に変換します。次に例を示します。

    var columns = ( (valuesFromPayload.keys map "`$`" ) joinBy ", ") // myKey1, myKey2
    var values = (valuesFromPayload.values joinBy ", ") // 'myValue1', 'myValue2'

出力の形式設定

各フローの出力は、次の形式にする必要があります。

{
  "entries":
  [
    {<entry1>},
    {<entry2>},
    {<entryN>}
  ]
}