今回は Common Data Service (CDS) でカスタムエンティティを作成した際に設定するプライマリーフィールドと、一意識別子、およびキーについて紹介します。
プライマリーフィールドとは
カスタムエンティティ作成時には、表示名や名前と合わせて、プライマリーフィールドを指定します。
プライマリーフィールドはレコードの特徴を表すためのフィールドであり、データベースにおける「キー」とは異なります。
以下に代表的な既定のエンティティのプライマリーフィールドと値を見てみましょう。
エンティティ (プライマリーフィールド) |
値 |
---|---|
取引先企業(取引先企業名) | アドベンチャー ワークス |
アルパイン スキー ハウス | |
コントソ製薬 | |
取引先担当者(氏名) | 越安 辰夫 |
加須 紀夫 | |
タスク(件名) | 顧客との予定をスケジュールすること |
評価計画の合意済み |
プライマリフィールドは通常の文字列フィールドであるため、値の重複もできます。
一意識別子
システムフィールドである GUID 型の一意識別子は、通常「エンティティの論理名+id」で作成され、データベースのキーとなります。一度アサインされたら変更は不可で、エンティティのみでなくシステムで一意です。
他のレコードから参照される場合など、こちらの GUID が使われます。また SDK や Web API でデータを一意に特定する際にも利用できます。
キー
キーは 2 つの役目を果たします。
- 値の一意を保証
- SDK や Web API でレコードを指定して取得することが可能
複数のフィールドを含めることができますが、システムとして一意性が重要である場合にのみ利用してください。重複を避けたい場合は「重複データ検出」を使うことができます。
開発者観点でのキー
SDK や Web API でレコードを取得する際、一意識別子が分からない場合は、たとえ電子メールアドレスなどエンティティで一意である値を使ってレコードを取得する時でも複数レコードの検索が行われ、戻り値もリストになります。
しかしシステム連携などでは CDS 側のレコード GUID を別途保持していないため、通常は電子メールアドレスなどを使ってレコードを検索することになります。電子メールアドレスをキーにすることで、以下のようにクエリを書け、戻り値として単体レコードを取得することができます。
[Organization URI]/api/data/v9.0/contacts(emailaddress1='abc@example.com')
まとめ
プライマリーフィールドはキーではないため、レコードの特性を表すものを設定し、キーが必要な場合は別途作成してください。また各レコードで重複を避けたいが柔軟に処理したい場合は、重複検出を使ってください。
動作についての考察は、CDSのエンティティのキーを設定する が良くまとまっていますので、是非ご覧ください。