次の方法で共有


Dataverse レコードの検索

Dataverse 検索では、複数のテーブルにまたがる包括的な検索結果が、1 つのリストで関連性の高い順にすばやく表示されます。 また、アプリでの提案とオートコンプリート エクスペリエンスをサポートする機能も提供します。

注意

この開発者向けドキュメントでは、Dataverse 検索 API をプログラムで操作する方法について説明します。

ユーザー エクスペリエンスとお客様の環境での Dataverse の構成方法の詳細については以下の詳細をご覧ください。

使用方法

開発者は、次の 3 つの異なる方法で検索 API を使用できます。

  • .NET 用 Dataverse SDK
  • Web API /api/data/v9.x エンドポイント
  • ネイティブ検索 /api/search/v2.0/ エンドポイント

検索操作はカスタム API を使用した Dataverse メッセージとして定義されています。 .NET プロジェクトの場合は、.NET 用 SDK を使用できます。

現在、SDK にはこれらの操作を使用するクラスが含まれていません。 .NET Framework プロジェクトの場合は、Power Platform CLI PAC modelbuilder ビルドを使用して、カスタム アクションの場合と同様に、これらのメッセージのために *Request および *Response クラスを生成します。

OrganizationRequest および OrganizationResponse クラスも使用できます。

詳細情報:

検索の操作

検索には、データの検索を可能にするユーザー インターフェイスをサポートする 3 つの操作が用意されています。

SDK のメッセージ名
Web API アクション
Search 2.0 エンドポイント
Description
searchquery
検索クエリのアクション
/api/search/v2.0/query
検索結果ページを返します。
Dataverse の検索クエリを参照する
searchsuggest
searchsuggest アクション
/api/search/v2.0/suggest
ユーザーがフォーム フィールドにテキストを入力するときに提案を表示します。
Dataverse の検索の提案を参照する
searchautocomplete
searchautocomplete アクション
/api/search/v2.0/autocomplete
ユーザーがフォーム フィールドにテキスト入力するときに入力のオートコンプリートを行います。
Dataverse の検索のオートコンプリート

検索が有効かどうかとその構成を理解するために使用できる 2 つの操作もあります。

SDK のメッセージ名
Web API 関数
Search 2.0 エンドポイント
Description
searchstatistics
searchstatistics 関数
/api/search/v2.0/statistics
組織のストレージ サイズとドキュメント数を提供します。
Dataverse 検索の統計を参照する
searchstatus
searchstatus 関数
/api/search/v2.0/status
組織の検索の状態。
Dataverse の検索の状態を参照する

Dataverse Web API で Insomnia を使用したことがある場合は、API を使用してみることがいかに便利であるかがわかるでしょう。 Insomnia 環境を設定して Dataverse Web API で認証するための手順がいくつかあります: Insomnia を Dataverse Web API で使用する

Web API 関数とアクションを使用した検索操作でも同じ手順を使用できます。 ネイティブ検索 2.0 エンドポイント を使用する場合は、次の 2 つの環境変数を変更します。

変数 Web API の値 Search 2.0 エンドポイント値
version 9.2 2.0
webapiurl {{url}}/api/data/v{{version}}/ {{url}}/api/search/v{{version}}/

検索が有効かどうかを検出する

Dataverse 検索は実稼働環境では既定で有効になっていますが、これはオプトアウト機能であるため、実稼働環境でもオフにすることができます。 実稼動環境以外の環境を使用している場合は、管理者で有効にする必要があります。 管理センターで検索を有効化する方法の説明

検索が有効になっていない場合のエラー

環境が有効になっていないときにクエリ、提案、またはオートコンプリート操作を使用すると、次のエラーが発生します。

ErrorCode: -2147185397 Message: Dataverse Search feature is disabled for this organization.

検索サービスが有効になっているかどうかは、組織テーブルの設定を確認するか、Dataverse 検索ステータス操作を使用して検出できます。

組織テーブルのチェック

組織テーブルには、組織の構成方法を制御する 1 行のデータが含まれています。 IsExternalSearchIndexEnabled ブール値列は、組織で検索が有効かどうかを示します。

この関数は、組織の IsExternalSearchIndexEnabled プロパティ値を返します。

static bool IsExternalSearchIndexEnabled(IOrganizationService service) {

    QueryExpression query = new QueryExpression("organization") { 
        ColumnSet = new ColumnSet("isexternalsearchindexenabled")
    };

    EntityCollection organizations = service.RetrieveMultiple(query);
    return (bool)organizations.Entities.FirstOrDefault()["isexternalsearchindexenabled"];
}

詳細情報: QueryExpression を使用してクエリを構築する

どのテーブルと列を検索可能にするかは、Dataverse のデータによって制御されます。

テーブルを有効化する

EntityMetadata.CanEnableSyncToExternalSearchIndex.Value プロパティおよび EntityMetadata.ChangeTrackingEnabled プロパティ が true であるテーブルのみを Dataverse 検索で有効にできます。 CanEnableSyncToExternalSearchIndex.CanBeChanged 値が false の場合、値を変更することはできません。 詳細: 管理プロパティ

テーブルの Dataverse 検索を有効にするには、EntityMetadata.SyncToExternalSearchIndex プロパティtrue に設定します。

テーブルの論理名を使用して、SDK または Web API でテーブルの値を確認できます。 次のクエリの account を、確認するテーブルの論理名に置き換えます。

static void RetrieveSearchSettingsForTable(IOrganizationService service, string logicalName = "account") {

    RetrieveMetadataChangesRequest request = new RetrieveMetadataChangesRequest() { 
            Query = new EntityQueryExpression() { 
                Properties = new MetadataPropertiesExpression(
                    "CanEnableSyncToExternalSearchIndex", 
                    "SyncToExternalSearchIndex")
            }
    };
    request.Query.Criteria.Conditions.Add(
        new MetadataConditionExpression(
            propertyName: "LogicalName", 
            conditionOperator: MetadataConditionOperator.Equals, 
            value: logicalName));

    var response = (RetrieveMetadataChangesResponse)service.Execute(request);

    EntityMetadata table = response.EntityMetadata.FirstOrDefault();

    Console.WriteLine($"CanEnableSyncToExternalSearchIndex: {table.CanEnableSyncToExternalSearchIndex.Value}");
    Console.WriteLine($"SyncToExternalSearchIndex: {table.SyncToExternalSearchIndex}");
}

出力

CanEnableSyncToExternalSearchIndex: True
SyncToExternalSearchIndex: True

詳細情報:

詳細情報:

列を有効化する

テーブルで検索可能な列は、各テーブルの簡易検索ビューに含まれているかどうかによって決まります。 ビュー (SavedQuery) テーブル内のビューの定義をクエリし、プログラムで更新できます。

詳細情報:

サービス保護の制限

Dataverse 検索は下限を適用するので、共通の Dataverse のサービス保護の API 制限が近づくことはありません。 それらを管理する方法も同じです。

Dataverse 検索では、ユーザーは 1 秒あたり 1 つのリクエストを送信できますが、各組織のリクエストは 1 分あたり 150 件に制限されています。 この制限を超えると、429 要求が多すぎますという応答が返されます。 429 エラーが返された場合は、Retry-After 応答ヘッダー値で定義された期間が経過するまで待ってから、さらにリクエストを送信する必要があります。 値は日付に追加される秒数を表します。

参照

Dataverse の検索クエリ
Dataverse の検索の提案
Dataverse の検索のオートコンプリート
Dataverse の統計と状態を検索する
Dataverse のレガシ検索
ご使用の環境で Dataverse 検索を構成する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。