擷取並執行預先定義的查詢

發行︰ 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 可讓您定義、儲存及執行兩種類型的查詢，如此處所列。

這兩種實體類型的記錄包含要傳回之資料的 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 屬性。 您可以直接使用 FetchXML 搭配 IOrganizationService。RetrieveMultiple 方法或搭配 RetrieveMultipleRequest。其他資訊：使用 FetchXML 建立查詢

您可以使用 FetchXML 參數將 URL 編碼的 FetchXML 做為查詢傳遞至實體集 (對應查詢的根實體)，以從 Web API 傳回結果。 例如，您可以擁有下列 FetchXML，其以客戶做為實體。

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

此 FetchXML 的 URL 編碼值如這裡所示。

%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 元素的 page 和 count 屬性來套用分頁。 例如，若要設定客戶的查詢並將實體數目限制為 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 的要求，您也可以要求分頁 Cookie 並將它包括在您的查詢中。其他資訊：分頁 FetchXML 大型結果集

分頁 Cookie 必須做為註解要求。 設定 odata.include-annotations 喜好設定使用 (或包括) Microsoft.Dynamics.CRM.fetchxmlpagingcookie，@Microsoft.Dynamics.CRM.fetchxmlpagingcookie 屬性將會隨結果一起傳回。

另請參閱

Web API 查詢資料範例 (C#)
Web API 查詢資料範例 (用戶端 JavaScript)
使用 Web API 執行作業
撰寫 HTTP 要求並處理錯誤
使用 Web API 查詢資料
使用 Web API，建立實體
使用 Web API 擷取實體
使用 Web API 更新和刪除實體
使用 Web API 建立和取消實體的關聯
使用 Web API 功能
使用 Web API 動作
使用 Web API，執行批次作業
使用 Web API 模擬其他使用者
使用 Web API 執行條件運算

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權