定義済みクエリの取得と実行

[アーティクル]
10/31/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

Microsoft Dynamics 365 は、すべてのユーザーが利用できるシステムビューを管理者が作成する方法を提供します。個々のユーザーはアプリケーション再利用できるように高度な検索のクエリを保存できます。これらはどちらも、Web API を使用して取得して実行できる定義済みクエリです。また、FetchXml を使用してクエリを構成し、そのクエリを使用してデータを取得することもできます。

このトピックの内容

定義済みクエリ

ユーザー定義の FetchXML を使用する

定義済みクエリ

Microsoft Dynamics 365 では、ここに示す 2 種類のクエリを定義、保存、および実行できます。

クエリの種類	内容
保存済みクエリ	エンティティのシステム定義ビュー。このビューは savedquery EntityType に格納されます。詳細:エンティティビューのカスタマイズ
ユーザークエリ	エンティティについてユーザーが保存する高度な検索の内容。このビューは userquery EntityType に格納されます。詳細:UserQuery (保存されているビュー) エンティティ

これらの両方の種類のエンティティのレコードには、返すデータに対する FetchXML 定義が含まれています。それぞれのエンティティの種類をクエリして、主キーの値を取得できます。主キーの値を使用する場合、主キー値を渡すことでクエリを実行できます。たとえば、アクティブなアカウント の保存済みクエリを実行するには、このようなクエリを使用して最初に主キーを取得する必要があります。

GET cc_WebAPI_ServiceURI/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

次に、savedqueryid 値を使用して、その値を savedQuery パラメーターへの値として、accounts エンティティセットに渡すことができます。

GET cc_WebAPI_ServiceURI/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

同じ方法を使用して userqueryid を取得し、その値を userQuery パラメータへの値として、保存したクエリの対応する returnedtypecode に一致するエンティティセットに渡します。

GET cc_WebAPI_ServiceURI/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

適切な種類のコレクションにクエリを適用する

メインエンティティセットのコレクションに保存済みクエリを単純に適用することに加えて、保存済みクエリまたはユーザークエリを使用して、適切な種類のエンティティのコレクションに同じフィルタリングを適用することもできます。たとえば、特定のエンティティに関連するエンティティだけにクエリを適用する場合は、同じパターンを適用できます。たとえば、次の URL は、opportunity_parent_account コレクション値を持つナビゲーションプロパティを使用して、[オープンされている営業案件] クエリを特定の取引先企業に関連する営業案件に適用します。

GET cc_WebAPI_ServiceURI/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

ユーザー定義の FetchXML を使用する

FetchXML は集計を実行する機能を提供する独自のクエリ言語です。savedquery EntityType と userquery EntityType にそれぞれ格納されている保存済みクエリおよびユーザークエリの両方に、クエリを定義する fetchxml が含まれています。IOrganizationService.RetrieveMultiple メソッドまたは RetrieveMultipleRequest を使用して FetchXML を直接使用できます。詳細:FetchXML を使用したクエリの構築

FetchXML パラメーターを使用して、クエリのルートエンティティに対応するエンティティセットに URL エンコードした FetchXML をクエリとして渡して、Web API から結果を返すことができます。たとえば、取引先企業をエンティティとして含んでいる次の FetchXML を使用できます。

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

この URL にはこの FetchXML のエンコード値が次のように表示されます。

%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E

ほとんどのプログラミング言語には、文字列を URL エンコードする関数が含まれています。たとえば、JavaScript では、encodeURI 関数を使用します。 RESTful Web サービスに送信する要求を URL エンコードする必要があります。 URL をブラウザーのアドレスバーに貼り付ける場合、ブラウザーはそのアドレスを自動的に URL エンコードする必要があります。次の例は、取引先企業用のエンティティセットパスを使用して、先に示した FetchXML を使用して GET 要求を示します。

要求

GET cc_WebAPI_ServiceURI/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(accountid,name)","value":[
    {
      "@odata.etag":"W/\"506678\"","accountid":"89390c24-9c72-e511-80d4-00155d2a68d1","name":"Fourth Coffee (sample)"
    },{
      "@odata.etag":"W/\"502172\"","accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1","name":"Litware, Inc. (sample)"
    },{
      "@odata.etag":"W/\"502174\"","accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1","name":"Adventure Works (sample)"
    },{
      "@odata.etag":"W/\"506705\"","accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1","name":"Fabrikam, Inc. (sample)"
    },{
      "@odata.etag":"W/\"506701\"","accountid":"91390c24-9c72-e511-80d4-00155d2a68d1","name":"Blue Yonder Airlines (sample)"
    },{
      "@odata.etag":"W/\"502180\"","accountid":"93390c24-9c72-e511-80d4-00155d2a68d1","name":"City Power & Light (sample)"
    },{
      "@odata.etag":"W/\"502182\"","accountid":"95390c24-9c72-e511-80d4-00155d2a68d1","name":"Contoso Pharmaceuticals (sample)"
    },{
      "@odata.etag":"W/\"506704\"","accountid":"97390c24-9c72-e511-80d4-00155d2a68d1","name":"Alpine Ski House (sample)"
    },{
      "@odata.etag":"W/\"502186\"","accountid":"99390c24-9c72-e511-80d4-00155d2a68d1","name":"A. Datum Corporation (sample)"
    },{
      "@odata.etag":"W/\"502188\"","accountid":"9b390c24-9c72-e511-80d4-00155d2a68d1","name":"Coho Winery (sample)"
    },{
      "@odata.etag":"W/\"504177\"","accountid":"0a3238d4-f973-e511-80d4-00155d2a68d1","name":"Litware, Inc."
    }
  ]
}

注意

リンクエンティティとその属性を含む FetchXML クエリの応答には Unicode 特殊文字が含まれており、「.」は「_x002e_」に、また「@」は「_x0040_」になります。

FetchXML によるページング

fetchXML では、fetch 要素の count 属性と page 属性を設定することで、ページングを適用できます。たとえば、取引先企業に対するクエリを設定し、エンティティ数を 2 に制限するには、また最初のページだけを返すには、次の fetchXML は以下を行う必要があります。

<fetch mapping="logical" page="1" count="2">
 <entity name="account">
  <attribute name="accountid" />
  <attribute name="name" />
  <attribute name="industrycode" />
 <order attribute="name" />
 </entity>
</fetch>

fetchXML を使用した要求では、ページングクッキーを要求して、クエリにその要求を組み入れることもできます。詳細:FetchXML による大量の結果セットのページング

ページングクッキーは注釈として要求される必要があります。Microsoft.Dynamics.CRM.fetchxmlpagingcookie を使用する (または含める) odata.include-annotations 基本設定を指定すると、@Microsoft.Dynamics.CRM.fetchxmlpagingcookie プロパティが結果といっしょに返されます。

定義済みクエリの取得と実行

このトピックの内容

定義済みクエリ

適切な種類のコレクションにクエリを適用する

ユーザー定義の FetchXML を使用する

FetchXML によるページング

関連項目

その他のリソース