使用 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 (Online 和內部部署) 的 2016 年 12 月更新新增。

若要從您要更新的實體擷取資料，您可以撰寫 PATCH 要求，如此從建立的記錄傳回的資料會有 200 (OK) 狀態。若要取得其結果，您必須在要求標頭中使用 return=representation 喜好設定。

若要控制傳回的屬性，請將 $select 查詢選項附加至實體集的 URL。$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"
}

更新單一屬性值

當您只要更新單一屬性值時，使用 PUT 要求並將屬性名稱附加至實體的 Uri。

下列範例會更新現有客戶實體的 name 屬性為 accountid 值 00000000-0000-0000-0000-000000000001。

要求

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

刪除單一屬性值

若要刪除單一屬性的值，使用 DELETE 要求並將屬性名稱附加至實體的 Uri。

下列範例會刪除客戶實體的 description 屬性值，其 accountid 值為 00000000-0000-0000-0000-000000000001。

要求

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 實體

基本刪除

另請參閱

更多資源