Dynamics 365 v9.0 新機能 仮想エンティティの使い方 その2 構成手順
前回、Dynamics 365 新機能の仮想エンティティについて、ざっくりとどんなものか紹介しました。
次は地味にちょっと面倒な、仮想エンティティの設定方法について書き留めたいと思います。
手順は大きく分けて3段階。
まずは、対象のODataサービスを準備すること。これはもともと存在すれば、特に準備は不要です。でも、ODataで準備するのって少し敷居が高いですよね。
その次に、対象の外部ODataサービスのエンドポイントやHTTPリクエストのベースをDynamics 365 に[Virtual Entity Data Source]として定義します。
最後に、[Virtual Entity Data Source]と紐付けた仮想エンティティをDynamics 365上で作成して、完了となります。
以下のようなイメージと捉えてもらえれば。
Step1 対象のODataサービスの準備
今回は、OData公式サイトで提供されている、以下のエンドポイントを利用します。
http://services.odata.org/V4/OData/OData.svc/
で、さっそくですが、結構ODataの要件が厳しいです。詳細は以下を参照ですが
[OData v4 データ プロバイダーの構成、要件、ベスト プラクティス]
特に注意しなければいけないのは、以下の項目。
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
「Property Name="ID" Type="Edm.Guid" Nullable="false"/」 ←これ！
Step2 Virtual Entity Data Sourceの設定
対象のODataサービスが決まったら、URLなどの情報をDynamics 365側に登録します。
[Settings]→[Administration]から
[Virtual Entity Data Source]を選択
[＋New]をクリックして、新しくデータソースを登録します。
ポイントになるのは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」だけ定義します。
あと、下の方にリクエストを投げる際の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サービスが複数形を指定していない場合は、どちらも同じ名前にしてかまいません。
次に大事なのがフィールドのプライマリーキー設定です。
フィールドのカスタマイズ画面に移動して、Primary Keyのフィールドを開きます。
ここに空欄で[External Name]という項目がありますので、ここに対象テーブルでGUIDの項目になっているフィールド名を指定します。こうしないとデータが取得できませんので、要注意。
「Property Name="ID" Type="Edm.Guid" Nullable="false"/」 ←これ！
あとは、他のフィールドも同じように作成し、External NameにODataのフィールドをマッピングさせていきます。
これでカスタマイズを公開後、設定が正しければ、以下のような感じでデータが参照できるようになります。
対象のODataサービスさえ、はっきりしていれば、結構気軽に試せる機能ではないでしょうか。
認証等がちと障害になりそうですが、是非活用してみたいところですね。
あと、一応トレーシングサービスをOnにすると、リクエストエラーなどが見えるっぽいです。
次回は私の会社で提供しているODataサービスを作成することができる「API Server」と組み合わせた作例を紹介したいと思います。
