Open Data Protocol (OData)

[アーティクル]
11/01/2024

この記事では、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 ページを参照してください。

トピック	Webpage
OData 標準	OData バージョン 4.01 のドキュメント
OData: Web、クラウド、モバイルデバイスなどのデータアクセス	ASP.NET Web API の OData

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

メモ

拡張機能を介して追加された OData アクションは、現在サポートされていません。

アドレス指定

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

リソース	URL	説明
サービスエンドポイント	[組織のルート URL]/data/	OData エンティティのルートサービスエンドポイント
エンティティコレクション	[組織のルート URL]/data/Customers	すべての顧客のコレクション
エンティティ	[組織のルート URL]/data/Customers("[キー]")	エンティティのコレクションから 1 つのエンティティ
ナビゲーションプロパティ	[組織のルート URL]/data/Customers("[キー]")/Reservations	顧客からその顧客の引当までのナビゲーション
プロパティ	[組織のルート URL]/data/Customers("[キー]")/FirstName	顧客の名

OData サービス

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

メモ

OData を使用してデータエンティティを操作する場合、OData 呼び出しを正常に実行するには、エンティティキーのすべてのフィールドを指定する必要があります。

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/$metadata は注釈を提供します。 EnumType は、$metadata でサポートされます。

EnumType メタデータ。

会社間動作

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

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

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

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

メソッドの検証

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

OData	メソッド (呼び出される順序で一覧表示されます)
新規	クリア () Initvalue() PropertyInfo.SetValue() 要求の指定されたすべてのフィールド Validatefield() Defaultrow Validatewrite() Write()
更新	Forupdate() Reread() クリア () Initvalue() PropertyInfo.SetValue() 要求の指定されたすべてのフィールド Validatefield() Defaultrow() Validatewrite() Write()
消去	Forupdate() Reread() checkRestrictedDeleteActions() Validatedelete() 削除 ()

OData エンティティを公開

OData エンティティは、更新可能なビューの概念に基づいています。更新可能なビューの IsPublic プロパティが TRUE 設定されているとき、そのビューは最上位レベルの 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 に似た言語を有効にして、結果に希望するデータ項目のみが含まれるようにします。クエリを作成するには、リソースパスに条件を追加します。たとえば、ブラウザで次のクエリオプションを加えることによって、顧客エンティティコレクションのクエリを行うことができます。

URL	説明
[組織のルート URL]/data/Customers	すべての顧客の一覧を表示します。
[組織のルート URL]/data/Customers?$top=3	最初の 3 つのレコードを一覧表示します。
[組織のルート URL]/data/Customers?$select=FirstName,LastName	すべての顧客の一覧を表示しますが、姓名のプロパティだけを表示します。
[組織のルート URL]/data/Customers?$format=json	JavaScript クライアントとやり取りするために使用できる JSON 形式ですべての顧客の一覧を表示します。

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 メタデータキャッシュを作成するを参照してください。

次の方法で共有

Open Data Protocol (OData)

OData とは

アドレス指定

OData サービス

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

フィルター詳細

バッチ要求

メタデータの注釈

会社間動作

メソッドの検証

OData エンティティを公開

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

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

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

列挙型の使用

認証

ヒントや秘訣

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

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

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

配列フィールド

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

フィードバック

その他のリソース

次の方法で共有

Open Data Protocol (OData)

OData とは

アドレス指定

OData サービス

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

フィルター詳細

バッチ要求

メタデータの注釈

会社間動作

メソッドの検証

OData エンティティを公開

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

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

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

列挙型の使用

認証

ヒントや秘訣

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

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

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

配列フィールド

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

フィードバック

その他のリソース

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