FetchXML を使用してクエリを構築します

[アーティクル]
06/10/2024

FetchXML は、 Microsoft Dataverse Web API または SDK for .NET を使用してデータをクエリするために使用される独自のXMLベースのクエリ言語です。 これは言語の機能を記述するスキーマを基に作成されています。 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 ステートメントはcountを使用して、クエリから返されるレコードの最大数を設定します。この場合、最初の 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 または SDK for .NET を使用して実行できます。

Web API の使用

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

.NET 用 SDK の使用

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

次のコードは、Organizationsサービスを使用してクエリを実行する方法を示しています。 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 文字列であることを常に確認してください。これは、&<> としてエンコードされる &<> などの条件値に特殊文字が含まれる可能性があるときに特に当てはまります。

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

FetchXML クエリ結果

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

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

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

注意

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

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

次の方法で共有