使用 Web API 更新和删除实体

项目
10/31/2017

发布日期： 2017年1月

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

修改数据的操作是 Web API 的核心部分。除了简单的更新和删除之外，您可以对单个属性执行操作和撰写将根据实体是否存在更新或插入一实体的 upsert 请求。

备注

定义实体的元数据以不同的方式更新。详细信息：使用 Web API 创建更新实体定义

本主题内容

基本更新

使用返回的数据更新

更新单个属性值

删除单个属性值

Upsert 实体

基本删除

基本更新

使用 HTTP PATCH 动词更新操作。将包含您要更新的属性的 JSON 对象传递到代表实体的 URI。如果更新成功，状态为 204 的响应将返回。

此示例更新 accountid 值为 00000000-0000-0000-0000-000000000001 的现有客户记录。

重要

当更新实体时，只包括您正在请求正文中修改的属性。只更新您以前检索的实体的属性并在请求中包括 JSON，将更新每个属性，即使值是相同的。这将导致在审核数据中已更新的属性出现，而实际上此时它们并未更改。

请求

PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0

备注

有关关联更新中实体的信息，请参阅更新时关联实体。

使用返回的数据更新

备注

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

若要从要更新的实体检索数据，可以撰写您的 PATCH 请求，以便来自所创建记录的数据返回时的状态为 200 (OK)。若要获得其结果，必须在请求头中使用 return=representation 首选项。

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

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

请求

PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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":"Updated Sample Account"}

响应

HTTP/1.1 200 OK
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/\"536537\"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2016-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

更新单个属性值

当要只更新单个属性值时，使用属性名称追加到 Uri 实体的 PUT 请求。

以下示例更新 accountid 的值为 00000000-0000-0000-0000-000000000001 的现有客户实体的 name 属性。

请求

PUT cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0

删除单个属性值

若要删除单个属性值，使用属性名称追加到 Uri 实体的 DELETE 请求。

以下示例删除 accountid 的值为 00000000-0000-0000-0000-000000000001 的客户实体的 description 属性的值。

请求

DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

响应

HTTP/1.1 204 No Content
OData-Version: 4.0

备注

这无法用于单一值导航属性解除两个实体的关联。有关备选方法，请参阅删除对实体的引用。

Upsert 实体

upsert 操作与更新非常相似。它使用 PATCH 请求并使用 URI 引用特定的实体。区别是，如果实体不存在将被创建。如果已经存在，将更新。通常，在创建新的实体时，您将允许系统分派唯一标识符。这是最佳实践。但是，如果您需要创建具有特定 id 值的记录，upsert 操作提供执行此操作的方法。当您在不同的系统中同步数据时，这可能非常有用。

有时存在您要执行 upsert，但同时要阻止潜在默认操作中的一个：创建或更新的情况。您可以通过添加 If-Match 或 If-None-Match 标题达到此目的。有关详细信息，请参阅限制 upsert 操作。

基本删除

删除操作非常简单。将 DELETE 动词用于您要删除的实体 URI。此示例消息删除主键 accountid 值等于 00000000-0000-0000-0000-000000000001 的客户实体。

请求

DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

响应
如果实体存在，您会收到状态 204 的正常响应，指示删除成功。如果未找到实体，您将收到状态 404 的响应。
```
HTTP/1.1 204 No Content
OData-Version: 4.0
```

另请参阅

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 更新和删除实体

本主题内容

基本更新

使用返回的数据更新

更新单个属性值

删除单个属性值

Upsert 实体

基本删除

另请参阅

其他资源