代替キーを使用してレコードを参照

Dataverse レコードの主キー値が分からない場合は、データ投稿で代替キーを使いデータ操作を操作します。 定義されているテーブルに対してのみ、代替キーを使用できます。 ほとんどの Dataverse テーブルには、代替キーを含めるようにカスタマイズされていない限り、代替キーはありません。

テーブルの代替キーを定義および特定する方法については、次の記事を参照してください。

• Power Apps を使用する: 行を参照する代替キーの定義
• コードを使用する: 代替キーに関する作業

Dataverse Web API または .NET 用 SDK を使い、代替キーを使用できます。

Web API

Web APIを使用する場合は、URL を使用して特定のレコードを参照し、POST、PATCH または DELETE Http メソッドを使用してデータ操作を実行します。 また、URL を使用し、@odata.bind 構文を使用する単一値ナビゲーション プロパティに対して、または関数およびアクションのパラメーターとして値を設定します。

次の表に、相対 URL を使用してレコードを参照する方法を示す例を示します。

状況	例
主キーを使用する	/accounts(00000000-0000-0000-0000-000000000001) または accounts(accountid=00000000-0000-0000-0000-000000000001) systemuser および team エンティティ タイプについては、次の注記を参照
単一の代替キーを使用する	/accounts(accountnumber='ABC123')
マルチパートである代替キーを使用する	/contacts(firstname='Joe',emailaddress1='abc@example.com')
検索列を使用する 代替キーを使用する	/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000002) 検索列に代替キーが定義されている場合、対応する検索プロパティの名前を使用する必要があります。 検索プロパティは、次の名前付け規則に従います: _<name of single-valued navigation property>_value。

注意

systemuser および team エンティティ型が principal エンティティ型から継承される方法により、名前の付いた主キーを使用してこれらのエンティティを参照することはできません。 これらのエンティティの両方の主キーは systemuserid または teamid ではなく、owneridです。 principal エンティティ型は、GET 操作をサポートしていません。 詳細: EntityType の継承

Web API を用いた代替キー使用時の例外

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

• 一意のキーとして定義されていない列を指定する場合は、一意のキー列の使用が必要であることを示すエラーがスローされます。 エラー メッセージは、The key in the request URI is not valid for resource 'Microsoft.Dynamics.CRM.<table logical name>'. Ensure that the names and number of key properties match the declared or alternate key properties for the resource 'Microsoft.Dynamics.CRM.<table logical name>'. です
• 次の文字 /、<、>、*、%、&、:、\\、?、+ を含む代替キーバリューは、現在サポートされていません。

詳細: 代替キーを使用してレコードを取得する

.NET 用 SDK

.NET 用 SDK を使用する場合、代替キーを使用するには 2 つの方法があります。

Entity クラスを使用する

エンティティ クラス のインスタンスを作成する場合は、キーを特定し、次のエンティティ コンストラクター を使いレコードを識別するために使用します。

// For use with the primary key
public Entity (string logicalName, Guid id) {…} 
// For use with a single alternate key value
public Entity (string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}  

これらの値を、Entity.Attributes プロパティ ではなく、Entity.KeyAttributes プロパティ に追加します。 KeyAttributes はレコードを識別するために使用されます。 Attributes はレコードのデータを含みます。

たとえば、テーブルに 2 つの代替キー列を含む代替キーがある場合、このようにエンティティを定義することができます。

KeyAttributeCollection keys = new KeyAttributeCollection() {
   { "example_key1", 5 },
   { "example_key2", 5 }
};

Entity thing = new Entity("example_thing", keys);
thing["example_name"] = "Test Name";

EntityReference クラスを使用する

EntityReference クラス のインスタンスを作成する場合は、エンティティ クラス と同じパターンを使用する次の EntityReference コンストラクター で、レコードを識別するためにキーを特定します。

// For use with the primary key
public EntityReference(string logicalName, Guid id) {…}
// For use with a single alternate key value
public EntityReference(string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}    

• EntityReference を使用してエンティティ検索列の値を設定することができます。 検索列の設定に使用した場合、キー値を使用して主キー値が検索され、主キー値はデータベースに格納されます。
• DeleteRequest クラス を使い Delete のようなプロパティとしてタイプを使用するメッセージの EntityReference を使えます。

.NET 用 SDK を用いた代替キー使用時の例外

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

• Entity.Id プロパティ は、提供されている場合、使われます。 提供されていない場合は、KeyAttributeCollection の確認が行われます。 KeyAttributeCollection が用意されていない場合は、エラーをスローします。
• 提供された KeyAttributeCollection にはテーブルの主キーである 1 つの列が含まれ値が有効の場合、提供された値を Entity.Id プロパティ または EntityReference.Id Property に代入します。
• キー列が提供されている場合、提供された列のセットと Entity に対して定義されているキーとの照合が試みられます。 一致が見つからない場合は、エラーがスローされます。 一致が検出された場合は、これらの列に対して提供された値の有効性が確認されます。 有効な場合、提供された代替キーの値に一致したレコードの主キー値を取得し、この値を Entity.Id プロパティ または EntityReference.Id Property に代入します。
• 一意のキーとして定義されていない列を指定する場合は、一意のキー列の使用が必要であることを示すエラーがスローされます。

関連項目

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

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。