检索和执行预定义的查询

 

发布日期： 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 允许您定义、保存和执行下列两种类型的查询。

查询类型	说明
已保存查询	系统为实体定义的视图。 这些视图存储在 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 使用 FetchXML。RetrieveMultiple 方法或使用 RetrieveMultipleRequest。详细信息：使用 FetchXML 构建查询

可以将 URL 编码的 FetchXML 作为查询传递到与使用 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 请求，而该 FetchXML 以前使用帐户的实体集路径显示。

• 请求

  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 并通过查询包含该 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。 保留所有权利。 版权