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

[アーティクル]
04/22/2022

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

注意

OData 構文を使用するクエリとは異なり、事前定義されたクエリまたは fetchXml から返されるデータは、null 値を持つプロパティを返しません。値が null の場合、プロパティは結果に含まれません。

OData 構文を使用してクエリが返されると、レコードには次のような null 値を持つプロパティが含まれます。

{
    "@odata.etag": "W/\"46849433\"",
    "name": "Contoso, Ltd. (sample)",
    "accountnumber": null,
    "accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89"
}

事前定義されたクエリまたは FetchXml を使用して取得した場合、同じレコードには accountnumber プロパティが含まれません。これは、次のように null であるためです。

{
    "@odata.etag": "W/\"46849433\"",
    "name": "Contoso, Ltd. (sample)",
    "accountid": "7a4814f9-b0b8-ea11-a812-000d3a122b89"
}

定義済みクエリ

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

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

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

GET [Organization URI]/api/data/v9.0/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

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

GET [Organization URI]/api/data/v9.0/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

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

GET [Organization URI]/api/data/v9.0/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

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

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

GET [Organization URI]/api/data/v9.0/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

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

FetchXML は集計を実行する機能を提供する独自のクエリ言語です。詳細: FetchXML でデータをクエリする

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

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

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

%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E

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

要求

GET [Organization URI]/api/data/v9.0/accounts?fetchXml=%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%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":"[Organization URI]/api/data/v9.0/$metadata#accounts(accountid,name)","value":[  
    {  
      "@odata.etag":"W/\"506678\"","accountid":"89390c24-9c72-e511-80d4-00155d2a68d1","name":"Fourth Coffee (sample)", "accountnumber":"1234",
    },{  
      "@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."  
    }  
  ]  
}

注意

null 値を持つプロパティは、FetchXml を使用して返される結果には含まれません。上記の例では、返された最初のレコードのみに accountnumber 値があります。

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>

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

バッチ要求内で FetchXML を使用する

GET 要求内の URL の長さは制限されています。 URL に FetchXML をパラメーターとして含めると、この制限に達する可能性があります。この制限が適用されない要求本体に URL から FetchXML を移動する方法として、POST 要求を使用する $batch オペレーションを実行することができます。詳細: Web API を使用してバッチ操作を実行する。

注意

バッチ内での GET リクエストの送信では、最大 32768 文字の長さの URL を使用できます。通常の GET リクエストよりもはるかに多くなりますが、無制限ではありません。

例

要求

POST [Organization URI]/api/data/v9.0/$batch HTTP/1.1

Content-Type:multipart/mixed;boundary=batch_AAA123
Accept:application/json
OData-MaxVersion:4.0
OData-Version:4.0

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary

GET [Organization URI]/api/data/v9.0/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3Cattribute%20name='telephone1'/%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='creditonhold'/%3E%3C/entity%3E%3C/fetch%3E HTTP/1.1
Content-Type: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0

--batch_AAA123--

回答

--batchresponse_cbfd44cd-a322-484e-913b-49e18af44e34
Content-Type: application/http
Content-Transfer-Encoding: binary

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

{  
   "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(accountid,name,telephone1,creditonhold)",
   "value":[  
      {  
         "@odata.etag":"W/\"563737\"",
         "accountid":"1f55c679-485e-e811-8151-000d3aa3c22a",
         "name":"Fourth Coffee (sample)",
         "telephone1":"+1-425-555-0121",
         "creditonhold":false
      },
      {  
         "@odata.etag":"W/\"563739\"",
         "accountid":"2555c679-485e-e811-8151-000d3aa3c22a",
         "name":"Litware, Inc. (sample)",
         "telephone1":"+1-425-555-0120",
         "creditonhold":false
      }
   ]
}
--batchresponse_cbfd44cd-a322-484e-913b-49e18af44e34--