エンティティの代替キーの定義
すべての Dynamics 365 Customer Engagement (on-premises) レコードには、GUID として定義されている一意の識別子を持っています。 これは、各エンティティの主キーです。 外部データ ストアと統合する必要がある場合は、Customer Engagement 内の一意の識別子への参照を格納するために、外部データベース テーブルに列を追加できる場合があります。 これにより、Customer Engagement レコードにリンクするためのローカル参照を設けることができます。 ただし、外部データベースを変更できないこともあります。 ユーザーは、現在は、代替キーを使用して、外部のデータ ストアが使用する一意の識別子 (または一意の列の組み合わせ) に一致するように、Customer Engagement エンティティの属性を定義できます。 主キーの代わりにこの代替キーを使用して、Customer Engagement のレコードを一意に識別できます。 どの属性が、レコードごとの一意の ID を表すかを定義できるようにする必要があります。 エンティティに対して一意となる属性を識別したら、それらの属性をカスタマイズ ユーザー インターフェイス (UI) によって、またはコードで、代替キーとして宣言できます。 このトピックでは、データ モデルでの代替キーの定義について説明します。
代替キーの作成
プログラムで、またはカスタマイズ ツールを使用して、代替キーを作成できます。 カスタマイズ ツールの使用の詳細については、「CRM レコードを参照する代替キーの定義」を参照してください。
代替キーをプログラムで定義するには、最初に EntityKeyMetadata (または、Web API で作業する場合は EntityKeyMetadata EntityType を使用) の種類のオブジェクトを作成する必要があります。 このクラスには、キー属性が含まれています。 キー属性が設定されると、CreateEntityKey を使用してエンティティに対するキーを作成することができます。 このメッセージは、エンティティ名と EntityKeyMetadata 値を、キーを作成するための入力として使用します。
代替キーを作成するときは、以下の制限に注意ください。
キー定義での有効な属性の種類
以下の種類の属性のみを、代替キーの定義に含めることができます。
属性の種類 表示名 DecimalAttributeMetadata 10 進数 IntegerAttributeMetadata 整数 StringAttributeMetadata 1 行テキスト DateTimeAttributeMetadata 日時 LookupAttributeMetadata 参照 PicklistAttributeMetadata Picklist
Note
属性 DateTime、Lookup、および Picklist は、Dynamics 365 Customer Engagement のオンプレミス バージョンでは使用できません。
属性は作成および更新で有効である必要がある
キーで使用されている各属性は作成および更新の両方をサポートする必要があります。 詳細: 属性の有効な操作
属性には適用されるフィールド レベルのセキュリティがあってはならない
属性は論理的または継承的であってはならない
最も論理的および継承的属性は読み取り専用に構成します。 ただし、取引先企業や取引先担当者などのエンティティの住所情報を含む属性の多くは論理的で、書き込み可能であっても、キーで使用することはできません。 詳細: 論理的属性
有効なキーのサイズ
キーの作成時に、合計のキー サイズが、キー当たり 900 バイト、キー当たり 16 列などの SQL ベースのインデックスの制約に違反しないことを含め、キーがプラットフォームによってサポートされることの確認が行われます。 キー サイズがその制約に適合しない場合は、エラー メッセージが表示されます。
1 つのエンティティに対する代替キーの定義の最大数
Customer Engagement インスタンス内の 1 つのエンティティに対して、代替キーの定義は最大 5 つまでです。
キー値内の特殊文字
代替キーで使用されるフィールド内のデータに
/、<、>、*、%、&、:、\\などの文字が含まれている場合は、get アクション および patch アクションは機能しません。 一意性のみを必要とする場合はこの方法も使用することができますが、これらのキーをデータ統合の一部として使用する必要がある場合は、これらの文字を持つデータを持たないフィールド上でキーを作成するのが最善です。
代替キーの取得および削除
代替キーを取得、または削除する必要がある場合は、コードを書かなくても、カスタマイズ UI を使用して、これを実行できます。 ただし、SDK は代替キーをプログラムで取得および削除するために、次の 2 つのメッセージを用意しています。
| メッセージ要求クラス | 説明 |
|---|---|
| RetrieveEntityKeyRequest | 指定した代替キーを取得します。 |
| DeleteEntityKeyRequest | 指定した代替キーを削除します。 |
1 つのエンティティのすべてのキーを取得するには、EntityMetadata (EntityMetadata EntityType または EntityMetadata クラス) の新しい Keys プロパティを使用します。 これは、1 つのエンティティに対するキーの配列を取得します。
代替キーのインデックス作成の監視
代替キーはデータベース インデックスを使用して、一意性を実施し、検索のパフォーマンスを最適化します。 テーブルに多数のレコードが存在する場合は、インデックスの作成は長いプロセスになる可能性があります。 インデックスの作成をバックグラウンド プロセスで行うことによって、カスタマイズ UI とソリューションのインポートの応答性を向上させることができます。 EntityKeyMetadata.AsyncJob プロパティ (EntityKeyMetadata EntityType または EntityKeyMetadata) は、インデックスの作成を実行する非同期ジョブを参照します。 EntityKeyMetadata.EntityKeyIndexStatus プロパティは、インデックス作成のジョブの進捗に合わせてキーの状態を指定します。 この状態は、以下のいずれかになります。
- 保留中
- 処理中
- アクティブ
- 失敗
API を使用して代替キーを作成するとき、インデックスの作成が失敗した場合は、失敗の原因の詳細を掘り下げて、問題を修正し、ReactivateEntityKey (ReactivateEntityKey Action または ReactivateEntityKeyRequest メッセージ) を使用して、キー要求を再びアクティブ化することができます。
インデックス作成のジョブが保留中または進行中に、代替キーが削除されると、そのジョブは取り消され、インデックスが削除されます。