Dynamics CRM Online 2015 Update 1 SDK 新機能: Upsert

みなさん、こんにちは。

Dynamics CRM Online 2015 Update 1 で提供されるプラット
フォームと SDK の新機能より、今回は Upsert を紹介します。
Upsert は代替えキーと連携して機能します。こちらの記事は
前回からの続きとなっているため以下の記事を前提とします。

Dynamics CRM Online 2015 Update 1 SDK 新機能: 代替えキー

概要

Upsert は Insert + Update の意味です。Upsert リクエストを
利用すると、既に存在するレコードは更新対象となり、まだ
存在しないレコードは作成対象となります。

レコードの存在確認は、代替えキーの値を利用します。よって
Upsert を利用するためには代替えキーの設定が必須です。

Upsert の利用

ここからは前回記事の操作の続きになります。

1. 前回作成したコンソールアプリケーションソリューションを
開きます。

2. 前回実装したコードのうち、組織サービスの作成以下を全て
コメントアウトします。

3. 以下のコードを追加します。代替えキーを指定した Entity
オブジェクトを作成し、UpsertRequest に渡しています。

Entity account = new Entity("account", "accountnumber", "UpsertTest");
account["name"] = "Upsert テスト取引先企業";
UpsertRequest request = new UpsertRequest()
{
    Target = account
};
UpsertResponse response = (UpsertResponse)service.Execute(request);

4. 以下のコードを追加して、レコードが作成されたか表示
するようにします。

if(response.RecordCreated)
    Console.WriteLine("レコードが作成されました");
else
    Console.WriteLine("レコードが更新されました");
Console.Read();

5. F5 キーを押下してプログラムを実行します。レコードが
作成されたことを確認します。

6. コードを変更せずに、再度プログラムを実行します。
レコードが更新対象と正しく認識されます。

より高度な使い方

Upsert と代替えキーで参照を指定することもできます。
今回は取引先企業の Upsert 時に、主取引先担当者を
指定します。

1. まず取引先担当者についても代替えキーを設定します。
今回は姓と名でキーとしました。

2. サンプルの取引先担当者を作成します。

3. 取引先企業のレコードの参照に渡す EntityReference を
作成します。代替えキーが複数ある場合は、以下のように
KeyAttributeCollection を利用します。

Entity account = new Entity("account", "accountnumber", "UpsertTest");
account["name"] = "Upsert テスト取引先企業";
// 取引先担当者の参照を追加
EntityReference contact = 
     ew EntityReference("contact",
    new KeyAttributeCollection { { "lastname", "サンプル" }, { "firstname", "担当者" } }
    );
account["primarycontactid"] = contact;

4. F5 キーを押下してプログラムを実行します。

5. レコードが更新されていることを確認します。

6. 新規作成時の挙動を検証するため、一旦取引先企業の
レコードを削除して、再度プログラムを実行します。
意図通りレコードが作成されることを確認します。

まとめ

Upsert を利用することで、他システム連携時のコードが
簡単に書けるだけでなく、読み取りと更新要求を別々に
送信していた時に比べて、Upsert 要求だけで良い事から
サーバーに対する要求数も削減でき、パフォーマンスの
向上も期待できます。 是非お試しください！

- 中村 憲一郎