FetchXML の使用によるクエリの作成

  • [アーティクル]

FetchXML は、Microsoft Dataverse 独自の XML ベースのクエリ言語で、Web API または .NET 用 SDK を使用してデータをクエリするために使用されます。 これは言語の機能を記述するスキーマを基に作成されています。 FetchXML 言語では、クエリ式と同様のクエリ機能がサポートされています。 さらに、この言語は主にクエリ式のシリアル化されたフォームとして使用され、UserQuery テーブル 内のユーザー所有の保存済みビューとして、または SavedQuery テーブル 内の組織所有の保存済みビューとしてクエリを保存するために使用されます。

FetchXML クエリ文字列の作成

FetchXML クエリを実行するには、まず XML クエリ文字列をビルドしておく必要があります。 クエリ文字列を作成後、IOrganizationService.RetrieveMultiple メソッドを使用してクエリ文字列を実行します。 ログオンしているユーザーの特権は、返される一連のレコードに影響します。 ログオンしているユーザーが読み取りアクセス権を持っているレコードのみが返されます。

FetchXML クエリ文字列は、FetchXML 言語のスキーマ定義に従っている必要があります。 詳細については、「Fetch XML スキーマ」を参照してください。

SavedQuery レコードを作成するとクエリを保存できます。 link-entity ノードの visible を false に設定し、高度な検索ユーザー インターフェイス内のリンクされたテーブルを非表示にします。 非表示にしてもクエリの実行には参加しており、適切な結果を返します。

警告

パフォーマンスへの悪影響があるため、クエリの全列を取得しないようにしてください。 これは、クエリが更新要求へのパラメーターとして使用される場合は特に true になります。 更新では、すべての列が含まれている場合、これによりすべてのフィールド値が、変更されなくても設定されます。また、多くの場合子レコードへ更新の伝播が発生します。

FetchXML クエリ文字列の例

以下の例の FetchXML 文はすべての取引先企業を取得します。

  
<fetch mapping='logical'>   
   <entity name='account'>  
      <attribute name='accountid'/>   
      <attribute name='name'/>   
   </entity>  
</fetch>

以下の例では FetchXML 文は、所有ユーザーの姓が Cannon に等しくないすべての取引先企業を取得します。

  
<fetch mapping='logical'>  
   <entity name='account'>   
      <attribute name='accountid'/>   
      <attribute name='name'/>   
      <link-entity name='systemuser' to='owninguser'>   
         <filter type='and'>   
            <condition attribute='lastname' operator='ne' value='Cannon' />   
          </filter>   
      </link-entity>   
   </entity>   
</fetch>

次の例では、FetchXML 文でカウントを使用してクエリから返されるレコードの最大数を設定します。 この場合、最初の 3 つの取引先企業がクエリで返され、

<fetch mapping='logical' count='3'>  
  <entity name='account'>  
   <attribute name='name' alias='name'/>  
  </entity>
</fetch>

この例は、EntityMapID が一致する EntityMap と AttributeMap 間での内部結合を示しています。

<fetch version='1.0' mapping='logical' distinct='false'>  
   <entity name='entitymap'>  
      <attribute name='sourceentityname'/>  
      <attribute name='targetentityname'/>  
      <link-entity name='attributemap' alias='attributemap' to='entitymapid' from='entitymapid' link-type='inner'>  
         <attribute name='sourceattributename'/>  
         <attribute name='targetattributename'/>  
      </link-entity>  
   </entity>  
 </fetch>

重要

FetchXML クエリでは、リンク テーブルは最大で 15 個までに制限されています。

FetchXML クエリの実行

FetchXML クエリを実行するには Web API または .NET 用 SDK のいずれかを使用します。

Web API の使用

URL エンコード FetchXml 文字列は fetchXml クエリ文字列パラメーターを使用して適切なエンティティセットに渡すことができます。 詳細: Web API で FetchXml を使用する。

.NET 用 SDK の使用

IOrganizationService.RetrieveMultiple Query プロパティに FetchXml クエリが含まれる FetchExpression を渡すメソッド。

以下のコードは組織サービスを使用した FetchXML クエリの実行方法を示しています:

  
// Retrieve all accounts owned by the user with read access rights to the accounts and   
// where the last name of the user is not Cannon.   
string fetch2 = @"  
   <fetch mapping='logical'>  
     <entity name='account'>   
        <attribute name='accountid'/>   
        <attribute name='name'/>   
        <link-entity name='systemuser' to='owninguser'>   
           <filter type='and'>   
              <condition attribute='lastname' operator='ne' value='Cannon' />   
           </filter>   
        </link-entity>   
     </entity>   
   </fetch> ";   
  
EntityCollection result = _serviceProxy.RetrieveMultiple(new FetchExpression(fetch2));
foreach (var c in result.Entities)
{
   System.Console.WriteLine(c.Attributes["name"]);
}

重要

上記の例のようなコードを扱うときは、文字列がエンコードされた有効な XML 文字列であることを常に確認してください。 これは、&amp;&lt;&gt; としてエンコードされる　"&<>" などの条件値に特殊文字が含まれる可能性があるときに特に当てはまります。

FetchXML クエリは FetchXmlToQueryExpressionRequest メッセージを使用してクエリ式に変換することができます。

FetchXML クエリ結果

OrganizationServiceProxy.RetrieveMultiple(QueryBase) メソッド、戻り値はクエリの結果を格納している EntityCollection です。 これで、テーブル コレクション内を反復できます。 前述の例では、foreach ループを使用して、FetchXML クエリの結果コレクション内を反復しています。

文字列値を使用する条件でワイルドカード文字を使用する

文字列値の条件を使用してクエリを作成する場合は、ワイルドカード文字を使用できます。 詳細: 文字列値の条件でワイルドカード文字を使用する

注意

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

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