次の方法で共有

代替キーを使用してレコードを作成

  • [アーティクル]

代替キーを使用して、Entity および EntityReference クラスのインスタンスを作成できます。 このトピックでは、使用パターンと、代替キー使用時にスローされる可能性のある例外について説明します。 エンティティに対して代替キーを定義する方法については、「エンティティの代替キーの定義」を参照してください。

エンティティを作成するための代替キーの使用

プライマリ ID または単一のKeyAttribute があれば、コンストラクターを使用して、1 回の呼び出しで、Entity を作成できます。

public Entity (string logicalName, Guid id) {…}    
public Entity (string logicalName, string keyName, object keyValue) {…}  
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}

更新操作に使用される有効な Entity には、エンティティの論理名と次のいずれかが含まれています。

  • ID の値 (主キーの GUID 値) (または)

  • そのエンティティに定義されているキーに一致する有効な属性セットを持つ KeyAttributeCollection。

EntityReference の作成に代替キーを使用

また、プライマリ ID がなくても、単一の KeyAttribute があれば、新しいコンストラクターを使用して、1 回の呼び出しで、EntityReference を作成することもできます。

public EntityReference(string logicalName, Guid id) {…}    
public EntityReference(string logicalName, string keyName, object keyValue) {…}    
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}

有効な EntityReference には、エンティティの論理名とつぎのいずれかが含まれています。

  • ID の値 (主キーの GUID 値) または、

  • そのエンティティに対して定義されているキーに一致する有効な属性セットを持つ KeyAttributeCollection コレクション。

メッセージへの代替入力

エンティティを CreateRequest および UpdateRequest に渡すとき、EntityReference を使用する検索属性のために提供された値は、EntityReference を KeyAttributes で定義された代替キーと共に使用して、関連レコードを指定することができるようになります。 これらは解決され、メッセージが処理される前にプライマリ ID ベースのエンティティ参照に置き換えられます。

代替キー使用時の例外

代替キーを使用するときは、以下のような条件と起こり得る例外に注意してください。

  • プライマリ ID が用意されている場合、プライマリ ID が使用されます。 用意されていない場合は、KeyAttributeCollection の確認が行われます。 KeyAttributeCollection が用意されていない場合は、エラーをスローします。

  • 用意された KeyAttributeCollection にエンティティの主キーである 1 つの属性が含まれていて、その値が有効である場合、その用意された値が Entity または EntityReference の ID プロパティに設定されます。

  • キーの属性が提供されている場合、提供された属性のセットと Entity に対して定義されているキーとの照合が試みられます。 一致が見つからない場合は、エラーがスローされます。 一致が検出された場合は、これらの属性に対して提供された値の有効性が確認されます。 有効な場合は、提供されたキー値に一致したレコードの ID が取得され、Entity または EntityReference の ID 値にこの値が設定されます。

  • 一意のキーとして定義されていない属性セットを指定する場合は、一意のキー属性の使用が必要であることを示すエラーがスローされます。

関連項目

エンティティの代替キーの定義
変更の追跡を使用してデータを外部システムに同期
Upsert を使用してレコードを挿入または更新