使用 OData 终结点的 OData 系统查询选项

项目
07/06/2017

发布日期： 2016年11月

适用于： Dynamics CRM 2015

您可以使用系统查询选项细化查询结果。下表列出了OData 协议中定义的查询字符串选项，在 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新的 OData 终结点实现。

选项	说明
$expand	指示应在所检索的记录或集合中检索相关记录。
$filter	指定为在集合中返回记录计算结果必须为“true”的表达式或函数。
$orderby	确定使用哪些值对记录集合进行排序。
$select	指定要返回的属性子集。
$skip	设置在集合中检索记录之前要跳过的记录数。
$top	确定要返回的最大记录数。

$expand

指示应在所检索的记录或集合中检索相关记录。

如果要检索相关记录，请查找定义此关系的实体关系的名称。可能必须查看应用程序中的实体关系信息，才能为 Organization Data Service 正确标识关系或概念架构定义语言 (CSDL)。

例如，若要检索与帐户相关的商机记录，请使用 opportunity_customer_accounts 实体关系。查询 /AccountSet?$expand=opportunity_customer_accounts 将返回商机记录和帐户记录。

如果要限制返回的列，则还必须在查询中包括导航属性的名称。例如，查询 /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts 只返回帐户名称和展开的商机记录。

Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新不支持查询多级别关系属性。例如，此查询（用于检索与客户有关的商机的所属用户信息）将不起作用：/AccountSet?$expand=opportunity_customer_accounts/opportunity_owning_user。

默认情况下，最多可以定义六个要展开的关系。此查询（展开商机和拥有帐户的系统用户）将起作用：/AccountSet?$select=Name,opportunity_customer_accounts,user_accounts&$expand=opportunity_customer_accounts,user_accounts。

备注

返回的相关记录数与返回的记录数服从同一限制。有关详细信息，请参阅返回记录数目的限制。通过更改 ServerSettingsMaxExpandCount设置值可以增加要展开的关系数。

详细信息：OData：筛选系统查询选项 ($expand)

$filter

指定为在集合中返回记录计算结果必须为 true 的表达式或函数。

如果您正在使用 next 链接检索其他数据集，则不应更改 $filter 查询选项值，因为这会导致不可预测的结果。

筛选系统查询选项的 OData 规格描述了用于创建要在筛选器中计算的表达式的运算符。Microsoft Dynamics 365 使用所有逻辑运算符和可用函数的子集，但是不支持使用算术运算符。筛选器可以使用用括号指示的分组条件。时间值的比较必须使用以下格式：datetime’<time value>’，例如 datetime'2010-07-15' 或 datetime'2010-07-15T16:19:54Z'。

下表列出 Microsoft Dynamics 365 支持的运算符。

运算符	描述	示例
eq	等于	/AccountSet?$filter=Address1_City eq 'Redmond'
ne	不等于	/AccountSet?$filter=Address1_City ne null
gt	大于	/AccountSet?$filter=CreditLimit/Value gt 1000
ge	大于或等于	/AccountSet?&$filter=CreditLimit/Value ge 1000
Lt	小于	/AccountSet?$filter=CreditLimit/Value lt 1000
le	小于或等于	/AccountSet?$filter=CreditLimit/Value le 1000
and	逻辑与	/AccountSet?$filter=CreditLimit/Value ge 1000 and Address1_StateOrProvince eq 'TX'
or	逻辑或	/AccountSet?$filter=AccountCategoryCode/Value eq 2 or AccountRatingCode/Value eq 1
not	逻辑非	/AccountSet?$filter=(AccountCategoryCode/Value ne null) and not (AccountCategoryCode/Value eq 1)

您可以使用 $filter 查询选项筛选 EntityReference 属性的值。例如，如果您具有 SystemUser 记录的 Id 值，则您可以检索用户使用以下筛选器分派的所有客户类型列表：

/AccountSet?$filter=OwnerId/Id eq (guid'" + SystemUserId + "')

下表列出 Microsoft Dynamics 365 支持的函数。

函数	示例
startswith	/AccountSet?$filter=startswith(Name, 'a')
substringof	/AccountSet?$filter=substringof('store',Name)
endswith	/AccountSet?$filter=endswith(Name, '(sample)')

详细信息：OData：筛选系统查询选项 ($filter)

$orderby

确定使用哪些值对记录集合进行排序。默认情况下，顺序为升序。使用 desc 使顺序反向或使用 asc 显式设置默认值。

如果您正在使用 next 链接检索其他数据集，则不应更改 $orderby 查询选项值，因为这会导致不可预测的结果。

备注

使用 $orderby 最多可以选择 12 列。
按复杂类型（如 EntityReference 或 OptionSetValue）排序时，只能指定属性名。例如，若要按帐户的主要联系人排序，请使用查询 $orderby=PrimaryContactId。指定 $orderby=PrimaryContactId/Name 将显示错误请求 HTTP 错误（HTTP 错误代码 400）。

以下示例以升序按国家/地区并以降序按城市列出客户类型：

/AccountSet?$select=Address1_Country,Address1_City,Name&$orderby=Address1_Country,Address1_City desc&$filter=(Address1_Country ne null) and (Address1_City ne null)

详细信息：OData：筛选系统查询选项 ($orderby)

$select

指定要返回的属性的子集以及数据列的组织顺序。默认为返回与 $select=* 对应的所有列。

如果使用 $expand 包括相关数据，并使用 $select 限制返回的列，则还必须在查询中包括导航属性的名称。例如，以下查询（/AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts）将只返回客户名称和展开的商机记录。

备注

在 Internet Explorer 中，POST 和 GET 请求的最大路径长度为 2048 个字符。如果曾在 $select 选项中包括客户实体中的每个属性，则很容易达到此限制。有关详细信息，请参阅 Microsoft KB 208427

详细信息：OData：筛选系统查询选项 ($select)

$skip

设置在集合中检索记录之前要跳过的记录数。

如果您正在使用 next 链接检索其他数据集，则不应更改 $skip 查询选项值，因为这会导致不可预测的结果。

详细信息：OData：筛选系统查询选项 ($skip)

$top

确定要返回的最大记录数。

如果您正在使用 next 链接检索其他数据集，则不应更改 $top 查询选项值，因为这会导致不可预测的结果。

详细信息：OData：筛选系统查询选项 ($top)

不支持的系统查询选项

Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新不支持使用以下系统查询选项：

$inlinecount
$count
$format

另请参阅

使用 OData 终结点查询 Microsoft Dynamics CRM 2015 数据
 OData：URI 约定