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

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

Dynamics 365(Dynamics CRM) Web API レコード作成編

time 2017/06/12

みなさん、こんにちは。
昨晩テレビを見ていて、たまらずハンバーグを食べた Harada ですw
3つも食べるとお腹いっぱいになりましたwww(食い過ぎです・・・)

Dynamics 365になり組織サービス(SOAP)エンドポイントが廃止されることが予告されているので、以前ご紹介したWeb API の続編としてレコード作成編を書きたいと思います。入門編とレコード取得編は下記からどうぞ!

Dynamics 365 レコード作成の基本

レコードの作成には”POST”メソッドを使用します。一番難しいのは各データ型に対してどのように値を設定すればよいかだと思うので、ちゃちゃっと作ったサンプルでご説明しましょ~

var contact = {};
// 2つのオプション
contact["creditonhold"] = true;
// 顧客(検索)
contact["parentcustomerid_account@odata.bind"] = "/accounts(394BD9A2-3945-E711-8110-C4346BC53068)";
// 日付
contact["birthdate"] = "1980-2-1";
// 浮動小数点数
contact["address1_latitude"] = 47.639583;
// 複数行テキスト
contact["description"] = "Web API サンプル";
// 所有者(検索)
contact["ownerid@odata.bind"] = "/systemusers(22C23226-E74E-E711-8111-C4346BC53068)";;
// オプションセット
contact["accountrolecode"] = 2;
// 1行テキスト
contact["firstname"] = "名";
// 1行テキスト
contact["lastname"] = "姓";
var requestUrl = "https://<orgname>.crm7.dynamics.com/api/data/v8.2/contacts";
var req = new XMLHttpRequest();
req.open("POST", encodeURI(requestUrl), true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.onreadystatechange = function () {
    if (this.readyState == 4 /* complete */) {
        req.onreadystatechange = null;
        if (this.status == 204) {
            var contactUri = req.getResponseHeader("OData-EntityId");
            Xrm.Utility.alertDialog(contactUri, null);
        } else {
            var error = JSON.parse(this.response).error;
            Xrm.Utility.alertDialog(error.message, null);
        }
    }
};
req.send(JSON.stringify(contact));

それでは、簡単に説明します。

1行目~19行目
POSTするデータの作成です。
ここでのミソは検索フィールドです。”@odata.bind”というアノテーション(注釈)をつけて関連付けを行っているところです。正確にはナビゲーションプロパティ名@odata.bind という形でフィールド名を指定します。ナビゲーションプロパティ名はMSDNのEntityTypeを確認したり、Dynamics 365の開発者リソースよりCSDL(Conceptual Schema Definition Language)をダウンロードして確認したり、関連(Relationship)のメタデータで確認することができます。”@odata.bind”に指定する値は「エンティティセット名(レコードを特定するGUID)」となります。
※ 複数値ナビゲーションプロパティは指定できません。別途レコードの更新(関連付け)をする必要があります
20行目
アクセスするURLを作成しています。Web API のアドレスにエンティティセット名を指定した形式です。
22行目
ここにもミソがあります。レコード作成では必ず”POST”メソッドを指定します。
23行目~26行目
もうおまじないのようなものですが、リクエストヘッダを指定します。
39行目
Dynamics 365にレコードの作成を要求します。最初に作成したPOSTデータをJSON文字列に変換してsend メソッドに引き渡します。
30行目
成功時のHTTPステータスは”204(コンテンツなし)”が返却されます。
31行目
レコード作成されたGUIDがレスポンスヘッダの「OData-EntityId」に設定されます。これはURL形式なので、そのまま検索フィールドの値として利用することや、レコードの更新に使用することが可能です。

いかがでしょうか?特に難しい事はないですね。

Dynamics 365 レコード作成のその他の機能

基本的なレコード作成は上記の通りですが、その他にもできることがあります。

1回のリクエストで関連レコードの同時作成

ナビゲーションプロパティの値として定義することで、関連するエンティティを作成することができます。これをディープ挿入と言うそうです。基本的なレコード作成と同様に、「OData-EntityId」には、作成したエンティティの Uri が含まれています。作成された関連するエンティティの URI は返されません。先ほどの”parentcustomerid_account@odata.bind”で指定した所を下記のように変更します。

//contact["parentcustomerid_account@odata.bind"] = "/accounts(394BD9A2-3945-E711-8110-C4346BC53068)";
contact["parentcustomerid_account"] = { "name" : "サンプル企業" };

作成した結果のレコードを取得

作成されたレコードのデータは 201 (Created) のステータスで返されます。結果を取得するには、要求のヘッダーで return=representation の基本設定を使用する必要があります。

req.setRequestHeader("Prefer", "return=representation");

どのフィールドを取得するかを制御するには、$selectクエリオプションを URL に追加します。$expandクエリオプションは、使用すると無視されます。この場合、作成されたレコードへの URL を含む「OData-EntityId」は返されません。


レコード作成はいかがでしたでしょうか。SOAPエンドポイントが廃止される事が決まっていますので外部システムからの連携などではWeb API が必須となりますのでご参考にして頂ければ幸いです。

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

The following two tabs change content below.

Kengo Harada

CRM事業部 製品開発部 マネージャーアーティサン株式会社

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

<アーティサン株式会社 CRM製品>

CRM製品に関するお問い合わせ TEL 042-444-4815

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

down

コメントする