Morning Girl

Web API, Windows, C#, .NET, Dynamics 365/CRM etc..

Dynamics 365 v9.0 新機能 仮想エンティティの使い方 その2 構成手順

前回、Dynamics 365 新機能の仮想エンティティについて、ざっくりとどんなものか紹介しました。

bit.ly

次は地味にちょっと面倒な、仮想エンティティの設定方法について書き留めたいと思います。

手順は大きく分けて3段階。

まずは、対象のODataサービスを準備すること。これはもともと存在すれば、特に準備は不要です。でも、ODataで準備するのって少し敷居が高いですよね。

その次に、対象の外部ODataサービスのエンドポイントやHTTPリクエストのベースをDynamics 365 に[Virtual Entity Data Source]として定義します。

最後に、[Virtual Entity Data Source]と紐付けた仮想エンティティをDynamics 365上で作成して、完了となります。

以下のようなイメージと捉えてもらえれば。

f:id:sugimomoto:20171119165111p:plain

Step1 対象のODataサービスの準備

今回は、OData公式サイトで提供されている、以下のエンドポイントを利用します。

http://services.odata.org/V4/OData/OData.svc/

で、さっそくですが、結構ODataの要件が厳しいです。詳細は以下を参照ですが

[OData v4 データ プロバイダーの構成、要件、ベスト プラクティス]

https://docs.microsoft.com/ja-jp/dynamics365/customer-engagement/customize/virtual-entity-odata-provider-requirements

特に注意しなければいけないのは、以下の項目。

Dynamics 365 では、すべてのエンティティが ID 属性を持つことが必要になります。この ID は一意の識別子として知られ、値は GUID にする必要があります。 ID フィールドは、EDM.Guid データ型の外部フィールドにのみマップできます。 Dynamics 365 では、EDM.Int32 データ型を uniqueidentifer データ型フィールドのマップする ことはできません。

ODataのフィールド項目の一つとして、必ずGUID、uniqueidentifer データ型の項目が必要です。むしろ、この項目が無いと仮想エンティティとして利用できません。

なので、今回はOData公式で公開されているテーブルの中でもGUIDをキーとして持っている[Advertisement]を対象とします。

metadataURLで一応中身を確認してみましょう。

http://services.odata.org/V4/OData/OData.svc/$metadata

f:id:sugimomoto:20171119165124p:plain

「Property Name="ID" Type="Edm.Guid" Nullable="false"/」 ←これ!

Step2 Virtual Entity Data Sourceの設定

対象のODataサービスが決まったら、URLなどの情報をDynamics 365側に登録します。

[Settings]→[Administration]から

f:id:sugimomoto:20171119165134p:plain

[Virtual Entity Data Source]を選択

f:id:sugimomoto:20171119165144p:plain

[+New]をクリックして、新しくデータソースを登録します。

f:id:sugimomoto:20171119165151p:plain

ポイントになるのはURLの部分。

今回対象となるテーブルは[Advertisement]で

Odata のベースURLは「http://services.odata.org/V4/OData/OData.svc

最終的なリクエストは「http://services.odata.org/V4/OData/OData.svc/Advertisements」となりますが、Advertisement(Advertisements)の部分はエンティティカスタマイズ側で定義するので

ここではURLの項目には「http://services.odata.org/V4/OData/OData.svc」だけ定義します。

f:id:sugimomoto:20171119165159p:plain

あと、下の方にリクエストを投げる際のHeaderやパラメータを付与する項目があります。

今回は公開されているODataのため、特に情報は指定しませんが、Headerで認証情報等を指定する際には、そこへ入力します。

Step3 仮想エンティティ用エンティティの設定

次にエンティティを作成します。

エンティティの作成での注意点は、以下の画像の赤枠2つ。

Virtual EntityのチェックをONにして、Datasourceに先程構成した「Virtual Entity Data Source」を指定します。

そして、ここでようやく「http://services.odata.org/V4/OData/OData.svc/Advertisements」の「Advertisements」を指定します。

今回のODataエンドポイントは複数形でレコードの一括取得を指定しているので、External Nameには「Advertisement」、External Collection Nameに「Advertisements」を指定します。対象のODataサービスが複数形を指定していない場合は、どちらも同じ名前にしてかまいません。

f:id:sugimomoto:20171119165207p:plain

次に大事なのがフィールドのプライマリーキー設定です。

フィールドのカスタマイズ画面に移動して、Primary Keyのフィールドを開きます。

f:id:sugimomoto:20171119165214p:plain

ここに空欄で[External Name]という項目がありますので、ここに対象テーブルでGUIDの項目になっているフィールド名を指定します。こうしないとデータが取得できませんので、要注意。

「Property Name="ID" Type="Edm.Guid" Nullable="false"/」 ←これ!

f:id:sugimomoto:20171119165224p:plain

あとは、他のフィールドも同じように作成し、External NameにODataのフィールドをマッピングさせていきます。

f:id:sugimomoto:20171119165233p:plain

これでカスタマイズを公開後、設定が正しければ、以下のような感じでデータが参照できるようになります。

f:id:sugimomoto:20171119165239p:plain

対象のODataサービスさえ、はっきりしていれば、結構気軽に試せる機能ではないでしょうか。

認証等がちと障害になりそうですが、是非活用してみたいところですね。

あと、一応トレーシングサービスをOnにすると、リクエストエラーなどが見えるっぽいです。

次回は私の会社で提供しているODataサービスを作成することができる「API Server」と組み合わせた作例を紹介したいと思います。

参考

Virtual Entities – Microsoft Lystavlen