次の方法で共有

QueryExpression を使用したデータのクエリ

  • [アーティクル]

QueryExpression クラス は、 Microsoft.Xrm.Sdk.Query 名前空間 の他のクラスとともに、 IOrganizationService.RetrieveMultiple 算出方法 を使用して Dataverse からレコードを取得するための複雑なクエリを作成するためのオブジェクト モデルを提供します。 SDK for .NET を使用してデータをクエリする際のオプションを比較する

クエリを作成する

QueryExpression を使用して、FetchXml を使用して 文字列/XML 操作を必要とせずに変更できる動的クエリを作成します。

すべてのクエリは単一のテーブルに基づいています。 QueryExpression クラスを使用して、クエリがデータを取得するテーブルを選択します。

オブジェクト初期化スタイル

次の例は、クエリは 1 つの割り当てで定義されるよう、オブジェクト初期化子を使用して、Account テーブルの最初の 5 行の Name 列を返す単純な QueryExpression クエリを表しています。ます。

public static EntityCollection SimpleExample(IOrganizationService service) {

   QueryExpression query = new("account")
   {
         ColumnSet = new ColumnSet("name"),
         TopCount = 5
   };

   return service.RetrieveMultiple(query);
}

クエリ インスタンスが初期化されると、次のことが可能になります。

プロパティ割り当てスタイル

QueryExpression(String) コンストラクター またはオブジェクト初期化スタイルを使用せずに同じクエリを作成し、次の例に示すように、インスタンス化されたインスタンスにプロパティを設定することもできます。

public static EntityCollection SimpleExample(IOrganizationService service)
{

   QueryExpression query = new();
   query.EntityName = "account";
   query.ColumnSet.AddColumn("name");
   query.TopCount = 5;

   return service.RetrieveMultiple(query);
}

このサンプルは、次の操作方法を示します。

このドキュメントの例では、オブジェクトの初期化とプロパティの割り当てスタイルの組み合わせを使用します。 クエリが複雑になるにつれて、オブジェクトの初期化スタイルが扱いにくくなる可能性があります。 クエリ プロパティをいつでも個別に定義し、プロパティを設定するか、使用可能な算出方法を使用してクエリに追加できます。

行数の制限

返される行数を制限するには、QueryExpression.TopCount プロパティを使用します。 TopCount プロパティを設定しないと、Dataverse が最大 5,000 行を返します。

または、ページングを使用して、返すレコードの数を指定します。 データのページを要求するときは、TopCount プロパティを使用しないでください。 ページングされた結果をリクエストする方法を解説します

PagingInfo.ReturnTotalRecordCount プロパティ を使用して行数を要求する場合、TopCount プロパティは使用できません。 行の計測方法について説明します。

明確な結果を返します

クエリの結果に重複する値が含まれないようにするには、QueryExpression.Distinct プロパティ を使用します。

Distinct プロパティを使用する場合は、ページングの一貫性を保つために、少なくとも 1 つの OrderExpression を QueryExpression.Orders プロパティ に追加する必要があります。

Distinct プロパティを使用すると、返される結果に各レコードの主キー値は含まれません。これは、主キー値がすべての個別の値の集計を表すためです。

データの取得

SDK for .NET を使用してデータをクエリする で説明したように、 QueryExpression は QueryBase クラス から派生する 3 つのタイプの 1 つであるため、それを IOrganizationService.RetrieveMultiple 算出方法 に渡して、結果を含む EntityCollection を取得できます。

EntityCollection results = service.RetrieveMultiple(query);

ヒント

QueryExpression サンプル コード を使って、この算出方法を使用してみてください。

また、RetrieveMultipleRequest クラス を使って、クエリを RetrieveMultipleRequest.Query プロパティ に設定し、IOrganizationService.Execute 算出方法を使って要求を送信することもできます。

RetrieveMultipleRequest request = new()
{
      Query = query
};
var response = (RetrieveMultipleResponse)service.Execute(request);

EntityCollection results = response.EntityCollection;

次のような場合、RetrieveMultipleRequest クラス を使用します。

クエリを絞り込む

クエリを開始するテーブルを選択した後、クエリを調整して必要なデータを取得します。 次の記事では、クエリを完了する方法について説明します。

記事 Task
列を選択する 返すデータの列を指定します。
テーブルの結合 結果としてどの関連テーブルを返すかを指定します。
行を並べ替える 返す行の並べ替え順を指定します。
行のフィルター 返すデータの行を指定します。
ページの結果 各リクエストで返すデータの行数を指定します。
データの集計 返されたデータのグループ化と集計を行う方法。
行数をカウントする 返された行数を取得する方法。
パフォーマンスの最適化 パフォーマンスを最適化する方法

制限

FetchXml を使用して実行できるが、QueryExpression がサポートしていない操作がいくつかあります。

重要

FetchXmlToQueryExpression メッセージを SDK FetchXmlToQueryExpressionRequest クラス または Web API FetchXmlToQueryExpression 関数のい​​ずれかで使用すると、QueryExpression でサポートされていない機能は適用されず、エラーは発生しません。

コミュニティ ツール

XrmToolBox FetchXMLBuilder は、FetchXml 要求を作成してテストするための無料ツールですが、同じデザイナー エクスペリエンスを使用して、QueryExpression クエリのコードも生成します。

注意

コミュニティによって作成されたツールは、Microsoft によってサポートされていません。 コミュニティ ツールに関する質問や問題は、ツールの公開元にお問い合わせください。

QueryExpression をメッセージ パラメーターとして使用する

また、QueryExpression は、次のメッセージなど Dataverse 操作のパラメーターとしても使用します。

メッセージ名 SDK for .NET リクエスト クラス Web API 操作
BackgroundSendEmail BackgroundSendEmailRequest BackgroundSendEmail アクション
BulkDetectDuplicates BulkDetectDuplicatesRequest BulkDetectDuplicates アクション
BulkDelete BulkDeleteRequest BulkDelete アクション
FullTextSearchKnowledgeArticle FullTextSearchKnowledgeArticleRequest FullTextSearchKnowledgeArticle アクション
QueryExpressionToFetchXml QueryExpressionToFetchXmlRequest QueryExpressionToFetchXml アクション
SendBulkMail SendBulkMailRequest SendBulkMail アクション
SyncBulkOperation SyncBulkOperationRequest SyncBulkOperation action
Rollup RollupRequest ロールアップ機能

注意

BulkDelete、SyncBulkOperation、 QueryExpressionToFetchXml アクション 以外の Web API 操作では、 FetchExpression 複合型を介して FetchXml を使用できます。 Web API には、QueryExpression、ColumnSet、FilterExpression 複合型などの QueryExpression を使用してクエリを作成するための構造が含まれていますが、現在、FetchXml のように、これらを使うことで Web API を使用して QueryExpression でデータを取得する方法はありません。 つまり、Web API を使用してパラメーターとして送信するクエリの結果をテストすることはできません。

次の手順

列を選択する方法について説明します。

列を選択する

いくつかのクエリを試してください。

QueryExpression のサンプル コード