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

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

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

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>'. です

• 代替キー値には、一部の特殊文字を含めることはできません。

  次の文字 /、<、>、*、%、&、:、\\、?、+ の代替キー値はサポートされていません。 これらの特殊文字は、URL パス セグメントで予約されているか、構造的に重要です。 これらの値を URL のかっこ内に含む GET 要求を送信すると、Dataverse はエラーを返します。 回避策は、1 つのレコードを取得するのではなく、代替キー値と $filter を使用して、代替キー値と一致する 1 つのレコードを含むコレクションを取得することです。

  たとえば、失敗するこのリクエストの代わりに:

  GET [Organization URI]/api/data/v9.2/new_skts(new_name='M%26M')
  

  $filter クエリを使用します。

  GET [Organization URI]/api/data/v9.2/new_skts?$filter=new_name eq 'M%26M'&$select=new_name
  

  レコードにのみアクセスする必要がある場合は、返された value コレクション内の最初の (および唯一の) 一致するレコードからデータを取得できます。 レコードの更新や削除など、他のアクションを実行する必要がある場合は、この方法を使用して一致するレコードの ID を取得し、代替キーの値ではなく ID 値を使用してレコードを従来参照できます。

  注意

  パラメーター エイリアス (@param) は、代替キー構文では機能しません。 キー述語でパラメーターエイリアスを使用すると、特殊文字のない値であっても 400 エラーが返されます。 $filter を代わりに使用します。

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

sdk for .NETを使用する場合は、2 つの方法で代替キーを使用できます。

Entity クラスを使用する

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 クラスのインスタンスを作成するときは、Entity クラス コンストラクターと同じパターンを使用する次の 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 を使用します。 これを使用してルックアップ列を設定すると、キー値によって主キー値が検索され、主キーの値がデータベースに格納されます。
• EntityReferenceを使用したDeleteなど、この型をプロパティとして使用するメッセージには、を使用します。

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

代替キーを使用する場合は、次の条件と考えられる例外に注意してください。

• 指定した場合、SDK は Entity.Id プロパティ を使用します。 指定しない場合、SDK は KeyAttributeCollectionを調べます。 KeyAttributeCollectionを指定しない場合、SDK はエラーをスローします。
• 指定された KeyAttributeCollection にテーブルの主キーである列が 1 つ含まれており、その値が有効な場合、SDK は Entity.Id プロパティ または EntityReference.Id Property に指定された値を設定します。
• キー列を指定すると、指定した列のセットと、 Entityに定義されているキーとの照合が試行されます。 一致が見つからない場合は、エラーがスローされます。 一致が見つかると、それらの列に指定された値が検証されます。 有効な場合は、指定された代替キー値と一致したレコードの主キー値を取得し、 Entity.Id プロパティ または EntityReference.Id Property に この値を設定します。
• 一意キーとして定義されていない列を指定すると、一意のキー列の使用が必要であることを示すエラーが SDK によってスローされます。