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

您可以撰寫 POST 要求，讓所建立記錄的資料傳回且狀態為 201 (Created)。若要取得其結果，您必須在要求標頭中使用 return=representation 喜好設定。

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

本主題內容

基本建立

在單一作業中建立相關實體

在建立時關聯實體

以傳回的資料建立

另請參閱

其他資源