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

CRM リーディングカンパニーであるアーカス・ジャパン株式会社 CRM 事業本部 の最先端 CRM ブログです。

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

time 2016/10/03

みなさん、こんにちは。
自宅でファミレスの宅配ができる事に気付いて、テンション高めでメニューを選んでいた Harada ですw

前回は入門編ということで、Dynamics CRM Web API について書かせてもらいました。HTTP通信などが出てきて「結局どうやんね~ん!」って聞こえてきそうな感じでしたwww
ただ、前提として理解しとかないといけない事があるということをお分かりいただけたら大成功です!ドヤァ~!笑

さて、今回は実際にレコードの取得を行ってみようかと思います。前回、既存の組織サービスがSOAPを使用してメッセージをやり取りしていることを記載しましたが、Dynamics CRM Web API は OData(Open Data Protocol)を使用します。OData ってなに?ってなる方もいらっしゃると思いますが、簡単に言うとAPIを呼び出すための決め事です。実際にどのようにパラメータなどを指定すればいいかなどが定義されています。(GoogleのGDataと似たようなものです。個人的にはMicrosoft がパクったと思ってますwww)

それでは、サクッと試しにやってみましょ~!お付き合いの程よろしくお願いしま~す♪

Dynamics CRM レコード取得の基本

まずは、簡単にできる事からやってみようと思います。プログラムを確かめるときに気になるのは認証周りですよね?安心してください! Dynamics CRM に登録された Webリソースからアクセスする場合は何も考えることなく接続することが可能ですので、是非一緒に試してみてください。

主キーとなるGUIDを指定したレコードの取得

とりあえず、開いているフォーム上で自レコードを取得するというJavaScriptのサンプルを書いて説明します。

var entity = Xrm.Page.data.entity;
var recordUrl = Xrm.Utility.getEntityUrl(entity.getEntityName(), entity.getId());
var xhr = new XMLHttpRequest()
xhr.open("GET", encodeURI(recordUrl), true);
xhr.setRequestHeader('Accept', 'application/json');
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
xhr.setRequestHeader('OData-MaxVersion', '4.0');
xhr.setRequestHeader('OData-Version', '4.0');
xhr.setRequestHeader('Prefer', 'odata.include-annotations="*"');
xhr.onreadystatechange = function () {
    if (this.readyState == 4) {
        if (this.status == 200) {
            var data = JSON.parse(this.response);
            for (key in data) {
                console.log(key + ':' + data[key]);
            }
        }
        else {
            var error = JSON.parse(this.response).error;
            Xrm.Utility.alertDialog(error.message, function () { });
        }
    }
};
xhr.send();

それでは重要なところを説明しますね~!

1行目
開かれているフォームの entity オブジェクトを取得しているだけなので特に難しくないですね。
2行目
レコードのURLを取得しています。レコードのURLは下記の形式。
https://[orgName].crmX.dynamics.com/api/data/[version]/[entitySetName]([recordid])

orgName:組織名
version:実行されているDynamics CRM のバージョン(最新の場合は”v8.1″)
entitySetName:メタデータ(エンティティの定義情報)に”EntitySetName”として定義がある。(営業案件の場合は”opportunities”)
recordid:レコードを特定するGUID
3行目
HTTPメソッド(前回説明済み)の指定、上記で組み立てたURLを渡してます。encodeURI は日本語や記号などがあるとURLとして正しくなるようにしています。(今回でいうとGUIDを括っている”(“と”)”を”%XX”という形に変換しています)
4行目~8行目
ヘッダの設定(前回説明したHTTPヘッダです。)
9行目
HTTPヘッダによるodata.include-annotations を指定。

“OData.Community.Display.V1.FormattedValue”:画面に表示している形式でデータを取得
“Microsoft.Dynamics.CRM.associatednavigationproperty”:関連付けの名前を取得
“Microsoft.Dynamics.CRM.lookuplogicalname”:検索フィールドの関連エンティティ名を取得

上記3つを取得する”*”を指定しています。個々のannotation を指定することも可能です。

12行目
HTTPレスポンスに含まれるステータスが”200″(成功)かどうかを判定。
13行目
Web API は JSON 形式でレスポンスデータが返却されるため、parse メソッドを利用して JavaScript で扱い易いオブジェクトに変換しています。
14行目~16行目
返却されたデータの全ての列の値をコンソールに出力。

というようなソースコードになります。理解してもらえましたか?(わかってもらえてると信じてますw)

取得レコードへのアクセス

それでは実際に取得したレコードを抜粋してどのように取得できているかを確認したいと思います。

// 検索フィールド
"_campaignid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":campaignid
"_campaignid_value@Microsoft.Dynamics.CRM.lookuplogicalname":campaign
"_campaignid_value@OData.Community.Display.V1.FormattedValue":イベント キャンペーン テンプレート (サンプル)
"_campaignid_value":7de41e92-b97f-e611-80f0-b4b52f5357f8
// 顧客フィールド
"_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":customerid_account
"_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":account
"_customerid_value@OData.Community.Display.V1.FormattedValue":ファブリカム (サンプル)
"_customerid_value":69e41e92-b97f-e611-80f0-b4b52f5357f8
// 日付と時間(日付のみ)フィールド
"actualclosedate@OData.Community.Display.V1.FormattedValue":2016/09/21
"actualclosedate":2016-09-21
// 金額フィールド
"budgetamount@OData.Community.Display.V1.FormattedValue":¥30,000
"budgetamount:30000
// 2つのオプションフィールド
"captureproposalfeedback@OData.Community.Display.V1.FormattedValue":はい
"captureproposalfeedback":false
// オプションセットフィールド
"opportunityratingcode@OData.Community.Display.V1.FormattedValue":高
"opportunityratingcode":1
// 日付と時間フィールド
"createdon@OData.Community.Display.V1.FormattedValue":2016/09/21 14:10
"createdon":2016-09-21T05:10:24Z
// 1行テキストフィールド
"name":製品 SKU JJ202 の 6 個の受注 (サンプル)

注目すべき点は、検索・顧客フィールドで”_[fieldName]_value”という形式になっている点です。
“customerid”の場合 “_customerid_value” というフィールド名でアクセスします。
また、 “@~”はHTTPヘッダに追加したアノテーションにより返されていることが分かると思います。
“@OData.Community.Display.V1.FormattedValue”は、検索・顧客フィールドだけでなく、金額や2つのオプション、オプションセット、日付と時間でも使用されていることがお分かりいただけると思います。

今回はとっても基礎的なことでしたが、結構重要な事がたくさんあったと思うので、そろそろ終わりにします(笑)(書き疲れっていうのは内緒でww)

次回予告!

次回は取得列の指定や検索条件の指定などをやっていきま~す!お見逃しなく~m(_ _)m

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

The following two tabs change content below.

Kengo Harada

CRM事業本部 製品開発部 シニアマネージャーアーカス・ジャパン株式会社

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

<アーカス・ジャパン株式会社 CRM製品>

CRM製品に関するお問い合わせ TEL 06-6195-7501

メールでお問い合わせはこちら

down

コメントする




アーカイブ