代替キーに関する作業

  • [アーティクル]

すべての 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ベースのインデックス制約に違反していないかどうかを確認します。 キーのサイズが制約を満たしていない場合は、エラー メッセージが表示されます。

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

    インスタンス内のテーブルには、最大10個の 代替キー テーブル定義を含めることができます。 Dataverse

  • キー値内のUnicode文字

    代替キー で使用される列内のデータに、 /、<、>、*、%、&、:、\\、?、+ のいずれかの文字が含まれている場合、取得 (GET)、更新、またはアップサート (PATCH) アクションは機能しません。 一意性だけが必要な場合はこのアプローチが機能しますが、データ統合の一部としてこれらのキーを使用する必要がある場合は、それらの文字を含むデータを持たない列にキーを作成するのが最適です。

  • 仮想テーブルではサポートされていません

    データが別のシステムにある場合は一意性を強制できないため、仮想テーブルでは代替キーはサポートされません。 詳細情報: 仮想テーブル (エンティティ) の使用を開始する

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

代替キーを取得、または削除する必要がある場合は、コードを書かなくても、カスタマイズ UI を使用して、これを実行できます。 ただし、SDK は代替キーをプログラムで取得および削除するために、次の 2 つのメッセージを用意しています。

メッセージ要求クラス 説明
RetrieveEntityKeyRequest 指定した代替キーを取得します。
DeleteEntityKeyRequest 指定した代替キーを削除します。

テーブルのすべてのキーを取得するには、 Keys プロパティ EntityMetadata (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を使用してレコードを挿入または更新する
レコードを参照するための代替キーを定義する