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

by 杉本和也 | February 22, 2021

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

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

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

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

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

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

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"
        }
    ]
}

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",
            "[email protected]": "コンサルタント",
            "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",
            "[email protected]": "パートナー",
            "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",
            "[email protected]": "顧客",
            "customertypecode": 3,
            "accountid": "a16b3f4b-1be7-e611-8101-e0071b6af231"
        }
    ]
}

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

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

docs.microsoft.com