使用 Web API 创建实体

项目
10/31/2017

发布日期： 2017年1月

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

使用 POST 请求发送数据以创建实体。可以使用“深层插入”在单个操作中创建多个相关实体。您还需要知道如何使用 @odata.bind 批注设置值以将一个新实体关联到现有实体。

备注

有关如何使用 Web API 创建和更新实体元数据的信息，请参阅使用 Web API 创建更新实体定义。

本主题内容

基本创建

在一个操作中创建相关实体

创建时关联实体

使用返回的数据创建

基本创建

本例创建一个新的客户实体。响应 OData-EntityId 标头包含创建的实体的 Uri。

请求

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

若要创建新的实体，必须确定有效的属性名称和类型。对于所有系统实体和属性，您都可以在 Web API EntityType Reference 中有关该实体的主题中找到此信息。对于自定义实体或属性，请参阅 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl 中该实体的定义。详细信息：d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_entityTypes

在一个操作中创建相关实体

您可以通过将实体定义为导航属性值来创建彼此相关的实体。这称为“深层插入”。

与基本创建一样，响应 OData-EntityId 标头包含创建的实体的 Uri。不返回创建的相关实体的 URI。

例如，发布到 Account 实体集的下列请求正文将在创建客户的上下文中创建总共四个新实体。

一个联系人被创建，因为它被定义为单值导航属性 primarycontactid 的对象属性。
一个商机被创建，因为它被定义为设置为集合值导航属性 opportunity_customer_accounts 值的数组内的一个对象。
一个任务被创建，因为它被定义为设置为集合值导航属性 Opportunity_Tasks 值的数组内的一个对象。

请求

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

创建时关联实体

若要在创建新实体时将其与现有实体关联，必须使用 @odata.bind 批注设置单值导航属性的值。

下列发布到客户实体集的请求正文将创建与现有联系人关联的新客户，该联系人的 contactid 值为 00000000-0000-0000-0000-000000000001。

请求

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
"name":"Sample Account",
"primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000002)

备注

Web API 不支持使用集合值导航属性以此方式关联实体。

使用返回的数据创建

备注

此功能是使用适用于 Dynamics 365 的 2016 年 12 月更新（联机和本地）添加的。

您可以撰写您的 POST 请求，以便从所创建记录返回的数据的状态为 201 (Created)。若要获得其结果，必须在请求头中使用 return=representation 首选项。

若要控制返回哪些属性，请向实体集的 URL 追加 $select 查询选项。$expand 查询选项如果使用将被忽略。

按照这种方法创建实体时，将不返回包含所创建记录的 URI 的 OData-EntityId 头。

此示例新建一个客户实体并在响应中返回请求的数据。

请求

POST cc_WebAPI_ServiceURI/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

响应

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

另请参阅

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 创建实体

本主题内容

基本创建

在一个操作中创建相关实体

创建时关联实体

使用返回的数据创建

另请参阅

其他资源