Open Data Protocol (OData)

この記事では、Open Data Protocol (OData) に関する情報を提供し、OData V4 を使用して更新可能なビューを公開する方法について説明します。

OData とは

OData は、データを作成および消費するための標準プロトコルです。 OData の目的は、作成、読み取り、更新、削除 (CRUD) 操作のための Representational State Transfer (REST) に基づくプロトコルを提供することです。 OData は、さまざまなプログラムからの情報にアクセスするために、HTTP および JavaScript Object Notation (JSON) などの Web テクノロジーを適用します。 OData には次のメリットがあります。

• これにより、開発者は RESTful Web サービスを使用してデータを操作できます。
• これにより、見つけやすい方法でデータを共有する簡単で一貫した方法が提供されます。
• 製品を越えた広範な統合を有効にします。
• HTTP プロトコル スタックを使用して統合を有効にします。

OData の詳細については、次の Web ページを参照してください。

パブリック OData サービス エンドポイントにより、幅広いクライアントにわたって、一貫した方法でデータにアクセスできるようになります。 公開されているすべてのエンティティの一覧を表示するには、OData サービスのルート URLを開きます。 システムのサービス ルートの URL の形式は[お客様の組織のルート URL/data]/data

アドレス指定

次のテーブルでは、フリート管理サンプルのリソースと対応する URL を示しています。

OData サービス

OData REST エンドポイントを提供します。 このエンドポイントは、アプリケーション オブジェクト ツリー (AOT) の IsPublic としてマークされているすべてのデータ エンティティを公開します。 ユーザーがデータを挿入およびシステムから取得するために使用できる完全な CRUD (作成、取得、更新、および削除) 機能をサポートしています。 この機能の詳細なラボは、LCS の方法論に基づいています。

OData サービスを使用するためのコード例については、Microsoft Dynamics AX 統合 GitHub リポジトリを参照してください。

OData 仕様からサポートされている機能

OData 仕様 に従って、OData サービスで使用可能な上位レベルの機能は次のとおりです.

• CRUD サポートは、転記、パッチ、挿入、および削除の HTTP 動詞サポートにより処理されます。

• 利用可能なクエリ オプションは

  • $filter
  • $count
  • $orderby
  • $skip
  • $top
  • $expand (第 1 レベルの展開のみがサポートされます)
  • $select

• OData サービスでは、最大ページ サイズが 10,000 のサービス ドリブン ページングをサポートします。

詳細については、以下を参照してください: エンティティにバインドされている OData アクション

フィルター詳細

$filter には組み込みの演算子があります。

• 等しい (eq)
• 等しくない (ne)
• より大きい (gt)
• 等しい 、またはより大きい (ge)
• より小さい (lt)
• 等しい 、またはより小さい (le)
• かつ
• 又は
• ない
• 加算 (add)
• 減算 (sub)
• 乗算 (mul)
• 除算 (div)
• 小数点除算 (divby)
• 剰余 (mod)
• 優先順位のグループ化 ({ })

また、Contains オプションを $filter 要求とともに使用することができます。 これは、ワイルドカード文字として実装されています。 例: http://host/service/EntitySet?$filter=StringField eq '*retail*'

「持つ」 と 「含む」 の演算子には対応していません。

詳細については、「OData 演算子」を参照してください。

バッチ要求

OData サービスでは、バッチ要求がサポートされています。 詳細については、「OData バッチ要求」を参照してください。

メタデータの注釈

/data/$ メタデータは、注釈を提供します。 EnumType は、$metadata でサポートされます。

会社間動作

既定では、OData はユーザーの既定の会社に属しているデータのみを返します。 ユーザーの既定の会社以外のデータを表示するには、?cross-company=true クエリ オプションを指定します。 このオプションは、ユーザーがアクセスできるすべての会社のデータを返します。

例：http://[baseURI\]/data/FleetCustomers?cross-company=true

既定の会社ではない特定の会社ごとにフィルター処理するには、次の構文を使用します。

http://[baseURI\]/data/FleetCustomers?$filter=dataAreaId eq 'usrt'&cross-company=true

メソッドの検証

次のテーブルは、OData スタックが対応するデータ エンティティで暗黙的に呼び出す検証方法を示します。

OData エンティティを公開

OData エンティティは、更新可能なビューの概念に基づいています。 更新可能なビューの IsPublic プロパティが TRUE 設定されているとき、そのビューは最上位レベルの OData エンティティとして公開されます。

OData エンティティ間のナビゲーション プロパティの設定

OData エンティティ間のリンクは、ナビゲーション プロパティによって記述されます。 ナビゲーション プロパティでは、アソシエーションの一方から他方までのナビゲーションについて説明します。

OData エンティティでのアクションの追加

アクションで動作をデータ モデルに挿入できます。 アクションを追加するには、更新可能なビューにメソッドを追加し、そのメソッドを特定の属性で修飾します。 次に例を示します。

[SysODataActionAttribute("CalcMaintenanceDuration", true)]
public int CalculateMaintenanceDuration()
{
    //do something
    return 0;
}

この例では、SysODataActionAttribute クラスがアクションとして公開されている CalculateMaintenanceDuration メソッドを修飾します。 属性の最初の引数は公開されているアクションの名前で、2 番目の引数はこのアクションが常に利用可能かどうかを示します。 アクションとして公開されているメソッドは、任意のプリミティブ型または別のパブリックの更新可能なビューを返すことができます。 このメソッドが公開されると、OData $ メタデータに表示されます。 次に例を示します。

<Action Name="CalcMaintenanceDuration" IsBound="true">
    <Parameter Name="ViewMaintenance" Type="Microsoft.Dynamics.AX.Resources.ViewMaintenance"/>
    <ReturnType Type="Edm.String" />
</Action>

次の OData アクションの例では、パラメーターで取り、リストを返します。

[SysODataActionAttribute("GetColors", true),
    SysODataCollectionAttribute("return", Types::Record, "CarColor")]
public List GetColorsByAvailability(boolean onlyAvailableVehicles)
{
    List returnList = new List(Types::Record);
    // do something
    return returnList;
}

この例では、OData は SysODataCollectionAttribute クラスによって X++ から強く定型化されたコレクションを公開できます。 このクラスは次の 3 つのパラメーターを取ります。

• リストを示すパラメーターの名前 (メソッドの戻り値として return を返します)。
• この一覧のメンバーの X++ タイプ
• コレクションに含まれている OData リソースのパブリック名

これらのアクションが公開された後、サービス ルートの URL から呼び出すことができます。

ソース コード内の SysODataActionAttribute 属性を検索することにより、データ エンティティ上で定義されたアクションを見つけることができます。

OData エンドポイントの照会や参照

OData は、データベースに対して豊富なクエリを作成できる SQL に似た言語を有効にして、結果に希望するデータ項目のみが含まれるようにします。 クエリを作成するには、リソース パスに条件を追加します。 たとえば、ブラウザで次のクエリ オプションを加えることによって、顧客エンティティ コレクションのクエリを行うことができます。

OData プロトコルは、エンティティで多くの似たフィルター処理とクエリ オプションをサポートします。 クエリ オプションの完全なセットについては、Windows Communication Foundation を参照してください。

列挙型の使用

列挙型は、名前空間 Microsoft.Dynamics.DataEntities の下にあります。 OData クエリに列挙型を含めるには、次の構文を使用します。

Microsoft.Dynamics.DataEntities.Gender'Unknown'

Microsoft.Dynamics.DataEntities.NoYes'Yes'

上記の列挙型の値を使用したクエリの例を次に示します。

https://environment.cloud.onebox.dynamics.com/data/CustomersV3?\$filter=PersonGender eq Microsoft.Dynamics.DataEntities.Gender'Unknown'

https://environment.cloud.onebox.dynamics.com/data/Currencies?\$filter=ReferenceCurrencyForTriangulation eq Microsoft.Dynamics.DataEntities.NoYes'No'

列挙型に対応している演算子は eq と neです。

認証

OData は、サーバーと同じ認証スタック上に配置されます。 認証の詳細については、 サービス エンドポイントの概要 を参照してください。

ヒントや秘訣

1 つのトランザクションで複数の要求を実行

OData バッチ フレームワークは、変更セットを使用します。 各変更セットには、単一アトミック ユニットとして扱われるべき要求のリストが含まれています。 つまり、すべての要求が正常に実行されるか、要求が失敗した場合はすべての要求が正常に実行されません。 次の例は、単一の変更セット内に要求のリストを持つバッチ要求を送信する方法を示しています。

SaveChanges() の SaveChangesOptions.BatchWithSingleChangeset オプションを使用すると、単一の変更セットにすべての要求がバンドルされていることを保証できます。

public static void CreateProductColors(Resources context)
{
    var productColorsCollection = new DataServiceCollection<ProductColor>(context);

    var color1 = new ProductColor();
    productColorsCollection.Add(color);
    color1.ColorId = "New Color1"; // set any other properties needed

    var color2 = new ProductColor();
    productColorsCollection.Add(color1);
    color2.ColorId = "New Color2"; // set any other properties needed

    context.SaveChanges(SaveChangesOptions.BatchWithSingleChangeset);
}

OData クライアントを使用する場合に設定されていないレコードが転記されることを防止する

例 1 に示すように、OData クライアントを使用して新しいレコードを作成するときは、設定されていないプロパティが要求の本体に含まれ、既定値がそれらのプロパティに割り当てられます。 この動作を回避し、明示的に設定されたプロパティのみをポストするには、例 2 に示すように、SaveChanges() の SaveChangesOptions.PostOnlySetProperties オプションを使用します。

例1

public static void CreateVendor(Resources context)
{
    var vendorCollection = new DataServiceCollection<Vendor>(context);
    var vendor = new Vendor();
    vendorCollection.Add(vendor);
    // set properties
    context.SaveChanges();
}

例2

public static void CreateVendor(Resources context)
{
    var vendorCollection = new DataServiceCollection<Vendor>(context);
    var vendor = new Vendor();
    vendorCollection.Add(vendor);
    // set properties

    // Save specifying PostOnlySetProperties flag
    context.SaveChanges(SaveChangesOptions.PostOnlySetProperties);
}

メタデータ内の列挙とエンティティ間の重複する名前の処理

列挙とエンティティが同じ名前を共有する場合があります。 この名前の重複により、OData クライアント コードの生成エラーが発生します。 このエラーから回復するには、削除しなければならない重複する名前のインスタンスを識別するために GitHub のヘルパー コード を使用できます。 生成されたメタデータ ドキュメントは、クライアント側で OData ロジック のより詳細な処理をするために使用することができます。

配列フィールド

OData はエンティティで配列フィールドをサポートしていません。 OData で使用されるエンティティを設計するときにこれを考慮する必要があります。

AOS を再起動した後、最初の OData 呼び出しの処理に時間がかかることがあります

メタデータがキャッシュされていないために、再起動された AOS によって処理される最初の OData 呼び出しは処理に時間がかかる場合があります。 この待ち時間は、AOS 起動時に OData をウォーム アップすることで回避できます。 詳細については、AOS 起動時に OData メタデータ キャッシュを作成するを参照してください。