使用 Web API 查询数据

项目
10/31/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

如果您要检索实体集的数据，请使用 GET 请求。在检索数据时，您可以应用查询选项为要检索的数据和应返回的实体属性设置条件。

在本主题中

基本查询示例

对返回实体数目的限制

指定在一个页面中返回的实体数

应用系统查询选项

请求特定属性

筛选结果

排序结果

将参数别名与系统查询选项一起使用。

限制结果

检索实体计数

包含格式化值

检索有关查找属性的数据

基于单值导航属性筛选记录

通过扩展导航属性检索相关实体

基本查询示例

此示例查询 accounts 实体集，使用 $select 和 $top 系统查询选项以返回前三个客户的 name 属性：

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name&$top=3 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

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

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
 "value": [
  {
   "@odata.etag": "W/\"501097\"",
   "name": "Fourth Coffee (sample)",
   "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501098\"",
   "name": "Litware, Inc. (sample)",
   "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501099\"",
   "name": "Adventure Works (sample)",
   "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
  }
 ]
}

对返回实体数目的限制

除非您指定较小的页面大小，否则会为每个查询返回最多 5000 个实体。如果有多个实体与查询筛选条件匹配，将会返回 @odata.nextLink 属性以及结果。将 @odata.nextLink 属性的值与新的 GET 请求一起使用以返回下一页数据。

备注

对模型实体的查询没有限制，也不分页。详细信息：使用 Web API 查询元数据

指定在一个页面中返回的实体数

使用 odata.maxpagesize 首选项值请求在响应中返回的实体数。

备注

不能使用大于 5000 的 odata.maxpagesize 首选项值。

以下示例查询 accounts 实体集并返回前三个客户的 name 属性。

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
  "value": [
    {
      "@odata.etag": "W/\"437194\"",
      "name": "Fourth Coffee (sample)",
      "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"437195\"",
      "name": "Litware, Inc. (sample)",
      "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"468026\"",
      "name": "Adventure Works (sample)",
      "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
    }
  ],
  "@odata.nextLink": "cc_WebAPI_ServiceURI/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

使用 @odata.nextLink 属性的值请求下一组记录。请勿更改该值或对该值追加任何额外的系统查询选项。对于每个后续请求（为了获得更多页面），您应当使用在原始请求中使用的相同 odata.maxpagesize 首选项值。另外，缓存返回的结果或 @odata.nextLink 属性的值，以便可以返回到以前检索的页面。

备注

@odata.nextLink 属性的值是 URI 编码的。如果您在发送值之前对其进行 URI 编码，URL 中的 XML Cookie 信息将会导致错误。

应用系统查询选项

您追加到实体集的 URL 中的每个系统查询选项都是使用查询字符串的语法添加的。第一个追加到 [?] 之后，后续的查询选项使用 [&] 分隔。所有查询选项都是区分大小写的，如以下示例所示。

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

请求特定属性

使用 $select 系统查询选项限制返回的属性，如以下示例所示。

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue

重要

这是性能最佳实践。如果属性不是使用 $select 指定的，则会返回所有属性。

请求特定类型的属性时，可以期望自动返回其他只读属性。

如果您请求货币值，将返回 _transactioncurrencyid_value 查找属性。该属性仅包含交易货币的 GUID 值，因此您可以使用该值通过使用 transactioncurrency EntityType 检索有关货币的信息。或者，通过请求批注也可以在相同的请求中获得额外的数据。详细信息：检索有关查找属性的数据

如果您请求的属性是某个地址的复合属性的一部分，您还将获得复合属性。例如，如果您的查询请求联系人的 address1_line1 属性，则还会返回 address1_composite 属性。详细信息：5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes。

筛选结果

使用 $filter 系统查询选项为返回的实体设置条件。

标准筛选器运算符

此 Web API 支持下表所列的标准 OData 筛选器运算符。

操作员	说明	示例
比较运算符
eq	等于	$filter=revenue eq 100000
ne	不等于	$filter=revenue ne 100000
gt	大于	$filter=revenue gt 100000
ge	大于或等于	$filter=revenue ge 100000
lt	小于	$filter=revenue lt 100000
le	小于或等于	$filter=revenue le 100000
逻辑运算符
and	逻辑与	$filter=revenue lt 100000 and revenue gt 2000
or	逻辑或	$filter=contains(name,'(sample)') or contains(name,'test')
not	逻辑非	$filter=not contains(name,'sample')
分组运算符
( )	优先分组	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

备注

这是 11.2.5.1.1 内置筛选器操作的子集。算术运算符和比较运算符在 Web API 中不受支持。

标准查询函数

此 Web API 支持这些标准 OData 字符串查询函数。

函数	示例
contains	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

备注

这是 11.2.5.1.2 内置查询函数的子集。Date、Math、Type、Geo 和其他字符串函数在 Web API 中不受支持。

Microsoft Dynamics 365 Web API 查询函数

Microsoft Dynamics 365 提供许多特殊函数，它们接受参数，返回布尔值，而且可以用作查询中的筛选条件。有关这些函数的列表，请参阅 Web API Query Function Reference。下面是 Between Function 的一个示例，用于搜索员工数介于 5 和 2000 之间的客户。

GET cc_WebAPI_ServiceURI/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

详细信息：使用函数组成查询。

排序结果

使用 $orderby 系统查询选项指定项目返回的顺序。使用 asc 或 desc 后缀分别指定升序或降序。如果不应用后缀，则默认为升序。以下示例显示检索客户的名称和收入属性，按收入升序和按名称降序排序。

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

将参数别名与系统查询选项一起使用。

可以将参数别名用于 $filter 和 $orderby 系统查询选项。参数别名允许同一个值在请求中被多次使用。如果未分派别名，值会假定为空。

不带参数别名

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

带参数别名

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=@p1 asc,@p2 desc&$filter=@p1 ne @p3&@p1=revenue&@p2=name

您还在可以使用函数时使用参数别名。详细信息：使用 Web API 功能

限制结果

您可以通过使用 $top 系统查询选项来限制返回的结果数。以下示例将仅返回前三个客户实体。

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3

备注

使用 $top 限制结果将会阻止应用 odata.maxpagesize 首选项。您可以使用 odata.maxpagesize 首选项或 $top，但不能同时使用二者。有关 odata.maxpagesize 的详细信息，请参阅指定在一个页面中返回的实体数。

另外，您不应将 $top 与 $count 一起使用。

检索实体计数

将 $count 系统查询选项与 true 的值一起使用，以包含最多 5000 个与筛选条件匹配的实体。

备注

计数值不代表系统中的实体总数。它受限于可以返回的实体数的最大值。详细信息：对返回实体数目的限制

响应 @odata.count 属性会包含与筛选条件匹配的实体数，无论 odata.maxpagesize 首选项限制如何。

备注

您不应将 $top 与 $count 一起使用。

以下示例显示，有十个客户与名称包含“sample”的条件匹配，但只返回前三个客户。

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

响应

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

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
"@odata.count":10,
"value":[
    {
      "@odata.etag":"W/\"502482\"","name":"Fourth Coffee (sample)","accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502483\"","name":"Litware, Inc. (sample)","accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502484\"","name":"Adventure Works (sample)","accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
    }
  ],"@odata.nextLink":"cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

如果您不希望返回除计数外的任何数据，您可以将 $count 应用到任意集合以获取该值。

请求

GET cc_WebAPI_ServiceURI/accounts/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

响应

HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

10

包含格式化值

当您希望获得属性的格式化值以及结果时，请将 odata.include-annotations 首选项与 OData.Community.Display.V1.FormattedValue 的值一起使用。响应会包括这些具有符合以下命名约定的属性的值：

<propertyname>@OData.Community.Display.V1.FormattedValue

以下示例查询客户实体集并返回第一个记录，包括支持格式化值的属性。

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue&$top=1 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
 "value": [
 {
  "@odata.etag": "W/"502170"",
  "name": "Fourth Coffee (sample)",
  "donotpostalmail@OData.Community.Display.V1.FormattedValue": "Allow",
  "donotpostalmail": false,
  "accountratingcode@OData.Community.Display.V1.FormattedValue": "Default Value",
  "accountratingcode": 1,
  "numberofemployees@OData.Community.Display.V1.FormattedValue": "9,500",
  "numberofemployees": 9500,
  "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
  "revenue": 100000,
  "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
  "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1" } ]
}

检索有关查找属性的数据

如果查询包括查找属性，您可以在这些属性中请求将提供有关数据的额外信息的批注。大多数情况下，如果知道单值导航属性和相关实体中包括的数据，可以派生相同数据。但是，如果属性表示可能引用多种实体类型的查找属性，则该信息可以告诉您什么类型的实体被查找属性引用。详细信息：d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_lookupProperties

有两种其他类型的批注可用于这些属性，

Annotation	说明
Microsoft.Dynamics.CRM.associatednavigationproperty	包括对实体的引用的单值导航属性的名称。
Microsoft.Dynamics.CRM.lookuplogicalname	查找所引用的实体的逻辑名称。

这些属性中还可以包括格式化值，如包含格式化值中所述。与格式化值类似，您可以使用设置为所需特定类型批注的 odata.include-annotations 首选项返回其他批注，也可以将该值设置为 "*" 并返回全部三个。以下示例显示了请求和响应，用以检索有关 _customerid_value 实体 incident 查找属性的信息（也包括批注）。

请求

GET cc_WebAPI_ServiceURI/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,customerid_value&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"

响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
   "@odata.context":"cc_WebAPI_ServiceURI/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
   "@odata.etag":"W/\"504696\"",
   "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
   "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
   "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
   "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
   "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
   "customerid_contact":{
      "@odata.etag":"W/\"503587\"",
      "fullname":"Susanna Stubberod (sample)",
      "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
   }
}

基于单值导航属性筛选记录

导航属性让您可以访问与当前实体相关的数据。单一值导航属性对应于支持多对一关系的查找属性，并允许设置对其他实体的引用。详细信息：d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_navprops

您可以基于单值导航属性值筛选实体集记录。例如，您可以检索指定客户的子客户。您只能使用单值导航属性所引用的实体的主属性值来筛选记录。例如：

检索指定联系人 ID 的所有匹配客户

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=primarycontactid/contactid%20eq%20a0dbf27c-8efb-e511-80d2-00155db07c77 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(name)",
     "value":[
    {
      "@odata.etag":"W/\"513479\"",
      "name":"Adventure Works (sample)",
      "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514057\"",
      "name":"Blue Yonder Airlines (sample)",
      "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
    }
  ]
}

检索指定客户 ID 的子客户。

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
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(name)",
    "value":[
    {
      "@odata.etag":"W/\"514058\"",
      "name":"Sample Child Account 1",
      "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514061\"",
      "name":"Sample Child Account 2",
      "accountid":"03312500-2afc-e511-80d2-00155db07c77"
    }
  ]
}

通过扩展导航属性检索相关实体

使用导航属性中的 $expand 系统查询选项来控制返回相关实体的哪些数据。有两种类型的导航属性：

单一值导航属性对应于支持多对一关系的查找属性，并允许设置对其他实体的引用。
集合值导航属性对应于一对多或多对多关系。

如果您仅包括导航属性的名称，则将收到相关记录的所有属性。您可以在导航属性名称后的括号中使用 $select 系统查询选项来限制相关记录返回的属性。此方法用于单一值和集合值导航属性。

备注

若要检索相关实体的实体实例，请参阅通过扩展导航属性检索实体的相关实体。

通过扩展单值导航属性来检索相关实体：以下示例演示如何检索合同的所有客户记录。对于相关联系人记录，我们只检索 contactid 和全名。

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname) 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(name,primarycontactid,primarycontactid(contactid,fullname))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Yvonne McKay (sample)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9edbf27c-8efb-e511-80d2-00155db07c77","fullname":"Susanna Stubberod (sample)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a2dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Maria Campbell (sample)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a6dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Scott Konersmann (sample)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a8dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Robert Lyon (sample)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aadbf27c-8efb-e511-80d2-00155db07c77","fullname":"Paul Cannon (sample)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"acdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Rene Valdes (sample)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aedbf27c-8efb-e511-80d2-00155db07c77","fullname":"Jim Glynn (sample)"
      }
    }
  ]
}

不是返回实体集的相关实体，您还可通过使用 $ref 选项扩展单值导航属性来返回相关实体的引用（链接）。以下示例返回所有客户的联系人记录的链接。

请求

GET cc_WebAPI_ServiceURI/accounts?$select=name&$expand=primarycontactid/$ref 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(name,primarycontactid)","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","_primarycontactid_value":"a2dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a2dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","_primarycontactid_value":"a6dbf27c-8efb-e511-80d2-00155db07c77","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a6dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","_primarycontactid_value":"a8dbf27c-8efb-e511-80d2-00155db07c77","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a8dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","_primarycontactid_value":"aadbf27c-8efb-e511-80d2-00155db07c77","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aadbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","_primarycontactid_value":"acdbf27c-8efb-e511-80d2-00155db07c77","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(acdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","_primarycontactid_value":"aedbf27c-8efb-e511-80d2-00155db07c77","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aedbf27c-8efb-e511-80d2-00155db07c77)"
      }
    }
  ]
}

通过扩展集合值导航属性来检索相关实体：如果您扩展集合值导航参数来检索实体集的相关实体，将为相关实体返回 @odata.nextLink 属性。您应该将 @odata.nextLink 属性的值与新的 GET 请求一起使用以返回所需数据。

以下示例检索分配给前 5 个客户记录的任务。

请求

GET cc_WebAPI_ServiceURI/accounts?$top=5&$select=name&$expand=Account_Tasks($select%20=%20subject,%20scheduledstart) 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(name,Account_Tasks,Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(36dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(38dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514074\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3adbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3cdbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3edbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    }
  ]
}

通过扩展单值和集合值导航属性来检索相关实体：以下示例演示如何使用单值和集合值导航属性来扩展实体集的相关实体。如上所述，通过展开集合值导航属性来检索实体集的相关实体将为相关实体返回 @odata.nextLink 属性。您应该将 @odata.nextLink 属性的值与新的 GET 请求一起使用以返回所需数据。

在本示例中，我们正在检索联系人及分配给前 3 个客户的任务。

请求

GET cc_WebAPI_ServiceURI/accounts?$top=3&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)  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(name,primarycontactid,Account_Tasks,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"550614\"",
          "name":"Fourth Coffee (sample)",
          "accountid":"5b9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c19648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Yvonne McKay (sample)"
      },
      "Account_Tasks":[

       ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5b9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550615\"",
          "name":"Litware, Inc. (sample)",
          "accountid":"5d9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c39648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Susanna Stubberod (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5d9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550616\"",
      "name":"Adventure Works (sample)",
      "accountid":"5f9648c3-68f7-e511-80d3-00155db53318",
      "primarycontactid":{
        "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
        "fullname":"Nancy Anderson (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5f9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    }
  ]
}

另请参阅

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 执行条件操作

Microsoft Dynamics 365

通过

使用 Web API 查询数据

在本主题中

基本查询示例

对返回实体数目的限制

指定在一个页面中返回的实体数

应用系统查询选项

请求特定属性

筛选结果

标准筛选器运算符

标准查询函数

Microsoft Dynamics 365 Web API 查询函数

排序结果

将参数别名与系统查询选项一起使用。

限制结果

检索实体计数

包含格式化值

检索有关查找属性的数据

基于单值导航属性筛选记录

通过扩展导航属性检索相关实体

另请参阅

其他资源