トピックス

知識創造研究室 by CRM(xRM)

Dynamics CRM Web API レコード取得編 Part.Ⅳ

吉野屋の牛すき鍋膳が大好きな Harada です!(美味しいんですよねぇ~)
最近の主食はケンタッキーフライドチキンの『よくばりパック』と吉野家の『牛すき鍋膳』と『牛丼 特盛 Cセット(キムチのセットです)』でホクホクな毎日です(笑)
さて、前回はシステムクエリオプションについて説明しました。
今回は、SQLでいうところの『結合』に近いものになります。$expandシステムクエリオプションを使用する方法をご説明します。
まずは、Dynamics CRM(Dynamics 365 の方が正しいのかなw)の肝となる検索フィールドと関連(1:N、N:1、N:N)についてからはじめます

関連と検索フィールドについて

関連には下記のように3種類用意されています。

1:N ⇒ One To Many
取引先企業と取引先担当者の関係になるんですが、ひとつの企業(1)には従業員が複数人(N)います。この関係がDynamics CRM では 1:Nの関連として表されています
N:1 ⇒ Many To One
1:Nと主になるのが反対だと思ってください。従業員が複数人(N)が所属する企業(1)はひとつの企業となります。この関係がDynamics CRM では N:1の関連として表されています
N:N ⇒ Many To Many
上記2つとは違い、マーケティングリストと取引先企業の関係になります。マーケティングリストとはターゲットリストなどアプローチ企業のリストを1週間に1回作る営業部署があったとすると1つのリスト(1)に複数の企業(N)という関係になります。ん?何か違和感を感じますね。企業側から見ると企業(N)に対してリスト(N)ひとつではないですね。こういう関係をDynamics CRM では N:Nの関連で表します。
※ 今回のテーマには関係がないのでN:Nについてはここまでにしておきます。

1:N、N:1の関連はどのように実現されているのかなんとなく想像つきましたか?そうなんです。これを実現しているのが検索フィールドなのです。検索フィールドがあるエンティティがN側になるのです。取引先企業(1)と取引先担当者(N)の場合は、取引先担当者の「会社名」という検索フィールドにより実現されています。

この関係を説明したのは$expand を使用する上で理解しておいて頂きたい前提知識となります。それでは、$expand を使用して2つのエンティティからレコードを取得してみたいと思います。

2つのエンティティからのレコード取得(N:1)

上記で説明した取引先担当者(N)と取引先企業(1)の関連を使用して取引先担当者の「氏名」と取引先企業の「取引先企業名」「売上高」を取得します。
この関連は取引先担当者の「会社名」という検索フィールドを使用して下記のURLでHTTPリクエストを行います。

[Web API URL]/contacts?$select=fullname,parentcustomerid_account&$expand=parentcustomerid_account($select=name,revenue)

ポイントは $select に「会社名」を指定し、$expand でその「会社名」を展開している点です。余談ですが、「会社名」の parentcustomerid_account は単一値ナビゲーションプロパティと呼ばれ、会社名が顧客フィールド(検索フィールドの特殊型)のためフィールド名の後ろに「_account」とエンティティを特定する文字列が追加されています。
参考までに実行結果を下記に載せておきます。

{
"@odata.context": "[Web API URL]/$metadata#contacts(fullname,parentcustomerid_account,parentcustomerid_account(name,revenue))", 
"value": [
    {
        "@odata.etag": "W/"588680"", 
        "contactid": "cfeb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "早川 諭 (サンプル)", 
        "parentcustomerid_account": {
            "_transactioncurrencyid_value": "aacdc623-0b9f-e611-80f5-c4346bc510bc", 
            "name": "フォース コーヒー (サンプル)", 
            "revenue": 100000.0
        }
    }, 
    {
        "@odata.etag": "W/"588686"", 
        "contactid": "d1eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "小原 すみ江 (サンプル)", 
        "parentcustomerid_account": {
            "_transactioncurrencyid_value": "aacdc623-0b9f-e611-80f5-c4346bc510bc", 
            "name": "リビングウェア (サンプル)", 
            "revenue": 20000.0
        }
    }, 
    {
        "@odata.etag": "W/"588692"", 
        "contactid": "d3eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "清岡 裕美子 (サンプル)", 
        "parentcustomerid_account": {
            "_transactioncurrencyid_value": "aacdc623-0b9f-e611-80f5-c4346bc510bc", 
            "name": "アドベンチャー ワークス (サンプル)", 
            "revenue": 60000.0
        }
    }
]
}

これがN:1の関連を使用した2つのエンティティからレコードを取得する方法です。

2つのエンティティからのレコード取得(1:N)

上記では取引先担当者に取引先企業を展開してレコードを取得しました。今度は取引先企業に取引先担当者を展開してレコードを取得します。この場合、検索フィールドは取引先担当者にあるので、1:Nの関連名を使用します。リクエストは下記の通りとなります。

[Web API URL]/accounts(79eb5f23-95ad-e611-80f6-c4346bc52044)?$select=name&$expand=contact_customer_accounts($select=fullname,emailaddress1)

$expand に関連名を指定し、取得したい取引先担当者のフィールドを指定します。注意点としては取引先担当者のGUIDを指定していない時は取引先担当者の内容は URL になり、「氏名」「電子メール」は取得できません。返却されたURLを使用して再度リクエストする必要があります。
また、先ほどの単一値ナビゲーションプロパティとは別に複数値ナビゲーションプロパティと呼ばれています。
今までと同様に、実行結果を下記に載せておきます

{ "@odata.context": "[Web API URL]/$metadata#accounts(name,contact_customer_accounts,contact_customer_accounts(fullname,emailaddress1))/$entity", "@odata.etag": "W/"589492"", "accountid": "79eb5f23-95ad-e611-80f6-c4346bc52044", "contact_customer_accounts": [ { "@odata.etag": "W/"588728"", "contactid": "dfeb5f23-95ad-e611-80f6-c4346bc52044", "emailaddress1": "someone_i@example.com", "fullname": "越安 辰夫 (サンプル)" }, { "@odata.etag": "W/"588746"", "contactid": "e5eb5f23-95ad-e611-80f6-c4346bc52044", "emailaddress1": "someone_l@example.com", "fullname": "金 起成 (サンプル)" } ], "name": "エー データム コーポレーション (サンプル)" }

2つのエンティティからのレコード取得(関連リンク)

続いては、N:1の関連を利用してフィールドを取得するのではなく、展開先のレコードURLを取得する方法を説明します。
関連リンクはURL形式で取得でき、そのURLを使用してレコードを取得することも可能なURLとなります。

[Web API URL]/contacts?$select=fullname,parentcustomerid_account&$expand=parentcustomerid_account/$ref

先ほどまで($select=name,revenue) としていた所を /$ref に変えました。結果は下記の通りです。

{
"@odata.context": "[Web API URL]/$metadata#contacts(fullname,parentcustomerid_account)", 
"value": [
    {
        "@odata.etag": "W/"584747"", 
        "_parentcustomerid_value": "f2ac16fd-c8a0-e611-80f5-c4346bc53068", 
        "contactid": "4cbab10f-d7a0-e611-80f5-c4346bc4ef58", 
        "fullname": "TEST0001 Taro", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(f2ac16fd-c8a0-e611-80f5-c4346bc53068)"
        }
    }, 
    {
        "@odata.etag": "W/"588680"", 
        "_parentcustomerid_value": "69eb5f23-95ad-e611-80f6-c4346bc52044", 
        "contactid": "cfeb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "早川 諭 (サンプル)", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(69eb5f23-95ad-e611-80f6-c4346bc52044)"
        }
    }, 
    {
        "@odata.etag": "W/"588686"", 
        "_parentcustomerid_value": "6beb5f23-95ad-e611-80f6-c4346bc52044", 
        "contactid": "d1eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "小原 すみ江 (サンプル)", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(6beb5f23-95ad-e611-80f6-c4346bc52044)"
        }
    }, 
    {
        "@odata.etag": "W/"588692"", 
        "_parentcustomerid_value": "6deb5f23-95ad-e611-80f6-c4346bc52044", 
        "contactid": "d3eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "清岡 裕美子 (サンプル)", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(6deb5f23-95ad-e611-80f6-c4346bc52044)"
        }
    }, 
    {
        "@odata.etag": "W/"588698"", 
        "_parentcustomerid_value": "6feb5f23-95ad-e611-80f6-c4346bc52044", 
        "contactid": "d5eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "佐々木 理恵 (サンプル)", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(6feb5f23-95ad-e611-80f6-c4346bc52044)"
        }
    }, 
    {
        "@odata.etag": "W/"588704"", 
        "_parentcustomerid_value": "71eb5f23-95ad-e611-80f6-c4346bc52044", 
        "contactid": "d7eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "佐本 久明 (サンプル)", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(71eb5f23-95ad-e611-80f6-c4346bc52044)"
        }
    }, 
    {
        "@odata.etag": "W/"588710"", 
        "_parentcustomerid_value": "73eb5f23-95ad-e611-80f6-c4346bc52044", 
        "contactid": "d9eb5f23-95ad-e611-80f6-c4346bc52044", 
        "fullname": "和辺 義隆 (サンプル)", 
        "parentcustomerid_account": {
            "@odata.id": "[Web API URL]/accounts(73eb5f23-95ad-e611-80f6-c4346bc52044)"
        }
    }
]
}

@odata.id というフィールドが返されている事がわかると思います。

4回にわたってレコード取得を行ってきましたが、いかがでしたでしょうか。レコードの取得方法は一通り説明したのですが、説明した以外にも取得方法があります。どの取得方法を選択すべきかなどは今後時間があれば書いていきたいと思います。

次回予告?

まだ何を書くか決めてません。Web APIをずっと書いているので少し脱線してみようかなとも考えています。何が書かれるかは楽しみにしていてくださ~いm(_ _)m

※ 記事の内容は個人発信の参考情報です。記事内容のご利用は、ご自身の判断でお願いします。

この記事を書いた人
原田 研吾

文系プログラマ(.NET Framework、Java)。
25歳から始めたプログラムは死ぬ気で頑張った(誰も褒めてくれないので自分で誉めてます)。
気が付けば製品開発部のマネージャー・・・
弊社Dynamics CRM トレーニングの講師をやったりもします。
事業部やら役職やらありますが、『事業部内の便利屋』が一番フィットする肩書です。
アーカス・ジャパン株式会社 CRM製品
CRM製品に関するお問い合わせ
TEL 06-6195-7501
お問い合わせはこちら

同じカテゴリの記事

Translate »