Dynamics 365(Dynamics CRM) Web API レコード作成編
みなさん、こんにちは。
昨晩テレビを見ていて、たまらずハンバーグを食べた 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 が必須となりますのでご参考にして頂ければ幸いです。
※ 記事の内容は個人発信の参考情報です。記事内容のご利用は、ご自身の判断でお願いします。