Dynamics 365・Dataverse(CDS) API で検索フィールドやオプションセットの表示名を取得する方法:CData Dynamics 365 / Dataverse Drivers

by 杉本和也 | 2021年02月22日

f:id:sugimomoto:20210222112524p:plain

こんにちは。CData Software Japanリードエンジニアの杉本です。

Dynamics 365 や Dataverse のAPIを使用している時によく躓くシチュエーションの一つが、検索フィールドやオプションセットフィールドの表示名を取得する方法だと思います。

そこで今回は、APIとしての使い方とCData Driverでの設定方法を合わせて紹介したいと思います。

API を使った通常の検索フィールド・オプションセットの取得方法

まずは普通に、取引先企業(Accounts)エンティティに存在する、検索フィールド「取引先責任者(primarycontactid)」とオプションセットの「関係内容(customertypecode)」の情報を取得してみましょう。

通常の画面だと、以下のようになっていて、この表示されている値を取得したいというのが、一般的なユースケースかと思います。

f:id:sugimomoto:20210222111853p:plain

APIでは、$selectのクエリパラメータで「_primarycontactid_value(検索フィールドの場合はこのように指定します)」と「customertypecode」を指定します。

GET /api/data/v9.0/accounts?$select=name,_primarycontactid_value,customertypecode&$top=3
Host: XXXX.crm7.dynamics.com
Authorization: Bearer XXXX

すると、以下のような結果が取得できます。_primarycontactid_valueにはGUID、customertypecodeではオプションセットのラベルではなく値が入力されていることがわかります。

{
    "@odata.context": "https://XXXX.crm7.dynamics.com/api/data/v9.0/$metadata#accounts(name,_primarycontactid_value,customertypecode)",
    "value": [
        {
            "@odata.etag": "W/\"5628346\"",
            "name": "CData Software Japan",
            "_primarycontactid_value": "6245baf7-af74-eb11-a812-000d3acf34e6",
            "customertypecode": 2,
            "accountid": "93c71621-bd9f-e711-8122-000d3a2ba2ea"
        },
        {
            "@odata.etag": "W/\"5628336\"",
            "name": "Blue Yonder Airlines",
            "_primarycontactid_value": "c7a2e5b9-88df-e311-b8e5-6c3be5a8b200",
            "customertypecode": 5,
            "accountid": "aca19cdd-88df-e311-b8e5-6c3be5a8b200"
        },
        {
            "@odata.etag": "W/\"5628342\"",
            "name": "エー データム コーポレーション",
            "_primarycontactid_value": "6245baf7-af74-eb11-a812-000d3acf34e6",
            "customertypecode": 3,
            "accountid": "a16b3f4b-1be7-e611-8101-e0071b6af231"
        }
    ]
}

f:id:sugimomoto:20210222111901p:plain

API を使った表示名の取得方法

対応方法としてはいくつか存在しますが、一番手軽な方法はリクエストヘッダーに「Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"」を指定する方法かなと思います。

docs.microsoft.com

GET /api/data/v9.0/accounts?$select=name,_primarycontactid_value,customertypecode&$top=3 
Host: XXXX.crm7.dynamics.com
Authorization: Bearer XXXX
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

これを指定することで、以下のように表示名を取得できるようになります。

{
    "@odata.context": "https://XXXXX.crm7.dynamics.com/api/data/v9.0/$metadata#accounts(name,_primarycontactid_value,customertypecode)",
    "value": [
        {
            "@odata.etag": "W/\"5628346\"",
            "name": "CData Software Japan",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "杉本 和也",
            "_primarycontactid_value": "6245baf7-af74-eb11-a812-000d3acf34e6",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "コンサルタント",
            "customertypecode": 2,
            "accountid": "93c71621-bd9f-e711-8122-000d3a2ba2ea"
        },
        {
            "@odata.etag": "W/\"5628336\"",
            "name": "Blue Yonder Airlines",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Glynn Jim",
            "_primarycontactid_value": "c7a2e5b9-88df-e311-b8e5-6c3be5a8b200",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "パートナー",
            "customertypecode": 5,
            "accountid": "aca19cdd-88df-e311-b8e5-6c3be5a8b200"
        },
        {
            "@odata.etag": "W/\"5628342\"",
            "name": "エー データム コーポレーション",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "杉本 和也",
            "_primarycontactid_value": "6245baf7-af74-eb11-a812-000d3acf34e6",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "顧客",
            "customertypecode": 3,
            "accountid": "a16b3f4b-1be7-e611-8101-e0071b6af231"
        }
    ]
}

「Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"」以外にも、expandクエリパラメータを利用する方法や、FetchXMLを使う方法もあります。

こちらの場合は、検索フィールドの表示名だけでなく、関連エンティティが持つ別なフィールドを表示したりもできます。ユースケースに合わせて検討すると良いでしょう。

docs.microsoft.com

docs.microsoft.com

CData Dynamics 365 / Dataverse Driversでの対処方法

それでは、CData Dynamics 365 / Dataverse Driver での対応方法です。

www.cdata.com

f:id:sugimomoto:20210222111910p:plain

デフォルトでは、APIと同様に取得結果にはGUIDやオプションセットの値しか含まれません。

そのため、以下のプロパティ「Include Formatted Values」をTrueにします。

cdn.cdata.com

f:id:sugimomoto:20210222111916p:plain

これで、以下のように値を表示できるようになります。

f:id:sugimomoto:20210222111922p:plain

関連コンテンツ

トライアル・お問い合わせ

30日間無償トライアルで、CData のリアルタイムデータ連携をフルにお試しいただけます。記事や製品についてのご質問があればお気軽にお問い合わせください。