次の方法で共有

代替キーの操作

Microsoft Dataverse の代替キーを使用すると、GUID 主キーだけでなく、ビジネス列を使用してテーブル行を一意に識別できます。 これらの識別子は各テーブルの主キーです。 外部データストアと統合する必要があるときは、Dataverse の行を一意に識別するための参照を格納する列を、外部データベースのテーブルに追加できる場合があります。 ただし、外部データベースを変更できないこともあります。 代替キーを使用すると、外部データ ストアで使用される一意識別子（または列の一意の組み合わせ）に対応する列を Dataverse テーブルに設定できます。 この代替キーは、主キーの代わりに Dataverse の行を一意に識別できます。 どの列が行の一意の ID を表すかを定義できる必要があります。 テーブルに対して一意となる列を識別したら、カスタマイズ ユーザー インターフェイス (UI) またはコードで、代替キーとして宣言できます。 この記事では、データ モデルでの代替キーの定義について説明します。

代替キーの作成

代替キーは、プログラムで作成することも、カスタマイズ ツールを使用して作成することもできます。 カスタマイズ ツールの使用の詳細については、「Power Apps を使って代替キーを定義する」を参照してください。

プログラムで代替キーを定義するには、最初に EntityKeyMetadata 型のオブジェクトを作成します (または、Web API を使用する場合 は EntityKeyMetadata EntityType を使用します)。 このクラスには、キー列が含まれています。 キー列を設定したら、 CreateEntityKey を使用してテーブルのキーを作成します。 このメッセージは、テーブル名と EntityKeyMetadata 値を、キーを作成するための入力として使用します。

代替キーを作成するときは、次の制約に注意してください。

  • キー テーブル定義内の有効な列

    代替キー テーブル定義には、次の型の列のみを含めます。

    列の種類 表示名
    DecimalAttributeMetadata (小数アトリビュートメタデータ) 10 進数
    IntegerAttributeMetadata 整数
    文字列属性メタデータ 1 行テキスト
    日時属性メタデータ 日時
    LookupAttributeMetadata 検索
    PicklistAttributeMetadata オプションセット

  • 属性には、適用されるフィールド レベルのセキュリティがあってはいけません

  • 有効なキーのサイズ

    キーを作成すると、キーの合計サイズが、キーあたり 900 バイト、キーあたり 16 列など、SQL ベースのインデックス制約に違反しないことを含め、キーが検証されます。 キーのサイズがその制約に適合しない場合は、エラー メッセージが表示されます。

  • テーブルに対する代替キー テーブル定義の最大数

    Dataverse インスタンス内のテーブルには、最大 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 を使用してレコードを挿入または更新
レコードを参照する代替キーの定義

  • Last updated on