代替キーに関する作業
すべての Microsoft Dataverse テーブル行には、GUID として定義されている一意の識別子を持っています。 これは、各テーブルの主キーです。 外部データ ストアと統合する必要がある場合は、Dataverse アプリ内の一意の識別子への参照を格納するために、外部データベース テーブルに列を追加できる場合があります。 これにより、Dataverse 行にリンクするためのローカル参照を設けることができます。 ただし、外部データベースを変更できないこともあります。 代替キーを使用して、外部データ ストアで使用される一意識別子 (または一意の列の組み合わせ) に一致するように、Dataverse テーブルの列を定義できるようになりました。 主キーの代わりにこの代替キーを使用して、Dataverse の行を一意に識別できます。 どの列が行の一意の ID を表すかを定義できる必要があります。 テーブルに対して一意となる列を識別したら、カスタマイズ ユーザー インターフェイス (UI) またはコードで、代替キーとして宣言できます。 このトピックでは、データ モデルでの代替キーの定義について説明します。
代替キーの作成
プログラムで、またはカスタマイズ ツールを使用して、代替キーを作成できます。 カスタマイズ ツールの使用の詳細については、「Power Apps を使って代替キーを定義する」を参照してください。
代替キーをプログラムで定義するには、最初に EntityKeyMetadata (または、Web API で作業する場合は EntityKeyMetadata EntityType を使用) の種類のオブジェクトを作成する必要があります。 このクラスには、キー列が含まれています。 キー列が設定されると、CreateEntityKey
を使用してテーブルに対するキーを作成することができます。 このメッセージは、テーブル名と EntityKeyMetadata
値を、キーを作成するための入力として使用します。
代替キーを作成するときは、以下の制限に注意ください。
キー テーブル定義の有効な列
以下の種類の列のみを、代替キーのテーブル定義に含めることができます:
列の種類 表示名 DecimalAttributeMetadata 10 進数 IntegerAttributeMetadata 整数 StringAttributeMetadata 1 行テキスト DateTimeAttributeMetadata 日時 LookupAttributeMetadata ルックアップ PicklistAttributeMetadata [オプション セット] 有効なキーのサイズ
キーの作成時に、合計のキー サイズが、キー当たり 900 バイト、キー当たり 16 列などの SQL ベースのインデックスの制約に違反しないことを含め、キーがプラットフォームによってサポートされることの確認が行われます。 キー サイズがその制約に適合しない場合は、エラー メッセージが表示されます。
テーブルに対する代替キー テーブル定義の最大数
Dataverse インスタンス内の 1 つのテーブルに対して、代替キー テーブル定義は最大 10 個です。
キー値内の Unicode 文字
代替キーで使用される列内のデータに
/
、<
、>
、*
、%
、&
、:
、\\
、?
、+
のいずれかの文字が含まれる場合、取得 (GET
)、更新、またはアップサート (PATCH
) アクションは動作しません。 一意性のみを必要とする場合はこの方法も使用することができますが、これらのキーをデータ統合の一部として使用する必要がある場合は、文字を持つデータを持たない列上でキーを作成するのが最善です。仮想テーブルではサポートされていません
データが別のシステムにある場合は一意性を強制できないため、仮想テーブルでは代替キーはサポートされません。 詳細: 仮想テーブル (エンティティ) で開始
代替キーの取得および削除
代替キーを取得、または削除する必要がある場合は、コードを書かなくても、カスタマイズ UI を使用して、これを実行できます。 ただし、SDK は代替キーをプログラムで取得および削除するために、次の 2 つのメッセージを用意しています。
メッセージ要求クラス | 説明 |
---|---|
RetrieveEntityKeyRequest | 指定した代替キーを取得します。 |
DeleteEntityKeyRequest | 指定した代替キーを削除します。 |
テーブルのすべてのキーを取得するには、EntityMetadata
の Keys プロパティを使用 (EntityMetadata EntityType または EntityMetadata クラス)。 テーブルのキーの配列を取得します。
この Web API クエリを使用して、すべてのテーブルを表示し、どのテーブルに代替キーがあるかを確認します。
GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$expand=Keys($select=KeyAttributes)
このリクエストによって返される例:
{
"SchemaName": "Account",
"MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84",
"Keys": [
{
"KeyAttributes": [
"accountnumber"
],
"MetadataId": "1dc7b1d2-6beb-ec11-bb3d-0022482ea769"
}
]
},
{
"SchemaName": "example_Table",
"MetadataId": "8f521e41-8934-ec11-b6e6-002248242f3b",
"Keys": [
{
"KeyAttributes": [
"example_key1",
"example_key2"
],
"MetadataId": "2f16d0c6-88ea-ec11-bb3d-0022482ea769"
}
]
}
代替キーのインデックス作成の監視
代替キーはデータベース インデックスを使用して、一意性を実施し、検索のパフォーマンスを最適化します。 テーブルに多数のレコードが存在する場合は、インデックスの作成は長いプロセスになる可能性があります。 インデックスの作成をバックグラウンド プロセスで行うことによって、カスタマイズ UI とソリューションのインポートの応答性を向上させることができます。 EntityKeyMetadata.AsyncJob
プロパティ (EntityKeyMetadata EntityType または EntityKeyMetadata) は、インデックスの作成を実行する非同期ジョブを参照します。 EntityKeyMetadata.EntityKeyIndexStatus
プロパティは、インデックス作成のジョブの進捗に合わせてキーの状態を指定します。 この状態は、以下のいずれかになります。
- 保留中
- 処理中
- アクティブ
- 失敗
API を使用して代替キーを作成するとき、インデックスの作成が失敗した場合は、失敗の原因の詳細を掘り下げて、問題を修正し、ReactivateEntityKey
(ReactivateEntityKey Action または ReactivateEntityKeyRequest メッセージ) を使用して、キー要求を再びアクティブ化することができます。
インデックス作成のジョブが保留中または進行中に、代替キーが削除されると、そのジョブは取り消され、インデックスが削除されます。
参照
代替キーを使用してレコードを参照
変更の追跡を使用してデータを外部システムに同期
Upsert を使用してレコードを挿入または更新
レコードを参照する代替キーの定義
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示