使用 Web API 检索实体

项目
10/31/2017

发布日期： 2017年1月

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

使用 GET 请求来检查指定为具有唯一标识符的资源的实体的数据。在检索实体时还可以请求特定的属性并展开导航属性以返回相关实体的属性。

备注

有关检索实体元数据的详细信息，请参阅使用 Web API 查询元数据。

本主题内容

基本检索示例

检索特定属性

使用备用键进行检索

检索单个属性值

检索导航属性值

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

应用于展开的实体的选项

检测实体自检索后是否更改

检索格式化值

基本检索示例

此示例将返回主键值等于 00000000-0000-0000-0000-000000000001 的客户实体实例的数据。

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)

若要同时检索多个实体，请参阅使用 Web API 查询数据主题中的基本查询示例。

注意

以上示例返回客户记录的任何属性，其参照检索数据的性能最佳实践。此示例是演示如何在 Dynamics 365 中进行实体实例的基本检索。由于不是返回所有属性，我们未在本示例中包括请求的响应信息。

作为性能最佳实践，您必须始终使用 $select 系统查询选项来限制在检索数据时返回的属性。有关此信息，请参阅以下部分，检索特定属性。

检索特定属性

通过包含逗号分隔的属性名列表使用 $select 系统查询选项限制返回的属性。这是重要的性能最佳实践。如果属性不是使用 $select 指定的，则会返回所有属性。

以下示例检索主键等于 00000000-0000-0000-0000-000000000001 的客户实体的 name 和 revenue 属性

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
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,revenue)/$entity",
"@odata.etag": "W/\"502186\"",
"name": "A. Datum Corporation (sample)",
"revenue": 10000,
"accountid": "00000000-0000-0000-0000-000000000001",
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"
}

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

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

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

使用备用键进行检索

如果实体定义了备用键，您还可以使用备用键检索实体而非实体的唯一标识符。例如，如果 Contact 实体拥有包含 firstname 和 emailaddress1 属性的备用键定义，您可以使用具有为这些键提供的数据（如此处所示）的查询检索联系人。

GET cc_WebAPI_ServiceURI/contacts(firstname='Joe',emailaddress1='abc@example.com')

任何时候您需要唯一标识要检索、更新或删除的实体，您都可以使用为实体配置的备用键。默认情况下，实体没有配置的备用键。只有当组织添加它们，备用键才可用。

检索单个属性值

当您只需要检索实体单个属性的值时，可以将属性的名称追加到实体的 URI 以仅返回该属性的值。这是性能最佳实践，因为需要在响应中返回较少数据。

此示例只返回客户实体的名称属性值。

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name 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(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

检索导航属性值

与您可以检索单个属性值使用的方法相同，您还可以通过将导航属性的名称追加到引用单个实体的 URI 来访问导航属性值（查找字段）。

如下示例使用 primarycontactid 单一值导航属性返回客户的主要联系人的全名。

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=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#contacts(fullname)/$entity",
"@odata.etag": "W/\"500128\"",
"fullname": "Rene Valdes (sample)",
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"
}

对于集合值导航属性，您可以选择请求只返回对相关实体的引用或相关实体的计数。

以下示例通过添加 /$ref 到请求将只返回对特定客户的相关任务的引用。

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$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#Collection($ref)",
"value": [
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)"
},
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)"
}
]
}

以下示例使用追加了 /$count 的 Account_Tasks 集合值导航属性返回一些与特定客户相关的任务。

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

响应
```
ï»¿2
```

备注

返回值包括 UTF-8 字节订单标记 (BOM) 字符 (ï»¿)，表示这是一个 UTF-8 文档。

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

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

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

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

备注

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

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

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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))/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"primarycontactid":{
"@odata.etag":"W/\"550626\"",
"contactid":"c59648c3-68f7-e511-80d3-00155db53318",
"fullname":"Nancy Anderson (sample)"
}
}

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

请求

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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)/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",
"primarycontactid":{
"@odata.id":"cc_WebAPI_ServiceURI/contacts(c59648c3-68f7-e511-80d3-00155db53318)"
}
}

通过扩展集合值导航属性来检索实体实例的相关实体：以下示例演示可以如何检索分派给客户记录的所有任务。

请求

GET cc_WebAPI_ServiceURI/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name&$expand=Account_Tasks($select=subject,scheduledstart)
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))/$entity",
"@odata.etag":"W/\"514069\"","name":"Sample Child Account 1","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

备注

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

通过扩展单一值和集合值导航属性来检索实体实例的相关实体：以下示例演示如何使用单一值和集合值导航属性来扩展实体实例的相关实体。

请求

GET cc_WebAPI_ServiceURI/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
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,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity","@odata.etag":"W/\"514069\"","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid":{
"@odata.etag":"W/\"514074\"","createdon":"2016-04-06T00:29:04Z",
"name":"Adventure Works (sample)",
"accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
},"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

备注

不能使用 /$ref 或 /$count 路径段来只返回相关实体的 URI 或相关实体数的计数

应用于展开的实体的选项

您可以在为集合值导航属性返回的实体中应用某些系统查询选项。在集合值导航属性的名称后使用以括号括住的以分号分隔的系统查询选项列表。您可以使用 $select、$filter、$orderby 和 $top。

下列示例筛选与某客户相关的任务实体结果，筛选出具有以“1”结尾的 subject 的实体。

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

以下示例基于 createdon 属性指定相关任务应按升序返回。

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

以下示例仅返回第一个相关任务。

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($top=1;$select=subject)

备注

这是在 OData 版本 4.0 第 1 部分：Protocol Plus Errata 02 的“11.2.4.2.1 扩展选项”一节中介绍的系统查询选项的子集。选项 $skip、$count、$search、$expand 和 $levels 不支持 Web API。

检测实体自检索后是否更改

作为性能最佳实践，您应只请求您需要的数据。如果您以前检索过某个实体记录，您可以使用与以前检索的记录关联的 ETag 对该记录进行条件检索。有关详细信息，请参阅条件检索。

检索格式化值

请求单个记录检索的格式化值与查询实体集时使用的方法相同。详细信息：包含格式化值。

另请参阅

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 检索实体

本主题内容

基本检索示例

检索特定属性

使用备用键进行检索

检索单个属性值

检索导航属性值

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

应用于展开的实体的选项

检测实体自检索后是否更改

检索格式化值

另请参阅

其他资源