代替キーに関する作業

2024-10-04

すべての Microsoft Dataverse テーブルの行には、GUID として書式設定された一意の識別子があります。これらの識別子は各テーブルの主キーです。外部データストアと統合する必要がある場合、外部データベースのテーブルに列を追加して、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 (EntityMetadata EntityType または EntityMetadata クラス) の新しい Keys プロパティを使用します。テーブルのキーの配列を取得します。

この 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 を使用してレコードを挿入または更新
 レコードを参照する代替キーの定義

次の方法で共有

代替キーに関する作業

代替キーの作成

代替キーの取得および削除

代替キーのインデックス作成の監視

参照

フィードバック

その他のリソース