.NET 用 SDK を使用したデータのクエリ

  • [アーティクル]

.NET 用 SDK は、データをクエリするメソッドをいくつか提供します。 それぞれにはさまざまな利点があります。

メソッド 利点
FetchExpression 返されるすべてのレコードの値の合計などの集計を返す複雑なクエリを作成するには FetchXML クエリ言語のプロパティを使用します。 FetchXML でグループ化操作も実行できます。 リンクされたテーブル行 (エンティティレコード) からのデータを含めることができます。
QueryExpression 複雑なクエリを作成するには、厳密に型指定されたオブジェクト モデルが必要です。 FetchXML の集計とグループ化を除くすべての機能をサポートします。 リンクされたテーブル行 (エンティティレコード) からのデータを含めることができます。
QueryByAttribute QueryExpression より単純なオブジェクトモデルです。 クエリ内のすべてのテーブル列（属性）値の基準が一致するかどうかをテストしているクエリの QueryByAttribute を使用します。 単一のテーブル (エンティティ タイプ) からのみデータを返すことができます。
LINQ OrganizationServiceContext.QueryProviderを使用し 一般的な LINQ 構文を使用してクエリを作成します。 すべての LINQ クエリは QueryExpression に変換されるため、この機能は QueryExpression で使用できるものに限定されています
このトピックでは、SDK アセンブリ クラスを使用して使用できるクエリのスタイルに焦点を当てます。 詳細: LINQ (.NET 統合言語クエリ) を使用してクエリを作成する

FetchExpression、QueryExpression、および QueryByAttribute は、QueryBase 抽象クラスから派生しています。 これらのクラスを使用して定義されたクエリの結果を取得するには、2 つの方法があります。

注意

IOrganizationService.RetrieveMultiple メソッドが優先されます。 RetrieveMultipleRequest クラスの使用を必要とする特別な機能はありません。

これらのメソッドは両方とも、Entities コレクション内のクエリの結果と、ページングされた結果を受信するための追加のクエリを管理するプロパティを含む EntityCollection を返します。

注意

最高のパフォーマンスを確保するために、各クエリ リクエストは最大 5000 行を返すことができます。 より大きな結果セットを返すには、追加のページをリクエストする必要があります。

文字列値のすべてのフィルター条件では、大文字と小文字は区別されません。

Null テーブルの列値は返されません

テーブル列 (エンティティ属性) に null 値が含まれている場合、または属性が FetchXml 属性または ColumnSet、Entity に含まれていない場合。Attributes には属性が含まれません。 属性にアクセスするためのキー、または返す値はありません。 属性の欠落は、それが null であることを示しています。 早期バウンド スタイルを使用する場合、生成された Entity クラス プロパティはこれを管理し、null 値を返します。

遅延バインド スタイルを使用する場合、Attributes または FormattedValues コレクションのインデクサを使用して値にアクセスしようとすると、The given key was not present in the dictionary メッセージの KeyNotFoundException が発生します。

遅延バインド スタイルを使用するときにこれを避けるには、2 つの方法があります。

  1. null の可能性のある属性の場合、属性が null かどうかをインデクサでアクセスしようとする前に確認するためにEntity.Contains(String) メソッド を使用します。 たとえば、次のようになります。

    Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);

  2. Entity.GetAttributeValue<T>(String) を使用し 値にアクセスします。 たとえば、次のようになります。

    Money revenue = entity.GetAttributeValue<Money>();

注意

GetAttributeValue<T>(String) で指定された型が、Boolean または DateTime などの null にできない値の型である場合、返される値は null ではなく、 false または 1/1/0001 12:00:00 AM などの既定値です。

FetchExpression を使用した FetchXML の使用

FetchXml は、FetchExpression を使用する SDK アセンブリ クエリと fetchXml クエリ文字列を使用する Web API で使用できる独自の XML ベースのクエリ言語です。 詳細情報: FetchXML を使用してデータをクエリする

次の例は、address1_city 値が Redmond と等しい最大 50 の一致するアカウント行を返す簡単なクエリを、name 順に示しています。

string fetchXml = @"
<fetch top='50' >
  <entity name='account' >
    <attribute name='name' />
    <filter>
      <condition 
        attribute='address1_city' 
        operator='eq' 
        value='Redmond' />
    </filter>
    <order attribute='name' />
  </entity>
</fetch>";

var query = new FetchExpression(fetchXml);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x => {
  Console.WriteLine(x.Attributes["name"]);
});

重要

テーブル行を取得するときは、attribute を使用して特定の属性を設定することにより、all-attributes をすべての属性を返す要素の代わりに必要な列の値のみを要求する必要があります。

詳細情報:

QueryExpression の使用

QueryExpression クラスは、クエリの実行時操作のために最適化された、厳密に型指定されたオブジェクトのセットを提供します。

次の例は、address1_city 値が Redmond と等しい最大 50 の一致するアカウント行を返す簡単なクエリを、name 順に示しています。

var query = new QueryExpression("account")
{
  ColumnSet = new ColumnSet("name"),
  Criteria = new FilterExpression(LogicalOperator.And),
  TopCount = 50
};
query.Criteria.AddCondition("address1_city", ConditionOperator.Equal, "Redmond");
query.AddOrder("name", OrderType.Ascending);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x =>
{
  Console.WriteLine(x.Attributes["name"]);
});

重要

行を取得するときは、ColumnSet クラス コンストラクタを使用して特定の属性を設定することにより、必要な列値のみを要求する必要があります。 ColumnSet クラス コンストラクターにはブーリアンの allColumns パラメータを受け入れる負荷がありますが、運用コードでは使用しないでください。

詳細:

QueryByAttribute の使用

QueryByAttribute クラスは、テーブル行の単純で一般的なクエリ用に最適化された、強く型付けされたオブジェクトのセットを提供します。 FetchXML や QueryExpression とは異なり、QueryByAttribute は谷津テーブルからのデータのみを返すことができます。 関連するテーブル行または複雑なクエリ条件からデータを取得することはできません。

次の例は、address1_city 値が Redmond と等しい最大 50 の一致するアカウント行を返す簡単なクエリを、name 順に示しています。

var query = new QueryByAttribute("account")
{
  TopCount = 50,
  ColumnSet = new ColumnSet("name")
};
query.AddAttributeValue("address1_city", "Redmond");
query.AddOrder("name", OrderType.Ascending);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x =>
{
  Console.WriteLine(x.Attributes["name"]);
});

詳細:

書式設定された値にアクセスする

テーブルのクエリに使用する方法に関係なく、データは EntityCollection.Entities として返されます。 Entity.Attributes を使用して、テーブルの列 (属性) のデータ値にアクセスできます の値を使用します。 しかし、これらの値は、アプリケーションで表示できる文字列値を取得するために操作する必要のある、文字列以外の型である可能性があります。

書式設定の環境設定を使用する文字列値にアクセスするには、Entity.FormattedValues コレクション の値を使用します。

次のサンプルは、次の取引先企業属性の書式設定された文字列値にアクセスする方法を示しています。

属性論理名 タイプ
primarycontactid EntityReference
createdon DateTime
revenue Money
statecode OptionSetValue 
var query = new QueryByAttribute("account")
{
TopCount = 50,
ColumnSet = new ColumnSet("name", "primarycontactid", "createdon", "revenue", "statecode")
};
query.AddAttributeValue("address1_city", "Redmond");
query.AddOrder("name", OrderType.Ascending);

EntityCollection results = svc.RetrieveMultiple(query);

results.Entities.ToList().ForEach(x =>
{
Console.WriteLine(@"
name:{0}
primary contact: {1}
created on: {2}
revenue: {3}
status: {4}",
  x.Attributes["name"],
  (x.Contains("primarycontactid")? x.FormattedValues["primarycontactid"]:string.Empty),
  x.FormattedValues["createdon"],
  (x.Contains("revenue") ? x.FormattedValues["revenue"] : string.Empty),
  x.FormattedValues["statecode"]
  );
});

注意

null 値を含むテーブル列 (属性) はクエリ Attributes コレクションや FormattedValues コレクションでは返されません。 列に null 値が含まれている可能性がある場合は、その値にアクセスを試みる前に Contains メソッドを使用することを確認してください。

書式設定された結果は、次のように表示されます。

name:A Datum (sample)
  primary contact: Rene Valdes (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $10,000.000
  status: Active

name:City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $100,000.000
  status: Active

name:Contoso Pharmaceuticals (sample)
  primary contact: Robert Lyon (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $60,000.000
  status: Active

FetchXml と QueryExpression の間でクエリを変換する

QueryExpression クエリを FetchXml、および FetchXml を QueryExpression に変換するには、QueryExpressionToFetchXmlRequest および FetchXmlToQueryExpressionRequest クラスを使用します。

SavedQuery テーブルには、テーブル (エンティティ タイプ) のシステムビューと UserQuery テーブルには、保存されたユーザー クエリが格納されます。 他のテーブルもクエリを FetchXml 文字列として格納する場合があります。 これらのメソッドを使用すると、FetchXml 文字列を QueryExpression に変換し、オブジェクト モデルを使用して操作し、FetchXml に変換して文字列として保存できるようになります。

詳細: サンプル: Fetch と QueryExpression の間でクエリを変換する

クエリ条件の制限

Dataverse で、クエリで許可される条件の合計は 500 に制限されています。 クエリに含まれる結合はすべて、この制限の一部としてカウントされます。 クエリ (およびその結合) の条件が 500 件を超えると、クエリの実行時にユーザーに次のエラーが表示されます。「クエリの条件の数が最大制限値を超えました。」

このエラーが発生した場合、ユーザーは次のいずれかを行う必要があります。

  • クエリの条件の数を減らします。
  • In 句を使用します。これにより、整数に制限のない最大 850 文字の GUID と文字列が許可されます。

注意

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

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