トピックス

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

Dynamics CRM 代替キーとUPSERT(API) のススメ 後編

みなさん、こんにちは。

前回はCREATE(API)を使用したレコード作成を説明しました。(ほほぉ~)
どうでしょうか?手間がかかる事がご理解いただけましたか?(どぉ!?)

今回は代替キーUPSERTを説明します(パチパチ パチパチ)

それでは張り切ってまいりましょ~♪

代替キー

代替キーとは

代替キー を使用すると、GUIDで行っていたレコードの特定をレコード内のフィールドの値で行う事が出来ます。たとえば、代替キーを使用して[取引先企業]レコードを識別するために、[取引先企業名]と[取引先企業番号]を使用して一意に識別することができます。
代替キーはコードを記述することなく、CRM?? のUIで代替キーを定義できます。もちろん、プログラムで定義することもできます。

代替キーの定義

代替キーの定義はカスタマイズエディターで行います。ここでは[取引先企業]に代替キーを定義します。
[システムのカスタマイズ] > [コンポーネント] > [エンティティ] > [取引先企業] > [キー] を選択し、[新規] を選択します。
下記のフォームで[表示名]、[名前]を入力し、キーに設定したいフィールドを選択します。
代替キーの定義
ここでは[代表電話]をキーにしています。(あとで使います)
※ 指定したキーに重複がある場合は作成処理に失敗します。

同じように取引先担当者に[電子メール]を代替キーととして登録しておきました。(CRM Online のサンプルデータは重複が存在するので、作成に失敗するのでお気を付けくださいw)
これで代替キーを使う準備が完了しました。次はUpsertを説明します。

Upsertを使用したデータ作成・更新

Upsertとは

Upsertは既にレコードが存在していたらレコード更新、存在しなければレコード作成を行います。(メッチャ便利やん♪)
SQL Server や Oracle でいうところのMERGE命令みたいなものですね。

それではUpsertと代替キーを使用して前回のデータを同じように作成/更新してみようと思います。

Entity オブジェクトの作成

今まではEntityオブジェクトのコンストラクタでエンティティ名を指定するのみでしたが、Dynamics CRM 2015 Update1 の SDK より、オーバーロードが追加されています。(知ってた?w)
下記のようにEntityのインスタンスを作成します。

var account = new Entity("account", "telephone1", "0x-123x-456x");

簡単ですよね?これを踏まえて実際にコードを書いてみます。

サンプルコードの作成

  1. [取引先企業]のデータを作成、または、更新(ループ変数があるのでややこしいかも・・・)
    // 電話を代替キーに指定してEntityのインスタンスを作成
    var telephone1 = string.Format("01-2345-67{0:00}", i + 1);
    var account = new Entity("account", "telephone1", telephone1);
    // 取引先企業名
    account["name"] = string.Format("Account{0:00}", i + 1);
    // メールアドレス
    account["emailaddress1"] = string.Format("some@account{0:00}.com", i + 1);
    // 住所1:都道府県
    account["address1_stateorprovince"] = "東京都";
    // 住所1:市区町村
    account["address1_city"] = "調布市";
    // 取引先企業作成(既に電話番号が存在する場合は更新)
    var request = new UpsertRequest() { Target = account };
    var response = service.Execute(request);
    
  2. 作成した[取引先企業]レコードの[電話] を使用して[取引先担当者]の[会社]に設定するEntityReferenceを作成
    // 代替キーを使用して取引先企業の参照のインスタンスを作成
    var accountReference = new EntityReference("account", "telephone1", telephone1);
    
  3. [取引先担当者]のデータ作成、または、更新(ここでもループ変数があるからややこしいかも・・・)
    // 電子メール
    var emailaddress1 = string.Format("contact{1:00}@account{0:00}.com", i + 1, j + 1);
    // 電子メールを代替キーに指定してEntityのインスタンスを作成
    Entity contact = new Entity("contact", "emailaddress1", emailaddress1);
    // 姓
    contact["lastname"] = string.Format(account["name"] + "-Contact{0:00}", j + 1);
    // 名
    contact["firstname"] = "John";
    // 勤務先電話番号
    contact["telephone1"] = string.Format("01-23{0:00}-67{1:00}", i + 1, j + 1);
    // 会社
    contact["parentcustomerid"] = accountReference;
    // 取引先担当者作成(既に電子メールが存在する場合は更新)
    request = new UpsertRequest() { Target = contact };
    response = service.Execute(request);
    

いかがですか?”GUID”が全く出てこなくなりましたね。この方法であれば外部システムからデータを連携したい場合に簡単に作れそうな気がしませんか?(するするw)
実際に動かした結果はこんな感じです。
アクティブな取引先担当者
ちゃんと会社名が入っていることが確認できると思います。

代替キーとUPSERTのススメ

今回はこちらで終了です。いかがでしたでしょうか。代替キーとUPSERTを使用することで、今まで「GUID」をどのように扱うかに頭を悩ませてた方にはインパクト抜群ではないでしょうか?(笑)
良ければ皆さんも試してみてください。

これからもこのような記事も掲載していこうと思っていますので、たまに覗いてみてくださいm(_ _)m

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

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

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

同じカテゴリの記事

Translate »