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