代替キーに関する作業

[アーティクル]
05/30/2023

すべての 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 分かかります。個人データは収集されません (プライバシーステートメント)。

代替キーに関する作業

代替キーの作成

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

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

参照

フィードバック

その他のリソース